server-to-server-integration

Integrate with Server-to-Server

The Server-to-Server integration is performed at the server level, that is, your server (merchant server) and PayU server. The transaction is initiated from your server; hence redirection hop is eliminated. Since the details are captured on your page, customers gain confidence and enhance the checkout experience.

Note: You must be PCI-DSS certified to use Server-to-Server integration. For more information on PCI-DSS certification, contact your Account Manager at PayU.

Steps to Integrate


Integration Security

After receiving a response from PayU, you must calculate the hash again and validate it against the hash that you sent in the request to ensure the transaction is secure. PayU recommends implementing the transaction details APIs and webhook/callback as an extra security measure. You can find more information on this process in the Transaction Details APIs and Webhooks documentation.

You need to ensure that sensitive information related to the integration is not part of the payment request to PayU. The details including — but are not limited to — the following are considered sensitive information:

  • salt value
  • plain text hash string

Along with the request, the sensitive information should not be a part of any merchant-level URL. The following are considered sources for the merchant-level URL:

  • The last web address accessed by a browser before loading PayU’s checkout page.
  • URLs shared as part of payment request to PayU in the parameters: surl, furl, curl, nurl, and termUrl.
  • Notification URLs configured with the merchant account.
  • Invoice Completion URLs configured with the merchant account.

Note: It is important to compare the parameters sent by PayU in the response with the ones you sent in the request to make sure none of them have been changed. You should verify specific parameters such as the transaction ID and amount. PayU is not responsible for any security breaches or losses resulting from your failure to implement the necessary security measures. 


Step 1: Post the Parameters to PayU

The first request from you to PayU with the required transaction mandatory/ optional parameters. This needs to be a server-to-server Curl call request.

Run Request in Real Time:

In the API Playground, select the Server to Server Flow category and run the request for the flow you want.

Request Parameters

ParameterDescriptionExample
key
mandatory
String The merchant key is provided by PayU and acts as a unique identifier for a specific merchant account in the PayU’s database.
Reference: For more information on how to generate the Key and Salt, refer to any of the following:


Your Test Key
txnid
mandatory
String The transaction ID is the order reference number generated by the merchant to track a particular order. It can be used only once and PayU’s system does not accept a duplicate Transaction ID.s7hhDQVWvbhBdN
amount
mandatory
String It should contain the payment amount of the particular transaction. The amount must be greater than Rs. 8000 for the cardless EMI option.10.00
productinfo
mandatory
String It should be a string containing a brief description of the product.iPhone
firstname
mandatory
String The first name of the customer.Ashish
email
mandatory
String The email of the customer.test@gmail.com
phone
mandatory
String The phone number of the customer.9876543210
lastname
optional
String The last name of the customer.Verma
address1
optional
String The first line of the billing address.
Note: This information is helpful when it comes to issues related to fraud detection and chargebacks. Hence, it is must to provide the correct information.
H.No- 17, Block C, Kalyan Bldg, Khardilkar Road, Mumbai
address2
optional
String The second line of the billing address.34 Saikripa-Estate, Tilak Nagar
city
optional
String The city where your customer resides as part of the billing address.Mumbai
state
optional
String The state where your customer resides as part of the billing address,Maharashtra
country
optional
String The country where your customer resides.India
zipcode
optional
String Billing address zip code is mandatory for the cardless EMI option.
Character Limit-20
400004
surl
mandatory
String Success URL(surl) – It must contain the URL on which PayU will redirect the final response if the transaction is successful.https://apiplayground-response.herokuapp.com/
furl
mandatory
String Failure URL (furl) – It must contain the URL on which PayU will redirect the final response in case of failure.https://apiplayground-response.herokuapp.com/
hash
mandatory
String It is used to avoid the possibility of transaction tampering. For more information on hash generation process, refer to Hashing Request and Response.eabec285da28fd
0e3054d41a4d24fe
9f7599c9d0b6664
6f7a9984303fd612
4044b6206daf831
e9a8bda28a6200d
318293a13d6c193
109b60bd4b4f8b09
c90972
udf1
optional
String User-defined fields(udf) are used to store any information corresponding to a particular transaction. Merchants can use up to 5 udfs in the post designated as udf1, udf2, udf3, udf4, udf5. For example, you can store customer's preferred payment.Payment Preference
udf2
optional
Shipping Method
udf3
optional
Shipping Address1
udf4
optional
Shipping City
udf5
optional
Shipping Zip Code
pg
mandatory
String It defines the payment category that the merchant wants the customer to see by default on the PayU’s payment page. If this field is empty, the system assumes the credit card payment option by default.CC
bankcode
mandatory
String Each payment option is identified with a unique bank code at PayU. The merchant must post this parameter with the corresponding payment option’s bank code value in it.
AMEX
s2s_client_ip
mandatory for S2S
String
This parameter must have the source IP of the customer.
Note: This information is helpful when it comes to issues related to fraud detection and chargebacks. Hence, it is must to provide the correct information.
66.15.149.87
s2s_device_info
mandatory for S2S
String
This parameter must have the customer agent’s device.
Note: This information is helpful when it comes to issues related to fraud detection and chargebacks. Hence, it is must to provide the correct information.
Mozilla

Additional Parameters for Card Payments

ParameterDescriptionExample
txn_s2s_flow
mandatory for S2S

String
Pass any of the following value as per your use case for S2S flow:

  • 3: Direct Authorization

  • 4: Zero Redirect Flow

4
ccvv
mandatory
varchar This parameter must contain the CVV number of the card – as entered by the customer for the transaction.
Note: If your customer is returning to your website to shop, you must fetch all the customer's stored cards from PayU, collect the CVV for the card the customer will be using to make payment and then post the CVV number to PayU.
123
ccexpmon
mandatory
integer This parameter must contain the network token expiry month.10
ccexpyr
mandatory
integer This parameter must contain the network token expiry year.2022
store_card_token
mandatory
varchar This must include the Network token generated at your end. 1234 4567 2456 3566
storecard_token_type
mandatory
integer This parameter is used to specify the store card token type. For this scenario, you must include 1.1
additional_info
mandatory
varchar This parameter will contain the additional information in the following JSON format:
{“last4Digits”: “1234”, “tavv”: “ABCDEFGH”,”trid”:”1234567890”, “tokenRefNo”:”abcde123456”}
Where:

  • trid (Token Requestor ID) is the identity given by the networks for creating the tokens. You should be able to get the same from your token provider.

  • tokenRefNo (Token Reference Number) is generated along with the network token. . You should be able to get the same from your token provider.

  • TAVV is a 20-byte Base64-encoded binary value that is used with tokens.


Notes:

  • The last 4 digits of cards is mandatory for all transactions.

  • Some payment gateways require the Token Requester ID (TRID) and Token Reference Number (tokenRefNo) to be passed for processing the transaction. Not passing these values will restrict the number of payment gateways available for processing the transaction.

{“last4Digits”: “1234”, “tavv”: “ABCDEFGH”,”trid”:”1234567890”, “tokenRefNo”:”abcde123456”}
threeDS2RequestData
conditional
JSON This parameter must contain the following information in JSON format. For more information, refer to Request Parameter for 3DS Secure 2.0 Transaction.Refer to Request Parameter for 3DS Secure 2.0 Transaction of Collect Payments with Cards.

For more information on parameters related to save cards or Tokenization, refer to Save Cards API Integration.

Sample Request


Step 2: Check Response from PayU

This will be an S2S call response involving:

  • If there is an error in the request processed, the following error is sent back to you: {“result”:null,”status”:”failed”,”error”:”E1616″,”message”:”Non-seamless not allowed in S2S Flow”}
  • If the request is correctly processed, a Curl response will be sent back to you.

Response Parameters

Note: The response contains a combination of the following JSON objects (metaData, result, and binData) based on the use case used in S2S, and the fields in each of them are described in the following tables.

metaData JSON Fields Description

FieldDescription
messageThis field contains any additional message about the transaction.
referenceIdThis field contains the reference ID of the transaction.
statusCodeThis field contains the status code for the transaction.
txnIdThis field contains the transaction ID of the transaction that was posted in the request.
unmappedStatusThis field contains the unmapped status of the transaction. For more information, refer to Status Explanations.

result JSON Fields Description

FieldDescription
mihpayidIt is a unique reference number created for each transaction at PayU’s end. You must note this transaction ID as this will be used as a reference for all the future actions on this transaction like Inquiry or Refund.
modeThis parameter describes the payment category by which the transaction was completed or attempted by the customer. For the payment categories, refer to Payment Mode Codes.
statusThis parameter gives the status of the transaction as either success, failed or pending.
Possible values: success, failure, pending
If the value of the ‘status’ parameter is ’success’, the transaction is successful.
If the value of ‘status’ is ‘failure’ or ‘pending’, must be treated as a failed transaction only.
keyThis parameter contains the merchant key for the merchant’s account at PayU. It would be the same as the key used while the transaction request is being posted from the merchant’s end to PayU.
txnidThis parameter would contain the transaction ID value posted by the merchant during the transaction request.
amountThis parameter would contain the original amount which was sent in the transaction request by the merchant.
productinfoThis parameter would contain the same value of product information which was sent in the transaction request from the merchant’s end to PayU.
firstnameThis parameter would contain the same value of first name which was sent in the transaction request from the merchant’s end to PayU.
lastnameThis parameter would contain the same value of last name which was sent in the transaction request from the merchant’s end to PayU.
emailThis parameter would contain the same value of email which was sent.
phoneThis parameter would contain the same value of phone which was sent in the transaction request from the merchant’s end to PayU.
udfThis parameter would contain the same value of udf values that were sent in the transaction request from the merchant’s end to PayU. It ranges from udf1 to udf5.
hashPayU calculates the hash using a string of other parameters and returns it to the merchant. The merchant must verify the hash, and only then mark a transaction as success/failure. This is to make sure that the transaction hasn’t been tampered with.
The calculation is as follows:
sha512(SALT|status||||||udf5|udf4|udf3|udf2|udf1|email|firstname|productinfo|amount|txnid|key)

Note: The handling of udf1 – udf5 parameters remains similar to the hash calculation when the merchant sends it in the transaction request to PayU. If any of the udf (udf1-udf5) was posted in the transaction request, it must be taken in hash calculation also.
If none of the udf parameters were posted in the transaction request, they should be left empty in the hash calculation too.
errorFor the failed transactions, this parameter provides the reason for 
failure.

Note: The reason for failure depends upon the error codes provided by different banks and hence the detailing of error reasons may differ from one transaction to another. The merchant can use this parameter to retrieve the reason for failure for a particular transaction.
bankcodeThis parameter contains the code indicating the payment option used for the transaction. For example, in the Debit Card mode, there are different options like Visa Debit Card, Mastercard, Maestro etc. For each option, a unique bank code exists. It would be returned in this bank code parameter. For example, Visa Debit Card – VISA, Master Debit Card – MAST.
PG_TYPEThis parameter gives information on the payment gateway used for the transaction. For example, if CC PG was used, it would contain the value CC-PG. Similarly, it would have a unique value for all different types of payment gateways.
bank_ref_numFor each successful transaction – this parameter would contain the bank reference number generated by the bank.
unmappedstatusThis parameter contains the status of a transaction as per the internal database of PayU. PayU’s system has several intermediate status which are used for tracking various activities internal to the system. For more information, refer to Status Explanations.

binData Fields Description (applicable for only for Cards)

FieldDescription
pureS2SSupportedThis field contains contains any of the following to indicate whether the card supports S2S:

  • true: Card supports S2S

  • false: Card does not support S2S

issuingBankThis field contains the card issuing bank.
cardTypeThis field contains the card type such as VISA, MasterCard, etc.
isDomesticThis field contains contains any of the following to indicate whether the card is domestic or international:

  • true: It is a domestic card

  • false: It is an international card

Sample Response

The response may contain a combination of the metaData, result, and binData JSON objects based on the use case in S2S. The metaData and result JSON objectin the response may contain additional fields based on the use case in S2S.

{
  "metaData": {
    "message": null,
    "referenceId": "2710cd2a20e08a006034861feea27f084a425e94920df9b1856eb6e90793067b",
    "statusCode": "E000",
    "txnId": "payuTestTransaction2909041",
    "unmappedStatus": "captured"
  },
  "result": {
    "mihpayid": "412345678912362515",
    "mode": "CC",
    "status": "success",
    "key": "J****g",
    "txnid": "payuTestTransaction2909041",
    "amount": "100",
    "addedon": "2020-06-09 16:54:26",
    "productinfo": "Product Info",
    "firstname": "Postman",
    "lastname": "",
    "address1": "",
    "address2": "",
    "city": "",
    "state": "",
    "country": "",
    "zipcode": "",
    "email": "test@payu.in",
    "phone": "9123456781",
    "udf1": "",
    "udf2": "",
    "udf3": "",
    "udf4": "",
    "udf5": "",
    "udf6": "",
    "udf7": "",
    "udf8": "",
    "udf9": "",
    "udf10": "",
    "card_no": "XXXXXXXXXXXX2346",
    "field0": "",
    "field1": "",
    "field2": "",
    "field3": "",
    "field4": "",
    "field5": "NW9WYkV0dzJCclpsMWNRbzg0VVk=",
    "field6": "02",
    "field7": "AUTHPOSITIVE",
    "field8": "",
    "field9": "Successful Transaction",
    "payment_source": "payuPureS2SAuth",
    "PG_TYPE": "CC-PG",
    "error": "E000",
    "error_Message": "Success",
    "unmappedstatus": "captured",
    "hash": "df540d8fc8265e9382415993e468cfe0884574ddc617b96053082195752e11e4405888bb96030e749be780805dcf8499241a3c51fb26f978cdb6d328cda2a138",
    "bank_ref_num": "",
    "bankcode": "CC"
  }
}