Version: current

UPI with Direct API

About this guide

This page explains how to add UPI to your existing Direct API integration. Direct API integration is basically the same for all payment methods, only varying the payment_type_code and some additional required fields.

Availability:

UPI integration for merchants offering digital products & services through Direct API is available to the following countries:

  • India

If you are not integrated with EBANX Direct API yet, please take a look in this basic guide about it. Are you not sure if EBANX Direct API is the best option for your e-commerce? Please, talk with one of our integration specialists.

What you will need

Before starting your integration, please make sure that you have:

  1. An EBANX Sandbox account. That's not the case? Please sign up for an Sandbox Account here;
  2. UPI enabled in your EBANX Dashboard.

How it works

To complete UPI integration through EBANX Direct API, please follow the steps below.

  1. Enable UPI

    UPI availability may vary depending on your contract. So the first step is to check if it is active in your EBANX dashboard.

    All set? We can go ahead to the next step, otherwise, please get in touch with our integration specialists.

  2. Configure your Notification URL

    For your UPI transactions, once the payment is confirmed you will receive a notification changing the status from pending to confirmed. Check the instructions for configuring your URL on Notifications

    Basic parameters:

    ParameterDescription
    operationOperation must be request
    integration_keyYour unique and secret integration key
    payment_type_codeFor UPI in India the types are upi-qrcode and upi-intent
    countryTwo-letter country code - in for India

    Customer data:

    ParameterDescription
    namePayer full name
    emailCustomer email
    phone_numberCustomer phone number, in full international format
    info

    A match validation will be performed to the value informed on the name parameter and the UPI ID account holder name.

    Charge parameters:

    ParameterDescription
    merchant_payment_codeUnique merchant payment code
    currency_codeISO-4217 Currency code transaction. Supported value: INR
    amount_totalTotal amount to be charged

    Check the examples:

    UPI QR Code:

    For the UPI QR flow, users will scan a QR code to be redirected to their UPI app and complete the transaction. Succeeding the redirection, the UPI app will load the pre-populated payment details and request user's UPI PIN authentication to complete the transaction.

    curl -L -X POST 'https://sandbox.ebanxpay.com/ws/direct' \
    -H 'Content-Type: application/json' \
    --data-raw '{
    "integration_key": "{{integration_key}}",
    "operation": "request",
    "payment": {
    "name": "John Doe",
    "email": "email@example.com",
    "phone_number": "7000000000",
    "country": "in",
    "payment_type_code": "upi-qrcode",
    "merchant_payment_code": "0x012B01-IN-U01",
    "order_number": "1234567",
    "currency_code": "INR",
    "amount_total": "100.00"
    }
    }'

    A successful request will return a JSON response like the one below.

    "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 information returned in the ws/direct response on qr_code_value object will be used to render the QR Code.

    UPI Intent:

    For the UPI Intent flow, users on mobile devices will pre-select their preferred UPI app, or a generic option for 'Other UPI app' displayed on checkout, and click to pay, to be redirected and complete the transaction. Succeeding the redirection, the UPI app will load the pre-populated payment details and request user's UPI PIN authentication to complete the transaction.

    curl -L -X POST 'https://sandbox.ebanxpay.com/ws/direct' \
    -H 'Content-Type: application/json' \
    --data-raw '{
    "integration_key": "{{integration_key}}",
    "operation": "request",
    "payment": {
    "name": "John Doe",
    "email": "email@example.com",
    "phone_number": "7000000000",
    "country": "in",
    "payment_type_code": "upi-intent",
    "merchant_payment_code": "0x012B01-IN-U02",
    "order_number": "1234567",
    "currency_code": "INR",
    "amount_total": "100.00"
    }
    }'

    A successful request will return a JSON response like the one below.

    {
    "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"
    }

    The deep link information to launch the specific UPI apps will be returned in the ws/direct response on app_links object. For the generic call, to be linked to the 'Other UPI app' option, the prefix "gpay://upi//pay?" information in the url should be replaced for "upi:/pay?" with all other parameters remaining unchanged.

    info

    The redirection behavior when invoking the generic url will be different on Android and iOS devices. Android will display the compatible apps on the user device for their selection. On iOS devices, users will be defaultly redirected to an app.

    info

    The complete API reference for the end-point ws/direct can be found here. We strongly recommend you to take a look in all the available options.

    At this point you have a pending (PE) payment in your EBANX Dashboard.

  3. Wait for the payment

    Shortly after completing the UPI PIN authentication your customer will receive a notification on their UPI App confirming that payment was successful.

    As soon as EBANX identifies that the payment was confirmed, payment status is modified from pending to confirmed.

    If your customers don't conclude the payment, it will be automatically canceled.

Getting help

We hope this article was enlightening, but in case we’ve failed to take out your doubts you have the following options to keep on seeking for answers:

  • If you’re not our partner yet and would like to know more about our prices and conditions please fill ou this form and our comercial team will get in touch with you.
  • In case you’re already our partner please get in touch with our support team at integration@ebanx.com.
Edit this page
Last updated on by José Cristiano de Sousa
On this page