> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yativo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Payment Method

> Add a payment method (bank account, wallet) to a beneficiary

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
```

<Note>
  Requires an `Idempotency-Key` header.
</Note>

## Request body

<ParamField body="gateway_id" type="integer" required>
  The ID of the payout method (gateway) to use. Obtain available IDs from the payout methods endpoint.
</ParamField>

<ParamField body="payment_data" type="object" required>
  Key/value pairs of account details required for this payment method. The fields vary depending on the selected `gateway_id`.
</ParamField>

<ParamField body="currency" type="string" required>
  Currency code for this payment method (e.g. `CLP`, `MXN`, `BRL`).
</ParamField>

<ParamField body="nickname" type="string" required>
  A label to identify this payment method.
</ParamField>

<ParamField body="beneficiary_id" type="string">
  The ID of the beneficiary to link this payment method to.
</ParamField>

## Payment data examples

<Accordion title="Chile — Bank Transfer">
  ```json theme={null}
  {
    "account_number": "12345678",
    "bank_code": "001",
    "account_type": "checking",
    "rut": "12.345.678-9"
  }
  ```
</Accordion>

<Accordion title="Mexico — SPEI">
  ```json theme={null}
  {
    "clabe": "012345678901234567"
  }
  ```
</Accordion>

<Accordion title="Brazil — PIX / Bank Transfer">
  ```json theme={null}
  {
    "account_number": "12345-6",
    "branch_number": "0001",
    "bank_code": "341",
    "account_type": "checking",
    "cpf": "123.456.789-00"
  }
  ```
</Accordion>

<RequestExample>
  ```bash cURL — Chile Bank Transfer theme={null}
  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"
      }
    }'
  ```

  ```bash cURL — Mexico SPEI theme={null}
  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"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>