Add Bank Account

curl --request POST \
  --url https://sandbox.zapyd.com/cms/api/v1/bank/create \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-SIGNATURE: <api-key>' \
  --header 'X-TIMESTAMP: <api-key>' \
  --data '
{
  "customer_id": "c2cf861b-342b-4318-a90e-85cd0312e82f",
  "bank_account_type": "ACCOUNT_DETAILS",
  "identifiers": {
    "account_number": "7627389201",
    "ifsc": "SBIN0001829"
  }
}
'

{
  "status": true,
  "message": "Success",
  "data": {
    "id": "4e6f1b20-a73c-11ec-b909-0242ac120002",
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "country": "IND",
    "bank_account_type": "ACCOUNT_DETAILS",
    "identifiers": {
      "account_number": "7627389201",
      "ifsc": "SBIN0001829"
    },
    "bank_account_status": "VERIFIED",
    "beneficiary_name": "JOHN DOE",
    "bank_name": "State Bank of India",
    "failure_reason": null
  }
}

{
  "status": false,
  "message": "Bad Request",
  "err_code": "REQ_FIELD_MISSING",
  "errors": {
    "identifiers": [
      "This field is required."
    ]
  },
  "data": null
}

{
  "status": false,
  "message": "Internal Server Error",
  "data": null,
  "err_code": "SYS_INTERNAL_ERROR",
  "errors": "Unexpected error occurred. Please try again later."
}

POST

bank

create

curl --request POST \
  --url https://sandbox.zapyd.com/cms/api/v1/bank/create \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-SIGNATURE: <api-key>' \
  --header 'X-TIMESTAMP: <api-key>' \
  --data '
{
  "customer_id": "c2cf861b-342b-4318-a90e-85cd0312e82f",
  "bank_account_type": "ACCOUNT_DETAILS",
  "identifiers": {
    "account_number": "7627389201",
    "ifsc": "SBIN0001829"
  }
}
'

{
  "status": true,
  "message": "Success",
  "data": {
    "id": "4e6f1b20-a73c-11ec-b909-0242ac120002",
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "country": "IND",
    "bank_account_type": "ACCOUNT_DETAILS",
    "identifiers": {
      "account_number": "7627389201",
      "ifsc": "SBIN0001829"
    },
    "bank_account_status": "VERIFIED",
    "beneficiary_name": "JOHN DOE",
    "bank_name": "State Bank of India",
    "failure_reason": null
  }
}

{
  "status": false,
  "message": "Bad Request",
  "err_code": "REQ_FIELD_MISSING",
  "errors": {
    "identifiers": [
      "This field is required."
    ]
  },
  "data": null
}

{
  "status": false,
  "message": "Internal Server Error",
  "data": null,
  "err_code": "SYS_INTERNAL_ERROR",
  "errors": "Unexpected error occurred. Please try again later."
}

Add Bank Account

Open in Cursor

The customer must be VERIFIED, and the account holder’s name must match the name on their KYC.

Rails by country

Send the rail in bank_account_type and its fields in identifiers. Which rails you can send depends on the customer’s alpha_3_country_code.

Country	`bank_account_type`	`identifiers`	Payout method
India (`IND`)	`ACCOUNT_DETAILS`	`account_number`, `ifsc`	`IMPS`
	`UPI`	`vpa`	`UPI`

United States: customers link their bank with Generate Bank Link instead.
Payout-only beneficiaries: use Add Payout Bank Account. Its fields are set per country and payout method.
India: NRE accounts aren’t supported. Remittance (RDA) payouts need ACCOUNT_DETAILS.

Verification

Save data.id as bank_id. The account starts as PROCESSING.
Zapyd verifies it asynchronously, and a BANK webhook reports VERIFIED or FAILED. On FAILED, failure_reason says why.
Quote only against a VERIFIED account.

In sandbox, set the result with Mock Bank Verification. It sends no webhook, so read the account afterwards.

Limits

At most 3 active accounts per rail per customer.
An account already linked to another customer is rejected.

Error Codes and Messages

API Status Code	Response	Reason
400	Customer not found or access denied	Customer not found
400	Customer not found or access denied	Customer does not belong to the organization
400	Customer is unverified	Customer is not KYC verified
400	VPA already in use	UPI ID is already in use
400	Maximum 3 UPI IDs allowed	3 UPI IDs are already added for the customer
400	Account number already in use	Account number is already in use
400	Maximum 3 bank account details allowed	3 bank accounts are already added for the customer
400	KYC already in use	KYC is being used by another customer
500	Internal Server Error	Internal Server Error

Authorizations

X-API-KEY

string

header

required

API Key for authentication

X-TIMESTAMP

string

header

required

Current timestamp in seconds since epoch

X-SIGNATURE

string

header

required

HMAC SHA256 signature of the request encoded in Base64

Body

application/json

customer_id

string<uuid>

required

Customer's unique identifier. The customer must be VERIFIED.

Example:

"c2cf861b-342b-4318-a90e-85cd0312e82f"

bank_account_type

string

required

Payment rail. The rails depend on the customer's country: see Rails by country. For example ACCOUNT_DETAILS or UPI.

Example:

"ACCOUNT_DETAILS"

identifiers

object

required

The fields for the rail in bank_account_type: see Rails by country. For example {account_number, ifsc} for ACCOUNT_DETAILS, or {vpa} for UPI.

Example:

{
  "account_number": "7627389201",
  "ifsc": "SBIN0001829"
}

Response

Bank account added successfully

status

boolean

Example:

true

message

string

Example:

"Success"

data

object

Hide child attributes

data.id

string<uuid>

Bank account ID

Example:

"4e6f1b20-a73c-11ec-b909-0242ac120002"

data.customer_id

string<uuid>

Customer ID

Example:

"550e8400-e29b-41d4-a716-446655440000"

data.country

string

Customer country (alpha-3)

Example:

"IND"

data.bank_account_type

enum<string>

Payment rail

Available options:

ACCOUNT_DETAILS,

UPI

Example:

"ACCOUNT_DETAILS"

data.identifiers

object

Rail-specific identifiers. ACCOUNT_DETAILS: account_number and ifsc. UPI: vpa.

Example:

{
  "account_number": "7627389201",
  "ifsc": "SBIN0001829"
}

data.bank_account_status

enum<string>

Verification status

Available options:

PROCESSING,

VERIFIED,

FAILED,

MANUAL_REVIEW

Example:

"VERIFIED"

data.beneficiary_name

string

Account holder name returned by bank verification

Example:

"JOHN DOE"

data.bank_name

string

Bank name

Example:

"State Bank of India"

data.failure_reason

string | null

Set when bank_account_status is FAILED

Example:

null

Using the API

Onboarding

Money movement

Platform

Sandbox

Add Bank Account

Rails by country

Verification

Limits

Error Codes and Messages

Authorizations

Body

Response

​Rails by country

​Verification

​Limits

​Error Codes and Messages

Authorizations

Body

Response

Rails by country

Verification

Limits

Error Codes and Messages