API Reference

Add an external account

Adds a bank account or mobile wallet that a customer pays out to. Use GET /v1/external-accounts/institutions for institution_id, and POST /v1/external-accounts/verify to check the holder's name first.

bank_account and mobile_money return 200 with status active. swift, sepa, ach_wire and fps return 202 with status pending while setup runs. Get the account until it is active or setup_failed, or wait for the external_account.active or external_account.setup_failed webhook.

A duplicate (same customer, holder name, and account and bank) is a 400 with code ERROR_CODE_DUPLICATE_PAYEE and the existing payee_id. Deleted and failed accounts count as duplicates.

POSThttps://api.gravv.xyz/v1/external-accounts

Headers

1 to 255 printable ASCII characters. A retry with the same key within 24 hours returns the first response, including a 400. After you correct a request, send a new key.

Request Body

Request Examples

{
"payee_type": "bank_account",
"customer_id": "3130ca8b-8b32-4843-8623-bf83e766b86a",
"currency": "NGN",
"account_name": "Ada Okafor",
"account_number": "0123456789",
"institution_id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f"
}

{
"payee_type": "bank_account",
"customer_id": "3130ca8b-8b32-4843-8623-bf83e766b86a",
"currency": "MAD",
"account_name": "Youssef Amrani",
"account_number": "007780000123400000012345",
"institution_id": "4f6a8c2e-1b3d-4e5f-9a7b-2c4d6e8f0a1b",
"address": {
"address_line1": "12 Rue Ibn Batouta",
"city": "Casablanca",
"country": "MA"
}
}

{
"payee_type": "bank_account",
"customer_id": "3130ca8b-8b32-4843-8623-bf83e766b86a",
"currency": "MXN",
"account_name": "Diego Hernandez",
"account_number": "002180000123456789",
"institution_country_iso_code": "MX",
"national_id": "GODE561231HDFRRN09",
"national_id_type": "CURP",
"address": {
"address_line1": "Av Vallarta 1520",
"city": "Guadalajara",
"country": "MX"
}
}

{
"payee_type": "bank_account",
"customer_id": "3130ca8b-8b32-4843-8623-bf83e766b86a",
"currency": "BRL",
"account_name": "Maria Souza",
"pix_key": "maria.souza@example.com",
"national_id": "52998224725",
"national_id_type": "CPF",
"address": {
"address_line1": "Rua Augusta 1500",
"city": "Sao Paulo",
"country": "BR"
}
}

{
"payee_type": "bank_account",
"customer_id": "3130ca8b-8b32-4843-8623-bf83e766b86a",
"currency": "COP",
"account_name": "Camila Rojas",
"account_number": "12345678901",
"institution_id": "7b9d1f3a-5c7e-4a9b-8d1f-3a5c7e9b1d2f",
"bank_account_type": "savings",
"national_id": "1020304050",
"national_id_type": "CC",
"address": {
"address_line1": "Carrera 7 71 21",
"city": "Bogota",
"country": "CO"
}
}

{
"payee_type": "bank_account",
"customer_id": "3130ca8b-8b32-4843-8623-bf83e766b86a",
"currency": "INR",
"account_name": "Priya Sharma",
"account_number": "50100123456789",
"routing_number": "HDFC0000123",
"address": {
"address_line1": "14 MG Road",
"city": "Bengaluru",
"country": "IN"
}
}

{
"payee_type": "bank_account",
"customer_id": "3130ca8b-8b32-4843-8623-bf83e766b86a",
"currency": "HKD",
"account_name": "Chan Tai Man",
"account_number": "123456789012",
"institution_id": "2a4c6e8f-0b1d-4f3a-9c5e-7a9b1c3d5e7f",
"address": {
"address_line1": "1 Queens Road Central",
"city": "Hong Kong",
"country": "HK"
}
}

{
"payee_type": "bank_account",
"customer_id": "3130ca8b-8b32-4843-8623-bf83e766b86a",
"currency": "PKR",
"account_name": "Ali Khan",
"account_number": "00123456789012",
"institution_id": "8e0a2c4f-6b8d-4a1c-9e3f-5b7d9f1a3c5e"
}

{
"payee_type": "mobile_money",
"customer_id": "3130ca8b-8b32-4843-8623-bf83e766b86a",
"currency": "UGX",
"account_name": "Grace Nakato",
"phone_number": "+256772123456",
"institution_id": "5c8d94fb-a927-5fed-b19d-1454c8f142a9"
}

{
"payee_type": "ach_wire",
"customer_id": "3130ca8b-8b32-4843-8623-bf83e766b86a",
"currency": "USD",
"account_name": "Jane Doe",
"account_number": "000123456789",
"routing_number": "021000021",
"payment_rail": "wire",
"account_owner_type": "individual",
"bank_name": "Example Bank",
"address": {
"address_line1": "350 Fifth Avenue",
"city": "New York",
"state": "NY",
"postal_code": "10118",
"country": "US"
}
}

{
"payee_type": "sepa",
"customer_id": "3130ca8b-8b32-4843-8623-bf83e766b86a",
"currency": "EUR",
"account_name": "Anna Schmidt",
"iban": "DE89370400440532013000",
"account_owner_type": "individual",
"bank_name": "Example Bank",
"address": {
"address_line1": "Unter den Linden 13",
"city": "Berlin",
"postal_code": "10117",
"country": "DE"
}
}

{
"payee_type": "swift",
"customer_id": "3130ca8b-8b32-4843-8623-bf83e766b86a",
"currency": "USD",
"account_name": "Acme Trading Ltd",
"account_number": "12345678",
"bic": "MIDLGB22",
"account_owner_type": "business",
"bank_address_line_1": "8 Canada Square",
"bank_city": "London",
"bank_state": "London",
"bank_postal_code": "E14 5HQ",
"bank_country": "GB",
"address": {
"address_line1": "1 King Street",
"city": "London",
"state": "London",
"postal_code": "EC2V 8AU",
"country": "GB"
}
}

{
"payee_type": "fps",
"customer_id": "3130ca8b-8b32-4843-8623-bf83e766b86a",
"currency": "GBP",
"account_name": "Tom Brown",
"account_number": "31926819",
"routing_number": "601613",
"account_owner_type": "individual",
"bank_name": "Example Bank",
"address": {
"address_line1": "1 King Street",
"city": "London",
"postal_code": "EC2V 8AU",
"country": "GB"
}
}

Responses

Status	Description
`200`	Added and `active`
`202`	Added and `pending` while setup runs
`400`	Invalid or missing field, a duplicate, or a failed bank check. Correct it and send a new Idempotency-Key.

200 response

An external account. Empty fields are left out.

Use it as the transfer destination

How the account is paid. bank_account and mobile_money are active at once. swift, sepa, ach_wire and fps need a setup step and start as pending.

Possible values: bank_account, mobile_money, swift, sepa, ach_wire, fps

Possible values: bank, mobile_money, swift, swift_intermediary

In upper case. It may be the name the bank holds.

The account holder's address. Required for swift, sepa, ach_wire and fps, and for some banks and payout corridors.

Checked against the country's postal code format

Alpha-2 code

Possible values: individual, business

pending while setup runs, then active (ready for transfers) or setup_failed (read error_message, then correct it with PATCH).

Possible values: pending, active, setup_failed, archived, deleted

Why setup failed

The national ID with only the last 4 characters shown

{
"data": {
"id": "6a2f0c1e-93b4-4d0e-8f57-1c2b3d4e5f60",
"payee_type": "bank_account",
"account_number": "0123456789",
"institution_id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
"institution_type": "bank",
"institution_name": "Example Bank",
"account_name": "ADA OKAFOR",
"customer_id": "3130ca8b-8b32-4843-8623-bf83e766b86a",
"currency": "NGN",
"institution_country_iso_code": "NG",
"status": "active",
"date_created": "2026-10-12T09:15:22.481Z"
},
"error": null
}

202 response