Developers

API Documentation

Reference for the Payout, Payment, Beneficiary, Transaction Status and Webhook APIs. All examples on this page use sample/demo data and are not live endpoints.

Getting Started

Create a business account, generate an API key from your dashboard, and start making requests against the sandbox environment. All base URLs shown on this page (api.example.com) are placeholders for illustration.

Authentication

Every request must include your API key as a bearer token. Keys are generated and managed from your dashboard and should never be exposed in frontend code.

header

Authorization: Bearer YOUR_API_KEY

Sandbox

Sandbox API keys let you integrate and test end-to-end flows without moving real funds. Sandbox and production environments use separate credentials and are fully isolated from each other.

POST/api/v1/payouts

Create a Payout

Initiates a payout to a previously added beneficiary. Returns immediately with a transaction ID; final status arrives via webhook or the transaction status endpoint.

Field	Type	Required	Description
amount	integer	Required	Amount in paise (INR)
beneficiaryId	string	Required	ID of a verified beneficiary
reference	string	Required	Your unique reference for this payout
purpose	string	Optional	Purpose code, e.g. vendor_payment, salary, refund

Request — sample data

curl -X POST https://api.example.com/api/v1/payouts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "beneficiaryId": "demo-beneficiary",
    "reference": "demo-reference",
    "purpose": "vendor_payment"
  }'

Request body — sample data

request.json

{
  "amount": 50000,
  "beneficiaryId": "demo-beneficiary",
  "reference": "demo-reference",
  "purpose": "vendor_payment"
}

Response — sample data

response.json

{
  "transactionId": "demo-transaction-id",
  "status": "PROCESSING",
  "amount": 50000,
  "beneficiaryId": "demo-beneficiary",
  "reference": "demo-reference",
  "createdAt": "2026-01-01T10:00:00Z"
}

Error codes

400 invalid_request
One or more request fields failed validation
401 unauthorized
Missing or invalid API key
404 beneficiary_not_found
The beneficiaryId does not exist or is not verified
409 duplicate_reference
A payout with this reference already exists
429 rate_limited
Too many requests — retry with backoff

POST/api/v1/payments

Create a Payment Collection Order

Creates a payment collection order that your customer can pay through a hosted checkout link or your own integrated flow.

Field	Type	Required	Description
amount	integer	Required	Amount in paise (INR)
reference	string	Required	Your unique reference for this order
customerEmail	string	Optional	Customer email for the receipt
methods	string[]	Optional	Allowed payment methods, e.g. upi, card, netbanking

Request — sample data

curl -X POST https://api.example.com/api/v1/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "reference": "demo-order-reference",
    "customerEmail": "demo@example.com",
    "methods": ["upi", "card", "netbanking"]
  }'

Request body — sample data

request.json

{
  "amount": 250000,
  "reference": "demo-order-reference",
  "customerEmail": "demo@example.com",
  "methods": ["upi", "card", "netbanking"]
}

Response — sample data

response.json

{
  "orderId": "demo-order-id",
  "status": "PENDING",
  "amount": 250000,
  "checkoutUrl": "https://pay.example.com/checkout/demo-order-id",
  "reference": "demo-order-reference"
}

Error codes

400 invalid_request
One or more request fields failed validation
401 unauthorized
Missing or invalid API key
409 duplicate_reference
An order with this reference already exists
429 rate_limited
Too many requests — retry with backoff

POST/api/v1/beneficiaries

Add a Beneficiary

Registers a beneficiary (employee, vendor or partner) so payouts can be initiated against them. Beneficiaries go through verification before they can receive funds.

Field	Type	Required	Description
name	string	Required	Beneficiary's registered name
accountNumber	string	Required	Bank account number
ifsc	string	Required	Bank branch IFSC code
reference	string	Optional	Your internal reference for this beneficiary

Request — sample data

curl -X POST https://api.example.com/api/v1/beneficiaries \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Demo Vendor Pvt Ltd",
    "accountNumber": "000000000000",
    "ifsc": "DEMO0000000",
    "reference": "demo-vendor-001"
  }'

Request body — sample data

request.json

{
  "name": "Demo Vendor Pvt Ltd",
  "accountNumber": "000000000000",
  "ifsc": "DEMO0000000",
  "reference": "demo-vendor-001"
}

Response — sample data

response.json

{
  "beneficiaryId": "demo-beneficiary",
  "status": "VERIFICATION_PENDING",
  "name": "Demo Vendor Pvt Ltd",
  "createdAt": "2026-01-01T10:00:00Z"
}

Error codes

400 invalid_request
Account number or IFSC failed format validation
401 unauthorized
Missing or invalid API key
422 verification_failed
Beneficiary details could not be verified

GET/api/v1/transactions/{transactionId}

Get Transaction Status

Retrieves the current status and details of a payout or payment transaction. Use this to poll for status if you are not consuming webhooks.

Request — sample data

curl https://api.example.com/api/v1/transactions/demo-transaction-id \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — sample data

response.json

{
  "transactionId": "demo-transaction-id",
  "type": "PAYOUT",
  "status": "SUCCESS",
  "amount": 50000,
  "reference": "demo-reference",
  "beneficiaryId": "demo-beneficiary",
  "paymentMethod": "IMPS",
  "failureReason": null,
  "createdAt": "2026-01-01T10:00:00Z",
  "updatedAt": "2026-01-01T10:00:42Z"
}

Error codes

401 unauthorized
Missing or invalid API key
404 transaction_not_found
No transaction exists with the given ID

POSTYour webhook URL

Webhook Event: Transaction Status Updated

When a payout or payment transaction changes status, a signed event is sent to the webhook URL configured in your dashboard. Verify the signature before trusting the payload.

Request — sample data

# Example signature verification (conceptual)
echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET"

Response — sample data

response.json

{
  "event": "transaction.status.updated",
  "transactionId": "demo-transaction-id",
  "status": "SUCCESS",
  "amount": 50000,
  "reference": "demo-reference",
  "timestamp": "2026-01-01T10:00:42Z"
}

Error codes

signature_mismatch
Computed signature did not match the X-Signature header — reject the event
retry_exhausted
Your endpoint did not return 2xx after repeated retries

Salary API

Create and manage salary batches programmatically — add employees, validate accounts, submit for approval and track processing status.