TPI Pay
Payout integration

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.

StepActionWhat you need next
1Connect your bank using the bank's API credentials.Save data.connection_id.
2Send a payout to the beneficiary using a connected bank.Save data.transaction_id.
3Poll the payout status endpoint using that transaction ID.Stop polling when the status is final.
Keep your API secret, bank private key, and other bank credentials on your server. Never expose them in browser-side code or public repositories.

Base URL and authentication

The API base URL below is generated from the host and scheme serving this documentation.

Base URL: https://staging.login.tpipay.ai/api/v1
HeaderRequiredDescription
X-API-KEYYesYour active merchant API key.
AuthorizationYesYour merchant API secret. Alternatively, send it as X-API-SECRET.
Content-TypeFor POSTSet to application/json.
AcceptRecommendedSet 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.

POST https://staging.login.tpipay.ai/api/v1/bank-connections/connect

JSON body fields

FieldTypeRequiredDescription
bank_codestringYesSupported code: IDFC, KOTAK, or AXIS.
bank_namestringYesDisplay name of the bank.
nicknamestringYesName to help identify this connection; maximum 100 characters.
environmentstringYesSANDBOX or PROD.
client_idstringYesBank-issued client ID.
kidstringYesBank-issued key ID.
base_urlstringYesBank API base URL for this environment.
private_keystringYesPrivate key in PEM format, including its BEGIN/END lines.
audiencestringYesBank token audience supplied for your environment.
token_urlURLYesBank token endpoint for your environment.
aes_keystringYesBank-provided AES key in 32, 48, or 64 hexadecimal characters.
debit_accountstringYesAccount number payouts are debited from.
teller_branchstringYesBank-provided teller branch identifier.
teller_idstringYesBank-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-----"
  }'
Example success response
{
  "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.

POST https://staging.login.tpipay.ai/api/v1/payouts/send
FieldTypeRequiredDescription
bank_connection_idintegerYesConnected bank's ID returned by the connect endpoint; it must belong to your merchant account.
beneficiary_namestringYesBeneficiary's name; maximum 150 characters.
beneficiary_accountstringYesBeneficiary bank account number; maximum 50 characters.
beneficiary_ifscstringYesBeneficiary IFSC; maximum 20 characters.
amountnumberYesPayout amount in INR; minimum 1.
beneficiary_bankstringNoBeneficiary bank name.
modestringNoIMPS, NEFT, RTGS, or UPI; defaults to IMPS.
narrationstringNoPayment 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"
  }'
Example success response
{
  "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"
  }
}
Persist 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.

GET https://staging.login.tpipay.ai/api/v1/payouts/{transaction_id}/status

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'
Example success response
{
  "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 statusMeaningWhat to check
401Missing or invalid merchant credentials.Verify the active API key and matching API secret.
400The bank payout service rejected the request.Read the returned message and error_code.
404Connection or transaction was not found for this merchant.Use the saved ID from your own successful API response.
422Request 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."]
  }
}