Connected Banking Payout API
Connect a supported bank account, submit a beneficiary payout, and check its latest status using your merchant API credentials.
How it works
Complete the steps in order. The bank connection ID returned by the connect request is required to send a payout. Save the transaction ID returned by the payout request to check its status later.
| Step | Action | What you need next |
|---|---|---|
| 1 | Connect your bank using the bank's API credentials. | Save data.connection_id. |
| 2 | Send a payout to the beneficiary using a connected bank. | Save data.transaction_id. |
| 3 | Poll the payout status endpoint using that transaction ID. | Stop polling when the status is final. |
Base URL and authentication
The API base URL below is generated from the host and scheme serving this documentation.
| Header | Required | Description |
|---|---|---|
X-API-KEY | Yes | Your active merchant API key. |
Authorization | Yes | Your merchant API secret. Alternatively, send it as X-API-SECRET. |
Content-Type | For POST | Set to application/json. |
Accept | Recommended | Set to application/json to receive JSON validation errors. |
1. Connect a bank
Send all bank credentials and account setup details provided to your business. Every field listed below is required. The connection belongs to the authenticated merchant.
JSON body fields
| Field | Type | Required | Description |
|---|---|---|---|
bank_code | string | Yes | Supported code: IDFC, KOTAK, or AXIS. |
bank_name | string | Yes | Display name of the bank. |
nickname | string | Yes | Name to help identify this connection; maximum 100 characters. |
environment | string | Yes | SANDBOX or PROD. |
client_id | string | Yes | Bank-issued client ID. |
kid | string | Yes | Bank-issued key ID. |
base_url | string | Yes | Bank API base URL for this environment. |
private_key | string | Yes | Private key in PEM format, including its BEGIN/END lines. |
audience | string | Yes | Bank token audience supplied for your environment. |
token_url | URL | Yes | Bank token endpoint for your environment. |
aes_key | string | Yes | Bank-provided AES key in 32, 48, or 64 hexadecimal characters. |
debit_account | string | Yes | Account number payouts are debited from. |
teller_branch | string | Yes | Bank-provided teller branch identifier. |
teller_id | string | Yes | Bank-provided teller identifier. |
cURL example
curl --request POST 'https://staging.login.tpipay.ai/api/v1/bank-connections/connect' \
--header 'X-API-KEY: your-merchant-api-key' \
--header 'Authorization: your-merchant-api-secret' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"bank_code": "IDFC",
"bank_name": "IDFC First Bank",
"nickname": "Primary payout account",
"environment": "SANDBOX",
"client_id": "demo-client-123",
"kid": "demo-key-001",
"audience": "https://sandbox.example-bank.test",
"token_url": "https://sandbox.example-bank.test/oauth/token",
"base_url": "https://sandbox.example-bank.test",
"aes_key": "replace-with-bank-provided-key",
"debit_account": "123456789012",
"teller_branch": "BR001",
"teller_id": "TELLER001",
"private_key": "-----BEGIN PRIVATE KEY-----\nREPLACE_WITH_YOUR_TEST_PRIVATE_KEY\n-----END PRIVATE KEY-----"
}'
{
"success": true,
"message": "IDFC First Bank connected successfully",
"data": {
"connection_id": 12,
"connection_ref": "IDFC_CONN_1791782730",
"bank_code": "IDFC",
"bank_name": "IDFC First Bank",
"status": "CONNECTED",
"environment": "SANDBOX",
"connected_at": "2026-10-12T10:00:00.000000Z",
"meta": {
"handshake_status": "VERIFIED",
"account_verified": true,
"token_generated": true,
"environment": "SANDBOX"
}
}
}
2. Send a payout
Use a connected bank's connection_id and provide beneficiary details. The amount is in INR; charges and GST are calculated by the service. A successful API response means the payout request was accepted, not necessarily completed.
| Field | Type | Required | Description |
|---|---|---|---|
bank_connection_id | integer | Yes | Connected bank's ID returned by the connect endpoint; it must belong to your merchant account. |
beneficiary_name | string | Yes | Beneficiary's name; maximum 150 characters. |
beneficiary_account | string | Yes | Beneficiary bank account number; maximum 50 characters. |
beneficiary_ifsc | string | Yes | Beneficiary IFSC; maximum 20 characters. |
amount | number | Yes | Payout amount in INR; minimum 1. |
beneficiary_bank | string | No | Beneficiary bank name. |
mode | string | No | IMPS, NEFT, RTGS, or UPI; defaults to IMPS. |
narration | string | No | Payment note; maximum 255 characters. |
cURL example
curl --request POST 'https://staging.login.tpipay.ai/api/v1/payouts/send' \
--header 'X-API-KEY: your-merchant-api-key' \
--header 'Authorization: your-merchant-api-secret' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"bank_connection_id": 12,
"beneficiary_name": "Aarav Sharma",
"beneficiary_account": "987654321012",
"beneficiary_ifsc": "HDFC0001234",
"beneficiary_bank": "HDFC Bank",
"amount": 1250.00,
"mode": "IMPS",
"narration": "Invoice INV-1001"
}'
{
"success": true,
"message": "Payout initiated successfully",
"data": {
"transaction_id": "TXN1791782730694",
"status": "PENDING",
"amount": "1250.00",
"charges": "6.25",
"gst": "1.13",
"net_amount": "1257.38",
"bank_ref_no": "IDFC1791782730",
"initiated_at": "2026-10-12T10:05:00.000000Z"
}
}
data.transaction_id from the real response. The transaction ID above is only an example.3. Check payout status
Call this endpoint with the transaction ID returned by Send a payout. The status is scoped to your merchant credentials and may remain PENDING until the bank confirms the transfer.
cURL example
curl --request GET 'https://staging.login.tpipay.ai/api/v1/payouts/TXN1791782730694/status' \ --header 'X-API-KEY: your-merchant-api-key' \ --header 'Authorization: your-merchant-api-secret' \ --header 'Accept: application/json'
{
"success": true,
"data": {
"transaction_id": "TXN1791782730694",
"status": "SUCCESS",
"utr": "UTR1791782760",
"amount": "1250.00",
"completed_at": "2026-10-12T10:06:00.000000Z"
}
}
Possible payout statuses are PENDING, PROCESSING, SUCCESS, FAILED, and REVERSED. Use the latest status returned by the API as the source of truth.
Errors and statuses
Check both the HTTP status code and the JSON response when a request fails.
| HTTP status | Meaning | What to check |
|---|---|---|
| 401 | Missing or invalid merchant credentials. | Verify the active API key and matching API secret. |
| 400 | The bank payout service rejected the request. | Read the returned message and error_code. |
| 404 | Connection or transaction was not found for this merchant. | Use the saved ID from your own successful API response. |
| 422 | Request validation failed. | Check required fields, allowed values, and field limits. |
{
"message": "The amount field must be at least 1.",
"errors": {
"amount": ["The amount field must be at least 1."]
}
}
