# Docs

- Guías: Cómo integrar Caibo Pay

  - **Empezar**
  - [Introducción](/docs): Una sola API para cobrar y pagar. Una clave, un webhook, un saldo.
  - [Inicio rápido](/docs/quickstart): De cero a tu primer cobro de prueba acreditado en tu saldo, en sandbox.
  - [SDKs](/docs/sdks): Librerías oficiales para Node.js y TypeScript, Python y Go. Generadas del mismo contrato que esta documentación.
  - [Sandbox y live](/docs/sandbox): Dos entornos separados con la misma API. Prueba todo en sandbox; para salir cambias solo la clave y el host.
  - [Pasar a producción](/docs/go-live): La lista de verificación antes de mover dinero real.

  - **Conceptos**
  - [Qué puedes hacer](/docs/capabilities): GET /v1/capabilities es el mapa de tu cuenta. Países, métodos y monedas se descubren ahí, nunca tienen endpoints propios.
  - [Autenticación](/docs/authentication): Una clave secreta por entorno, enviada como Bearer en cada solicitud.
  - [Idempotencia](/docs/idempotency): Reintenta sin miedo. La misma Idempotency-Key nunca cobra ni paga dos veces.
  - [Errores](/docs/errors): Un solo formato de error, tipos estables y códigos en los que puedes confiar.
  - [Listas y paginación](/docs/pagination): Todas las listas se leen igual. Páginas estables, filtros que se combinan y registros en orden.
  - [Montos y monedas](/docs/money): Los montos son texto decimal con la precisión exacta de su moneda. Nunca números.

  - **Cobrar**
  - [Cómo cobrar](/docs/collect): Abres un cobro, le muestras las instrucciones a tu cliente, él paga y el dinero entra a tu saldo.
  - [Cobrar un monto exacto](/docs/collect-one-payment): Un pago único por el monto de tu orden. PIX en Brasil y transferencia bancaria en Perú.
  - [Cobros acreditados](/docs/payins): El recurso payin es un pago que entró a una de tus cuentas de cobro, y lo que acreditó a tu saldo.
  - [Página alojada](/docs/hosted-pages): Una página de pago lista, con tu marca, que Caibo aloja por ti en pay.caibopay.app o en tu propio dominio.
  - [Reembolsos](/docs/refunds): Devuelve todo o parte de un cobro al pagador, desde tu saldo.

  - **Pagar**
  - [Cómo pagar](/docs/pay-out): Del saldo de tu cuenta a una cuenta bancaria, PIX o pago móvil, con el precio fijado antes de pagar.
  - [Clientes](/docs/customers): Las personas y empresas por las que actúas. Son el remitente de un pago cuando el país lo pide.
  - [Beneficiarios](/docs/beneficiaries): La cuenta a la que pagas. La registras una vez y le pagas cuantas veces quieras.
  - [Cotizaciones](/docs/quotes): Fija el precio de un pago antes de hacerlo. Sabes cuánto sale y cuánto llega, con todo incluido.
  - [Pagos](/docs/payouts): El recurso payout, sus estados, cómo cancelarlo y qué hacer cuando falla.
  - [Pagos en lote](/docs/payout-batches): Hasta 1000 pagos en una sola solicitud, cada uno con su estado y sus eventos.
  - [Remesas](/docs/remittances): Un cobro en una moneda y un pago en otra, con un solo precio.

  - **Tu saldo**
  - [Saldos](/docs/balances): Un saldo por moneda, con cada movimiento explicado.
  - [Retiros](/docs/withdrawals): Lleva tu saldo a una cuenta propia cuando quieras.
  - [Liquidaciones](/docs/settlements): Tu dinero enviado a tu cuenta según un calendario acordado con Caibo.
  - [Reportes](/docs/reports): Tus operaciones en JSON o CSV, por periodo, listas para tu contabilidad.

  - **Webhooks y eventos**
  - [Webhooks](/docs/webhooks): Te avisamos al instante de cada cambio. Firmados, con reintentos y en orden.
  - [Verificar la firma](/docs/webhook-signatures): Comprueba que cada webhook viene de Caibo y no fue alterado. Código listo en Node.js, Python y Go.
  - [Eventos](/docs/events): Todo lo que pasa en tu cuenta, como un registro ordenado. Lo mismo que llega por webhook.

  - **Cobertura**
  - [Países y métodos](/docs/coverage): Dónde cobras y pagas con Caibo Pay, y cómo saberlo siempre desde la API.

  - **IA**
  - [Construye con IA](/docs/ai): Esta documentación está hecha también para agentes. Conecta tu asistente y deja que integre por ti, bien.
- Referencia de la API: OpenAPI
  - Account: Who the credential is: the account, its environment and the key in use.
    - [Retrieve the account of the credential](/docs/api/account/get-account): Who the credential is: the account it belongs to, the environment that answered (sandbox or live) and the credential itself, without its secret. Use it to check a key and to show which account and environment a client is working in. The credential is an API key: there are no user identities (people, roles, single sign-on) yet, so nothing here describes a person.
    - [Who is calling](/docs/api/account/get-me): Who the credential of the request is: an API key (kind api_key) or a member of the account, a person signed in to the dashboard through its identity provider (kind member), with the account it acts for and its scopes. A member's role and scopes are the platform's: a client reads them here, never from the identity provider. For a member it also lists every account the person may act for; send the Caibo-Account header (acct_…) to act for another one. A person signed in to the dashboard who is no active member of an active account is answered 403 no_membership, one answer whatever the reason; this route binds the person's open invitations first. A dashboard session token is accepted only by this API, an operator console's never.
  - Balances: Funds per currency, by how usable they are, and the statement behind them.
    - [List balances](/docs/api/balances/list-balances): The account's money per currency, by how usable it is. Every figure is read from the ledger; total = available + pending + reserved + in_settlement. Earnings are shown apart and not added.
    - [List the statement of a currency](/docs/api/balances/list-balance-entries): Every movement on the account's balances in a currency, newest first: one entry per ledger posting on one of the account's own balances, with the operation it belongs to. Pass next_cursor as after to continue; the statement is walked without gaps or repeats.
  - Beneficiaries: Who is paid.
    - [List beneficiaries](/docs/api/beneficiaries/list-beneficiaries): Newest first.
    - [Create a beneficiary](/docs/api/beneficiaries/create-beneficiary): Registers who is paid. The same account registered twice for the same customer is the same beneficiary (200 with the existing one). Account details are write-only. The country is the method's when the method has one.
    - [Retrieve a beneficiary](/docs/api/beneficiaries/get-beneficiary)
  - Capabilities: What the account can do.
    - [List what the account can do](/docs/api/capabilities/list-capabilities): The products (payin, payout, remittance), methods, currencies and countries available to the account, with the fields each one requires and whether it can be used right now. Countries and rails are discovered here; they never have endpoints of their own.
  - Customers: The people and businesses you act for.
    - [List customers](/docs/api/customers/list-customers): Newest first. The profile is not in a list; retrieve a customer for it.
    - [Create a customer](/docs/api/customers/create-customer): Registers a person or business you act for, under your own external_id. The same external_id sent again with the same identity (type, country, display_name, profile) returns the existing customer (200); with a different identity it is a 409 conflict. metadata is yours and is not compared.
    - [Retrieve a customer](/docs/api/customers/get-customer)
    - [Update a customer's metadata or close it](/docs/api/customers/update-customer): metadata replaces the whole object. status takes active or closed; closed is final. A blocked customer is blocked by the platform and cannot be reactivated here.
  - Events: What happened, in order.
    - [List events](/docs/api/events/list-events): Events in the order they became visible. Store next_cursor and pass it as after to poll; no event is ever skipped. With resource_id the list is the story of one resource, oldest first: every status it went through, from its creation to its outcome. Filters combine, and the cursor works the same with them.
    - [Retrieve an event](/docs/api/events/get-event)
  - Webhooks: Events pushed to your servers, signed.
    - [Send an event to webhook endpoints again](/docs/api/webhooks/redeliver-event)
    - [List webhook endpoints](/docs/api/webhooks/list-webhook-endpoints)
    - [Create a webhook endpoint](/docs/api/webhooks/create-webhook-endpoint): The response carries the signing secret. It is shown only here and after a rotation.
    - [Retrieve a webhook endpoint](/docs/api/webhooks/get-webhook-endpoint)
    - [Update, pause or resume a webhook endpoint](/docs/api/webhooks/update-webhook-endpoint)
    - [Delete a webhook endpoint](/docs/api/webhooks/delete-webhook-endpoint)
    - [List recent deliveries to an endpoint](/docs/api/webhooks/list-webhook-deliveries)
    - [Send a test event](/docs/api/webhooks/ping-webhook-endpoint)
    - [Rotate the signing secret](/docs/api/webhooks/rotate-webhook-secret): Returns the new secret. For a grace period deliveries are signed with both the new and the previous secret.
  - Funding: Money in: funding accounts and the pay-ins that arrive through them.
    - [Create a funding account](/docs/api/funding/create-funding-account): An account the balance is funded through. It is created pending; its payment instructions are available once it is active (event funding_account.active). With amount it is one payment of exactly that amount (collection payment in GET /v1/capabilities): the payer pays the amount and nothing more, and the account closes once it is paid; the pay-in that credits it is payin.completed.
    - [Retrieve a funding account](/docs/api/funding/get-funding-account)
    - [List pay-ins](/docs/api/funding/list-pay-ins): Newest first. refunded and refundable are not in a list; retrieve a pay-in for them.
    - [Retrieve a pay-in](/docs/api/funding/get-pay-in): A credited pay-in also says what it has given back (refunded) and what can still be refunded (refundable).
  - Hosted pages: The hosted remittance page: its configuration and branding, the hostnames it is served at, and the sessions your customers go through.
    - [List hosted domains](/docs/api/hosted-pages/list-hosted-domains)
    - [Claim a hostname for the hosted page](/docs/api/hosted-pages/create-hosted-domain): Claims a hostname the page should be served at. The claim starts pending, with a verification_token to publish; the hostname serves the page only once the platform has verified it. A hostname with a live claim, yours or anybody's, is refused with hostname_taken.
    - [Retrieve a hosted domain](/docs/api/hosted-pages/get-hosted-domain)
    - [Remove a hosted domain](/docs/api/hosted-pages/delete-hosted-domain): The hostname stops serving the page at once and can be claimed again.
    - [Retrieve the hosted page configuration](/docs/api/hosted-pages/get-hosted-page): How the account's hosted remittance page is configured. An account that never configured it gets the defaults, with no id.
    - [Replace the hosted page configuration](/docs/api/hosted-pages/put-hosted-page): Replaces the whole configuration; a field left out is reset to its default. The theme is data, validated here: colours are #rrggbb, the radius is one of a fixed scale, the font is the key of a font the page ships, and URLs are https. branding_mode white_label needs the entitlement (white_label_entitled), which the platform grants; it is refused with white_label_not_entitled otherwise.
    - [List hosted sessions](/docs/api/hosted-pages/list-hosted-sessions): Newest first, those your customers started from the page included. Never with a token. A session's status is read off its remittance and its expiry when you ask, so the list is not filtered by it.
    - [Create a hosted session](/docs/api/hosted-pages/create-hosted-session): Starts a session of the hosted remittance flow for one of your customers. The response carries the session token and the path the hosted page serves it at (/s/<token>); they are shown only here. Send the customer to that path on your page's host: the same link is where they follow the remittance afterwards. A session creates at most one remittance, ever. Repeating the request with the same Idempotency-Key returns the same session, without the token. The hosted page must be enabled.
    - [Retrieve a hosted session](/docs/api/hosted-pages/get-hosted-session): With the ids of what the session holds: its customer, beneficiary, quote, funding account and remittance. payment_reported_at is when the customer said they paid; it is a statement, not a confirmation: follow the remittance and its pay-in for that.
  - Members: The people who act for the account through the dashboard, and their invitations.
    - [List the account's members](/docs/api/members/list-members): The people who act for the account through the dashboard, and the open invitations, newest first. A member's role maps to scopes: owner, admin and developer hold read and write, viewer read.
    - [Invite a person](/docs/api/members/create-member): Invites an e-mail address with a role. The invitation expires after 7 days; it is bound at the person's first signed-in call to the person whose verified primary address it is, and the member becomes active. Inviting an address that was invited and never signed in renews its invitation (200). Only a signed-in owner or admin invites, and only an owner invites an owner: an API key does not manage people (403 insufficient_role). An address that is already a member is 409 member_exists.
    - [Change a member's role or disable it](/docs/api/members/update-member): status disabled refuses the member's next request at once, whatever its session; active enables it again (only a member that signed in once). Only a signed-in owner or admin changes members, not their own; only an owner touches an owner; the account keeps at least one active owner (409 last_owner). Withdraw an invitation by disabling it.
  - Payouts: Money out.
    - [List payout batches](/docs/api/payouts/list-payout-batches): Newest first, each with its summary, totals and cancellation as they are now. A batch accepted while you page never shifts or repeats the pages that follow.
    - [Create a payout batch](/docs/api/payouts/create-payout-batch): Accepts up to 1000 payouts in one request. Every item is checked for form first: one malformed item refuses the whole batch (400, param items[i].field) and nothing is created. The batch is then accepted and each item becomes, asynchronously and at most once, an ordinary payout with its own status and events, in index order. An item that cannot be paid does not stop the others: it is refused (status refused, error_code) when it never became a payout, or its payout fails (insufficient_funds) as a single payout would. A quote named by an item is used by that item from the moment the batch is accepted. A payout kill switch for the account refuses the whole batch (503). Repeating the request with the same Idempotency-Key returns the same batch and creates nothing.
    - [Retrieve a payout batch](/docs/api/payouts/get-payout-batch): With its summary and totals, computed from its payouts as they are now. A payout whose outcome is not yet certain is counted as uncertain (its item is verification_pending) and keeps the batch processing; it is never sent again.
    - [Cancel a payout batch](/docs/api/payouts/cancel-payout-batch): Asks for the batch to be cancelled. Nothing that was sent is reversed. The request is recorded at once and carried out asynchronously, item by item: an item not yet issued is cancelled; an item whose payout has provably not reached a provider is cancelled with its payout (the payout fails with failure_code cancelled_before_submission and its funds are available again); every other item keeps its state, with not_cancelled_reason saying why (in_review, submitted, outcome_uncertain, already_completed, already_failed, already_returned, already_refused). A payout whose outcome is uncertain is never cancelled and never sent again. The answer is the batch as it is now: cancellation.status is in_progress until every item has its decision (event payout_batch.cancellation_finished); the batch then ends cancelled (no payout was executed), partially_cancelled (some were) or, when nothing could be cancelled, completed or completed_with_failures. Asking again, or for a batch that is already finished, changes nothing and returns the batch as it is.
    - [List the items of a payout batch](/docs/api/payouts/list-payout-batch-items): In index order, each with its payout's status now, why it was refused, or what the batch's cancellation decided about it.
    - [List payouts](/docs/api/payouts/list-payouts): Newest first. A list carries the payout without its detail (description, country, completed_at, failed_at, returned_at); retrieve a payout for it.
    - [Create a payout](/docs/api/payouts/create-payout): Reserves the funds and accepts the payout; it is executed asynchronously. A payout the balance cannot fund is created with status failed and failure_code insufficient_funds. Repeating the request with the same Idempotency-Key returns the same payout and never pays twice.
    - [Retrieve a payout](/docs/api/payouts/get-payout): With its detail: your own description, the country of the beneficiary's account, when it completed, failed, was returned or was cancelled, and its latest cancellation if one was asked for. Its story, step by step, is GET /v1/events?resource_id={id}. A payout whose submission's outcome is uncertain is verification_pending: its funds stay reserved, it is being verified with the provider, and nothing sends it again or in its place; it ends completed or failed on the provider's evidence. No request retries or cancels it.
    - [Cancel a payout that was never sent](/docs/api/payouts/cancel-payout): Asks for a payout to be cancelled. Only a payout nothing of which can have reached a provider is cancelled: it is processing, it was never sent (or every send is proven never to have left) and it is not waiting for a risk review. A payout that was sent, may have been sent (verification_pending), is final, waits for a risk review, or belongs to a payout batch or a remittance is refused with 409 payout_not_cancellable, reasons saying why (submitted, outcome_uncertain, already_completed, already_failed, already_returned, in_review, managed_by_batch, managed_by_remittance); nothing changes. The request is recorded at once and decided by the platform, under the payout's lock, before the payout would be sent: the answer is 202 with cancellation.status requested. Once cancelled, the payout's status is cancelled (failure_code cancelled_before_submission), its funds are available again and payout.cancelled is published; asking again, with any key, answers 200 with the cancelled payout. If the payout was sent in the meantime, cancellation.status becomes refused with not_cancelled_reason, and the payout goes on. Repeating the request with the same Idempotency-Key never cancels twice; the same key for another payout is 409 idempotency_key_reused.
  - Quotes: Frozen prices.
    - [Create a quote](/docs/api/quotes/create-quote): Freezes a price for a short time. A quote is used by at most one payout.
    - [Retrieve a quote](/docs/api/quotes/get-quote)
  - Reconciliation: Inconsistencies found about your operations, and where their investigation stands.
    - [List reconciliation exceptions](/docs/api/reconciliation/list-reconciliation-exceptions): Inconsistencies the platform found about your own operations (a pay-in, a payout, a withdrawal, a refund, a settlement or a remittance) and is working on, newest first. Read-only: the platform's operators investigate and close them.
    - [Retrieve a reconciliation exception](/docs/api/reconciliation/get-reconciliation-exception)
  - Refunds: Money given back: part or all of a credited pay-in sent back to its payer.
    - [List refunds](/docs/api/refunds/list-refunds): Newest first.
    - [Refund a pay-in](/docs/api/refunds/create-refund): Sends part or all of a credited pay-in back to its payer, from the available balance, through the provider that received it. Reserves the funds and accepts the refund; it is executed asynchronously. A refund the platform's risk controls hold for a review is created with status pending_review: its funds are reserved and it counts against what is left to refund, but nothing is sent until it is approved; a refund they refuse is a 422 risk_blocked. Omit amount to refund everything that is left. Repeating the request with the same Idempotency-Key returns the same refund and never refunds twice.
    - [Retrieve a refund](/docs/api/refunds/get-refund)
  - Remittances: Money in from a payer, out to a beneficiary, at a quoted price.
    - [List remittances](/docs/api/remittances/list-remittances): Newest first. payin_id and payout_id find the remittance a pay-in funded or a payout pays: at most one.
    - [Create a remittance](/docs/api/remittances/create-remittance): Sends a quote's destination amount to a beneficiary, funded by a deposit: either the next deposit into a funding account (source.funding_account_id; the remittance awaits it and the deposit must be credited before the quote expires) or a pay-in that already credited the balance (source.payin_id; a pay-in funds at most one remittance). The quote is used by the remittance from the moment it is created. The remittance never spends more than its pay-in credited. It is executed asynchronously and makes exactly one payout; while that payout's outcome is uncertain the remittance stays processing or review, and no second payout is ever made.
    - [Retrieve a remittance](/docs/api/remittances/get-remittance)
  - Reports: Read-only reports of a period: operations, fees, conversions and balances, as JSON or CSV.
    - [Run a report](/docs/api/reports/get-report): A read-only view of a period, never the authority for money (the ledger is). The answer says what it was computed from (source) and the instant it is complete up to (as_of). name is one of transactions, payins, payouts, remittances, refunds, withdrawals, settlements, fees, fx, balances. Row reports list what was created in [from, to), oldest first, in pages (pass next_cursor as after); balances is returned whole: per currency and balance, the opening at from, the credits and debits of the period and the closing at to, with opening + credits - debits = closing exactly. Every value is a string (amounts as decimal strings in the currency's precision, timestamps in UTC) or null. With format=csv the whole report is streamed as RFC 4180 CSV with a header row, as an attachment.
  - Sandbox: Sandbox-only helpers.
    - [Simulate a deposit into a funding account](/docs/api/sandbox/simulate-deposit): Sandbox only. The simulated provider reports a deposit; it is verified and credited through the same path as a real one. Not served in live.
  - Settlements: What the account is owed per period, and its transfer to the account's settlement destination.
    - [Read how the account is settled](/docs/api/settlements/get-settlement-configuration): Whether and how settlements are generated, for the account and per currency. The account's state is unconfigured when no schedule is in force in any currency: nothing is settled automatically and the balance stays available until you withdraw it or the platform puts a schedule in force. Per currency, state is unconfigured (no schedule in force), active (the schedule in force generates settlements as its frequency says; automatic is false for a manual schedule, whose settlements are generated only on request to the platform) or unexecutable (a schedule is in force but cannot be executed now; reason says why, e.g. no_destination; settlements that fall due wait and are generated once it can). currencies lists every currency the account holds a balance in or has a schedule for; with the currency parameter, that currency alone, whatever the account holds.
    - [List settlement schedules](/docs/api/settlements/list-settlement-schedules): The account's settlement terms per currency, as agreed in its contract: the one in force (status active) and those it replaced (closed), newest first. Read-only: a schedule carries the fee and the destination and is set by the platform; a change is a new schedule and applies from the period that is open: settlements that exist do not change. An empty list means no schedule was ever in force; GET /v1/settlement-configuration says so explicitly (unconfigured).
    - [List settlements](/docs/api/settlements/list-settlements): The periodic statements of what the account is owed, newest first. Each one is a closed (or still open) period of one currency: what accrued to the balance, the fee, the adjustments, and the net that is or was transferred to the account's settlement destination.
    - [Retrieve a settlement](/docs/api/settlements/get-settlement): With its items: the ledger journals its figures are made of.
  - Withdrawals: Your own funds to your own bank account: settlement destinations and withdrawals.
    - [List settlement destinations](/docs/api/withdrawals/list-settlement-destinations)
    - [Create a settlement destination](/docs/api/withdrawals/create-settlement-destination): Registers an account of your own that withdrawals go to. The same account registered twice is the same destination (200 with the existing one). Account details are write-only.
    - [Retrieve a settlement destination](/docs/api/withdrawals/get-settlement-destination)
    - [List withdrawals](/docs/api/withdrawals/list-withdrawals): Newest first.
    - [Create a withdrawal](/docs/api/withdrawals/create-withdrawal): Holds the amount plus the fee from the available balance and sends it to one of your settlement destinations, in the destination's currency, asynchronously. The fee is fixed when the withdrawal is created and stated in the response (fee, total); the balance must cover both. A withdrawal the balance cannot fund is created with status failed and failure_code insufficient_funds. Above the account's approval threshold it is created pending_approval and waits for the platform's operators. Repeating the request with the same Idempotency-Key returns the same withdrawal and never sends twice.
    - [Retrieve a withdrawal](/docs/api/withdrawals/get-withdrawal)

# Docs

- Guides: How to integrate Caibo Pay

  - **Get started**
  - [Introduction](/en/docs): One API to collect and pay out. One key, one webhook, one balance.
  - [Quickstart](/en/docs/quickstart): From zero to your first test pay-in credited to your balance, in sandbox.
  - [SDKs](/en/docs/sdks): Official libraries for Node.js and TypeScript, Python and Go. Generated from the same contract as this documentation.
  - [Sandbox and live](/en/docs/sandbox): Two separate environments with the same API. Test everything in sandbox; to go live you change only the key and the host.
  - [Go live](/en/docs/go-live): The checklist before you move real money.

  - **Concepts**
  - [What you can do](/en/docs/capabilities): GET /v1/capabilities is the map of your account. Countries, methods, and currencies are discovered there; they never get endpoints of their own.
  - [Authentication](/en/docs/authentication): One secret key per environment, sent as a Bearer token on every request.
  - [Idempotency](/en/docs/idempotency): Retry without fear. The same Idempotency-Key never collects or pays twice.
  - [Errors](/en/docs/errors): One error format, stable types, and codes you can rely on.
  - [Lists and pagination](/en/docs/pagination): Every list reads the same way. Stable pages, combinable filters, and logs in order.
  - [Amounts and currencies](/en/docs/money): Amounts are decimal strings with the exact precision of their currency. Never numbers.

  - **Collect**
  - [How to collect](/en/docs/collect): You open a pay-in, show your customer the instructions, they pay, and the money lands in your balance.
  - [Collect an exact amount](/en/docs/collect-one-payment): A one-time payment for your order amount. PIX in Brazil and bank transfer in Peru.
  - [Credited pay-ins](/en/docs/payins): The payin resource is a payment that came into one of your funding accounts, and what it credited to your balance.
  - [Hosted page](/en/docs/hosted-pages): A ready-made payment page, with your brand, that Caibo hosts for you on pay.caibopay.app or on your own domain.
  - [Refunds](/en/docs/refunds): Return all or part of a pay-in to the payer, from your balance.

  - **Pay out**
  - [How to pay out](/en/docs/pay-out): From your account balance to a bank account, PIX, or mobile payment, with the price locked before you pay.
  - [Customers](/en/docs/customers): The people and businesses you act on behalf of. They are the sender of a payout when the country requires one.
  - [Beneficiaries](/en/docs/beneficiaries): The account you pay. You register it once and pay it as many times as you want.
  - [Quotes](/en/docs/quotes): Lock the price of a payout before you make it. You know what leaves and what arrives, all included.
  - [Payouts](/en/docs/payouts): The payout resource, its statuses, how to cancel it, and what to do when it fails.
  - [Payout batches](/en/docs/payout-batches): Up to 1000 payouts in a single request, each with its own status and events.
  - [Remittances](/en/docs/remittances): A pay-in in one currency and a payout in another, at a single price.

  - **Your balance**
  - [Balances](/en/docs/balances): One balance per currency, with every movement explained.
  - [Withdrawals](/en/docs/withdrawals): Move your balance to an account of your own whenever you want.
  - [Settlements](/en/docs/settlements): Your money sent to your account on a schedule agreed with Caibo.
  - [Reports](/en/docs/reports): Your operations in JSON or CSV, by period, ready for your accounting.

  - **Webhooks and events**
  - [Webhooks](/en/docs/webhooks): We notify you instantly of every change. Signed, retried, and in order.
  - [Verify the signature](/en/docs/webhook-signatures): Confirm that every webhook comes from Caibo and wasn't tampered with. Ready-to-use code in Node.js, Python, and Go.
  - [Events](/en/docs/events): Everything that happens in your account, as an ordered log. The same thing you receive by webhook.

  - **Coverage**
  - [Countries and methods](/en/docs/coverage): Where you collect and pay out with Caibo Pay, and how to always know it from the API.

  - **AI**
  - [Build with AI](/en/docs/ai): These docs are built for agents too. Connect your assistant and let it integrate for you, correctly.
- API reference: OpenAPI
  - Account: Who the credential is: the account, its environment and the key in use.
    - [Retrieve the account of the credential](/en/docs/api/account/get-account): Who the credential is: the account it belongs to, the environment that answered (sandbox or live) and the credential itself, without its secret. Use it to check a key and to show which account and environment a client is working in. The credential is an API key: there are no user identities (people, roles, single sign-on) yet, so nothing here describes a person.
    - [Who is calling](/en/docs/api/account/get-me): Who the credential of the request is: an API key (kind api_key) or a member of the account, a person signed in to the dashboard through its identity provider (kind member), with the account it acts for and its scopes. A member's role and scopes are the platform's: a client reads them here, never from the identity provider. For a member it also lists every account the person may act for; send the Caibo-Account header (acct_…) to act for another one. A person signed in to the dashboard who is no active member of an active account is answered 403 no_membership, one answer whatever the reason; this route binds the person's open invitations first. A dashboard session token is accepted only by this API, an operator console's never.
  - Balances: Funds per currency, by how usable they are, and the statement behind them.
    - [List balances](/en/docs/api/balances/list-balances): The account's money per currency, by how usable it is. Every figure is read from the ledger; total = available + pending + reserved + in_settlement. Earnings are shown apart and not added.
    - [List the statement of a currency](/en/docs/api/balances/list-balance-entries): Every movement on the account's balances in a currency, newest first: one entry per ledger posting on one of the account's own balances, with the operation it belongs to. Pass next_cursor as after to continue; the statement is walked without gaps or repeats.
  - Beneficiaries: Who is paid.
    - [List beneficiaries](/en/docs/api/beneficiaries/list-beneficiaries): Newest first.
    - [Create a beneficiary](/en/docs/api/beneficiaries/create-beneficiary): Registers who is paid. The same account registered twice for the same customer is the same beneficiary (200 with the existing one). Account details are write-only. The country is the method's when the method has one.
    - [Retrieve a beneficiary](/en/docs/api/beneficiaries/get-beneficiary)
  - Capabilities: What the account can do.
    - [List what the account can do](/en/docs/api/capabilities/list-capabilities): The products (payin, payout, remittance), methods, currencies and countries available to the account, with the fields each one requires and whether it can be used right now. Countries and rails are discovered here; they never have endpoints of their own.
  - Customers: The people and businesses you act for.
    - [List customers](/en/docs/api/customers/list-customers): Newest first. The profile is not in a list; retrieve a customer for it.
    - [Create a customer](/en/docs/api/customers/create-customer): Registers a person or business you act for, under your own external_id. The same external_id sent again with the same identity (type, country, display_name, profile) returns the existing customer (200); with a different identity it is a 409 conflict. metadata is yours and is not compared.
    - [Retrieve a customer](/en/docs/api/customers/get-customer)
    - [Update a customer's metadata or close it](/en/docs/api/customers/update-customer): metadata replaces the whole object. status takes active or closed; closed is final. A blocked customer is blocked by the platform and cannot be reactivated here.
  - Events: What happened, in order.
    - [List events](/en/docs/api/events/list-events): Events in the order they became visible. Store next_cursor and pass it as after to poll; no event is ever skipped. With resource_id the list is the story of one resource, oldest first: every status it went through, from its creation to its outcome. Filters combine, and the cursor works the same with them.
    - [Retrieve an event](/en/docs/api/events/get-event)
  - Webhooks: Events pushed to your servers, signed.
    - [Send an event to webhook endpoints again](/en/docs/api/webhooks/redeliver-event)
    - [List webhook endpoints](/en/docs/api/webhooks/list-webhook-endpoints)
    - [Create a webhook endpoint](/en/docs/api/webhooks/create-webhook-endpoint): The response carries the signing secret. It is shown only here and after a rotation.
    - [Retrieve a webhook endpoint](/en/docs/api/webhooks/get-webhook-endpoint)
    - [Update, pause or resume a webhook endpoint](/en/docs/api/webhooks/update-webhook-endpoint)
    - [Delete a webhook endpoint](/en/docs/api/webhooks/delete-webhook-endpoint)
    - [List recent deliveries to an endpoint](/en/docs/api/webhooks/list-webhook-deliveries)
    - [Send a test event](/en/docs/api/webhooks/ping-webhook-endpoint)
    - [Rotate the signing secret](/en/docs/api/webhooks/rotate-webhook-secret): Returns the new secret. For a grace period deliveries are signed with both the new and the previous secret.
  - Funding: Money in: funding accounts and the pay-ins that arrive through them.
    - [Create a funding account](/en/docs/api/funding/create-funding-account): An account the balance is funded through. It is created pending; its payment instructions are available once it is active (event funding_account.active). With amount it is one payment of exactly that amount (collection payment in GET /v1/capabilities): the payer pays the amount and nothing more, and the account closes once it is paid; the pay-in that credits it is payin.completed.
    - [Retrieve a funding account](/en/docs/api/funding/get-funding-account)
    - [List pay-ins](/en/docs/api/funding/list-pay-ins): Newest first. refunded and refundable are not in a list; retrieve a pay-in for them.
    - [Retrieve a pay-in](/en/docs/api/funding/get-pay-in): A credited pay-in also says what it has given back (refunded) and what can still be refunded (refundable).
  - Hosted pages: The hosted remittance page: its configuration and branding, the hostnames it is served at, and the sessions your customers go through.
    - [List hosted domains](/en/docs/api/hosted-pages/list-hosted-domains)
    - [Claim a hostname for the hosted page](/en/docs/api/hosted-pages/create-hosted-domain): Claims a hostname the page should be served at. The claim starts pending, with a verification_token to publish; the hostname serves the page only once the platform has verified it. A hostname with a live claim, yours or anybody's, is refused with hostname_taken.
    - [Retrieve a hosted domain](/en/docs/api/hosted-pages/get-hosted-domain)
    - [Remove a hosted domain](/en/docs/api/hosted-pages/delete-hosted-domain): The hostname stops serving the page at once and can be claimed again.
    - [Retrieve the hosted page configuration](/en/docs/api/hosted-pages/get-hosted-page): How the account's hosted remittance page is configured. An account that never configured it gets the defaults, with no id.
    - [Replace the hosted page configuration](/en/docs/api/hosted-pages/put-hosted-page): Replaces the whole configuration; a field left out is reset to its default. The theme is data, validated here: colours are #rrggbb, the radius is one of a fixed scale, the font is the key of a font the page ships, and URLs are https. branding_mode white_label needs the entitlement (white_label_entitled), which the platform grants; it is refused with white_label_not_entitled otherwise.
    - [List hosted sessions](/en/docs/api/hosted-pages/list-hosted-sessions): Newest first, those your customers started from the page included. Never with a token. A session's status is read off its remittance and its expiry when you ask, so the list is not filtered by it.
    - [Create a hosted session](/en/docs/api/hosted-pages/create-hosted-session): Starts a session of the hosted remittance flow for one of your customers. The response carries the session token and the path the hosted page serves it at (/s/<token>); they are shown only here. Send the customer to that path on your page's host: the same link is where they follow the remittance afterwards. A session creates at most one remittance, ever. Repeating the request with the same Idempotency-Key returns the same session, without the token. The hosted page must be enabled.
    - [Retrieve a hosted session](/en/docs/api/hosted-pages/get-hosted-session): With the ids of what the session holds: its customer, beneficiary, quote, funding account and remittance. payment_reported_at is when the customer said they paid; it is a statement, not a confirmation: follow the remittance and its pay-in for that.
  - Members: The people who act for the account through the dashboard, and their invitations.
    - [List the account's members](/en/docs/api/members/list-members): The people who act for the account through the dashboard, and the open invitations, newest first. A member's role maps to scopes: owner, admin and developer hold read and write, viewer read.
    - [Invite a person](/en/docs/api/members/create-member): Invites an e-mail address with a role. The invitation expires after 7 days; it is bound at the person's first signed-in call to the person whose verified primary address it is, and the member becomes active. Inviting an address that was invited and never signed in renews its invitation (200). Only a signed-in owner or admin invites, and only an owner invites an owner: an API key does not manage people (403 insufficient_role). An address that is already a member is 409 member_exists.
    - [Change a member's role or disable it](/en/docs/api/members/update-member): status disabled refuses the member's next request at once, whatever its session; active enables it again (only a member that signed in once). Only a signed-in owner or admin changes members, not their own; only an owner touches an owner; the account keeps at least one active owner (409 last_owner). Withdraw an invitation by disabling it.
  - Payouts: Money out.
    - [List payout batches](/en/docs/api/payouts/list-payout-batches): Newest first, each with its summary, totals and cancellation as they are now. A batch accepted while you page never shifts or repeats the pages that follow.
    - [Create a payout batch](/en/docs/api/payouts/create-payout-batch): Accepts up to 1000 payouts in one request. Every item is checked for form first: one malformed item refuses the whole batch (400, param items[i].field) and nothing is created. The batch is then accepted and each item becomes, asynchronously and at most once, an ordinary payout with its own status and events, in index order. An item that cannot be paid does not stop the others: it is refused (status refused, error_code) when it never became a payout, or its payout fails (insufficient_funds) as a single payout would. A quote named by an item is used by that item from the moment the batch is accepted. A payout kill switch for the account refuses the whole batch (503). Repeating the request with the same Idempotency-Key returns the same batch and creates nothing.
    - [Retrieve a payout batch](/en/docs/api/payouts/get-payout-batch): With its summary and totals, computed from its payouts as they are now. A payout whose outcome is not yet certain is counted as uncertain (its item is verification_pending) and keeps the batch processing; it is never sent again.
    - [Cancel a payout batch](/en/docs/api/payouts/cancel-payout-batch): Asks for the batch to be cancelled. Nothing that was sent is reversed. The request is recorded at once and carried out asynchronously, item by item: an item not yet issued is cancelled; an item whose payout has provably not reached a provider is cancelled with its payout (the payout fails with failure_code cancelled_before_submission and its funds are available again); every other item keeps its state, with not_cancelled_reason saying why (in_review, submitted, outcome_uncertain, already_completed, already_failed, already_returned, already_refused). A payout whose outcome is uncertain is never cancelled and never sent again. The answer is the batch as it is now: cancellation.status is in_progress until every item has its decision (event payout_batch.cancellation_finished); the batch then ends cancelled (no payout was executed), partially_cancelled (some were) or, when nothing could be cancelled, completed or completed_with_failures. Asking again, or for a batch that is already finished, changes nothing and returns the batch as it is.
    - [List the items of a payout batch](/en/docs/api/payouts/list-payout-batch-items): In index order, each with its payout's status now, why it was refused, or what the batch's cancellation decided about it.
    - [List payouts](/en/docs/api/payouts/list-payouts): Newest first. A list carries the payout without its detail (description, country, completed_at, failed_at, returned_at); retrieve a payout for it.
    - [Create a payout](/en/docs/api/payouts/create-payout): Reserves the funds and accepts the payout; it is executed asynchronously. A payout the balance cannot fund is created with status failed and failure_code insufficient_funds. Repeating the request with the same Idempotency-Key returns the same payout and never pays twice.
    - [Retrieve a payout](/en/docs/api/payouts/get-payout): With its detail: your own description, the country of the beneficiary's account, when it completed, failed, was returned or was cancelled, and its latest cancellation if one was asked for. Its story, step by step, is GET /v1/events?resource_id={id}. A payout whose submission's outcome is uncertain is verification_pending: its funds stay reserved, it is being verified with the provider, and nothing sends it again or in its place; it ends completed or failed on the provider's evidence. No request retries or cancels it.
    - [Cancel a payout that was never sent](/en/docs/api/payouts/cancel-payout): Asks for a payout to be cancelled. Only a payout nothing of which can have reached a provider is cancelled: it is processing, it was never sent (or every send is proven never to have left) and it is not waiting for a risk review. A payout that was sent, may have been sent (verification_pending), is final, waits for a risk review, or belongs to a payout batch or a remittance is refused with 409 payout_not_cancellable, reasons saying why (submitted, outcome_uncertain, already_completed, already_failed, already_returned, in_review, managed_by_batch, managed_by_remittance); nothing changes. The request is recorded at once and decided by the platform, under the payout's lock, before the payout would be sent: the answer is 202 with cancellation.status requested. Once cancelled, the payout's status is cancelled (failure_code cancelled_before_submission), its funds are available again and payout.cancelled is published; asking again, with any key, answers 200 with the cancelled payout. If the payout was sent in the meantime, cancellation.status becomes refused with not_cancelled_reason, and the payout goes on. Repeating the request with the same Idempotency-Key never cancels twice; the same key for another payout is 409 idempotency_key_reused.
  - Quotes: Frozen prices.
    - [Create a quote](/en/docs/api/quotes/create-quote): Freezes a price for a short time. A quote is used by at most one payout.
    - [Retrieve a quote](/en/docs/api/quotes/get-quote)
  - Reconciliation: Inconsistencies found about your operations, and where their investigation stands.
    - [List reconciliation exceptions](/en/docs/api/reconciliation/list-reconciliation-exceptions): Inconsistencies the platform found about your own operations (a pay-in, a payout, a withdrawal, a refund, a settlement or a remittance) and is working on, newest first. Read-only: the platform's operators investigate and close them.
    - [Retrieve a reconciliation exception](/en/docs/api/reconciliation/get-reconciliation-exception)
  - Refunds: Money given back: part or all of a credited pay-in sent back to its payer.
    - [List refunds](/en/docs/api/refunds/list-refunds): Newest first.
    - [Refund a pay-in](/en/docs/api/refunds/create-refund): Sends part or all of a credited pay-in back to its payer, from the available balance, through the provider that received it. Reserves the funds and accepts the refund; it is executed asynchronously. A refund the platform's risk controls hold for a review is created with status pending_review: its funds are reserved and it counts against what is left to refund, but nothing is sent until it is approved; a refund they refuse is a 422 risk_blocked. Omit amount to refund everything that is left. Repeating the request with the same Idempotency-Key returns the same refund and never refunds twice.
    - [Retrieve a refund](/en/docs/api/refunds/get-refund)
  - Remittances: Money in from a payer, out to a beneficiary, at a quoted price.
    - [List remittances](/en/docs/api/remittances/list-remittances): Newest first. payin_id and payout_id find the remittance a pay-in funded or a payout pays: at most one.
    - [Create a remittance](/en/docs/api/remittances/create-remittance): Sends a quote's destination amount to a beneficiary, funded by a deposit: either the next deposit into a funding account (source.funding_account_id; the remittance awaits it and the deposit must be credited before the quote expires) or a pay-in that already credited the balance (source.payin_id; a pay-in funds at most one remittance). The quote is used by the remittance from the moment it is created. The remittance never spends more than its pay-in credited. It is executed asynchronously and makes exactly one payout; while that payout's outcome is uncertain the remittance stays processing or review, and no second payout is ever made.
    - [Retrieve a remittance](/en/docs/api/remittances/get-remittance)
  - Reports: Read-only reports of a period: operations, fees, conversions and balances, as JSON or CSV.
    - [Run a report](/en/docs/api/reports/get-report): A read-only view of a period, never the authority for money (the ledger is). The answer says what it was computed from (source) and the instant it is complete up to (as_of). name is one of transactions, payins, payouts, remittances, refunds, withdrawals, settlements, fees, fx, balances. Row reports list what was created in [from, to), oldest first, in pages (pass next_cursor as after); balances is returned whole: per currency and balance, the opening at from, the credits and debits of the period and the closing at to, with opening + credits - debits = closing exactly. Every value is a string (amounts as decimal strings in the currency's precision, timestamps in UTC) or null. With format=csv the whole report is streamed as RFC 4180 CSV with a header row, as an attachment.
  - Sandbox: Sandbox-only helpers.
    - [Simulate a deposit into a funding account](/en/docs/api/sandbox/simulate-deposit): Sandbox only. The simulated provider reports a deposit; it is verified and credited through the same path as a real one. Not served in live.
  - Settlements: What the account is owed per period, and its transfer to the account's settlement destination.
    - [Read how the account is settled](/en/docs/api/settlements/get-settlement-configuration): Whether and how settlements are generated, for the account and per currency. The account's state is unconfigured when no schedule is in force in any currency: nothing is settled automatically and the balance stays available until you withdraw it or the platform puts a schedule in force. Per currency, state is unconfigured (no schedule in force), active (the schedule in force generates settlements as its frequency says; automatic is false for a manual schedule, whose settlements are generated only on request to the platform) or unexecutable (a schedule is in force but cannot be executed now; reason says why, e.g. no_destination; settlements that fall due wait and are generated once it can). currencies lists every currency the account holds a balance in or has a schedule for; with the currency parameter, that currency alone, whatever the account holds.
    - [List settlement schedules](/en/docs/api/settlements/list-settlement-schedules): The account's settlement terms per currency, as agreed in its contract: the one in force (status active) and those it replaced (closed), newest first. Read-only: a schedule carries the fee and the destination and is set by the platform; a change is a new schedule and applies from the period that is open: settlements that exist do not change. An empty list means no schedule was ever in force; GET /v1/settlement-configuration says so explicitly (unconfigured).
    - [List settlements](/en/docs/api/settlements/list-settlements): The periodic statements of what the account is owed, newest first. Each one is a closed (or still open) period of one currency: what accrued to the balance, the fee, the adjustments, and the net that is or was transferred to the account's settlement destination.
    - [Retrieve a settlement](/en/docs/api/settlements/get-settlement): With its items: the ledger journals its figures are made of.
  - Withdrawals: Your own funds to your own bank account: settlement destinations and withdrawals.
    - [List settlement destinations](/en/docs/api/withdrawals/list-settlement-destinations)
    - [Create a settlement destination](/en/docs/api/withdrawals/create-settlement-destination): Registers an account of your own that withdrawals go to. The same account registered twice is the same destination (200 with the existing one). Account details are write-only.
    - [Retrieve a settlement destination](/en/docs/api/withdrawals/get-settlement-destination)
    - [List withdrawals](/en/docs/api/withdrawals/list-withdrawals): Newest first.
    - [Create a withdrawal](/en/docs/api/withdrawals/create-withdrawal): Holds the amount plus the fee from the available balance and sends it to one of your settlement destinations, in the destination's currency, asynchronously. The fee is fixed when the withdrawal is created and stated in the response (fee, total); the balance must cover both. A withdrawal the balance cannot fund is created with status failed and failure_code insufficient_funds. Above the account's approval threshold it is created pending_approval and waits for the platform's operators. Repeating the request with the same Idempotency-Key returns the same withdrawal and never sends twice.
    - [Retrieve a withdrawal](/en/docs/api/withdrawals/get-withdrawal)