Create Beneficiary

POST/beneficiaries

Description

Register a bank account that can receive fiat payouts. Returns a beneficiary object whose id you reference as the beneficiary_id when creating a payout.

A beneficiary is a reusable template: register a payee once (a business, vendor, or other recipient), then route payouts from many customers to it.

Headers

Header	Description	Required
Authorization	Bearer token with your API key	yes
Content-Type	application/json	yes

Request Body

Name	Type	Description	Required
name	string	Display name of the payee.	yes
bank_account	object	The bank account, identified by a "type" discriminator (SEPA, ACH, Wire, SWIFT, FPS, CHAPS) plus the rail-specific fields and a "holder_name".	yes

Example Request

const response = await fetch('https://checkout-api.exodus-int.com/beneficiaries', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Acme Inc',
    bank_account: {
      type: 'SEPA',
      iban: 'DE89370400440532013000',
      holder_name: 'Acme Inc',
      country: 'DE',
    },
  }),
});

Response

SUCCESSFUL RESPONSE

{
  "id": "ben_1a2b3c",
  "object": "beneficiary",
  "name": "Acme Inc",
  "status": "registered",
  "bank_account": { "type": "SEPA", "iban_last4": "3000", "country": "DE" },
  "created_at": "2026-06-04T12:00:00Z"
}

The returned bank_account is partially masked (e.g., iban_last4) for security.

Error Responses

VALIDATION ERROR

{
  "error": {
    "type": "validation_error",
    "message": "Invalid IBAN",
    "param": "bank_account.iban"
  }
}