Skip to main content

API Specification

Merchant Onboarding APIs#

note

All the APIs mentioned below use HTTP Basic Auth for authentication. Credentials can be obtained directly by contacting our sales.

Create a merchant#

POST https://web-v2.bharatx.tech/api/merchant
Headers:Authorization: Basic dGVzdFBhcnRuZXJJZDp0ZXN0UHJpdmF0ZUtleQ==Content-Type: application/json
Body:{  "merchant": {    "brandName": "BharatX",    "entityName": "AuroraX Pvt Limited",    "defaultLogo": "https://bharatx.tech/logo.png",    "defaultFavicon": "https://bharatx.tech/favicon.ico",    "defaultColor": "#000000",    "settlementDetails": {      "accountNumber": "121132323",      "ifscCode": "ICIC0000001",      "beneficiaryName": "Payment Gateway",      "mdrChargedOnMerchant": 10    }  }}
  • merchant.brandName, merchant.defaultLogo, merchant.defaultFavicon and merchant.defaultColor are parameters required for white labelling and hence are user-facing params.
  • merchant.entityName: Legal name for the merchant
  • merchant.settlementDetails: The settlement account details for transactions done for this merchant.
  • merchant.settlementDetails.mdrChargedOnMerchant: The mdr amount to be charged to the merchant.
  • merchant.basicAuthDetails: Authentication details to consume Transactional APIs.
note

When a merchant is created using this API, they are granted LIVE access for 24h only. KYC documents for the merchant needs to be shared with BharatX for continued usage.

mdrChargedOnMerchant should refer to the total MDR charged to the merchant. The amount that BharatX will settle to the account described by settlementDetails will be equal to order value - mdr on merchant + pg's revenue share on the transaction.

Get A Merchant#

GET https://web-v2.bharatx.tech/api/merchant/{merchantId}
Headers:Authorization: Basic dGVzdFBhcnRuZXJJZDp0ZXN0UHJpdmF0ZUtleQ==

merchantId is merchant.id from Create a merchant API.

Upload KYC Data For Merchant#

POST https://web-v2.bharatx.tech/api/merchant/{merchantId}/kyc
Headers:Authorization: Basic dGVzdFBhcnRuZXJJZDp0ZXN0UHJpdmF0ZUtleQ==Content-Type: application/json
Body:{  "merchantKycData": [    {      "document": "cancelled_cheque",      "type": "base64",      "value": "CmBgYGh0dHAKUE9TVCBodHRwczovL3dlYi12Mi5iaGFyYXR4LnRlY2gvYXBpL21lcmNoYW50L3ttZXJjaGFudElkfS9reWMKCkhlYWRlcnM6CkF1dGhvcml6YXRpb246IEJhc2ljIGRHVnpkRkJoY25SdVpYSkpaRHAwWlhOMFVISnBkbUYwWlV0bGVRPT0KQ29udGVudC1UeXBlOiBhcHBsaWNhdGlvbi9qc29u"    },    {      "document": "pan_card",      "type": "url",      "value": "https://bucket.s3.amazon.com/pan.pdf"    }  ]}

  • merchantKycData[].document: the kind of document being uploaded

  • merchantKycData[].type: the way the document is being uploaded. Can be url or base64.

  • merchantKycData[].value: If type is url then the url from which the document needs to be fetched. If type is base64 then the base64 encoded format of the file.

  • receivedDocuments is the list of all documents uploaded for the merchant so far

note

This API can be called multiple times to upload documents as they are collected. Once all required documents are uploaded and verified the 24h limit on the merchant credentials is removed.

Transactional APIs#

note

All the APIs mentioned below use HTTP Basic Auth for authentication. Credentials can be obtained from either the Create Merchant API or Get Merchant API.

You can use testPartnerId as your username and testPrivateKey as your password for basic authentication to test out the APIs.

warning

Never share your API Keys with anyone. Anyone with the API Key will be able to create transactions on your behalf.

Create New Transaction#

This sample request represents the minimum parameters required to make a successful request.

POST https://web-v2.bharatx.tech/api/merchant/transaction
Headers:Authorization: Basic dGVzdFBhcnRuZXJJZDp0ZXN0UHJpdmF0ZUtleQ==Content-Type: application/json
Body:{  "transaction": {    "id": "de7b1bca-4374-4ec6-a52d-b095404593cd",    "amount": 12000  },  "user": {    "name": "Shyam Murugan",    "phoneNumber": "+919912991233"  },  "createConfiguration": {    "successRedirectUrl": "https://bharatx.tech/success/de7b1bca-4374-4ec6-a52d-b095404593cd",    "failureRedirectUrl": "https://bharatx.tech/failure/de7b1bca-4374-4ec6-a52d-b095404593cd",    "webhookUrl": "https://bharatx.tech/api/transaction/de7b1bca-4374-4ec6-a52d-b095404593cd/webhook",  }}

Parameters

  • [ required ] transaction.id: Transaction ID generated by the payment gateway for the current attempt.
  • [ required ] transaction.amount: The total order amount of the transaction in paise
  • [ required ] transaction.notes: Meta data about the order
  • [ optional ] transaction.notes.merchantData: Additional params passed by the merchant to the PG
  • [ requried ] transaction.notes.merchantOrderId: The order ID for supplied by the merchant
  • [ read-only ] transaction.status: Status of the transaction - can be "SUCCESS"/"PENDING"/"FAILURE"/"CANCELLED"
  • [ read-only ] transaction.uri: The uri where the PG needs to redirect the customer to complete the transaction.
  • [ optional ] createConfiguration: Configuration values that overrides the defaults set while onboarding of the merchant
  • [ optional ] createConfiguration.successRedirectUrl: The URL to redirect the customer after the payment is successful
  • [ optional ] createConfiguration.webhookUrl: The URL to post updates when the transaction status updates
  • [ optional ] createConfiguration.failureRedirectUrl: The URL to redirect the customer if the payment fails or the customer cancels the transacion.
  • [ optional ] createConfiguration.logoOverride: The URL of the logo of the merchant for branding
  • [ optional ] createConfiguration.colorOverride: The hex for the primary color according to merchant's branding requirements
  • [ optional ] createConfiguration.cartPageEnabled: Should be false.
  • [ required ] user: The transacting user's details
  • [ required ] user.name: Full name of the user
  • [ required ] user.phoneNumber: The phone number of the user in the given format
  • [ optional ] user.email: Email address of the user
  • [ optional ] orderDetails: The order details as passed by the merchant to the PG. The PG can pass along whatever data they have from the merchant.

Get a transaction#

GET https://web-v2.bharatx.tech/api/merchant/transaction/{transactionId}
Headers:Authorization: Basic dGVzdFBhcnRuZXJJZDp0ZXN0UHJpdmF0ZUtleQ==

Get Preapproved Check Status#

GET https://web-v2.bharatx.tech/api/merchant/transaction/{transactionId}?include=pre-approval-status
Headers:Authorization: Basic dGVzdFBhcnRuZXJJZDp0ZXN0UHJpdmF0ZUtleQ==

Create a refund for a transaction#

POST https://web-v2.bharatx.tech/api/merchant/transaction/{transactionId}/refund
Headers:Authorization: Basic dGVzdFBhcnRuZXJJZDp0ZXN0UHJpdmF0ZUtleQ==Content-Type: application/json
{  "refund": {    "amount": 1000  },  "createConfiguration": {    "webhookUri": "https://bharatx.tech/api/transaction/de7b1bca-4374-4ec6-a52d-b095404593cd/refund/webhook"  }}
  • refund.id: ID for the refund
  • refund.status: Status of the refund - can be "SUCCESS"/"PENDING"
  • refund.amount: The amount to be refunded in paise. If the amount exceeds the non refunded amount for the transaction, the API fails and the refund is not created.
  • createConfiguration.webhookUri: The url for subscribing to refund event updates.

Get a refund#

GET https://web-v2.bharatx.tech/api/merchant/transaction/{transactionId}/refund/{refundId}
Headers:Authorization: Basic dGVzdFBhcnRuZXJJZDp0ZXN0UHJpdmF0ZUtleQ==

refundId is the refund.id obtained from Create a refund API.