UPI (Unified Payments Interface) is one of India’s most popular digital payment systems, enabling instant, secure, and real-time payments directly from customers’ bank accounts. Managed by the National Payments Corporation of India (NPCI), UPI has revolutionized digital transactions in India with features like 24/7 availability, multi-bank support, and seamless transaction processing. Integrating UPI with EBANX allows international merchants to accept payments from Indian customers using one of the most trusted payment methods in the region.
Requirements
- API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
- Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters.
Workflow options
UPI offers two distinct payment flows to accommodate different user interactions:
- UPI QR Code - This flow generates a QR code that users scan with their UPI app. It redirects them to the app, where the payment details are pre-filled. Users then enter their UPI PIN to complete the transaction.
- UPI Intent - This flow is designed for mobile devices. Users tap to pay, pre-selecting their UPI app (or a generic option). The deep link redirects them directly to the chosen app, with pre-filled payment details, where they authenticate the transaction with their UPI PIN.
The main difference is in how each flow is initiated: upi-qrcode requires scanning a QR code, while upi-intent involves tapping and selecting the UPI app.
How it Works
- Customer initiates payment - At checkout, the customer selects UPI as their preferred payment option.
- Payment method selection - The customer can choose between scanning a QR code (upi-qrcode) or tapping to pay using a specific UPI app (upi-intent).
- Redirection to UPI app
- For upi-qrcode, the user scans the QR code, which redirects them to the UPI app with pre-filled payment details.
- For upi-intent, the user is directly redirected to their chosen UPI app with pre-filled payment details.
- UPI PIN authentication - In the UPI app, the customer enters their UPI PIN to authorize and complete the transaction.
- Payment confirmation - Once the transaction is successful, the customer receives a confirmation notification in their UPI app, and the merchant is updated with the transaction status.
- EBANX notification - EBANX sends a notification to the you, confirming the successful transaction, allowing you to fulfill your customer's order.
Instructions
Follow the steps below.
Select your environment
Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.
https://sandbox.ebanx.com/ws/directDefine your parameters
Basic parameters:
Parameter Description operationSet to requestintegration_keyYour EBANX integration key payment_type_codeSet to upi-qrcodeorupi-intentcountrySet to infor IndiaCustomer data:
Parameter Description nameCustomer name emailCustomer email phone_numberCustomer phone addressCustomer address street_numberCustomer street number cityCustomer city stateCustomer state zipcodeCustomer zip code Name Validation The value provided in the
nameparameter will undergo a validation process to ensure it matches the UPI ID account holder’s registered name.Charge parameters:
Parameter Description merchant_payment_codeUnique merchant payment code currency_codeSupported value: INRamount_totalTotal amount to be charged UPI QR Code
In the upi-qrcode flow, users scan a QR code, which redirects them to their UPI app to complete the transaction. Upon redirection, the UPI app loads the pre-filled payment details and prompts the user to enter their UPI PIN for authentication, finalizing the transaction.
Request
Use the following example to initiate a request.
// ****** UPI QR Code ******
curl -X POST \
--location 'https://sandbox.ebanx.com/ws/direct' \
--header 'Content-Type: application/json' \
--data '{
"integration_key": "your_ebanx_integration_key",
"operation": "request",
"payment": {
"name": "John Doe",
"email": "email@example.com",
"phone_number": "7000000000",
"address": "MG Road",
"street_number": "101",
"city": "Bangalore",
"state": "KA",
"zipcode": "560001",
"country": "in",
"payment_type_code": "upi-qrcode", // Set to 'upi-qrcode'.
"merchant_payment_code": "0x012B01-IN-U01",
"order_number": "1234567",
"currency_code": "INR",
"amount_total": "100.00"
}
}'Response
A successful request returns a response like the example below.
// ****** UPI QR Code ******
"payment": {
"hash": "656de0b6c82a3416e2ad70ef1234a774d405114b7c03b1fd",
"country": "in",
"merchant_payment_code": "0x012B01-IN-U01",
"order_number": "1234567",
"status": "PE",
"status_date": null,
"open_date": "2024-01-01 01:01:01",
"confirm_date": null,
"transfer_date": null,
"amount_br": "100.00",
"amount_ext": "100.00",
"amount_iof": "0.00",
"currency_rate": "1.0000",
"currency_ext": "INR",
"due_date": "2024-01-01 01:06:01",
"instalments": "1",
"payment_type_code": "upi-qrcode",
"pre_approved": false,
"capture_available": null,
},
"requested_currency" : "INR",
"upi": {
"qr_code_value": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlBMVEX///8AAABVwtN+AAAACXBIWXMAAA7EAAAOxAGVKw4bAAADn0lEQVRogdVZQZKkMAwzxSFHnsBP4GNdDVN8LP2TPIFjDhReSWFmZ097xOTUgLoKJ7IsG3Os/T2s44Yfda6d58F3G1Y7Rtw5LQKgmnX74l56XCa3Wf94DZsfo5lNMQCzf/Zl78tr9OIZgHM4EYONx5i8BgLYcIwrAMnTaTOCUgzBAB22mlFwo7H3Nmz7yx4FIGHeg/uBO+7W1Qms5uHYL0bdDLhSb0MUfalz+gDwRVaXf3PzVoDW4qQLAdY1ku9LsV/rbkBLvaW8mmrpxaEO0jTjxRMA6bNPiqb3vkDnPiL5Ohy4YaRTBABeGXd2g4AY2ZPxj8UP0BxHY+kMAajdDhqDMOvIrYYgQCx2/A8kh+zFAJDGKBEb5AD1gkXt41+MAo+lEBEAkINsb1OJsMSthlxg/8kHFOKnAFpcm6/GqieOdAhza2FOIQB46UmJtzZ1yPZNGfInDmCGIBysu0YvBrvIoFAvWOXOEIDrtVdrSstii6LWK/mM+/4IQEWQ1F4+1OZDjGl6vQnxFAKAl87DqvYBLjdD5QxRLIwCNA8DgMtlj0P/ANNLb956HJN6RAFYozGiqCZ70NGqgw8VYYUANNvCa6zUPAwt7qYH6XwGAFLMemEkDGwZnPmMPETqjSofMQCIgHbxBX1gYw5nTh/GgwHJC88iAuCjKF60iyy1iEJppyjYBEcApIzDR+dVaLzULc5ytIv4gNR7BOBSi5ctRZ07zwKcxuEwTNE+ACAPMDl7r3mCZ289DuKQvWQUAQCyiywPoEyRyoE/bZbEyptDAHDdwcT2RVWM9mBWJi5SZk4PAgDU46zoFqgPiYaGIsbVxPcZADncTgaSnTi8+cyax8nNKAGJAFBJcymvaZRAsfgpzUEAMjnN05IwtcPeL5rTyj+eIQCQqck4hutbx5vpaSFiastpFx8BQJBkiGuaRJJz+9W40ajXIICWXcfIcSIH4ojihMlhvagm9P0AWnGonIaJjGKuplJMO6HiEQLAyuscebHUZnp1BnX9A5cRAOwWnI3YNd9011a7LgtL8xMAWqh6/tuZD5zb0JmnMwSA743T2EoPUTM6c2smx/ix6fvjws0AfQGxa3ZsmtszCk6TTHYxBIBj+bdUq5fxhn88aXFaH5kfBFjAj4XDxNkmpGMnZ87nP18nAwD4sYlFgg+ruomBI5GfGentABKGI6+jfcadkj6Iy/T+ZfXNgCv1UNSQerSLFz3kaMe/+nAr4H/rD82DGsSsJwHxAAAAAElFTkSuQmCC",
"expiration_date": "2024-01-01 09:36:01"
},
"currency_ext_base": "INR"
},
"status": "SUCCESS"
}The Base64 encoded
qr_code_valuewill be used to render the QR Code.UPI Intent
In the upi-intent flow, mobile users select their preferred UPI app or choose the ‘Other UPI app’ option at checkout before proceeding with payment. Upon clicking to pay, they are redirected to their chosen UPI app. The app then loads the pre-filled payment details and prompts the user to enter their UPI PIN for authentication, completing the transaction.
Request
Use the following example to initiate a request.
// ****** UPI Intent ******
curl -X POST \
--location 'https://sandbox.ebanx.com/ws/direct' \
--header 'Content-Type: application/json' \
--data '{
"integration_key": "your_ebanx_integration_key",
"operation": "request",
"payment": {
"name": "John Doe",
"email": "email@example.com",
"phone_number": "7000000000",
"address": "MG Road",
"street_number": "101",
"city": "Bangalore",
"state": "KA",
"zipcode": "560001",
"country": "in",
"payment_type_code": "upi-intent", // Set to 'upi-intent'.
"merchant_payment_code": "0x012B01-IN-U02",
"order_number": "1234567",
"currency_code": "INR",
"amount_total": "100.00"
}
}'Response
A successful request returns a response like the example below.
// ****** UPI Intent ******
{
"payment": {
"hash": "656de0b6c82a3416e2ad70ef1234a774d405114b7c03b1fd",
"country": "in",
"merchant_payment_code": "0x012B01-IN-U02",
"order_number": "1234567",
"status": "PE",
"status_date": null,
"open_date": "2024-01-01 01:01:01",
"confirm_date": null,
"transfer_date": null,
"amount_br": "100.00",
"amount_ext": "100.00",
"amount_iof": "0.00",
"currency_rate": "1.0000",
"currency_ext": "INR",
"due_date": "2024-01-01 01:06:01",
"instalments": "1",
"payment_type_code": "upi-intent",
"pre_approved": false,
"capture_available": null,
},
"requested_currency" : "INR",
"upi": {
"app_links": [
"gpay://upi//pay?pa=pay.merch0000000@bankltd&pn=Merchant&am=1.00&tr=000000000000&mc=0000&mode=00&purpose=00"
"phonepe://upi//pay?pa=pay.merch0000000@bankltd&pn=Merchant&am=1.00&tr=000000000000&mc=0000&mode=00&purpose=00",
"paytm://upi//pay?pa=pay.merch0000000@bankltd&pn=Merchant&am=1.00&tr=000000000000&mc=0000&mode=00&purpose=00"
],
"expiration_date": "2024-01-01 09:36:01"
},
"currency_ext_base": "INR"
},
"status": "SUCCESS"
}App Links (Deep Links)
Deep links are URLs that direct users to a specific app or page within an app, enabling seamless navigation directly to the desired content. The deep link details for launching specific UPI apps are provided within the
app_linksobject.Generic UPI App Link - When creating a URL to initiate a payment with a generic UPI app (instead of a specific one like Google Pay), you need to modify the URL structure:
- Original URL for Google Pay -
"gpay://upi//pay?"– This prefix is specifically for Google Pay. - Modified URL for a Generic UPI App -
"upi:/pay?"– This is a standardized prefix that works with any UPI app.
- Original URL for Google Pay -
By changing the prefix from Google Pay to generic, you ensure compatibility with all UPI apps, allowing users to complete the payment using their preferred app, not just Google Pay. All other URL parameters related to the transaction remain the same.
Redirection behavior
The redirection behavior for the generic URL varies between Android and iOS devices. On Android, users will see a list of compatible apps installed on their device and can select their preferred app. On iOS, users are automatically redirected to a default app.
Monitor payment for status change
At this stage, the payment will appear as pending (PE) in yourEBANX Dashboardchevron_rightAfter completing UPI PIN authentication, your customer will receive a confirmation notification on their UPI app, indicating that the payment was successful.
Notifications
EBANX will send a notification whenever a payment status changes.
Make sure your system is set up to receive notifications from EBANX for any changes in payment status.
Status
After receiving a notification that status has changed, retrieve the payment status.
When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will eventually change to cancelled (CA).
Congratulations!
You have succesfully integrated UPI.
For more information, refer to theDirect API reference guidechevron_right
Resources
Use the following resources when testing in your sandbox environment.
Sample Cards
Click here to view mock card data to validate your payment integration.
API Reference
Click here to access detailed API documentation to integrate efficiently.
Mock Customer Data
Click here to view mock customer data for testing and validating user flows.
Error Codes
Click here to review common error codes to troubleshoot and resolve issues quickly.
Still need help?
We hope this article was helpful. If you still have questions, you can explore the following options:
- Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
- Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.