---
title: codespar_pay
description: Outbound spend. Money leaves the wallet or account your agent governs. 26 provider rails across BR (incl. 9 banks direct via mTLS), MX, PE, CL, CO, and international card/wire.
---

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

# codespar_pay

<Callout title="Meta-tool" type="info">
**Buy-side.** Your agent is the spender: money leaves the wallet/account your agent governs, under a signed mandate.

`codespar_pay` is the spend primitive. Use it whenever money leaves the wallet or account the agent governs and lands with a payee (a Pix key, a bank account, a card recipient): paying suppliers, marketplace payouts, refunds, and consumer spend under mandate. The agent specifies the recipient and the amount; CodeSpar picks the rail.
</Callout>

Collecting FROM a buyer instead? That is [`codespar_charge`](/docs/concepts/meta-tools/charge) (sell-side).

Pay is **async**. The call returns immediately with a `tool_call_id` and `idempotency_key`; settlement is correlated by the [async settlement chain](/docs/concepts/async-settlement). Poll `paymentStatus(toolCallId)` or stream `paymentStatusStream(toolCallId)` until terminal.

## Rails

| Rail | Currency | Country | Providers |
|---|---|---|---|
| Pix | BRL | BR | **Asaas** (default), Mercado Pago, a licensed Brazilian BaaS provider — plus **9 banks direct via mTLS**: Banco do Brasil, Itaú, Bradesco, Santander, Caixa, Sicoob, Sicredi, C6, Original |
| Card | BRL | BR | Cielo (+ 3DS), Pagar.me |
| Boleto | BRL | BR | Stark Bank |
| Card | MXN | MX | Conekta |
| Card | PEN | PE | Culqi |
| Card | CLP | CL | Transbank |
| Card | COP | CO | Wompi |
| Bank transfer | COP | CO | Cobre |
| Wire | CLP | CL | Khipu |
| Card · hosted checkout | USD / EUR | US / INTL | Stripe ACP, Adyen, Airwallex, dLocal, Rapyd |

26 provider rails across six countries. The router fails over **within a rail** when the primary provider degrades — e.g. Pix BRL walks Asaas → Mercado Pago → a direct bank. See `/dashboard/router` for live failover telemetry. The 9 Brazilian banks connect over mTLS (client certificate) for direct-from-account Pix; see [cert auth](/docs/concepts/cert-auth).

## Direct execute

There is no typed wrapper for `codespar_pay` yet — call via `session.execute()`.

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

```ts tab="TypeScript"
const result = await session.execute("codespar_pay", {
  amount: 25000,
  currency: "BRL",
  method: "pix",
  recipient: {
    document: "12345678900",
    pix_key: "vendor@example.com",
  },
  idempotency_key: crypto.randomUUID(),
});
console.log(result.tool_call_id, result.status); // "pending"
```

```python tab="Python"
import uuid

result = session.execute("codespar_pay", {
    "amount": 25000,
    "currency": "BRL",
    "method": "pix",
    "recipient": {
        "document": "12345678900",
        "pix_key": "vendor@example.com",
    },
    "idempotency_key": str(uuid.uuid4()),
})
print(result["tool_call_id"], result["status"])
```

</Tabs>

## Args shape

| Field | Type | Required | Description |
|---|---|---|---|
| `amount` | `number` | Yes | Amount in smallest currency unit (centavos for BRL) |
| `currency` | `string` | Yes | ISO 4217 — `BRL`, `MXN`, `CLP`, `COP` |
| `method` | `string` | Yes | `pix`, `spei`, `khipu`, `transbank` |
| `recipient` | `object` | Yes | Object with `document`, one of `pix_key` / `bank_account` / `wallet_address`, optional `name` |
| `idempotency_key` | `string` | Yes | Caller-supplied UUID. Backend writes it through to provider's external-reference field |
| `metadata` | `object` | No | Arbitrary key-value pairs persisted on the `tool_calls` row |

## Result shape

```ts
type PayResult = {
  tool_call_id: string;
  idempotency_key: string;
  status: "pending"; // always "pending" — terminal state lands via paymentStatus
  rail: string;       // resolved rail, e.g. "asaas-pix"
};
```

## Operator setup

Each rail needs operator-stamped credentials in `/dashboard/auth-configs`:

- **Asaas** — API key (`api_key` auth_type). Sandbox key for test, production key for live.
- **Mercado Pago** — Access token (`api_key` auth_type). Tied to a single seller account.
- **Wompi / Conekta / Khipu / Transbank** — Per-provider API key + sandbox toggle.

The dashboard wizard renders the right inputs based on each server's `auth_type` declared in the catalog.

## Async settlement

After `codespar_pay` returns, settlement happens via the provider webhook. The flow:

```
session.execute("codespar_pay", ...) → { tool_call_id, idempotency_key, status: "pending" }
  ↓
provider settles asynchronously (seconds for Pix, hours-to-days for SPEI/wallet)
  ↓
provider POSTs webhook → backend correlates external_reference ↔ idempotency_key
  ↓
session.paymentStatus(tool_call_id) → { status: "succeeded", final_amount_minor, settled_at }
```

See [async settlement](/docs/concepts/async-settlement) for the full correlation chain and per-provider idempotency-key shapes (Asaas `externalReference`, Mercado Pago `X-Idempotency-Key` header, etc.). Streaming variant: [SSE streaming](/docs/concepts/sse-streaming).

## See also

- [codespar_charge](/docs/concepts/meta-tools/charge) — inbound counterpart
- [Async settlement](/docs/concepts/async-settlement) — correlation chain + webhook flow
- [SDK reference](/docs/api/sdk#paymentstatustoolcallid-promisepaymentstatusresult) — `paymentStatus` / `paymentStatusStream`
- [Tools & meta-tools](/docs/concepts/tools) — full meta-tool list
- [Pix Payment Agent cookbook](/docs/cookbooks/pix-payment-agent) — simplest end-to-end example
- [Marketplace Payout cookbook](/docs/cookbooks/marketplace-payout) — split fee + seller payout