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.
Payment Method | Payment Method Type |
---|---|
Airtel Money | eWallet |
Amazon pay | eWallet |
American Express | Cards |
DINERS | Cards |
Dynamic QR | Bank Transfer |
FreeCharge | eWallet |
JioMoney | eWallet |
MAESTRO | Cards |
MASTERCARD | Cards |
Netbanking | Bank Transfer |
Ola Money | eWallet |
Pay Zapp | eWallet |
Paytm | eWallet |
Phonepe | eWallet |
RUPAY | Cards |
UPI | Bank Transfer |
VISA | Cards |
VISA Electron | Cards |
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.
Requests
The following table lists all supported requests. Use the bodybuilder to create a sample request body for each request type.
Request | Partial/Multiple | Mode |
---|---|---|
Charge | Not Applicable | Asynchronous |
Refund | Both partial and multiple are supported | Asynchronous |
Request | Partial/Multiple | Mode |
---|---|---|
Charge | Not Applicable | Asynchronous |
Refund | Both partial and multiple are supported | Asynchronous |
Request | Partial/Multiple | Mode |
---|---|---|
Charge | Not Applicable | Asynchronous |
Refund | Both partial and multiple are supported | Asynchronous |
Setup Procedures
The following table lists the setup procedures that are specific to this provider.
Configuration | Required/Optional |
---|---|
In the PaymentsOS Control Center, configure the following credentials:
| Required |
Enable idempotency for all transaction types. Contact your PayU India account representative and request that idempotency is enabled for all transaction types. | Required |
In the PaymentsOS Control Center, register webhooks to be notified when a transaction changes its status. | Required |
In your PaymentsOS account, configure the payment currency you want to support.Important note: The currency you specify must be the same as the currency of your PayU India account. | Required |
In your PayU India account, enable the Standing Instructions payment method. Contact PayU India support for assistance. | Optional |
In your PayU India account, enable payment methods. Contact PayU India support for assistance. | Optional |
Integration Procedures
The following sections list the integration procedures that are specific to this provider.
Implementing a Recurring Transaction Flow
Card Transactions versus Bank Transfers
Recurring transactions are supported for both card transactions and bank transfers. Beware that the request bodies you must construct may differ, depending on whether the recurring transaction is for a card transaction or a bank transfer. Those differences are specifically mentioned in the explanations that follow.
Of course, you can also use the BodyBuilder to generate the sample requests shown in the steps below, including an explanation of all fields. For card transactions, choose the Cards payment type. For bank transfers, choose the Bank Transfer payment type and select the Netbanking payment method. Make sure to include optional fields in the output (for both card and bank transfer transactions).
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 "si":"1"
in the provider_specific_data
object to issue a Standing Instruction (SI), which instructs PayU India to setup a recurring transaction flow.
Here's an example of the attributes you need to pass in the first Create Charge request to trigger a recurring, SMS-based (zero-redirect), transaction flow:
{
"provider_specific_data": {
"payu_india": {
"additional_details": {
"si": "1",
"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.
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"
}
Bank Codes
See Supported Bank Codes for Recurring Netbanking Transactions for a list of supported bank codes.
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
No Local Entity in India?
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. For more information, see Implementing an OPGSP Flow.
On subsequent Create Charge requests, pass in "recurring":"1"
in the provider_specific_data
object. You do not need to pass in any of the attributes sent in the initial Consent Transaction.
{
"provider_specific_data": {
"payu_india": {
"additional_details": {
"recurring": "1"
}
}
}
}
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"
}
}
}
Note
It can take up to 2 days to receive the final status (Succeed
or Failed
) of the recurring transaction. PaymentsOS will inform you of a change in the transaction status through a webhooks notification.
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
.
Note
The response of the Create Charge request will also include a redirection
object with a url
attribute. This enables you to direct your customers to an external authentication page, as an alternative authentication option for customers who do not want to enter an SMS authentication code on your web page. The url
is always returned by the Create Charge request, also if you set "zeroRedirect":"1"
.
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.
Important Note
The url of your site to which customers are redirected after completing a transaction, will also include a transaction status (see step 9 in Implementing a Redirection Flow). You should only use this status for providing customers with additional information about the transaction. Do not use this status for determining the final transaction status. To determine the final transaction status, you must solely rely on the status received in the webhook notification.
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.
Supported Currency
Only INR is supported with the Retrieve Supported Plans request.
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.
Using the Bodybuilder
When using the BodyBuilder to generate sample requests, make sure to choose the Bank Transfer payment type and include optional fields in the output.
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": {
...
}
}
Supported Bank Codes for Recurring Netbanking Transactions
Bank | Code |
---|---|
Bank OF Baroda |
BARBENCC |
Central Bank of India |
CBINENCC |
City Union Bank |
CIUBENCC |
Deutsch Bank |
DEUTENCC |
Equitas Small Finance Bank |
ESFBENCC |
Federal Bank |
FDRLENCC |
HDFC Bank |
HDFCENCC |
IDBI First Bank |
IBKLENCC |
ICICI Bank |
ICICENCC |
IDFC Bank |
IDFBENCC |
IndusInd Bank |
INDBENCC |
Indian Overseas Bank |
IOBAENCC |
Kotak Mahindra Bank |
KKBKENCC |
Bank of Maharashtra |
MAHBENCC |
Punjab National Bank |
PUNBENCC |
PayTm Payments Bank |
PYTMENCC |
RBL Bank |
RATNENCC |
State Bank of India |
SBINENCC |
Tamilnad Mercantile Bank |
TMBLENCC |
Ujjivan Small Finance Bank |
USFBENCC |
Axis Bank |
UTIBENCC |
YES Bank |
YESBENCC |
Testing
You can use the following PayU India test card for testing:
Card number | Expiration date | CVV | Card Type |
---|---|---|---|
4854 4601 9876 5435 | May 20 2021 | 123 | Debit/Credit Card |
5123 4567 8901 2346 (recurring payments) | May 20 2021 | 123 | Debit/Credit Card |
To test both an SMS-based (zero-redirect) authentication request and an authentication step through an external authentication page, use the following codes:
Code | Simulates |
---|---|
123456 | Success |
000000 | Failure |
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.