Recipient

A Recipient (beneficiary) is the person or company who receives the funds. Recipients are created on their own role-scoped endpoint, POST /v2/beneficiaries, which records the person with the BENEFICIARY role. Senders have a parallel endpoint, POST /v2/senders.

⚠️ The /people endpoints are deprecated. Earlier integrations created both senders and recipients through the shared POST /people endpoint and let the role be inferred from how the ID was used in a transaction. That model is superseded — create recipients on POST /v2/beneficiaries and senders on POST /v2/senders. The legacy /people and /v2/people routes stay live for migration (both stamp SENDER), so they can't create a beneficiary — use the role-scoped route.

Schema-Driven Recipient Creation

Recipient data requirements vary by destination country. Before collecting user data, always fetch the recipient schema:

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/payout/recipients/schema/co \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY"

This returns a JSON Schema (draft-07) defining exactly which fields are required for that country. See Recipient Schema for details.

Creating a Recipient

Endpoint: POST /organizations/{tenant}/v2/beneficiaries
Authentication: Tenant-level (x-api-key)

The request shape matches the sender endpoint — beneficiaries are persons rows too, distinguished only by role — and runs the same document-validation pipeline. A create returns 201 (or 200 if a person with the same externalId already exists).

Example: Brazilian Recipient

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/v2/beneficiaries \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --data '{
  "firstName": "Maria",
  "lastName": "Silva",
  "phoneNumber": "+5511999998888",
  "documents": [
    {
      "type": "cpf",
      "document": "12345678901",
      "countryCode": "BR"
    }
  ]
}'

Example: Colombian Recipient

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/v2/beneficiaries \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --data '{
  "firstName": "Carlos",
  "lastName": "Gutierrez",
  "phoneNumber": "+573001234567",
  "address": {
    "countryCode": "CO",
    "city": "Bogotá",
    "line1": "Calle 100 #15-20"
  },
  "documents": [
    {
      "type": "cc",
      "document": "1234567890",
      "countryCode": "CO"
    }
  ]
}'

Save the returned id — this is the recipientId used in the transaction.

Country-Specific Document Types

Always consult the recipient schema for the authoritative list of accepted document types per country.

Reusing Recipients

A recipient only needs to be created once and can be referenced as the recipientId in unlimited future transactions.

A person is created with a single role. If the same individual needs to both send and receive, create them once on each endpoint (/v2/senders and /v2/beneficiaries) — the sender role carries the full KYC/compliance obligations, while the beneficiary role is scoped to receiving payouts.

After Creating the Recipient

Once you have the recipientId, the next step is to link a bank account:

1. Fetch the account schema — GET /payout/recipientAccounts/schema/{countryCode}
2. Fetch the bank list (if required) — GET /payout/{countryCode}/banks
3. Create the recipient account — POST /payout/participants/{recipientId}/recipientAccounts/gateway

See Recipient Account for full details.

Best Practices

• Always use the schema endpoint to determine required fields — don't hardcode field requirements per country.
• Dynamically render forms based on the schema response to automatically support new countries.
• Collect only required fields — submitting unnecessary data may trigger additional compliance checks.
• Validate input client-side using the schema's pattern, minLength, and enum constraints before submitting.
• Handle the address requirement — some countries require a recipient address, others don't. The schema is your source of truth.