Save a bank destination

curl --request POST \
  --url https://api.agentcard.sh/api/v2/wallet/withdrawal-recipients \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "usr_123",
  "type": "international_wire",
  "beneficiary_name": "Alex Example",
  "country_code": "DE",
  "iban": "DE89 3704 0044 0532 0130 00",
  "swift_code": "DEUTDEFF",
  "bank_name": "Deutsche Bank",
  "nickname": "Main account"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    user_id: 'usr_123',
    type: 'international_wire',
    beneficiary_name: 'Alex Example',
    country_code: 'DE',
    iban: 'DE89 3704 0044 0532 0130 00',
    swift_code: 'DEUTDEFF',
    bank_name: 'Deutsche Bank',
    nickname: 'Main account'
  })
};

fetch('https://api.agentcard.sh/api/v2/wallet/withdrawal-recipients', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agentcard.sh/api/v2/wallet/withdrawal-recipients"

payload = {
    "user_id": "usr_123",
    "type": "international_wire",
    "beneficiary_name": "Alex Example",
    "country_code": "DE",
    "iban": "DE89 3704 0044 0532 0130 00",
    "swift_code": "DEUTDEFF",
    "bank_name": "Deutsche Bank",
    "nickname": "Main account"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "object": "withdrawal_recipient",
  "user_id": "usr_123",
  "id": "wrec_9f2c1a",
  "type": "international_wire",
  "nickname": "Main account",
  "beneficiary_name": "Alex Example",
  "country_code": "DE",
  "currency": null,
  "bank_name": "Deutsche Bank",
  "account_number_last4": null,
  "routing_number": null,
  "account_type": null,
  "iban_last4": "••••3000",
  "swift_code": "DEUTDEFF",
  "created_at": "2026-07-16T00:00:00.000Z"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

POST

api

wallet

withdrawal-recipients

Save a bank destination

curl --request POST \
  --url https://api.agentcard.sh/api/v2/wallet/withdrawal-recipients \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "usr_123",
  "type": "international_wire",
  "beneficiary_name": "Alex Example",
  "country_code": "DE",
  "iban": "DE89 3704 0044 0532 0130 00",
  "swift_code": "DEUTDEFF",
  "bank_name": "Deutsche Bank",
  "nickname": "Main account"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    user_id: 'usr_123',
    type: 'international_wire',
    beneficiary_name: 'Alex Example',
    country_code: 'DE',
    iban: 'DE89 3704 0044 0532 0130 00',
    swift_code: 'DEUTDEFF',
    bank_name: 'Deutsche Bank',
    nickname: 'Main account'
  })
};

fetch('https://api.agentcard.sh/api/v2/wallet/withdrawal-recipients', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agentcard.sh/api/v2/wallet/withdrawal-recipients"

payload = {
    "user_id": "usr_123",
    "type": "international_wire",
    "beneficiary_name": "Alex Example",
    "country_code": "DE",
    "iban": "DE89 3704 0044 0532 0130 00",
    "swift_code": "DEUTDEFF",
    "bank_name": "Deutsche Bank",
    "nickname": "Main account"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "object": "withdrawal_recipient",
  "user_id": "usr_123",
  "id": "wrec_9f2c1a",
  "type": "international_wire",
  "nickname": "Main account",
  "beneficiary_name": "Alex Example",
  "country_code": "DE",
  "currency": null,
  "bank_name": "Deutsche Bank",
  "account_number_last4": null,
  "routing_number": null,
  "account_type": null,
  "iban_last4": "••••3000",
  "swift_code": "DEUTDEFF",
  "created_at": "2026-07-16T00:00:00.000Z"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

How it works

Before a user can withdraw to a bank, they save the destination once. Collect the bank details in your UI and pass them through; we validate per type and return the destination masked (last four digits only) — store the id and render the masked fields, never the raw numbers.

US accounts (type: "ach"): routing_number (9-digit ABA), account_number, account_type.
Everywhere else (type: "international_wire"): iban + swift_code. Some countries need one extra field via country_specific — for example {"ifsc": "..."} for India, {"clabe": "..."} for Mexico, {"bsb": "..."} for Australia. For those common cases a missing key is rejected as recipient_fields_invalid with the field named; for other countries, include the fields the destination bank requires.
A user can hold up to 25 active destinations; remove one to add more.

The full details are only used by our team to execute the transfer — they never appear in any read endpoint.

Authorizations

Authorization

string

header

required

A platform access token. Get one on the Create an access token endpoint by exchanging your client_id + client_secret, then send it as Authorization: Bearer <token>. Tokens live one hour.

Body

application/json

user_id

string

required

The connected user's id.

type

enum<string>

required

Available options:

ach,

international_wire

beneficiary_name

string

required

The account holder's legal name.

country_code

string

required

ISO 3166-1 alpha-2 country of the bank account.

nickname

string

string<email>

routing_number

string

ACH: 9-digit ABA routing number.

account_number

string

ACH: the account number.

account_type

enum<string>

ACH only.

Available options:

checking,

savings

iban

string

International wire: the IBAN (spaces ok, normalized on save).

swift_code

string

International wire: the SWIFT/BIC.

bank_name

string

address_line1

string

address_line2

string

city

string

region

string

postal_code

string

country_specific

object

Country-specific banking fields, e.g. {"ifsc": "..."} for India or {"clabe": "..."} for Mexico.

Response

The saved destination, masked.

A saved bank destination. Account and IBAN numbers are always masked to their last four digits in responses.

object

enum<string>

Available options:

withdrawal_recipient

user_id

string

The connected user this destination belongs to.

string

Recipient id (wrec_...). Pass it as recipient_id when creating a withdrawal.

type

enum<string>

Available options:

ach,

international_wire

nickname

string | null

beneficiary_name

string

country_code

string

ISO 3166-1 alpha-2 country of the bank account.

currency

string | null

bank_name

string | null

account_number_last4

string | null

Masked, ACH only. Example: ••••6789.

routing_number

string | null

ACH only.

account_type

enum<string> | null

Available options:

checking,

savings

iban_last4

string | null

Masked, international wire only.

swift_code

string | null

International wire only.

created_at

string<date-time>

Verify the phone code List saved bank destinations

⌘I

Authentication

Connect

Card attachment

Identity verification

Balance funding

Withdrawals

Platform connect

Save a bank destination

How it works

Authorizations

Body

Response

​How it works

Authorizations

Body

Response

How it works