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

# Country Requirements

> Beneficiary fields, document types, and check-digit rules per country

Each country has its own set of beneficiary fields, document types, and
bank-account shape. The Pydantic models on the API enforce these, including
**check-digit validation** for CLABE (MX), CPF (BR), CBU/CUIL (AR), RUT (CL),
and CCI (PE).

<Tip>
  For runtime form-building, call `GET /v1/payouts/requirements/{country}` —
  it returns the live shape directly from the server and stays in sync if
  fields are added.
</Tip>

A failing check digit raises `422 VALIDATION_ERROR`, not a `REJECTED` payout
— it's a bad **request**, not a bad **payout**.

***

## Mexico (MX)

| Property              | Value                     |
| --------------------- | ------------------------- |
| Payout currency       | `MXN`                     |
| Payment methods       | `BANK_TRANSFER`           |
| Document types        | `RFC`, `CURP`, `PASSPORT` |
| Bank account required | `clabe`                   |

CLABE is 18 digits with a **mod-10 weighted check digit** (Banxico spec).
The algorithm: weight the first 17 digits cyclically by `(3, 7, 1)`, take
each product modulo 10, sum them, and the check digit is `(10 - sum % 10) % 10`.

### Example

```json theme={null}
{
  "amount": "20039.25",
  "currency": "MXN",
  "country": "MX",
  "external_id": "payroll-mx-2026-05-emp-001",
  "beneficiary": {
    "name": "Juan García",
    "document_type": "RFC",
    "document_id": "GARJ800101ABC",
    "bank_account": {
      "clabe": "012180001234567890"
    }
  }
}
```

***

## Colombia (CO)

| Property              | Value                                         |
| --------------------- | --------------------------------------------- |
| Payout currency       | `COP`                                         |
| Payment methods       | `BANK_TRANSFER`                               |
| Document types        | `CC`, `CE`, `NIT`, `PASSPORT`                 |
| Bank account required | `bank_code`, `account_type`, `account_number` |
| `bank_code`           | 4 digits (ACH Colombia entity code)           |
| `account_type`        | `CHECKING` or `SAVINGS`                       |
| `account_number`      | 5–17 digits                                   |

### Example

```json theme={null}
{
  "amount": "4600000.00",
  "currency": "COP",
  "country": "CO",
  "external_id": "payroll-co-2026-05-emp-001",
  "beneficiary": {
    "name": "Juan Pérez",
    "document_type": "CC",
    "document_id": "1023456789",
    "bank_account": {
      "bank_code": "1007",
      "account_type": "CHECKING",
      "account_number": "12345678901"
    }
  }
}
```

***

## Argentina (AR)

| Property              | Value                                        |
| --------------------- | -------------------------------------------- |
| Payout currency       | `ARS`                                        |
| Payment methods       | `BANK_TRANSFER`                              |
| Document types        | `DNI`, `CUIL`, `CUIT`, `PASSPORT`            |
| Bank account required | `cuil` + **one of** (`cbu` *or* `alias_cbu`) |
| `cbu`                 | 22 digits                                    |
| `alias_cbu`           | 6–20 alphanumeric chars                      |
| `cuil`                | 11 digits (hyphens accepted on input)        |

If you pass `document_type: "CUIL"` for the beneficiary, the engine also
runs the CUIL format check against `document_id` (11 digits).

### Example (CBU)

```json theme={null}
{
  "amount": "850000.00",
  "currency": "ARS",
  "country": "AR",
  "external_id": "payroll-ar-2026-05-emp-001",
  "beneficiary": {
    "name": "María González",
    "document_type": "CUIL",
    "document_id": "27123456789",
    "bank_account": {
      "cbu": "0070123456789012345678",
      "cuil": "27123456789"
    }
  }
}
```

### Example (alias)

```json theme={null}
{
  "beneficiary": {
    "name": "María González",
    "document_type": "CUIL",
    "document_id": "27123456789",
    "bank_account": {
      "alias_cbu": "MARIA.GONZALEZ.NOMINA",
      "cuil": "27123456789"
    }
  }
}
```

***

## Brazil (BR)

| Property        | Value                    |
| --------------- | ------------------------ |
| Payout currency | `BRL`                    |
| Payment methods | `BANK_TRANSFER` or `PIX` |
| Document types  | `CPF`, `CNPJ`            |

CPF is 11 digits with **two mod-11 check digits**. The engine validates them
when `document_type: "CPF"` (and again on PIX keys with `pix_key_type: "CPF"`).
All-identical-digit CPFs (e.g. `"11111111111"`) are rejected even though
they pass the mod-11 algebra — that's the standard Receita Federal rule.

### `BANK_TRANSFER` shape

| Field            | Required | Format                  |
| ---------------- | -------- | ----------------------- |
| `bank_code`      | yes      | 3 digits                |
| `branch`         | yes      | agência number          |
| `account_number` | yes      | string                  |
| `account_type`   | yes      | `CHECKING` or `SAVINGS` |

```json theme={null}
{
  "amount": "8500.00",
  "currency": "BRL",
  "country": "BR",
  "external_id": "folha-br-2026-05-emp-001",
  "payment_method_id": "BANK_TRANSFER",
  "beneficiary": {
    "name": "Carlos Silva",
    "document_type": "CPF",
    "document_id": "39053344705",
    "bank_account": {
      "payment_method": "BANK_TRANSFER",
      "bank_code": "341",
      "branch": "0001",
      "account_number": "123456-7",
      "account_type": "CHECKING"
    }
  }
}
```

### `PIX` shape

| Field          | Required | Format                                |
| -------------- | -------- | ------------------------------------- |
| `pix_key`      | yes      | string (validated per `pix_key_type`) |
| `pix_key_type` | yes      | `CPF`, `EMAIL`, `PHONE`, or `EVP`     |

* `CPF` keys are validated as CPFs (same check-digit rule)
* `EMAIL` keys must contain `@`
* `PHONE` keys must contain ≥ 8 digits
* `EVP` keys are opaque (any non-empty string)

```json theme={null}
{
  "amount": "8500.00",
  "currency": "BRL",
  "country": "BR",
  "external_id": "folha-br-2026-05-emp-001",
  "payment_method_id": "PIX",
  "beneficiary": {
    "name": "Carlos Silva",
    "document_type": "CPF",
    "document_id": "39053344705",
    "bank_account": {
      "payment_method": "PIX",
      "pix_key": "carlos.silva@example.com",
      "pix_key_type": "EMAIL"
    }
  }
}
```

***

## Chile (CL)

| Property              | Value                                         |
| --------------------- | --------------------------------------------- |
| Payout currency       | `CLP`                                         |
| Payment methods       | `BANK_TRANSFER`                               |
| Document types        | `RUT`, `PASSPORT`                             |
| Bank account required | `bank_code`, `account_type`, `account_number` |
| `account_type`        | `CHECKING`, `SAVINGS`, `VISTA`, or `RUT`      |

RUT follows the format `NNNNNNNN-D` (1–9 digits, dash, check digit). The
check digit is computed with a **mod-11 algorithm** (weights `2..7` cycling
over the digits, reversed). When the algorithm yields `11` the check digit
is `0`; when it yields `10` it's `K`. Both upper- and lower-case `K` are
accepted on input.

### Example

```json theme={null}
{
  "amount": "850000.00",
  "currency": "CLP",
  "country": "CL",
  "external_id": "remuneracion-cl-2026-05-emp-001",
  "beneficiary": {
    "name": "Andrés Muñoz",
    "document_type": "RUT",
    "document_id": "12345678-5",
    "bank_account": {
      "bank_code": "012",
      "account_type": "CHECKING",
      "account_number": "00012345678"
    }
  }
}
```

***

## Peru (PE)

| Property              | Value                                                           |
| --------------------- | --------------------------------------------------------------- |
| Payout currency       | `PEN`                                                           |
| Payment methods       | `BANK_TRANSFER`                                                 |
| Document types        | `DNI`, `CE`, `RUC`, `PASSPORT`                                  |
| Bank account required | **one of:** `cci` (alone) *or* (`bank_code` + `account_number`) |
| `cci`                 | 20 digits (Código de Cuenta Interbancario)                      |
| `account_number`      | 10–20 digits (when used without CCI)                            |

### Example (CCI)

```json theme={null}
{
  "amount": "4500.00",
  "currency": "PEN",
  "country": "PE",
  "external_id": "planilla-pe-2026-05-emp-001",
  "beneficiary": {
    "name": "Ricardo Vargas",
    "document_type": "DNI",
    "document_id": "12345678",
    "bank_account": {
      "cci": "00219012345678901234"
    }
  }
}
```

### Example (bank code + account number)

```json theme={null}
{
  "beneficiary": {
    "name": "Ricardo Vargas",
    "document_type": "DNI",
    "document_id": "12345678",
    "bank_account": {
      "bank_code": "002",
      "account_number": "1234567890123"
    }
  }
}
```

***

## Live form-building

Hardcoding these field tables into your UI works, but the canonical source
of truth is the API itself. Call:

```bash theme={null}
GET /v1/payouts/requirements/{country}
```

…to get the structured shape — required fields, allowed document types,
allowed account types, and format hints. New countries get added to that
endpoint as a schema-only change, with no client work needed.

```bash theme={null}
curl https://api.clevis.dev/v1/payouts/requirements/CO \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "country": "CO",
  "payout_currency": "COP",
  "payment_methods": ["BANK_TRANSFER"],
  "default_payment_method": "BANK_TRANSFER",
  "beneficiary": {
    "required": ["name", "document_type", "document_id", "bank_account"],
    "document_types": ["CC", "CE", "NIT", "PASSPORT"],
    "bank_account": {
      "required": ["bank_code", "account_type", "account_number"],
      "account_types": ["CHECKING", "SAVINGS"],
      "bank_code": { "format": "4 digits", "note": "ACH Colombia entity code" },
      "account_number": { "format": "5..17 digits" }
    }
  }
}
```

Countries outside MX/CO/AR/BR/CL/PE return `404 PAYOUT_COUNTRY_NOT_SUPPORTED`.