---
title: codespar_charge
description: Inbound charges — buyer pays merchant. 19 provider rails — Pix/boleto/card/wallet across BR, MX, PE, CO, CL, AR + USD. Async settlement, uniform payload.
---

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

# codespar_charge

<Callout title="Meta-tool" type="info">
**Sell-side.** Your agent is the merchant: it collects from, invoices, ships to, or verifies a counterparty.

`codespar_charge` is 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. Covered by `session.charge(args)` typed wrapper.
</Callout>

Charge is **async**. The call returns immediately with the payment artifact (Pix copy-paste, Stripe Checkout URL, etc.) plus a `tool_call_id`. Wait for settlement via `paymentStatus(toolCallId)` or `paymentStatusStream(toolCallId)`. The common downstream pattern is: charge → wait for settlement → invoice + ship + notify.

## Rails

| Rail | Currency | Country | Providers |
|---|---|---|---|
| Pix | BRL | BR | **Asaas** (default), Mercado Pago, EBANX, iugu, Stone |
| Card | BRL | BR | Getnet, PagSeguro, Rede |
| 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 |

19 provider rails. Asaas Pix returns `pix_copy_paste` synchronously; iugu (create_invoice) and Stone (create_pix_charge) are the two newest BR Pix charge rails; Stripe ACP and the LATAM card rails return a hosted checkout URL the agent surfaces to the buyer. The router fails over within a rail (e.g. Pix BRL: Asaas → Mercado Pago).

## Typed wrapper (TS / Python)

<Tabs items={["TypeScript", "Python"]}>

```ts tab="TypeScript"
const charge = await session.charge({
  amount: 9990,
  currency: "BRL",
  method: "pix",
  description: "Order #1234",
  buyer: {
    name: "Maria Silva",
    document: "12345678900",
    phone: "+5511999998888",
  },
  metadata: { order_id: "1234" },
});

console.log(charge.id, charge.pix_copy_paste, charge.tool_call_id);
```

```python tab="Python"
charge = session.charge({
    "amount": 9990,
    "currency": "BRL",
    "method": "pix",
    "description": "Order #1234",
    "buyer": {
        "name": "Maria Silva",
        "document": "12345678900",
        "phone": "+5511999998888",
    },
    "metadata": {"order_id": "1234"},
})

print(charge["id"], charge["pix_copy_paste"], charge["tool_call_id"])
```

</Tabs>

## Direct execute

```ts
const charge = await session.execute("codespar_charge", {
  amount: 9990,
  currency: "BRL",
  method: "pix",
  description: "Order #1234",
  buyer: { name: "Maria Silva", document: "12345678900", phone: "+5511999998888" },
});
```

## Args shape

| Field | Type | Required | Description |
|---|---|---|---|
| `amount` | `number` | Yes | Amount in smallest currency unit |
| `currency` | `string` | Yes | `BRL` for Pix; `USD` for card |
| `method` | `string` | Yes | `pix` or `card` |
| `description` | `string` | Yes | Shown to the buyer on the invoice / checkout page |
| `buyer` | `object` | Yes | `{ name, document, phone, email? }` |
| `metadata` | `object` | No | Arbitrary key-value pairs persisted on the `tool_calls` row |

## Result shape

Uniform across providers — the backend normalizes the per-PSP response into a single envelope:

```ts
type ChargeResult = {
  id: string;                      // provider's payment id
  tool_call_id: string;            // CodeSpar correlation id
  pix_copy_paste?: string;         // Pix BRL only
  qr_code_url?: string;            // Pix BRL only
  checkout_url?: string;           // Stripe Checkout / Stripe ACP rails
  status: "pending";               // always pending; terminal state via paymentStatus
  expires_at?: string;             // ISO 8601
};
```

## Operator setup

Each rail expects credentials in `/dashboard/auth-configs`:

- **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` scope. The same key handles both regular charges and ACP `create_checkout_session`.

## Async settlement

`codespar_charge` returns the artifact immediately so the buyer can pay; the merchant must wait for the webhook to know it settled. Pattern:

```ts
const charge = await session.charge({ method: "pix", amount: 9990, currency: "BRL", ... });
// 1. Show pix_copy_paste / checkout_url to the buyer

// 2. Poll until terminal:
let status = await session.paymentStatus(charge.tool_call_id);
while (status.status === "pending") {
  await new Promise((r) => setTimeout(r, 2000));
  status = await session.paymentStatus(charge.tool_call_id);
}

// 3. Now status.status === "succeeded" — issue invoice, ship, notify.
```

See [async settlement](/docs/concepts/async-settlement) for the full correlation chain (the Mercado Pago `external_reference` GET-back caveat in particular). Use [`paymentStatusStream`](/docs/api/sdk#paymentstatusstreamtoolcallid-options) when you need sub-second latency to terminal — e.g. live UX or boleto.

## See also

- [codespar_pay](/docs/concepts/meta-tools/pay) — outbound counterpart
- [Async settlement](/docs/concepts/async-settlement) — correlation + webhook flow
- [SDK reference](/docs/api/sdk#chargeargs-promisechargeresult) — `session.charge()` typed wrapper
- [E-Commerce Checkout cookbook](/docs/cookbooks/ecommerce-checkout) — charge → invoice → ship → notify
- [Tools & meta-tools](/docs/concepts/tools) — full meta-tool list