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

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. 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
• Async settlement: correlation and webhook flow
• E-Commerce Checkout cookbook: charge → invoice → ship → notify

Notes

Rails and providers, as previously documented

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 (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.