codespar_charge

The inbound counterpart to codespar_pay. Use it for ecommerce checkout, marketplace order capture, and any flow where money comes IN.

Actions

Example

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

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

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"
});

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

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

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:

• 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 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

Errors and what to do

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.

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: the outbound counterpart, and the tool that settles an existing boleto
• codespar_checkout: a cart summed into a charge with a hosted payment page
• codespar_invoice: the fiscal document after settlement
• Triggers: commerce.charge.created, commerce.charge.paid, and why commerce.charge.payment_notified is not the same thing
• Async settlement: correlation and webhook flow
• E-Commerce Checkout cookbook: charge → invoice → ship → notify

Notes

Rails and providers, as previously documented

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.

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); 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 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.

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.