--- updatedAt: 2026-07-20T21:19:04.000Z agentTools: projectIndex: https://docs.cardda.com/llms.txt --- # Retrieve one Returns a bank accounts given it's id # OpenAPI definition ````json { "openapi": "3.0.0", "info": { "version": "1.0.0", "title": "banking API" }, "servers": [ { "url": "https://api.cardda.com" } ], "paths": { "/v1/banking/bank_accounts/{bank_account_id}": { "get": { "summary": "Retrieve one", "description": "Returns a bank accounts given it's id", "operationId": "showBankAccount", "parameters": [ { "$ref": "#/paths/~1v1~1banking~1bank_keys/get/parameters/0" }, { "$ref": "#/components/parameters/Bank_account_id" } ], "tags": [ "Bank account" ], "responses": { "200": { "description": "Body of the searched bank account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bank_account" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found — no `bank_account` with that id is visible to your company. The\nlookup is company-scoped, so an id that exists but belongs to another\ncompany also answers `404` (not `401`).\n", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "examples": { "resource_not_found": { "summary": "Unknown or out-of-scope bank account", "value": { "message": "Resource not found" } } } } } } } } }, "/v1/banking/bank_keys": { "get": { "summary": "List bank keys", "description": "Returns a paginated list of bank keys — the credentials Cardda holds on behalf of a company to operate against a bank's online portal.\n\nA bank key is what lets Cardda actually move money: it grants Cardda the rights to **list** bank accounts, **enroll** recipients, **create** transactions, and **pull** statements/transactions from the bank. Without an `approved` bank key for a given bank, the rest of the Banking API has no upstream connection.\n\n## When you'll use this endpoint\n\n- Show the user \"which banks are linked\" in your dashboard.\n- Detect that a key needs re-authentication (`status: declined`) — most often because the user changed their bank password.\n- Pick the right `user_id` before issuing a `POST /v1/banking/bank_keys/{id}/confirm` (re-validation flow). A credential is no longer tied to a single company — see the `companies` array in the response.\n\n## Response structure\n\nEach item is a **filtered** view of the bank key — sensitive fields (`password`, `secrets`, `auth_seed`, `card`) are stripped automatically. You get:\n\n| Field | Description |\n| --- | --- |\n| `id` | UUID. |\n| `user_id` | Firebase user id of the person who provided the credentials. |\n| `companies` | Per-company KYC status. A credential can be shared across several companies (razones sociales); each entry carries `id`, `name`, `identifier` (RUT) and `kyc_completed`. Replaces the removed single-company `holder_id`. |\n| `source_key_id` | If this key was cloned from a parent key (used for multi-account banks where one set of credentials grants access to multiple accounts), the parent's id. |\n| `type` | STI subclass — bank-specific behavior (e.g. `Banking::Cl::BancoDeChile::Key`, `Banking::ItauKey`). |\n| `aux_type` | Auxiliary classification, used by some banks to differentiate business / personal / corporate flows. |\n| `status` | Lifecycle status (see enum). |\n| `rut` | Tax id of the credential's account. Format `XXXXXXXX-Y`. |\n| `email` | Notification email registered at the bank. |\n| `authorization_method` | Second factor pinned on this credential (`token`, `digipass`, `device`, `multipass`, `santander_pass`, `bice_pass`, `itau_pass`). Almost always `null`: the method is normally chosen per operation and sent in the authorize/preauthorize body, not stored here. |\n| `priority` | Sort order when multiple keys share the same company + `bank`. Higher wins. |\n| `bank_errors` | Recent errors (auth failures, captcha challenges, scheduled maintenance). |\n| `accounts` | Bank accounts visible through this key. |\n| `kyc_completed` | Whether KYC was completed for the user that owns the key. |\n\n## Common queries\n\nThe list is scoped to the credentials owned by the caller (by `user_id`); the\ncompany link now lives in each key's `companies` array, not a queryable\n`holder_id` column.\n\n```bash\n# Keys for a specific person (the dashboard's pattern)\nGET /v1/banking/bank_keys?\\\n user_id=&\\\n _order=desc&_field=created_at&_start=0&_end=60\n\n# Only declined keys that need re-auth\nGET /v1/banking/bank_keys?\\\n status=declined\n\n# Filter by RUT\nGET /v1/banking/bank_keys?\\\n rut=76123456-7\n\n# Filter by bank type (Banco de Chile only)\nGET /v1/banking/bank_keys?\\\n type=Banking::Cl::BancoDeChile::Key\n```\n\n## Security note\n\nBank-key sensitive fields (`password`, `auth_seed`, `card`, `secrets`) are **never** exposed by this endpoint. Cardda exposes them only through a separate, internal-by-default reveal flow that requires a dedicated permission plus a fresh second-factor confirmation; if your integration needs that flow, contact your Cardda account manager.\n\nAll operators in [Filters](https://docs.cardda.com/docs/filters) are supported on the columns listed below.\n", "operationId": "listBankKeys", "tags": [ "Bank key" ], "parameters": [ { "name": "company-id", "in": "header", "required": true, "description": "UUID of the company on whose behalf the request is made. Send it on banking\nrequests to identify the acting company. Note that user-scoped list endpoints\n(e.g. the recipients/transactions indexes) resolve results across all companies\nthe authenticated user is a member of, rather than strictly from this header.\nSee [The company-id header](https://docs.cardda.com/docs/company-id) for details on how to obtain\na value for this header and the error responses to expect when it is missing or invalid.\n", "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "$ref": "#/paths/~1v1~1banking~1banks/get/parameters/0" }, { "$ref": "#/paths/~1v1~1banking~1banks/get/parameters/1" }, { "$ref": "#/paths/~1v1~1banking~1banks/get/parameters/2" }, { "$ref": "#/paths/~1v1~1banking~1banks/get/parameters/3" }, { "name": "id", "in": "query", "required": false, "description": "Filter by bank key UUID. Supports `$in` for batch lookups.", "schema": { "type": "string" }, "example": "{\"$in\":[\"a36dc2aa-9f27-4dc4-9d4f-61e88e9c1396\"]}" }, { "name": "user_id", "in": "query", "required": false, "description": "Firebase user id of the person whose credentials backed the key.", "schema": { "type": "string" }, "example": "U2MGkNZT6zNPKtB85OpJi9SjFvG2" }, { "name": "type", "in": "query", "required": false, "description": "STI subclass — bank-specific behavior. Supply the exact namespaced class\nname. `Banking::Cl::Cardda::Key` is the Cardda wallet credential and is by far the\nmost numerous type; `Banking::BankKey` is the base class, used by credentials with no\nbank integration behind them. The values in use today are:\n", "schema": { "type": "string", "enum": [ "Banking::BankKey", "Banking::ItauKey", "Banking::BciKey", "Banking::Cl::BancoBice::Key", "Banking::Cl::BancoDeChile::Key", "Banking::Cl::BancoInternacional::Key", "Banking::Cl::BancoSantanderChile::Key", "Banking::Cl::BancoScotiabank::Key", "Banking::Cl::BancoSecurity::Key", "Banking::Cl::Cardda::Key", "Banking::Mx::Stp::Key", "Banking::Us::Mercury::Key", "Banking::Pe::BancoBcp::Key", "Banking::VirtualKey" ], "example": "Banking::Cl::BancoDeChile::Key" } }, { "name": "aux_type", "in": "query", "required": false, "description": "Auxiliary classification used by some banks (e.g. `business`, `personal`,\n`corporate`, `enterprise`). Set by the bank-specific subclass; consult\nthe team if you need to filter by this for a specific bank.\n", "schema": { "type": "string" }, "example": "corporate" }, { "name": "status", "in": "query", "required": false, "description": "Lifecycle status of the key.", "schema": { "type": "string", "enum": [ "pending", "approved", "declined", "preauthorized" ], "example": "approved" } }, { "name": "rut", "in": "query", "required": false, "description": "Tax id of the credential. Format `XXXXXXXX-Y` (Chilean RUT) or country-specific format.\n", "schema": { "type": "string" }, "example": "76123456-7" }, { "name": "email", "in": "query", "required": false, "description": "Notification email at the bank. Accepts a plain email string\n(`email=ops@acme.cl`) or a JSON-encoded operator object\n(`{\"$regex\":\"acme.cl$\"}`) for text search. Schema is `type: string`\n(no `format: email`) so both forms validate; see\n[Filters](https://docs.cardda.com/docs/filters).\n", "schema": { "type": "string" }, "example": "{\"$regex\":\"acme.cl$\"}" }, { "name": "authorization_method", "in": "query", "required": false, "description": "Second factor pinned on this credential. Almost always `null` — see the response schema.\n", "schema": { "type": "string", "enum": [ "token", "digipass", "device", "multipass", "santander_pass", "bice_pass", "itau_pass" ], "example": "santander_pass" } }, { "name": "priority", "in": "query", "required": false, "description": "Sort order when several keys exist for the same company+bank. Defaults\nto `0`. Accepts a plain integer (`priority=1`) or a JSON-encoded operator\nobject (`{\"$gte\":1}`). Schema is `type: string` so both forms validate;\nsee [Filters](https://docs.cardda.com/docs/filters).\n", "schema": { "type": "string" }, "example": "{\"$gte\":1}" }, { "name": "source_key_id", "in": "query", "required": false, "description": "If you cloned a key (multi-account banks), the parent key's UUID. Pull\nall clones of a parent with `source_key_id=`.\n", "schema": { "type": "string", "format": "uuid" }, "example": "a36dc2aa-9f27-4dc4-9d4f-61e88e9c1396" }, { "name": "created_at", "in": "query", "required": false, "description": "Creation timestamp (UTC ISO-8601). Accepts a single date-time string or\na JSON-encoded operator object (`{\"$gte\":\"...\",\"$lt\":\"...\"}`). Schema\nis `type: string` (no `format`) so both forms validate.\n", "schema": { "type": "string" }, "example": "{\"$gte\":\"2026-01-01T00:00:00Z\"}" } ], "responses": { "200": { "description": "Paginated list of bank keys (sensitive fields filtered out). Headers\ninclude `X-Total-Count` and `Content-Range` for offset pagination —\nsee [Pagination](https://docs.cardda.com/docs/pagination).\n", "headers": { "Content-Range": { "description": "Range of items returned (end exclusive, no unit prefix).", "schema": { "type": "string", "example": "0-25/150" } }, "X-Total-Count": { "description": "Total number of bank keys available.", "schema": { "type": "integer", "example": 150 } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/paths/~1v1~1banking~1bank_keys~1%7Bbank_key_id%7D/get/responses/200/content/application~1json/schema" } }, "examples": { "mixed_key_statuses": { "summary": "One approved and one declined key for the same company at different banks", "value": [ { "id": "a36dc2aa-9f27-4dc4-9d4f-61e88e9c1396", "user_id": "U2MGkNZT6zNPKtB85OpJi9SjFvG2", "source_key_id": null, "type": "Banking::Cl::BancoDeChile::Key", "aux_type": "business", "status": "approved", "rut": "76123456-7", "email": "tesoreria@acme.cl", "authorization_method": "digipass", "priority": 1, "kyc_completed": true, "bank_errors": [], "companies": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Acme SpA", "identifier": "76123456-7", "kyc_completed": true } ], "accounts": [ { "id": "1942f2e7-1a6e-4729-8ec8-70e82d053f63", "holder_id": "550e8400-e29b-41d4-a716-446655440000", "bank_id": "cl_banco_de_chile", "number": 12345678, "rut": "76123456-7", "account_type": "corriente", "type": "Banking::Cl::BancoDeChile::Account", "bank_errors": [] } ], "created_at": "2026-01-15T10:00:00Z", "updated_at": "2026-04-15T08:30:00Z" }, { "id": "f8504c71-1adc-478a-96a9-df4c7eac3688", "user_id": "U2MGkNZT6zNPKtB85OpJi9SjFvG2", "source_key_id": null, "type": "Banking::Cl::BancoSantanderChile::Key", "aux_type": "corporate", "status": "declined", "rut": "76123456-7", "email": "tesoreria@acme.cl", "authorization_method": "santander_pass", "priority": 0, "kyc_completed": true, "bank_errors": [ { "code": "auth_failed", "message": "Bank rejected credentials. Re-enter password.", "detected_at": "2026-04-28T03:15:00Z" } ], "companies": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Acme SpA", "identifier": "76123456-7", "kyc_completed": true } ], "accounts": [], "created_at": "2026-02-20T14:30:00Z", "updated_at": "2026-04-28T03:15:00Z" } ] } } } } }, "401": { "description": "Unauthorized — missing or invalid bearer token, `company-id` header not\nset, or the caller is not authorized for the requested scope. Pundit\nauthorization failures return `401` with an empty body (no `403`).\n" } } } } }, "tags": [ { "name": "Bank account" }, { "name": "Bank key" } ], "components": { "parameters": { "Bank_account_id": { "name": "bank_account_id", "in": "path", "required": true, "description": "The id of the bank account", "schema": { "type": "string" } } }, "schemas": { "Bank_account": { "type": "object", "required": [ "id", "number", "rut" ], "properties": { "id": { "type": "string", "format": "uuid" }, "balance": { "type": "integer", "nullable": true, "description": "The account balance, in the currency's minor unit, as Cardda read it the\nlast time it synced the account with the bank.\n\n**This field is not included in every response that uses this schema.**\nOnly `GET /v1/banking/bank_accounts`,\n`GET /v1/banking/bank_accounts/{bank_account_id}` and the payroll-level\n`sender` (`Bank_payroll.sender`) of each row in\n`GET /v1/banking/bank_payrolls/` (the account the\npayroll is paid from, not the `sender` of its transactions) return it, and only if\nthe company that holds the account turned on\n**\"Mostrar el saldo y las inversiones\"** in its company settings\n(Configuración de la empresa). When that setting is off, the `balance` key is omitted entirely (it is not sent\nas `null`, which in this API means something else: \"we have never read\nthis account\").\n\nEverywhere else this schema is reused — `Bank_transaction.sender` and\n`Bank_key_filtered.accounts` — the key is always omitted, regardless of\nthat setting: there the account identifies where the payment comes from,\nit does not report its funds. An integration that needs the balance should\nread it from `GET /v1/banking/bank_accounts`.\n" }, "holder_id": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of the Person (company or counterpart) that owns the account." }, "bank_id": { "type": "string", "description": "Bank identifier, e.g. `cl_banco_de_chile`, `mx_stp`, `us_mercury`.", "example": "cl_banco_de_chile" }, "type": { "type": "string", "description": "STI subclass, bank-specific (e.g. `Banking::Cl::BancoDeChile::Account`).", "example": "Banking::Cl::BancoDeChile::Account" }, "number": { "type": "string", "example": "0011223344" }, "rut": { "type": "string", "example": "77989372K" }, "email": { "type": "string", "example": "pagos@cardda.com" }, "name": { "type": "string", "example": "pagos cardda" }, "account_type": { "type": "string", "enum": [ "corriente", "vista", "ahorro", "clabe", "yape" ], "description": "Chilean account types are the following:\n\n> * 'corriente'\n> * 'vista'\n> * 'ahorro'\n\nMexican account types are the following:\n> * 'clabe'\n\nPeruvian account types are the following:\n> * 'yape'\n\nFor more details check the [guide](https://docs.cardda.com/docs).\n", "nullable": true }, "bank_errors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "banking_entity_id": { "type": "string", "format": "uuid" }, "banking_entity_type": { "type": "string", "example": "Banking::BankEntity" }, "error_code": { "type": "string", "nullable": true, "enum": [ "auth/wrong-credentials", "auth/invalid-body", "recipient/create/invalid-body", "recipient/create/unknown-bank-name", "recipient/create/unknown-account-type", "recipient/get/unknown-bank-name", "recipient/get/unknown-account-type", "recipient/authorization/not-found", "recipient/authorization/invalid-data", "transaction/enqueue/invalid-body", "transaction/enqueue/first-transaction-max-amount", "transaction/enqueue/transaction-daily-max-amount", "transaction/enqueue/recipient-not-registered", "transaction/enqueue/sender-account-not-fund", "transaction/enqueue/recipient-collision", "transaction/enqueue/sender-collision", "transaction/dequeue/invalid-body", "transaction/dequeue/not-found", "transaction/dequeue/dequeue-all-unsuccessful", "transaction/dequeue/no-queued-transactions", "transaction/get/unknown-status", "transaction/get/unknown-date-format", "transaction/get/invalid-body", "transaction/authorization/invalid-body", "transaction/authorization/wrong-token", "transaction/authorization/invalid-method", "transaction/authorization/no-queued-transactions", "transaction/authorization/insufficient-funds", "transaction/authorization/account-token-blocked", "account/get/not-found", "account/common/blocked-auth-devices", "account/common/temporary-blocked", "page/failed-to-load-components", "page/recipient-save-unsuccessful", "page/transaction-enqueue-unsuccessful", "page/transaction-authorization-unsuccessful", "request/expired-cookies" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } }, "security": [ { "bearerAuth": [] } ] } ````