Docs / Core Guides / Beneficiaries

Beneficiaries

Beneficiaries are the individuals or corporate entities receiving funds in their local currency.

1. Discover Corridor Requirements#

Always query the corridor specifications dynamically before rendering bank detail forms to users:

http

GET /recipients/{orgId}/corridors

Example response:

json

{
  "capabilities": {
    "exactOutput": true,
    "indicativePricing": true
  },
  "corridors": [
    {
      "currency": "MXN",
      "country": "MX",
      "fields": [
        {
          "id": "clabeNumber",
          "title": "CLABE (18 digits)",
          "pattern": "^[0-9]{18}$",
          "required": true
        }
      ]
    }
  ]
}

WARN

Read the fields dynamically; never hardcode form fields. Both the available corridors and the required field names depend on how your organization is routed. For example, Mexican payouts on one routing require a single clabeNumber (18 digits), while an alternative banking rail might require bank name, branch code, and account number. Dynamic discovery ensures your integration adapts automatically without code releases.

2. Register a Beneficiary#

http

POST /recipients/{orgId}
Idempotency-Key: 7b2e3f81-91a3-481d-91b4-2b13c7a00f2e
Content-Type: application/json

{
  "type": "individual",
  "name": "María González",
  "email": "maria.gonzalez@example.com",
  "country": "MX",
  "externalId": "emp_42_beneficiary_1",
  "endUserId": "employee_42",
  "method": {
    "kind": "fiat",
    "currency": "MXN",
    "recipientDetails": {
      "clabeNumber": "012345678901234567"
    }
  }
}

Essential Parameters#

email: Required for beneficiary creation and used by rails that need recipient contact details.
externalId: Your own unique identifier for this recipient record. Supplying externalId makes the creation call safe to retry: sending the same ID returns the existing beneficiary record instead of creating duplicate accounts.
endUserId: Scopes the recipient to a specific user in your platform. Always pass endUserId when listing or fetching recipients for end users. Omitting it returns all beneficiaries across your entire organization.
destinationAccountId: Returned in paymentMethods[].destinationAccountId. Store this identifier to pass to subsequent payout requests.

Adding Additional Payment Methods#

An existing beneficiary can have additional bank accounts or fiat payment methods attached:

http

POST /recipients/{orgId}/{recipientId}/methods
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "kind": "fiat",
  "currency": "EUR",
  "recipientDetails": {
    "iban": "DE89370400440532013000"
  }
}