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:

GET /recipients/{orgId}/corridors

Example response:

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

🚧

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

Register the recipient bank details using POST /recipients/{orgId}:

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

{
  "type": "individual",
  "name": "María González",
  "email": "[email protected]",
  "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:

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

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