---
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="Call · tools/call">

```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"
  }
}
```

</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` |
| `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 |

## 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`. |

## 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. 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`
- [Async settlement](/docs/api/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**

| 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/session#chargeargs-promisechargeresult)); `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/session#paymentstatusstreamtoolcallid-options) for sub-second latency to terminal.

**Result shape (SDK), as previously documented.** `{ id, tool_call_id, pix_copy_paste?, qr_code_url?, checkout_url?, status: "pending", expires_at? }`. This revision did not re-verify that list against the runtime; the states the tool document itself names are `PROCESSING` and `payable: false` on a cobrança com vencimento, and `PENDING` as the only state a cancel is accepted in.