Skip to main content
Add a payment method to a beneficiary. The structure of the payment_data object varies by payment method type — retrieve the required fields for a specific payout method from the payout methods endpoint. 
POST /v1/beneficiaries/payment-methods
Requires an Idempotency-Key header.

​
Request body

​
gateway_id
integer
required
The ID of the payout method (gateway) to use. Obtain available IDs from the payout methods endpoint.
​
payment_data
object
required
Key/value pairs of account details required for this payment method. The fields vary depending on the selected gateway_id.
​
currency
string
required
Currency code for this payment method (e.g. CLP, MXN, BRL).
​
nickname
string
required
A label to identify this payment method.
​
beneficiary_id
string
The ID of the beneficiary to link this payment method to.

​
Payment data examples

{
  "account_number": "12345678",
  "bank_code": "001",
  "account_type": "checking",
  "rut": "12.345.678-9"
}

{
  "clabe": "012345678901234567"
}

{
  "account_number": "12345-6",
  "branch_number": "0001",
  "bank_code": "341",
  "account_type": "checking",
  "cpf": "123.456.789-00"
}

curl -X POST 'https://api.yativo.com/api/v1/beneficiaries/payment-methods' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pm-create-001' \
  -d '{
    "gateway_id": 42,
    "currency": "CLP",
    "nickname": "Maria CLP Account",
    "beneficiary_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "payment_data": {
      "account_number": "12345678",
      "bank_code": "001",
      "account_type": "checking",
      "rut": "12.345.678-9"
    }
  }'

curl -X POST 'https://api.yativo.com/api/v1/beneficiaries/payment-methods' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pm-create-001' \
  -d '{
    "gateway_id": 15,
    "currency": "MXN",
    "nickname": "Tech Solutions SPEI",
    "beneficiary_id": "8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e",
    "payment_data": {
      "clabe": "012345678901234567"
    }
  }'

{
  "status": "success",
  "data": {
    "id": "pm-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "user_id": "usr-001",
    "gateway_id": 42,
    "currency": "CLP",
    "nickname": "Maria CLP Account",
    "payment_data": {
      "account_number": "12345678",
      "bank_code": "001",
      "account_type": "checking",
      "rut": "12.345.678-9"
    },
    "beneficiary_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "created_at": "2026-04-02T10:30:00.000000Z",
    "updated_at": "2026-04-02T10:30:00.000000Z"
  }
}