---
title: "Create Bank Recipient"
method: POST
path: "/v1/banking/bank_recipients"
tags: ["Bank recipient"]
---

# Create Bank Recipient

`POST /v1/banking/bank_recipients`

## Request

- Base URL: `https://api.cardda.com`
- URL: `https://api.cardda.com/v1/banking/bank_recipients`
- Auth: HTTP bearer

Creates a new bank recipient (beneficiary) for transfers. Recipients must be created before you can send them payments.

## Recipient Creation Flow

### Basic Flow (Most Banks)
1. Create recipient with account details
2. Recipient is automatically enrolled at the bank
3. Once approved, recipient can receive transfers

### Banco de Chile Flow
Requires authorization token or device:
1. Create recipient with authorization method
2. Provide token or device_id
3. Recipient is enrolled and approved

### Draft Recipients (for Payrolls)
Set `transition: null` to create as draft:
1. Create draft recipient
2. Associate with payroll
3. Authorize along with payroll

## Examples

### Standard Recipient Creation
```json
{
  "owner_id": "456e7890-a12b-34c5-d678-901234567890",
  "account_number": "123456789",
  "account_type": "corriente",
  "rut": "761234567",
  "name": "Proveedor ABC SpA",
  "alias": "proveedor-abc",
  "email": "pagos@proveedor.cl",
  "bank_id": "cl_banco_estado"
}
```

### Banco de Chile with Token
```json
{
  "owner_id": "456e7890-a12b-34c5-d678-901234567890",
  "account_number": "987654321",
  "account_type": "corriente",
  "rut": "772345678",
  "name": "Empresa XYZ",
  "alias": "empresa-xyz",
  "email": "finanzas@xyz.cl",
  "bank_id": "cl_banco_de_chile",
  "authorization_method": "digipass",
  "token": "123456"
}
```

## Important Notes
- The `owner_id` must be a bank account you have access to
- RUT format must include only numbers and verification digit
- Email is used for transfer notifications at some banks
- Alias should be unique within your recipients for easy identification

## Parameters

- `#/paths/~1v1~1banking~1bank_keys/get/parameters/0` (unresolved $ref)

## Request body

- object
  - `owner_id` string, uuid, required: UUID of the bank account that will own this recipient. Get this from GET /v1/banking/bank_accounts
  - `account_number` string, required: Recipient's bank account number
  - `account_type` 'corriente' | 'vista' | 'ahorro', required: Type of bank account
  - `rut` string, required: Recipient's RUT (tax ID). Format: Include only numbers and verification digit (e.g., 761234567)
  - `name` string, required: Recipient's full legal name. Length and character set are enforced by the bank of the **`owner_id` account** — the account you enrol into — not by the recipient's `bank_id`. Caps, strictest first: Itaú 30, BCI / BICE / STP 40, Santander / Scotiabank / Cardda wallet 60, Banco de Chile 64; Banco Security, Banco Internacional and BCP set none. Over the cap: `422 "Validation failed: Name is too long (maximum is N characters)"`. Two owner banks also restrict the characters. **BICE** accepts unaccented ASCII letters and spaces only — no digits, no punctuation, no accents — and rejects the rest with `422 "Validation failed: Name recipient's names only can contain letters"`. **BCI** accepts `/\A[A-zÀ-ú0-9\-ñÑ&.@() ]+\Z/`.
  - `alias` string: Friendly identifier for the recipient. Recommended: Use lowercase with hyphens (e.g., proveedor-abc) Like `name`, the cap comes from the `owner_id` account's bank: Itaú 20, BCI 25, STP 40, BICE 50, Banco de Chile 64, everyone else 60. It is **required** at the banks that do not override the requirement (BCI, Itaú, Banco Estado, Banco Internacional, Banco Security), and optional at Banco de Chile, BICE, Santander, Scotiabank, the Cardda wallet, STP and BCP. At BCI it takes the same character set as `name`.
  - `email` string, email: Recipient's email for notifications
  - `bank_id` 'cl_banco_de_chile' | 'cl_banco_bci' | 'cl_banco_santander_chile' | 'cl_banco_itau' | 'cl_banco_bice' | 'cl_banco_scotiabank' | 'cl_banco_security' | 'cl_banco_estado' | 'cl_banco_internacional', required: Recipient's bank identifier. Must be a valid Chilean bank ID.
  - `transition` 'enroll' | 'null', nullable: Initial transition. Set to null for draft recipients (payroll use). Default: "enroll" (immediately enrolls at bank)
  - `bank_key_id` string, uuid: Optional selector for the bank key (crawler credential) used to enroll the recipient. When omitted, Cardda uses the highest-priority approved bank key of the owning account for your user. Provide it only to pick a specific key.
  - `authorization_method` 'digipass' | 'device': Authorization method — **only applies to Banco de Chile** recipients. Defaults to `digipass`. Ignored for other banks.
  - `token` string: One-time password for authorization. **Banco de Chile only.** Optional on create; **required on `enroll`** when authorizing a Banco de Chile recipient.
  - `device_id` string, uuid: Bank device UUID for authorization. **Banco de Chile only.** Optional on create; **required on `enroll`** for Banco de Chile.

## Response `201`

Successfully created bank recipient

- object
  - `id` string, uuid, required
  - `name` string
  - `alias` string
  - `owner_id` string, uuid, required
  - `rut` string: The rut must not contain dots or hyphens, and if it ends up with a k this letter should be capitalized
  - `email` string
  - `account_type` 'corriente' | 'vista' | 'ahorro' | 'clabe' | 'yape': Chilean account types are the following: > * 'corriente' > * 'vista' > * 'ahorro' Mexican account types are the following: > * 'clabe' Peruvian account types are the following: > * 'yape' For more details check the [guide](https://docs.cardda.com/docs).
  - `account_number` string, required
  - `person_id` string, uuid: the id of the company that owns this recipient
  - `bank_id` 'cl_banco_de_chile' | 'cl_banco_internacional' | 'cl_banco_scotiabank' | 'cl_banco_scotiabank_azul' | 'cl_banco_bci' | 'cl_banco_bice' | 'cl_hsbc_bank' | 'cl_banco_santander_chile' | 'cl_banco_itau' | 'cl_banco_security' | 'cl_banco_falabella' | 'cl_banco_ripley' | 'cl_banco_consorcio' | 'cl_banco_btg_pactual_chile' | 'cl_banco_estado' | 'cl_banco_corpbanca' | 'cl_banco_paris' | 'cl_coopeuch' | 'cl_mercado_pago' | 'cl_prepago_los_heroes' | 'cl_tapp_caja_los_andes' | 'cl_tenpo_prepago_sa' | 'cl_banco_del_desarrollo' | 'cl_transbank' | 'cl_banco_do_brasil' | 'cl_jp_morgan_chase_bank' | 'cl_mufg_bank' | 'cl_banco_sudamericano' | 'cl_rabobank' | 'cl_china_construction_bank' | 'cl_bank_of_china' | 'cl_banco_de_la_nacion_argentina' | 'cl_banco_penta' | 'cl_abn_amro_bank' | 'mx_banxico' | 'mx_bancomext' | 'mx_banobras' | 'mx_banjercito' | 'mx_nafin' | 'mx_babien' | 'mx_hipotecaria_fed' | 'mx_banamex' | 'mx_bbva_mexico' | 'mx_santander' | 'mx_hsbc' | 'mx_bajio' | 'mx_inbursa' | 'mx_mifel' | 'mx_scotiabank' | 'mx_banregio' | 'mx_invex' | 'mx_bansi' | 'mx_afirme' | 'mx_banorte' | 'mx_bank_of_america' | 'mx_mufg' | 'mx_jp_morgan' | 'mx_bmonex' | 'mx_ve_por_mas' | 'mx_azteca' | 'mx_autofin' | 'mx_barclays' | 'mx_compartamos' | 'mx_multiva_banco' | 'mx_actinver' | 'mx_intercam_banco' | 'mx_bancoppel' | 'mx_abc_capital' | 'mx_consubanco' | 'mx_volkswagen' | 'mx_cibanco' | 'mx_bbase' | 'mx_bankaool' | 'mx_pagatodo' | 'mx_inmobiliario' | 'mx_donde' | 'mx_bancrea' | 'mx_banco_covalto' | 'mx_icbc' | 'mx_sabadell' | 'mx_shinhan' | 'mx_mizuho_bank' | 'mx_bank_of_china' | 'mx_banco_s3' | 'mx_monexcb' | 'mx_gbm' | 'mx_masari' | 'mx_value' | 'mx_vector' | 'mx_finamex' | 'mx_valmex' | 'mx_profuturo' | 'mx_cb_intercam' | 'mx_ci_bolsa' | 'mx_fincomun' | 'mx_nu_mexico' | 'mx_reforma' | 'mx_stp' | 'mx_credicapital' | 'mx_kuspit' | 'mx_unagra' | 'mx_asp_integra_opc' | 'mx_alternativos' | 'mx_libertad' | 'mx_caja_pop_mexica' | 'mx_cristobal_colon' | 'mx_caja_telefonist' | 'mx_transfer' | 'mx_fondo_fira' | 'mx_invercap' | 'mx_fomped' | 'mx_tesored' | 'mx_nvio' | 'mx_indeval' | 'mx_arcus' | 'pe_banco_bcp' | 'pe_banco_yape'
  - `metadata` unknown
  - `external_id` string, uuid
  - `bank_former_name` string
  - `status` 'draft' | 'enrolled' | 'preauthorized' | 'deleted' | 'approved'
  - `transition` 'enroll' | 'authorize' | 'preauthorize' | 'delete', nullable
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `400`: Bad Request - Invalid parameters
- `401`: Unauthorized - Missing or invalid authentication
- `403`: Forbidden - User lacks permission for the owner account
- `404`: Not found — `owner_id` matches no `bank_account` at all. An account that exists but is not yours is rejected as `401`, not `404`.
- `422`: Unprocessable Entity - Validation or enrollment errors

## Changes

- **2026-11-03** `785332193a09`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cardda/apis/banking-api/changes/v1/banking/bank_recipients/post.md)

---

[API](https://skmtc.dev/cardda/apis/banking-api.md) - [All operations](https://skmtc.dev/cardda/apis/banking-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardda/apis/banking-api/revisions/785332193a09?raw)