PayU India

Follow the standard PaymentsOS integration procedure, and then apply the relevant extra specifications described below.

• API Version
• Payment Methods
• Currencies
• Features
• Requests
• Setup Procedures
• Integration Procedures
• Supported Bank Codes for Recurring Netbanking Transactions
• Testing

API Version

Minimum required API version: 1.2.0

Payment Methods

The following table lists all supported payment methods.

Currencies

AED,AUD,BDT,BHD,CAD,CHF,CNY,DKK,EUR,GBP,HKD,INR,JPY,KES,KWD,LKR,MUR,MYR,NOK,NPR,NZD,OMR,PHP,QAR,SAR,SEK,SGD,THB,USD,ZAR

The currency you specify in your PaymentsOS provider configuration, must be the same as the currency of your PayU India account.

Features

The following table provides an overview of all supported and non-supported features.

Feature	Supported
3DS 1.0 External	Yes
3DS 1.0 Internal	Yes
3DS 2.0 External	No
3DS 2.0 Internal	No
End-to-End Encryption (E2EE)	No
Installments	Yes
Level 2 and 3 Data	No
Network Tokens	No
Payment Facilitator	No
Pre-authorization	No
Retrieve Supported Payment Methods	Yes
Retrieve Supported Plans	Yes
Statement Soft Descriptor	No
Stored Credentials Flag	Yes
Transaction Processing without CVV	No

Requests

The following table lists all supported requests. Use the bodybuilder to create a sample request body for each request type.

Setup Procedures

The following table lists the setup procedures that are specific to this provider.

Integration Procedures

The following sections list the integration procedures that are specific to this provider.

Implementing a Recurring Transaction Flow

A recurring transaction flow allows you to charge your customers a specific amount for goods or services, on a pre-arranged, recurring schedule. Examples include regular payments such as vehicle insurance, janitorial services, and subscriptions or dues.

In a recurring transaction flow, customers authenticate themselves only once (when initiating their first transaction) and give you permission to automatically deduct the payment from their credit card or bank account. For card transactions, this first step also means that your customers agree to having their card information stored so that the information can be used in the recurring transaction. No authentication is required for subsequent transactions.

Step 1: Save a Customer's Card Information (Cards Only)

For card transactions, start by implementing logic for saving a reusing a customer's card information with PaymentsOS, as explained in Saving the Token.

Step 2: Create a Consent Transaction (Initial Charge Request)

The very first Create Charge request is also known as a Consent Transaction. When initiating this transaction, customers agree to the automatic payment (for card transaction, they also agree to having their card information stored) and then authenticate themselves either by entering an SMS authentication code that was sent to them, or through an authentication page.

Card Transactions

To trigger an SMS-based (zero-redirect) authentication step, pass in "zeroRedirect":"1" in the provider_specific_data object (just beware that SMS-based authentication is only supported if you have a legal entity registered in India). Simply omit this parameter to redirect a customer to an authentication page instead. Also pass in a cof_transaction_indicators.card_entry_mode field with one of the following values:

• consent_transaction: The initial transaction in which the customer agrees to using stored card information for subsequent customer-initiated transactions, or subsequent unscheduled transactions initiated by the merchant.

• recurring_consent_transaction: The initial transaction in which the customer agrees to using stored card information for subsequent scheduled (recurring) transactions.

  In addition, pass in fields holding more information (such as amount and interval) about the periodic payment. Here's an example of all fields you need to pass (for an explanation of all fields, create a sample request using the BodyBuilder and refer to the Fields Overview table):

{
  "cof_transaction_indicators": {
      "card_entry_mode": "consent_transaction",
  },
  "provider_specific_data": {
    "payu_india": {
      "additional_details": {
        "si_amount": "1.00",                              
        "si_cycle": "ADHOC",
        "si_end_date": "2021-07-21",
        "si_interval": 1,
        "si_start_date": "2020-12-03",
        "zeroRedirect": "1" // Omit to redirect customers to an authentication page
      }
    }
  }
}

If you initiated an SMS-based (zero-redirect) authentication request, then you will need to send us the SMS code entered by the customer in order to proceed with the transaction flow. See Handling Zero-redirect Authentication Responses. For a flow in which you redirect customers to an authentication page (which is triggered if you did not initiate an SMS-based authentication request), implement the flow as explained in Redirecting Customers to an Authentication Page.

After initiating the consent transaction, you must validate that the consent transaction was successfully setup. To do so, check the response of the consent transaction's Create Charge request and validate the values of the following fields in the provider_dataobject.

The response of the Create Charge request will also include a cof_transaction_indicators_transactions.cof_consent_transaction_id field. Make sure to store the ID, since you will need it when initiating a pre-debit notification request (explained in the sections that follow).

Bank Transfers

Recurring bank transfers are done through Netbanking. The underlying infrastructure for collecting recurring payments is e-NACH (Electronic National Automated Clearing House). e-NACH is a robust, secure and scalable platform built by National Payments Corporation of India (NPCI) to facilitate interbank, high volume electronic transactions which are repetitive and periodic in nature.

When creating a consent transaction for Netbanking, pass si: 1 in the payment_method.additional_details object to indicate this is a consent transaction. Also pass the customer's bank code in the payment_method.additional_details.bank_code field, as well as fields holding additional information (such as amount and interval) about the periodic payment. Here's an example (for an explanation of all fields, create a sample request using the BodyBuilder and refer to the Fields Overview table):

{ 
    "merchant_site_url": "http://www.mysite.com/return-url",    
    "payment_method": { 
        "type": "untokenized", 
        "source_type": "bank_transfer", 
        "vendor": "netbanking",  
        "additional_details": {  
            "bank_code": "KKBKENCC",  
            "si": "1",    
            "si_amount": "1.00",                              
            "si_customer_account_name": "RADHANATH SIKDAR",  
            "si_customer_account_number": "xxxxxxxx",  
            "si_customer_account_type": "SAVINGS",
            "si_cycle": "ADHOC",                      
            "si_end_date": "2021-07-21",    
            "si_interval": 1,  
            "si_start_date": "2020-12-03"  
        } 
    }, 
    "reconciliation_id": "123456789987655" 
}

The response of the Create Charge request will include two important fields:

• redirection.url: This is the url to the bank's authentication page, to which you must redirect your customer so that they can authenticate themselves and approve the recurring payment. Make sure to setup the redirection flow, as explained in Redirecting Customers to an Authentication Page.

• provider_data.external_id: This is an ID that is used to identify the consent transaction. You will need to pass this ID in all subsequent recurring payments, so make sure to save it in your own backend system.

Step 3: Implement the Recurring Transactions (Subsequent Charge Requests)

After having obtained your customer's consent for the automatic payment, you can go ahead debit your customer's credit card or bank account at periodic intervals. To do so, implement the schedule at which to deduct the payment and invoke the Create Charge request at each due date.

Card Transactions

Before initiating a recurring transaction, you need to initiate a pre-debit notification. This notification informs the customer by SMS that their card is about to be charged. Please contact your account manager for the details of the API you need to invoke. Just make sure to have the consent transaction ID at hand (you received this ID in the cof_transaction_indicators_transactions.cof_consent_transaction_id field in the response of the consent transaction), since you will need it when initiating the pre-debit notification request.

On subsequent Create Charge requests, you can optionally pass a cof_transaction_indicators.cof_consent_transaction_id field holding the ID identifying the initial request in which the customer consented to using stored payment credentials for processing the payment. Also pass a cof_transaction_indicators_transactions.card_entry_mode field with one of the following values:

• recurring_subsequent_transaction: A transaction in a series of transactions that use stored card information and that are processed at fixed, regular intervals.

• cof_merchant_initiated_transaction: Used for unscheduled card-on-file transactions, initiated by you (as the merchant).

Optionally, pass in a provider_specific_data.payu_india.additional_details.pre_debit_id field holding the ID that you passed in the invoiceDisplayNumber field of the pre-debit request API.

Here's an example (note that you do not need to pass a CVV code for a recurring transaction):

{
  "cof_transaction_indicators": {
    "card_entry_mode": "cof_merchant_initiated_transaction",
     "cof_consent_transaction_id": "3715246843"
  },
  "payment_method": {
      "token": "f78cbf5b-0e23-44e0-be11-2081791d9501",
      "type": "tokenized",
  },
  "provider_specific_data": {
    "payu_india": {
      "additional_details": {
        "pre_debit_id": "1234"
      }    
}

Bank Transfers

In the request body of all subsequent Create Charge requests, make sure to pass an payment_method.additional_details.si_external_id field with the value of the ID identifying the consent transaction. Also pass pass recurring: 1 in the payment_method.additional_details object, to indicate that this is a recurring transaction. Here's an example:

{
"payment_method": {
  "type": "untokenized",
  "source_type": "bank_transfer",
  "vendor": "netbanking",
  "additional_details": {
      "si_external_id": "11744444053",
      "recurring": "1"
    }
  }
}

Implementing a Non-recurring Transaction Flow

Non-recurring flows are used for single, one-time, transactions. Customers must authenticate themselves per transaction, either by entering an SMS authentication code (for card transactions only) or through an authentication page.

Card Transactions

To redirect customers to an authentication page, simply omit the provider_specific_data object when invoking a Create Charge request. Make sure to setup the redirection flow, as explained in Redirecting Customers to an Authentication Page.

For SMS-based (zero-redirect) authentication, pass in "zeroRedirect":"1" in the provider_specific_data object when invoking a Create Charge request.

{
  "provider_specific_data": { 
    "payu_india": {
      "additional_details": {
        "zeroRedirect": "1" // Omit to redirect customers to an authentication page
      }
    }
  }
}

If you initiated an SMS-based (zero-redirect) authentication request, then you will need to send us the SMS code entered by the customer in order to proceed with the transaction flow. See Handling Zero-redirect Authentication Responses.

Bank Transfers

For a one-time bank transfer, you can use either regular Netbanking or a UPI flow.

For more information about using a UPI flow, see Implementing a UPI Flow.

When using Netbanking, pass a payment_method.vendor field with a value of netbanking. In the payment_method.additional_details.bank_code field pass the code of the bank from which the transfer should be made. You can fetch a list of all supported bank codes using the Retrieve Supported Payment Methods API request. Also make sure to setup the redirection flow, as explained in Redirecting Customers to an Authentication Page.

Here's an example request body:

{
  "merchant_site_url": "http://www.mysite.com/return-url",
  "payment_method": {
    "source_type": "bank_transfer",
    "type": "untokenized",
    "vendor": "netbanking",
    "additional_details": {
      "bank_code": "AXIB"
    }
  },
  "reconciliation_id": "40762342"
}

Handling Zero-redirect Authentication Responses

If you initiated an SMS-based (zero-redirect) authentication request, then the response of the Create Charge request will include an sms_submission_url, sms_resend_url and sms_cancel_url URL:

{
  "provider_data": {
    "provider_name": "payu_india",
    "raw_response": "raVVKdDcrcWMrOHJKdVRDN2xpZnRpL0cycUt0QU5",
    "external_id": "403993715517799596",
    "additional_information": {
      "transaction_status": "sms_confirmation_pending",
      "sms_submission_url": "https://api.paymentsos.com/payments/0269f212-bd23-48ae-a944-be9a8e926ada/charges/3716e0a3-1139-441c-af16-bebbb19ca0f7/callbacks?q=NmNiMDU4YTMtMTgxMy00N2UzLTlhYmEtNjAzOTBmODNiNzk2Y3Z2X2RlbGltaXRlcnZhdWx0OnYx2jR2R1FWeUMrbnNPdTZ6dG1KWEpCRmgweHMyZml0czFxSm5KRTlxWUJWMlot",
      "sms_resend_url": "https://api.paymentsos.com/payments/0269f212-bd23-48ae-a944-be9a8e926ada/charges/3716e0a3-1139-441c-af16-bebbb19ca0f7/callbacks?q=NmNiMDU4YTMtMTgxMy00N2UzLTlhYmEtNjAzOTBmODNiNzk2Y3Z2X2RlbGltaXRlcnZhdWx0OnYx2jR2R1FWeUMrbnNPdTZ6dG1KWEpCRmgweHMyZml0czFxSm5KRTlxWUJWMlot",
      "sms_cancel_url": "https://api.paymentsos.com/payments/0269f212-bd23-48ae-a944-be9a8e926ada/charges/3716e0a3-1139-441c-af16-bebbb19ca0f7/callbacks?q=NmNiMDU4YTMtMTgxMy00N2UzLTlhYmEtNjAzOTBmODNiNzk2Y3Z2X2RlbGltaXRlcnZhdWx0OnYx2jR2R1FWeUMrbnNPdTZ6dG1KWEpCRmgweHMyZml0czFxSm5KRTlxWUJWMlot"
    }
  }
}

Invoke a POST request to the sms_submission_url to send us the SMS code entered by the customer. In the request body, pass in the sms_confirmation_code:

{
  "sms_confirmation_code": "123456"
}

Invoke a POST request with an empty body to the sms_resend_url URL to resend an SMS code to the customer, if sending the SMS code to the sms_submission_url URL failed. To invalidate the SMS code sent to the customer, invoke a POST request with an empty body to the sms_cancel_url.

SMS (Zero-redirect) POST Request Responses

When creating a successful POST request to the sms_submission_url or sms_cancel_url, the response body will always be empty.

A request sent successfully to the sms_resend_url URL will return the number of resend attempts left:

{
    "resendOtpAttemptLeft":"1"
}

If any of the POST requests failed, then PaymentsOS returns an error object with more information about the error that occurred.

Redirecting Customers to an Authentication Page

Both recurring and non-recurring transaction flows require that customers authenticate themselves. In a recurring flow, this is required only once (during the first transaction); in a non-recurring flow this is required for each transaction.

If you require customers to authenticate themselves on an external authentication page, then implement a redirection flow to redirect customers to that page.

Implementing a Payment Flow with Installments

If you allow your customers to pay with installments, simply pass an installments object in the Create Charge request and include all required installment information.

{
  ...
  "installments": {
      "number_of_installments": 3
  },
  ...
}

Showing Customers Available Installment Options during Checkout

If you configured different installment plans in your PayU India account, then you can fetch those plans and display the various installment options in your checkout page when a customer initiates the payment. To do so, call the Retrieve Supported Plans request. Make sure to pass the transaction amount and currency for which to fetch the available plans as query parameters.

The response of the Retrieve Supported Plans request will include for each plan, a place code representing the number of allowed installments for the specific plan. You should pass this code in the provider_specific_data.payu_india.additional_details.code field in the request body of the Create Charge request , like so:

...
"provider_specific_data": {
    "payu_india": {
      "additional_details": {
        "code": "EMIA12",
        ...
      }
    }
  }
...

Also make sure that the value you pass for installments.number_of_installments matches the number of installments allowed by the plan selected by the customer. For example, a plan code of EMIA12 (as in the example above) indicates that 12 installments are allowed, so you should pass installments.number_of_installments accordingly:

{
  ...
  "installments": {
      "number_of_installments": 12
  },
  ...
}

Implementing an OPGSP Flow

If you do not have a local entity in India and your business is classified as software, digital goods or gaming, then you can register for an OPGSP flow with PayU India. After doing so, make sure to pass an invoice_id in the Create Charge request (this is required).

{
"provider_specific_data": {
    "payu_india": {
      "additional_details": {
        ...
        "invoice_id": "1234",
        ...
      }
    }
  },
  ...
}

Once the payment has been completed, you need to upload a copy of the invoice to your PayU India control panel.

Implementing a UPI Flow

UPI (Unified Payments Interface) is an instant real-time payment system facilitating inter-bank transactions. The system works by instantly transferring funds between two bank accounts.

There are two types of UPI flows you can implement:

• collect flow: In this flow, a shopper completes the payment through a UPI-enabled app using a so-called Virtual Payment Address (VPA). The VPA is a unique identifier that you must generate in order to send and accept money via UPI. When you pass the identifier in the payment flow, the shopper will receive a notification in their UPI-enabled app (such as Google Pay) which they can then click to complete the transaction.

• intent flow: In this flow, you display the checkout screen within a user's app (the term intent refers to an Android intent which is used for launching a screen within an app). Shoppers can then select their payment method of choice in the checkout screen in order to complete the transaction.

UPI Collect Flow

To implement a UPI collect flow, simply pass the vpa identifier in the body Create Charge request. Optionally, also pass a upi_type with a value of collect (if you do not pass the upi_type, the flow will default to a UPI collect flow). Here's a sample request body:

  "merchant_site_url": "http://www.abc.com/return-url",
  "payment_method": {
    "source_type": "bank_transfer",
    "type": "untokenized",
    "vendor": "UPI",
    "additional_details": {
      "upi_type": "collect",
      "vpa": "abc@icici"
    }
  },
  "reconciliation_id": "40762342"
}

UPI Intent Flow

To implement a UPI intent flow, pass a upi_type with a value of intent in the body Create Charge request (do not pass a vpa field, since this will result in an error when doing so in combination with an intent flow). Here's a sample request body:

  "merchant_site_url": "http://www.abc.com/return-url",
  "payment_method": {
    "source_type": "bank_transfer",
    "type": "untokenized",
    "vendor": "UPI",
    "additional_details": {
      "upi_type": "intent"
    }
  },
  "reconciliation_id": "40762342"
}

The url that you must open in the app's screen is then returned in the provider_data.additional_information.upi_linking_url field in the Create Charge request's response body. Here's a sample response (truncated for brevity):

{
    "id": "664c66b4-b6f3-419c-92ca-9bc9f4b88a99",
    "created": "1602771647476",
    "reconciliation_id": "378",
    "payment_method": {
        ...
    },
    "result": {
        "status": "Pending"
    },
    "provider_data": {
        ...
        "additional_information": {
            "upi_linking_url": "upi://pay?pa=payu%40indus&pn=company&tr=11364592317&tid=378&am=1.00&cu=INR&tn=UPI"
        }
    },
    "redirection": {
       ...
    },
    "amount": 100,
    "provider_configuration": {
        ...
    }
}

Implementing Installments with a Subvention EMI Scheme

Subvention EMI (Equated Monthly Installments) is a scheme offered by several banks that allows you to pay the full or partial interest amount on installments, instead of charging this amount to your shoppers. This, in turn, allows you to offer your customers the option of paying in interest-free installments, or in installments with a reduced interest amount.

To know the total interest amount that is charged to you, invoke the Retrieve Supported Plans API request. The interest amount is returned in the provider_data.emiAmount field. Here's a sample response:

[
    {
        "configuration_id": "e8426525-2e22-4157-a925-4bdccda6e8bf",
        "configuration_name": "payuindia",
        "provider_id": "cca51d5b-6bc9-4bb3-844a-70850d687a1b",
        "provider_name": "PayUIndia",
        "plans": [
            {
                "type": "installments",
                "code": "EMIA3",
                "number_of_installments": 3,
                "provider_data": {
                    "transactionAmount": 100,
                    "paybackAmount": 0,
                    "loanAmount": 100,
                    "emiAmount": 33.33,
                    "additionalCost": "0.00",
                    "emiBankInterest": "13",
                    "bankRate": "10",
                    "bankCharge": 10,
                    "amount": 33.33,
                    "tenure": "03 months",
                    "cardType": "credit card",
                    "emiValue": 34.06,
                    "emiInterestPaid": 2.17,
                    "bank_name": "AXIS",
                    "bank_code": "7"
            },
            ...
    }
]

To subvent the interest for your customers, pass the full or partial transaction amount in the installments.subvention_amount field of the Create Charge request.

{
  "installments": {
        "number_of_installments": 3,
        "subvention_amount": 33.33
    },
  ...
}

Supported Bank Codes for Recurring Netbanking Transactions

Testing

You can use the following PayU India test card for testing:

To test both an SMS-based (zero-redirect) authentication request and an authentication step through an external authentication page, use the following codes:

For an SMS-based (zero-redirect) authentication request, pass one of the test codes when invoking the POST request to the sms_submission_url to which you send the SMS code.

To test an authentication step when using an external authentication page, grab the redirect URL from the Charge Request response body. This URL will redirect you to an authentication page created for testing purposes by PayU India, in which you can enter one of the test codes. Bear in mind that you will only be redirected to the test authentication page when initiating a test using test credentials.