Create a beneficiary

Create a beneficiary for fiat payouts (offramp) or crypto outbound transfers.

Pass type, currency, and corridor fields at the top level (country_code, network, account_number,provider_id, routing_number, address, etc.). On read, we nest account information under details and expand provider_id to provider.

Body — shared fields

• type — required. One of fiat, crypto.
• name — required. Max 255 chars.
• label — required. Max 128 chars.
• currency — required. ISO/crypto currency code (2–8 uppercase alphanumerics).
• metadata — optional. Free-form Record<string, string>.
• merchant_reference — optional. Max 128 chars. Auto-generated as ref_<ULID> when omitted. Per-integration unique.
• customer_id — optional. GlobalStack customer external id (cust_<ULID>). When omitted, the integration’s default customer is used; in that case data.customer_id in the response will carry the default customer’s external id, which is intentionally not addressable via GET /v1/customers/:customer_id.

Body — fiat fields (type = "fiat")

• country_code — required. ISO-3166-1 alpha-2 (e.g. NG, KE).
• provider_id — required. GlobalStack provider external id (prov_<ULID>).
• network — required. One of bank, mobile_money.
• account_number — required. For network = "mobile_money" this field carries the phone number; for network = "bank" it carries the bank account number.
• account_name — required when network = "mobile_money"; optional when network = "bank". For bank beneficiaries the account name is resolved later when GlobalStack opens the account at the provider.

Body — crypto fields (type = "crypto")

• network — required. One of solana, base, ethereum.
• address — required. Max 128 chars.

Example — fiat (bank)

POST /v1/beneficiaries
{
  "type": "fiat",
  "name": "Alice Bank Beneficiary",
  "label": "Alice's salary account",
  "currency": "NGN",
  "country_code": "NG",
  "network": "bank",
  "account_number": "0039415616",
  "provider_id": "prov_01KPBAP7WTDKQKW5B3R31VPNX4"
}

Example — crypto (USDC on Solana)

POST /v1/beneficiaries
{
  "type": "crypto",
  "name": "Alice Wallet",
  "label": "Personal cold wallet",
  "currency": "USDC",
  "network": "solana",
  "address": "9wFFa…"
}