4. Add a beneficiary

Register the destination before paying it. The same endpoint serves bank accounts and wallets; payment_details selects the shape.

Bank beneficiary

POST /v1/payments/beneficiaries

curl -X POST https://api-staging.checker.finance/v1/payments/beneficiaries \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Nonce: $(uuidgen)" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "type": "BUSINESS",
    "business_name": "Vendor Supplies Inc",
    "first_party": false,
    "address": {
      "line1": "200 Main St",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "payment_details": {
      "bank_name": "Test Bank",
      "account_name": "Vendor Supplies Inc",
      "currency": "USD",
      "bank_country_code": "US",
      "routing_number": "021000021",
      "account_number": "111122223"
    }
  }'

Response — 201 Created:

{
  "beneficiary_id": "ben_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "business_name": "Vendor Supplies Inc",
  "type": "BUSINESS",
  "first_party": false,
  "status": "ACTIVE",
  "payment_details": {
    "bank_name": "Test Bank",
    "account_name": "Vendor Supplies Inc",
    "currency": "USD",
    "bank_country_code": "US"
  }
}

Destination	Required routing fields
US domestic (`ACH`, `FEDWIRE`)	`routing_number` + `account_number`, `bank_country_code: "US"`
Cross-border (`SWIFT`)	`swift_code` + `account_number` or `iban`, with a non-US `bank_country_code`

Wallet beneficiary

curl -X POST https://api-staging.checker.finance/v1/payments/beneficiaries \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Nonce: $(uuidgen)" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "type": "BUSINESS",
    "business_name": "Treasury Wallet",
    "address": {
      "line1": "500 Coffee Ave",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94107",
      "country": "US"
    },
    "payment_details": {
      "account_name": "Treasury Wallet",
      "currency": "USDT",
      "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
      "network": "ETH"
    }
  }'

Notes:

first_party declares whose account this is: true for the customer's own account, false (the default) for a third party. Classify correctly at creation — the distinction is enforced at payout.
A wallet beneficiary needs account_name, currency (the asset ticker), wallet_address, and network. Bank fields are not required; network is mandatory whenever wallet_address is present.
type: "INDIVIDUAL" replaces business_name with first_name and last_name.
Bank details are treated as personal data and are not returned in full.
A beneficiary is PENDING until it is confirmed, then ACTIVE. Paying a beneficiary that is not active returns 400 BENEFICIARY_NOT_ACTIVE.