CAcardda
Bank recipient

Create Bank Recipient

Changed on

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

{
  "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

{
  "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
post/v1/banking/bank_recipients

Request

  • Base URL
    https://api.cardda.com
  • Auth
    HTTP bearer

Parameters

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

Request body

owner_idstring uuid required

UUID of the bank account that will own this recipient. Get this from GET /v1/banking/bank_accounts

account_numberstring required

Recipient's bank account number

account_type'corriente' | 'vista' | 'ahorro' required

Type of bank account

rutstring required

Recipient's RUT (tax ID). Format: Include only numbers and verification digit (e.g., 761234567)

namestring 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/.

aliasstring

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.

emailstring 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_idstring 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.

tokenstring

One-time password for authorization. Banco de Chile only. Optional on create; required on enroll when authorizing a Banco de Chile recipient.

device_idstring uuid

Bank device UUID for authorization. Banco de Chile only. Optional on create; required on enroll for Banco de Chile.

Example request

{
  "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",
  "bank_key_id": "47b93e3d-36a6-423a-acbe-c23b5484c3ed",
  "authorization_method": "digipass",
  "token": "123456",
  "device_id": "17b05803-ff34-4b17-8850-4d11217a2ae8"
}

Response

Successfully created bank recipient

idstring uuid required
namestring
aliasstring
owner_idstring uuid required
rutstring

The rut must not contain dots or hyphens, and if it ends up with a k this letter should be capitalized

emailstring
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.

account_numberstring required
person_idstring 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'
metadataunknown
external_idstring uuid
bank_former_namestring
status'draft' | 'enrolled' | 'preauthorized' | 'deleted' | 'approved'
transition'enroll' | 'authorize' | 'preauthorize' | 'delete' nullable
created_atstring date-time
updated_atstring date-time

Example response

{
  "name": "John Doe",
  "alias": "JD",
  "rut": "1111111K",
  "email": "john@example.com",
  "account_number": "1010101010",
  "bank_former_name": "Itau"
}

Changes