API Reference

Create Bank Recipient

post
https://api.cardda.com/v1/banking/bank_recipients

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": "[email protected]",
  "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": "[email protected]",
  "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
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Recipient details

uuid
required

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

string
required
^[0-9]+$

Recipient's bank account number

string
enum
required

Type of bank account

Allowed:
string
required
^[0-9]*K?$

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

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

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.

string

Recipient's email for notifications

string
enum
required

Recipient's bank identifier.
Must be a valid Chilean bank ID.

string | null
enum
Defaults to enroll

Initial transition. Set to null for draft recipients (payroll use).
Default: "enroll" (immediately enrolls at bank)

Allowed:
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.

string
enum

Authorization method — only applies to Banco de Chile recipients.
Defaults to digipass. Ignored for other banks.

Allowed:
string
^[0-9]{6,12}$

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

uuid

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

Headers
uuid
required

UUID of the company on whose behalf the request is made. Send it on banking
requests to identify the acting company. Note that user-scoped list endpoints
(e.g. the recipients/transactions indexes) resolve results across all companies
the authenticated user is a member of, rather than strictly from this header.
See The company-id header for details on how to obtain
a value for this header and the error responses to expect when it is missing or invalid.

Responses

Updated 26 days ago

Did this page help you?
Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 26 days ago

Did this page help you?