codespar_charge

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

Typed wrapper (TS / Python)

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

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

Direct execute

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

Result shape

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

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:

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 for the full correlation chain (the Mercado Pago external_reference GET-back caveat in particular). Use paymentStatusStream when you need sub-second latency to terminal — e.g. live UX or boleto.

See also

• codespar_pay — outbound counterpart
• Async settlement — correlation + webhook flow
• SDK reference — session.charge() typed wrapper
• E-Commerce Checkout cookbook — charge → invoice → ship → notify
• Tools & meta-tools — full meta-tool list