Skip to main content

Issue a charge for a receivable

POST 
/receivables/:id/charge

Issues a bank slip or a Pix charge on the gateway so the customer has something to pay, and mirrors it onto the receivable. Requires scope finance.receivables.charge — a dedicated action scope, never bundled into .write, and the read god-scope finance.all does not satisfy it. An X-Idempotency-Key header is required: a duplicate charge is a second debt your customer receives.

⚠️ The charge in the response is not deliverable yet. Registration at the institution is asynchronous, so it comes back charge_state: "registering" — a bank slip does not exist at the bank yet and a Pix has no kobana_pix_qrcode. Poll GET /receivables/{id} until charge_state is registered before sending anything to the payer. There is no refresh endpoint on purpose: the mirror is kept current by a background poll and by the gateway's webhook, and a per-call re-read would burn the same hourly request budget the rest of the integration shares.

The two rails differ in what they require of the payer — a bank slip needs their full address, a Pix only name and document — and in what must be registered on the gateway account (an agreement vs. a Pix charging account). A missing piece comes back as 422 naming it; a state that forbids charging comes back as 409.

Request​

Responses​

Charge issued. The body is the refreshed receivable detail with the charge mirror populated (charge_state will read registering).