---
title: codespar_charge
description: Inbound charges, the buyer pays the merchant. An immediate Pix, a cobrança com vencimento (boleto or Pix, with a due date), hosted card checkout or a wallet redirect; then read or cancel what you issued.
---

import { Callout } from "fumadocs-ui/components/callout";
import { Tabs, Tab } from "fumadocs-ui/components/tabs";

<MetaToolHeader tool="codespar_charge" />

The inbound counterpart to [`codespar_pay`](/docs/concepts/meta-tools/pay). Use it for ecommerce checkout, marketplace order capture, and any flow where money comes IN.

## Actions

<MetaToolActions tool="codespar_charge" />

## Example

`action: "create"` (the default, so `action` may be omitted) of an immediate Pix charge.

<Split min={380}>
<SplitPane label="The same call, four ways">

<Tabs items={["MCP", "TypeScript", "Python", "CLI"]}>
<Tab value="MCP">

```json title="arguments"
{
  "name": "codespar_charge",
  "arguments": {
    "action": "create",
    "amount": 25,
    "currency": "BRL",
    "method": "pix",
    "description": "Example order",
    "buyer": {
      "name": "Example Buyer",
      "document": "00000000000",
      "email": "buyer@example.com"
    },
    "idempotency_key": "charge_0000"
  }
}
```

</Tab>
<Tab value="TypeScript">

```ts
const result = await session.execute("codespar_charge", {
  action: "create",
  amount: 25,
  currency: "BRL",
  method: "pix",
  description: "Example order",
  buyer: {
    name: "Example Buyer",
    document: "00000000000",
    email: "buyer@example.com"
  },
  idempotency_key: "charge_0000"
});
```

</Tab>
<Tab value="Python">

```python
result = session.execute("codespar_charge", {
  "action": "create",
  "amount": 25,
  "currency": "BRL",
  "method": "pix",
  "description": "Example order",
  "buyer": {
    "name": "Example Buyer",
    "document": "00000000000",
    "email": "buyer@example.com"
  },
  "idempotency_key": "charge_0000"
})
```

</Tab>
<Tab value="CLI">

```bash
codespar tool codespar_charge \
  -i '{
       "action": "create",
       "amount": 25,
       "currency": "BRL",
       "method": "pix",
       "description": "Example order",
       "buyer": {
         "name": "Example Buyer",
         "document": "00000000000",
         "email": "buyer@example.com"
       },
       "idempotency_key": "charge_0000"
     }'
```

</Tab>
</Tabs>

</SplitPane>
<SplitPane label="Result">

Result shape: see runtime. The tool document says an immediate Pix charge returns its copia-e-cola right away (it expires in the next hour or so), and that a cobrança com vencimento answers `status: "PROCESSING"` with `payable: false` and no document yet; it names no other field. The published document is [`/v1/meta-tools.json`](https://api.codespar.dev/v1/meta-tools.json).

</SplitPane>
</Split>

`amount` here is in the **major** unit (R$ 125.00 → `125`), unlike `codespar_pay`, which takes minor units.

## When to use

The two Brazilian instruments are not two flavours of the same thing, and picking the wrong one is the most common way this tool disappoints:

| you pass | you get | good for |
|---|---|---|
| `method: "pix"` | an **immediate** Pix charge: a copia-e-cola returned right away, expiring in about an hour | someone paying now, in front of you |
| `method: "boleto"` + `due_date` | a **cobrança com vencimento**: ONE receivable the payer settles either as a boleto (barcode + linha digitável) **or by Pix** | an instalment, a debt agreement, any invoice with a date |

- **An agreement in N instalments is N cobranças com vencimento**, one per parcela, each with its own `due_date` and its own `idempotency_key`. There is no single "parcelado" charge: each parcela stands on its own, can be paid or cancelled on its own, and fires its own `commerce.charge.paid`.
- **A cobrança com vencimento is not payable the instant you create it.** It is registered with the banking clearing house first, so `create` answers `status: "PROCESSING"` with no document and `payable: false`. The barcode and the Pix code arrive about 30 seconds later, occasionally up to an hour. Do not read the empty barcode as a failure: subscribe a [trigger](/docs/concepts/triggers) to `commerce.charge.created`, or poll `action: "status"`.
- **The key is the debt.** A cobrança com vencimento requires `idempotency_key`, and the key is reserved before the issuer is called: two calls under one key issue once, and a retry gets the same charge back. When the issuer's answer is lost (a timeout, a dropped connection) the key is kept, not freed: the result names it, a retry with the same key answers `issuance_unconfirmed: true` with `id: null` and issues nothing, and `commerce.charge.created` (or `action: "status"` with the key) resolves it once the clearing house registers the charge. To issue a second receivable on purpose, use a new key. The instrument is issued by one issuer and never falls over to another: a refusal is reported, not routed around.
- **`status` and `cancel` serve the cobrança com vencimento only.** An immediate Pix charge hands you its copia-e-cola at create time and expires on its own; there is nothing to read back or withdraw.
- **Card and wallet**: `method: "card"` returns a hosted checkout URL the agent surfaces to the buyer; `method: "wallet"` is a digital-wallet redirect (PicPay in Brazil).

## Arguments

| Field | Type | Required | Description |
|---|---|---|---|
| `action` | `string` | No | `create` (the default when omitted) \| `status` \| `cancel` \| `recurrence_status` \| `recurrence_list` \| `recurrence_instruct` \| `recurrence_instruct_cancel` \| `recurrence_retry` \| `recurrence_cancel` \| `recurrence_cycle_cancel` (the Pix Automático recurrence actions, see Notes) |
| `amount` | `number` | For `create` | Major currency unit (R$ 125.00 → `125`) |
| `currency` | `string` | For `create` | `BRL`, `USD`, `EUR` |
| `method` | `string` | For `create` | `pix`, `boleto`, `card`, `wallet`. In Brazil the instrument follows `method` plus `due_date` (table above) |
| `description` | `string` | For `create` | Shown to the buyer |
| `buyer` | `object` | For `create` | `{ name, email, document, phone }`. For a BR due-dated charge `document` is required and must be a real CPF/CNPJ: the clearing house validates its check digit, and the charge names who owes it |
| `due_date` | `string` | No | `YYYY-MM-DD` (a full ISO-8601 instant is narrowed to the date). With `method: "boleto"` issues the cobrança com vencimento; the immediate Pix charge has no due date and refuses one |
| `country` | `string` | No | ISO 3166-1 alpha-2 for the eligibility rail (`BR`, `US`, `MX`, `AR`, `CL`, `CO`, `INTL`). Defaults to `BR`; `US` for cross-border USD card via Stripe ACP, `INTL` for hosted-checkout flows |
| `charge_id` | `string` | For `status`, `cancel` | The id `create` returned. Resolved against the charges this project issued, so an id from elsewhere is simply not found |
| `idempotency_key` | `string` | For `create` of a cobrança com vencimento | Stable caller key that identifies the debt. Required with `method: "boleto"` + `due_date`: a repeat with the same key returns the charge already issued (or its still-open reservation, see `issuance_unconfirmed`) instead of a second one, and a call without it is refused before anything is sent. On `status` and `cancel` it can stand in for `charge_id` |
| `metadata` | `object` | No | Provider-specific overrides |
| `consumer_id` | `string` | For `create` of a cobrança com vencimento without a session user | The merchant-side consumer the charge settles into (its wallet is credited when the payer pays); refused as `consumer_id_required` when missing and nothing can stand in. With a `recurrence`, the receiving legal person |
| `recurrence` | `object` | No | On `create`: a Pix Automático recurrence instead of a one-off charge. `{ frequency (WEEKLY \| MONTHLY \| QUARTER \| SEMESTER \| YEARLY), start_date, end_date?, contract { number, description? }, amount (FIXED) or min_amount (VARIABLE), journey (1 push to the payer's bank, default; 2 QR with the recurrence; 3 QR that charges `amount` now and carries it), payer_account (journey 1), qr_expiration_seconds (2 and 3), retries, auto_instructions }`. `idempotency_key` is required with it. The receiver is a legal person with its own account; the payer is `buyer` and can bank anywhere |
| `mandate_id` | `string` | No | With a `recurrence`: the mandate of the receiving consumer the agent acts under, recorded beside the recurrence. On a VARIABLE recurrence its caps bound every cycle, and without one no VARIABLE cycle is sent |
| `recurrence_id` | `string` | For every `recurrence_*` action | The recurrence: the id `create` returned, its RR id, or its `idempotency_key`; resolved against this project's recurrences only (`recurrence_not_found` otherwise) |
| `end_to_end_id` | `string` | For `recurrence_retry`, `recurrence_cycle_cancel` | The cycle, by the endToEndId its instruction webhook named (also listed by `recurrence_status`). `recurrence_instruct` and `recurrence_instruct_cancel` take it or the cycle's `due_date` |
| `new_date` | `string` | For `recurrence_retry` | The new debit date, `YYYY-MM-DD`, within D+1..D+7 of the cycle's due date |
| `reason` | `string` | No | `recurrence_cancel`, `recurrence_cycle_cancel`: `CREDIT_PARTY_REQUEST` (default) \| `ACCOUNT_CANCELLATION` \| `CREDIT_PARTY_END_OF_ACTIVITIES` \| `PAYER_DEAD` \| `CONFIRMATION_ERROR` \| `FRAUD` \| `CONFIRMED_IN_OTHER_JOURNEY` \| `DEBIT_PARTY_REQUEST` \| `TIMEOUT` |
| `change_to_next_working_day` | `boolean` | No | `recurrence_instruct`: move a due date on a non-working day to the next working day (default `true`) |
| `status` | `string` | No | `recurrence_list`: only recurrences in this status (for example `CONFIRMED`) |
| `limit` | `number` | No | `recurrence_list`: at most this many, newest first (default 50, max 200) |

## Errors and what to do

| Error | Cause | What to do |
|---|---|---|
| `invalid_args` | A `create` without `amount`, `currency`, `method`, `description` or `buyer`; a cobrança com vencimento without `idempotency_key`; a `due_date` on an immediate Pix; an unknown `action`; a `cancel` on a key whose issuance is still unconfirmed. Nothing is issued. | Fix the call against the Arguments table. For the unconfirmed key, wait for `commerce.charge.created` or poll `status`, then cancel by id. |
| `no_eligible_providers` | The `method` × `currency` × `country` intent has no catalog line, or none of its providers is connected. Nothing is issued. | See the rails in Notes; connect the provider via [`codespar_manage_connections`](/docs/concepts/meta-tools/manage-connections). |
| A refused `cancel` on a `PROCESSING` charge | The clearing house accepts a cancellation only while the charge is `PENDING`; a still-registering charge is refused, and a paid charge cannot be withdrawn. | Retry once it registers (poll `status`). |
| `issuance_unconfirmed: true` in the result | The issuer's answer to a `create` under this key was lost; the key is held so a retry cannot issue a second receivable for the same debt. `id` is `null` and `payable` is `false`. | Wait for `commerce.charge.created`, or poll `status` with the same `idempotency_key`. Use a new key only if you mean a second charge. |
| An empty barcode right after `create` | Not an error: the cobrança com vencimento is registering. | Wait for `commerce.charge.created` or poll `status`. |
| `local_status: "failed"` with `failure.code: "issuer_rejected"` (`status: "ERROR"`) | The issuer refused to register the charge. No boleto and no Pix were ever generated, so nobody could pay it and nothing was charged. The charge is closed for good and `commerce.charge.failed` was sent once. Waiting does not change it: a slow registration shows `PROCESSING`, never this. | Issue a new charge. Keep the failed one's id for your records; its history stays readable. |

## Money and mandate

No money moves on this tool. `create` issues a receivable (a copia-e-cola, a boleto, a checkout URL) that the buyer settles later; `commerce.charge.paid` fires when they do, by either leg, and it is the event that means the funds are in the account. CodeSpar sends it only after it has settled the charge and credited the wallet, and once per charge.

Do not act on anything earlier than that. A boleto payment can be preceded by `commerce.charge.payment_notified`, the clearing house's operational baixa, which the issuer says explicitly is not proof of payment. Every convênio has a daily cut-off, so a boleto paid after it is notified on one day and credited on the next business day; the notification carries `liquidation_date` if you want to tell the payer when. There is no consumer mandate on the sell side: the operator's connected rail authorizes issuance. The idempotency rule is what protects the buyer from paying twice: a retry of a cobrança com vencimento with the same key returns the same charge, and only a cobrança com vencimento is replayed; retrying an immediate Pix, card or wallet `create` issues a new charge.

## Related

- [`codespar_pay`](/docs/concepts/meta-tools/pay): the outbound counterpart, and the tool that settles an existing boleto
- [`codespar_checkout`](/docs/concepts/meta-tools/checkout): a cart summed into a charge with a hosted payment page
- [`codespar_invoice`](/docs/concepts/meta-tools/invoice): the fiscal document after settlement
- [Triggers](/docs/concepts/triggers): `commerce.charge.created`, `commerce.charge.paid`, `commerce.charge.failed`, and why `commerce.charge.payment_notified` is not the same thing
- [Async settlement](/docs/api/reference/sessions#async-settlement): correlation and webhook flow
- [E-Commerce Checkout cookbook](/docs/cookbooks/ecommerce-checkout): charge → invoice → ship → notify

## Notes

**Rails and providers, as previously documented**

<RoutingDiagram
  tool="codespar_charge"
  inputs={[
    { label: "method", value: "pix" },
    { label: "currency", value: "BRL" },
    { label: "country", value: "BR" },
  ]}
  providers={[
    { name: "Asaas", tag: "pix · br · default" },
    { name: "Mercado Pago", tag: "pix · br · failover" },
    { name: "Stark Bank", tag: "boleto · br" },
    { name: "Getnet", tag: "card · br" },
  ]}
  note="You never name the provider. The three inputs pick the catalog line; the line lists the connected providers, in order."
/>

You do not choose a provider, and there is no field to choose one with. `method` × `currency` × `country` selects a catalog line, and the line carries the providers that this project has connected, in order. The table below is that catalog.

Two consequences worth reading before the table. **Failover is within a rail, not across rails**: a Pix BRL charge that Asaas refuses is retried on Mercado Pago, and never silently becomes a boleto. And a combination with no catalog line, or whose providers are all unconnected, answers `no_eligible_providers` and **issues nothing** — it is not a partial charge to reconcile later.


| Rail | Currency | Country | Providers |
|---|---|---|---|
| Pix | BRL | BR | **Asaas** (default), Mercado Pago, EBANX, iugu, Stone |
| Boleto | BRL | BR | Stark Bank |
| Card | BRL | BR | Getnet, PagSeguro, Rede, Rinne |
| Card | USD | US | Stripe ACP |
| Card · hosted checkout | USD | US | Stripe ACP |
| Card | USD | INTL | Circle |
| Card | MXN | MX | Clip, Kushki |
| Card | PEN | PE | Izipay, Niubiz, Kushki |
| Card | COP | CO | Bold, ePayco, Kushki |
| PSE | COP | CO | Bold |
| Card | CLP | CL | Kushki |
| Card | ARS | AR | Payway |
| Card | USD | EC | Kushki |
| Wallet | BRL | BR | PicPay |
| Wallet | COP | CO | Nequi |

27 catalog lines over 21 providers, across seven countries (BR, MX, PE, CO, CL, AR, EC) plus US and the international USD corridor. The router fails over within a rail (Pix BRL: Asaas → Mercado Pago). The cobrança com vencimento runs on the licensed BaaS partner.

**Operator setup.** Asaas / Mercado Pago / iugu / Stone: API key (`api_key` auth_type), sandbox vs production toggle in the modal. Stripe: restricted key with `payment_intents:write`; the same key handles regular charges and ACP `create_checkout_session`.

**From the SDK.** `session.charge(args)` is the typed wrapper ([SDK reference](/docs/api/sdk/money#charge)); `session.execute("codespar_charge", arguments)` takes the same arguments as the MCP call. Settlement is asynchronous: poll `session.paymentStatus(tool_call_id)` until it leaves `pending`, or use [`paymentStatusStream`](/docs/api/sdk/status#paymentstatusstream) for sub-second latency to terminal.

**Result shape of a cobrança com vencimento**, read from the code that builds it (`bolepixOutputFromRow`, measured 11/09/2026). Every `create`, `status` and idempotent replay of a `method: "boleto"` + `due_date` charge answers this object.

| Field | What it is |
|---|---|
| `id` | The issuer's charge id. Null while the issuance is unconfirmed |
| `status` | The provider's state as far as we know it, normalized. Forced to `PROCESSING` until the issuance is confirmed |
| `local_status` | What CodeSpar recorded, which is a different question from the line above |
| `status_conflict` | True when the two disagree terminally, instead of one of them silently winning |
| `method`, `currency`, `amount`, `amount_minor`, `due_date` | The debt. `amount` is in units, `amount_minor` in centavos |
| `payable` | True only when all four hold: the issuance is confirmed, our row is still open, the provider says `PENDING`, and at least one document exists. This is the field to branch on, not `status` |
| `boleto_bar_code`, `boleto_bank_line`, `pix_copy_paste` | The two legs of the one debt. All null before registration |
| `credit_correlation_armed` | Whether an inbound Pix on this charge's Pix leg can resolve a wallet on its own. False until registration hands us the leg's identifier |
| `payment_in_flight` | True when a payment was notified and the receivable is still open. Read this before you write anything off |
| `issuance_unconfirmed` | True while the row is a reservation with no charge id: the issuer's answer to the create was lost, or a create is in flight elsewhere under the same key. Nothing is payable and nothing was duplicated |

Four fields appear only when they apply. `payment_notified_at`, `liquidation_date` and `payment_release_date` arrive together once the clearing house notifies a payment, and the last two are what you tell the payer when the credit lands. `issuance` and `next_action` appear only while `issuance_unconfirmed` is true, and `next_action` names the two ways out in words. `idempotent_replay` and `status_is_last_known` mark an answer served from the row with no provider call, so a stale `PROCESSING` does not read as a fresh one. `raw` carries the provider's own body on a live read.

**`payment_in_flight` exists because refusing to close a paid receivable is only half the job.** The issuer can answer `EXPIRED` for a boleto it already told us was paid: the baixa happened before the due date and the credit lands on the next business day. CodeSpar refuses to write that row off, but without this field a caller sees a clean `EXPIRED` with no disagreement flagged and writes it off itself, which is the same loss one layer up.

**The other methods' result shape has not been verified.** `{ id, tool_call_id, pix_copy_paste?, qr_code_url?, checkout_url?, status: "pending", expires_at? }` is what earlier revisions documented for an immediate Pix, card or wallet charge, and this revision did not re-read the runtime for those paths. Treat the table above as measured and that list as inherited.

### Pix Automático recurrences

A `create` with a `recurrence` block creates a recurrence instead of a one-off charge: the payer authorizes once at their own bank and every cycle is then debited with no new action from them. The receiver (`consumer_id`) is a legal person with its own account; the payer is `buyer` and can bank anywhere; `idempotency_key` is required, since a retry must be the same recurrence or the payer is asked twice. Journey 1 (default) pushes the request to the payer's banking app from `payer_account`; journey 2 returns a QR that carries only the recurrence; journey 3 returns a QR that charges `amount` now and carries the recurrence, and paying it is the acceptance.

The recurrence's state comes from the payer's bank through webhooks (`commerce.recurrence.requested` / `authorized` / `cancelled` / `denied`, and per cycle `commerce.recurrence.cycle.awaiting_instruction` / `scheduled` / `accepted` / `rejected` / `expired` / `cancelled` / `paid`); `commerce.recurrence.cycle.paid` is the one that means the money is in the consumer's wallet. A FIXED recurrence (`amount`) lets the bank send every cycle's instruction; a VARIABLE one (`min_amount`) needs `recurrence_instruct` for each cycle: from 10 calendar days to 2 business days before it is due the instruction is sent at once; earlier, or before the cycle is announced, it is queued (name the cycle by `due_date`) and sent inside that window, replaceable by instructing again or withdrawn with `recurrence_instruct_cancel` until then. A VARIABLE amount is held to the caps of the mandate the recurrence was created under (`mandate_id`) and to the payer's own ceiling: above any of them nothing is sent. A refused instruction is never re-sent by itself; a cycle that expires unpaid is retried only by `recurrence_retry` (up to 3 times, within 7 days, same amount) and only when `retries` was true. `recurrence_status` reads one recurrence with its cycles, `recurrence_list` the project's recurrences, `recurrence_cancel` ends one at the payer's bank, `recurrence_cycle_cancel` one scheduled cycle. None of these moves money by itself: the debit is the payer's bank's, on the cycle's date, and it is not guaranteed (the payer may cancel, a debit can fail for lack of balance). The journeys are in [Collect: recurring charges](/docs/concepts/collect).
