CAcardda
Bank recipient

List Bank Recipients

Changed on

Returns a paginated list of bank recipients (beneficiaries) configured for your bank accounts.

🚧 Recipients are per bank account, not per company. A recipient belongs to exactly one bank_account (its owner_id). The same person enrolled in two of your accounts is two different recipients, with two different ids. Before creating a transfer, look the recipient up scoped to the account that pays — ?owner_id={sender_id} — never by name alone: passing a recipient from another account fails with 422 "Recipient must belong to same account as transaction".

The per-field operators in Filters — $gt, $gte, $lt, $lte, $in, $nin, $ne, $regex — are supported on the columns listed in Query parameters, passed as the value of that column (?alias={"$regex":"proveedor"}). The set is the same for every listable resource; the inclusive comparisons $gte / $lte are available here too, they are just of little use on this resource's mostly-textual columns. A bare value is an exact match; use {"$regex": "..."} for partial, case-insensitive matching.

$or is not a per-field operator: it is a separate top-level query parameter taking an array of filter objects (?$or=[{"alias":{"$regex":"abc"}},{"name":{"$regex":"abc"}}]), so it does not belong inside a field filter — see the $or parameter below and Logical OR operations.

Common Use Cases

Finding a Recipient by Name or Alias

To find recipients by their alias (commonly used identifier):

GET /v1/banking/bank_recipients?alias=proveedor-abc

Finding Recipients by RUT

To find all recipients with a specific RUT:

GET /v1/banking/bank_recipients?rut=761234567

Finding Recipients for a Specific Bank Account

To list recipients associated with a specific bank account:

GET /v1/banking/bank_recipients?owner_id=456e7890-a12b-34c5-d678-901234567890

Finding Recipients by Status

To filter by approval status:

GET /v1/banking/bank_recipients?status=approved

Finding Recipients by Bank

To list all recipients from a specific bank:

GET /v1/banking/bank_recipients?bank_id=cl_banco_estado

Pagination and Sorting

GET /v1/banking/bank_recipients?_start=0&_end=50&_order=desc&_field=created_at

Important Notes

  • The id field in the response is what you'll use as recipient_id when creating transactions
  • owner_id is the bank account this recipient belongs to. A transfer only accepts a recipient whose owner_id equals the transfer's sender_id
  • Recipients must be in approved status to receive individual transfers; a payroll transfer accepts any status except deleted
  • Some banks require authorization tokens when creating recipients
  • recipient_account_id is an internal field returned only to Cardda administrators; company users won't see it in the index/show responses

Recipient Status Values

  • draft - Recipient created but not enrolled in bank
  • enrolled - Enrolled at the bank
  • preauthorized - Preauthorized, awaiting final authorization
  • deleted - Soft-deleted recipient
  • approved - Ready to receive transfers
get/v1/banking/bank_recipients

Request

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

Query parameters

_startinteger

Starting index for pagination (0-based)

_endinteger
Example:50

Ending index for pagination (exclusive)

_order'ASC' | 'DESC'
Example:DESC

Sort order (ASC or DESC)

_fieldstring
Example:name

Field to sort by

idstring

Filter by recipient UUID. Use id={"$in":["...","..."]} for batch lookups, which is the most common form in production traffic.

$orstring

Logical OR across sub-conditions. Common pattern: search either by alias or by name simultaneously — $or=[{"alias":{"$regex":"abc"}},{"name":{"$regex":"abc"}}].

aliasstring
Example:proveedor-abc

Filter by recipient alias. A bare value is an exact match; for a partial, case-insensitive search use {"$regex": "proveedor"}. Alias is a friendly identifier you assign to recipients.

namestring
Example:Proveedor ABC SpA

Filter by recipient name. A bare value is an exact match; for a partial, case-insensitive search use {"$regex": "proveedor"}.

Searching by name alone is not enough to pick a recipient for a transfer — combine it with owner_id={sender_id}, because the same name can exist in several of your accounts.

rutstring
Example:761234567

Filter by recipient's RUT (exact match). Format: Include only numbers and verification digit

owner_idstring uuid
Example:456e7890-a12b-34c5-d678-901234567890

Filter by owner bank account UUID

bank_idstring
Example:cl_banco_estado

Filter by recipient's bank identifier

account_numberstring
Example:123456789

Filter by recipient's account number

status'draft' | 'enrolled' | 'preauthorized' | 'deleted' | 'approved'
Example:approved

Filter by recipient status

account_type'corriente' | 'vista' | 'ahorro'
Example:corriente

Filter by account type

Parameters

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

Response

Paginated list of bank recipients. The response includes metadata headers:

  • Content-Range: Indicates the range of items returned
  • X-Total-Count: Total number of recipients available
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'
external_idstring uuid
bank_former_namestring
status'draft' | 'enrolled' | 'preauthorized' | 'deleted' | 'approved'
transition'enroll' | 'authorize' | 'preauthorize' | 'delete' nullable
bank_errorsItems[] (unresolved $ref)
metadataunknown
created_atstring date-time
updated_atstring date-time

Changes