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.
#
APIsThere are two types of APIs that are relevant to this integration.
#
Merchant APIThis 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 APIThis 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 AuthenticationAll 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 OnboardingThe prerequisite to creating Transactions is creating Merchants.
#
Creating a MerchantA PG can create a Merchant using the following API
- Request
- Success Response
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=" } }}
Content-Type: application/json
{ "merchant": { "id":"brand_00", "status": "documents_pending" }}
- Merchant Category Code
A merchant is verified by BharatX before issuing credentials to create Transactions. The status of verification can be inspected using:
- Request
- Success Response
GET https://web-v2.bharatx.tech/api/merchant/{id}
Authorization: Basic Auth Credentials
Content-Type: application/json
{ "merchant": { "id":"brand_00", "status": "documentsPending" }}
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:
- Request
- Success Response
POST https://web-v2.bharatx.tech/api/merchant/{id}/document
Authorization: Basic Auth CredentialsContent-Type: application/json
{ "documentType": "PAN", "document": { "type": "base64", "value": "abcd=" }}
Content-Type: application/json
{ "document": { "id": "8ee9329e-871c-4e7b-83cb-014415d8d8da", "status": "verificationInProgress" }}
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 APIOnce the Merchant is enabled
, you can view the issued API credentials for Transactional API access using:
- Request
- Success Response
GET https://web-v2.bharatx.tech/api/merchant/{id}
Authorization: Basic Auth Credentials
Content-Type: application/json
{ "merchant": { "id":"brand_00", "status": "enabled", "basicAuthCredentials": { "username": "abcd_brand_00", "password": "aaa4358d-1789-40bd-a029-d409c18f74b0" } }}
#
TransactionsOnce 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 TransactionAll 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:
- Request
- Success Response
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" }}
Content-Type: application/json
{ "preEligibilityCheck": { "id":"de55930a-c0dd-4a4e-8d98-16ed35d4ac47", "isApproved": true }}
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:
- Request
- Success Response
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 }}
Content-Type: application/json
{ "transaction": { "id": "order_00_attempt_01", "status": "PENDING", ... }}
- 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 isFAILED
. It is recommended to includepreEligibilityCheck.id
if a check was performed for ideal user experience. Multiple transactions can be created using the samepreEligibilityCheck.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.- 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:
- Request
- Success Response
GET https://web-v2.bharatx.tech/api/merchant/transaction/{id}
Authorization: Basic Auth Credentials
Content-Type: application/json
{ "transaction": { "id": "order_00_attempt_01", "status": "PENDING", ... }}
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:
- Request
- Success Response
GET https://web-v2.bharatx.tech/api/merchant/transaction/{id}?include=stage
Accept: application/jsonAuthorization: Basic Auth Credentials
Content-Type: application/json
{ "transaction": { "id":"order_00_attempt_01", "status": "PENDING", ... }, "transactionStage": { "nextStep": { "step":"authenticate", // *1 "options": { ... // *2 } } }}
- The
nextStep.step
could beauthenticate
,wait
,payment
,success
orfailure
.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 } ] } } }}
type
could benumeric
oralphanumeric
.
After the user inputs the OTP, it can passed along to BharatX using:
- Request
- Success Response
POST https://web-v2.bharatx.tech/api/merchant/transaction/{transactionId}/user-inputs/{referenceId}
Authorization: Basic Auth CredentialsContent-Type: application/json
{ "value": "123456"}
Content-Type: application/json
{ "isFieldAccepted": true, "errorMessage": null}
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:
- Request
- Success Response
POST https://web-v2.bharatx.tech/api/merchant/transaction/{transactionId}/payment/register-external
Authorization: Basic Auth CredentialsContent-Type: application/json
{ "metaData": { ... // *1 }}
Content-Type: application/json
{ "referenceId": "101a2803-864e-4f92-8e7d-c0f8be53b9ef"}
- 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 TransactionThe PG can issue a refund for a transaction using the following API. Multiple refunds of partial amounts can be issued against a Transaction.
- Request
- Success Response
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 }}
Content-Type: application/json
{ "refund": { "id": 1234, "amount": 1000000, "status": "PENDING", "createTimestamp": 0 }}
- 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.- Refund workflows have independant webhook subscriptions.