Skip to main content

Introduction

This document gives an overview of how Payment Gateways can incorporate BharatX powered pay later option as one of their offerings.

note

To test out the flows and for production access, please reach out to BharatX team.

note

All APIs described in this document have simplified request and response structures for brevity. You can find the complete API reference here.

APIs#

There are two types of APIs that are relevant to this integration.

Merchant API#

This API allows Payment Gateways to onboard/enable new merchants to create transactions through BharatX. Onboarding a merchant is a pre-requisite prior to creating transactions. The Merchant API includes:

  • Create/Onboard a Merchant,
  • Disable a Merchant,
  • Create Dashboard Access for Merchant, and more.

Transactional API#

This API allows Payment Gateways to create and manage Transactions and perform/trigger transaction-related workflows. This includes:

  • Create a Transaction,
  • Refund a Transaction,
  • List Transactions,
  • Get Settlement information, and more.

API Authentication#

All our APIs use HTTP Basic Auth as the authentication mechanism. Please note that the credentials for Merchant API and Transactional API differ. While Merchant API credentials are constant for a Payment Gateway, the credentials for Transactional API differs for each merchant onboarded.

Merchant Onboarding#

The prerequisite to creating Transactions is creating Merchants.

Creating a Merchant#

A PG can create a Merchant using the following API

POST https://web-v2.bharatx.tech/api/merchant

Authorization: Basic Auth CredentialsContent-Type: application/json
{  "merchant": {    "id":"brand_00",    "brandName": "My Awesome Brand",    "entityName":"My Awesome Company Pvt Ltd",    "brandHomePageUrl": "https://mywebsite.com",    "mccCode": 5451, // *1    "defaultLogo": {      "type": "base64",      "values": "abcd="    },    "defaultFavicon": {      "type": "base64",      "values": "abcd="    }  }}
  1. Merchant Category Code

A merchant is verified by BharatX before issuing credentials to create Transactions. The status of verification can be inspected using:

GET https://web-v2.bharatx.tech/api/merchant/{id}

Authorization: Basic Auth Credentials

A Merchant creation workflow could be in one of the following stages:

  • documentsPending
  • verificationInProgress
  • enabled
  • disabled

For the verification to happen, PG is required to upload documents using the following API:

POST https://web-v2.bharatx.tech/api/merchant/{id}/document

Authorization: Basic Auth CredentialsContent-Type: application/json 
{  "documentType": "PAN",  "document": {    "type": "base64",    "value": "abcd="  }}

Once all the required documents have been uploaded, the status of the Merchant would move to verificationInProgress and once the automated verification process is complete it would move to enabled stage automatically.

Note: For more details about the documents required and formats, please contact BharatX Team or refer the API reference.

Getting access to Merchant's Transactional API#

Once the Merchant is enabled, you can view the issued API credentials for Transactional API access using:

GET https://web-v2.bharatx.tech/api/merchant/{id}

Authorization: Basic Auth Credentials

Transactions#

Once the Merchant is enabled, the PG can start utilizing the Transactional APIs for the corresponding Merchant.

Note that the following APIs require the credentials fetched as described here for authentication.

Creating a Transaction#

All PGs are recommended to check for pre-eligibility of the user prior to creating a Transaction for most optimum user-experience.

Pre-eligibility of a user for using BharatX's pay later product can be checked using:

POST https://web-v2.bharatx.tech/api/merchant/transaction/pre-eligibility

Authorization: Basic Auth CredentialsContent-Type: application/json
{  "user": {    "name": "Some User",    "phoneNumber": "+919876543210",    "email": "some.email@somewhere.com" // optional  },  "transaction": {    "amount": 1350000 // paise  },  "deviceInformation": {    "userAgent": "abcd /v12.34",    "ipAddress": "10.12.32.33"  }}

If the user is eligible, then user can be presented with the BharatX enabled option at checkout. Once user decides to proceed with BharatX, PG can proceed to create a Transaction:

POST https://web-v2.bharatx.tech/api/merchant/transaction

Authorization: Basic Auth CredentialsContent-Type: application/json 
{  "transaction": {    "id": "order_00_attempt_01",    "amount": 1350000, // paise    "notes": {      "referenceId":"123456",      "billNo":"122234"    }  },  "user": {    "name": "Some User",    "phoneNumber": "+919876543210",    "email": "some.email@somewhere.com" // optional  },  "deviceInformation": {    "userAgent": "abcd /v12.34",    "ipAddress": "10.12.32.33"  },  "preEligibilityCheck": {    "id": "de55930a-c0dd-4a4e-8d98-16ed35d4ac47" // *1  },  "createConfiguration": { // optional    "webhookUrl": "https://myapp.myweb.com/webhooks/bharatx/order_00_attempt_01", // *2    "expiryTimestamp": 1662746115  }}
  1. By providing preEligibilityCheck.id, BharatX will reuse the precomputed check to move ahead with the transaction quickly. If this is not included, checks are performed again. If this value is provided, but the transaction information does not match with the ones provided during preEligibilityCheck, the transaction is FAILED. It is recommended to include preEligibilityCheck.id if a check was performed for ideal user experience. Multiple transactions can be created using the same preEligibilityCheck.id (to represent multiple attempts) but only one of them will be allowed to succeed, the remaining transactions will fail automatically once one of them succeeds.
  2. A default webhook can be configured while creating a Merchant. The value (if provided) createConfiguration.webhookUrl will override the default webhook URL configured.

Once a transaction has been created, the status of the transaction can be either polled for using the following API, or changes can be subscribed to using Webhooks.

A Transaction can be fetched by using:

GET https://web-v2.bharatx.tech/api/merchant/transaction/{id}

Authorization: Basic Auth Credentials

The response of the GET API is identical to the payload posted via webhooks.

A Transaction, to complete, requires authentication and a down payment. The current stage of the Transaction can be fetched using:

GET https://web-v2.bharatx.tech/api/merchant/transaction/{id}?include=stage

Accept: application/jsonAuthorization: Basic Auth Credentials
  1. The nextStep.step could be authenticate, wait, payment, success or failure.
  2. options is filled based on what step the Transaction is at (nextStep.step)

If step = authenticate, the options will contain:

{  "transaction": {    ...  },  "transactionStage": {    "nextStep": {      ...      "options": {        "userInputOptions": [          {            "inputType": "otp",            "referenceId": "2e63b988-c302-4a46-9369-6829adf92b86",            "label": "OTP",            "description": "Enter OTP",            "length": 6,            "type": "numeric" // *1          }        ]      }    }  }}
  1. type could be numeric or alphanumeric.

After the user inputs the OTP, it can passed along to BharatX using:

POST https://web-v2.bharatx.tech/api/merchant/transaction/{transactionId}/user-inputs/{referenceId}

Authorization: Basic Auth CredentialsContent-Type: application/json
{  "value": "123456"}

Once the OTP is verified, nextStep.step would move to payment, and options would contain:

{  "transaction": {    ...  },  "transactionStage": {    "nextStep": {      ...      "options": {        "paymentOptions": {          "amount": 450000,          "shouldEnforceAutopay": false        }      }    }  }}

After collecting the down payment you can post the payment information through this API:

POST https://web-v2.bharatx.tech/api/merchant/transaction/{transactionId}/payment/register-external

Authorization: Basic Auth CredentialsContent-Type: application/json
{  "metaData": {    ... // *1  }}
  1. The metaData schema depends on the PG's mode of collection. This can be confirmed during onboarding.

You can confirm the status of the Transaction through polling or webhooks.

Refunding a Transaction#

The PG can issue a refund for a transaction using the following API. Multiple refunds of partial amounts can be issued against a Transaction.

POST https://web-v2.bharatx.tech/api/merchant/transaction/{transactionId}/refund

Authorization: Basic Auth CredentialsContent-Type: application/json
{  "refund": {    "amount": 1000000 // paise  // *1  },  "createConfiguration": {    "webhookUrl": "https://webhook.url/transaction/order_00_attempt_01/refund" // *2  }}
  1. The refund.amount represents the amount that the merchant intends to refund from the original transaction amount. Payouts to the customer is calculated based on what they have paid already and processed by BharatX. This is an optional field, if not provided or set to 0, whole transaction is assumed to be refunded. The refund fails, if this amount is greater than the remaining unrefunded amount.
  2. Refund workflows have independant webhook subscriptions.