codespar_pay

Collecting FROM a buyer instead? That is codespar_charge (sell-side).

Every call must pass action: pay executes a payment or transfer under governance (policy, mandate, routing); status reads a charge or boleto issued through the platform's charge rail by its payment_id (it does not read a Pix cash-out or a boleto settlement; those report inline and confirm via webhook). Settlement is rail-dependent: some rails return a terminal result inline, others accept the payment and settle asynchronously. A Pix cash-out returns settled plus a status_message; PROCESSING means accepted and settling within seconds, with the wallet already debited. A boleto settlement with settled: false means not yet confirmed (neither paid nor failed); the confirmation arrives through the payment webhook. Read the result you get back; do not treat accepted-and-settling as failure.

Rails

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.

Direct execute

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

const result = await session.execute("codespar_pay", {
  action: "pay",
  amount: 25000,
  currency: "BRL",
  method: "pix",
  recipient: "vendor@example.com", // a Pix key: email, phone, CPF/CNPJ or EVP
  description: "Invoice 1042, vendor payout",
});
console.log(result.tool_call_id, result.data); // executor output lives under data

result = session.execute("codespar_pay", {
    "action": "pay",
    "amount": 25000,
    "currency": "BRL",
    "method": "pix",
    "recipient": "vendor@example.com",  # a Pix key: email, phone, CPF/CNPJ or EVP
    "description": "Invoice 1042, vendor payout",
})
print(result["tool_call_id"], result["data"])  # executor output lives under data

Args shape

This mirrors the published schema in @codespar/types (SHARED_META_TOOL_DEFINITIONS.codespar_pay).

A caller-supplied idempotency_key is not part of the published schema. The backend keeps its own correlation key on the tool-call record; it is not returned in the call result.

Result shape

session.execute returns the standard tool envelope; the executor output is under data.

type ToolResult = {
  success: boolean;
  data: {
    // action: "pay"
    id: string;                // provider payment id
    status: string;            // status as reported by the rail (e.g. CONFIRMED, PROCESSING)
    settled?: boolean;         // async rails: true once the provider confirmed
    status_message?: string;   // human-readable state to relay to the user
    amount?: number;
    currency?: string;
    method?: string;
    // rail-specific extras, e.g. end_to_end_id (Pix), linha_digitavel / beneficiary / due_date (boleto)
    // action: "status" returns { id, status, billing_type, value, due_date }
  };
  error: string | null;
  tool_call_id?: string;
  server: string;              // provider that executed the call
};

How to read settled and status:

• Pix cash-out: PROCESSING with settled: false means the rail accepted the payment and is settling (seconds); the wallet is already debited. A terminal failure is returned as an error, not as a status.
• Boleto: settled: false means not yet confirmed. Do not treat it as paid or as failed; the confirmation arrives through the payment webhook (or the account statement).
• action: "status" reads a charge or boleto issued through the platform's charge rail by payment_id and returns the provider status verbatim (e.g. OVERDUE). It does not read Pix cash-outs or boleto settlements made with action: "pay".

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", { action: "pay", ... }) → { tool_call_id, data: { status, settled?, status_message? } }
  ↓
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 for the full correlation chain and per-provider idempotency-key shapes (Asaas externalReference, Mercado Pago X-Idempotency-Key header, etc.). Streaming variant: SSE streaming.

See also

• codespar_charge — inbound counterpart
• Async settlement — correlation chain + webhook flow
• SDK reference — paymentStatus / paymentStatusStream
• Tools & meta-tools — full meta-tool list
• Pix Payment Agent cookbook — simplest end-to-end example
• Marketplace Payout cookbook — split fee + seller payout