codespar_pay

Collecting FROM a buyer instead? That is codespar_charge (sell-side). Settling in USDC or any on-chain asset? That is codespar_crypto_pay.

Actions

Example

action: "pay" over Pix, to a Pix key, from the consumer's governed wallet. Amounts are in minor units (centavos).

{
  "name": "codespar_pay",
  "arguments": {
    "action": "pay",
    "amount": 2500,
    "currency": "BRL",
    "method": "pix",
    "recipient": "payee@example.com",
    "description": "Example payout",
    "consumer_id": "consumer_0000",
    "idempotency_key": "pay_0000"
  }
}

{
  "status": "PROCESSING",
  "settled": false,
  "status_message": "Accepted by the rail and settling; the wallet is already debited.",
  "initiation_type": "DICT",
  "charge_correlation": "none",
  "end_to_end_id": "e2e_0000"
}

A Pix cash-out is asynchronous: PROCESSING means accepted and settling within seconds, with the wallet already debited. Relay status_message to the user; do not surface a bare PROCESSING and do not treat it as a failure. A static QR (the code taped to a small merchant's wall) carries no charge identifier, so its result says charge_correlation: "none": settled means the rail moved the money, not that the merchant marked an order paid. Pass the end_to_end_id to the payee if they need to reconcile.

When to use

• Paying a store order from codespar_shop. Pass the checkout_session_id with the same consumer_id used in the checkout; the backend resolves the exact Pix copia-e-cola server-side. Never re-type the long Pix code yourself (re-typing corrupts the CRC). If you already hold a copia-e-cola, pass it as copia_e_cola, never as recipient.
• Paying a Pix key. recipient is the key (email, phone, CPF/CNPJ, EVP). For a destination with no key, recipient is a bank-account object; pass it literally, not JSON-stringified, because the argument's runtime type is what selects the path.
• Settling an existing boleto. method: "boleto" with linha_digitavel. Quote first with action: "boleto_quote", then settle passing expected_amount_minor, so a stale quote fails cleanly instead of paying a different amount. This settles an existing boleto; it does not issue one (that is codespar_charge).
• A bank wire. method: "ted" sends a real outbound TED to a bank account with no Pix key. It executes only under a consumer mandate whose signed withdrawal_allowlist names the destination; see Money and mandate.
• Reading state. action: "status" reads a payment, charge or boleto by the id a previous codespar_pay or codespar_charge result returned, and answers with that provider's status verbatim (for example OVERDUE for an unpaid boleto). Pin provider when you already know which rail holds it.
• The consumer's own Pix account. The dda_* actions register the consumer's document for national boleto visibility and list what they owe; the dict_key_* and dict_claim_* actions manage the keys on their account and the claim lifecycle. None of these moves money; the account is always resolved server-side from consumer_id.
• Refunding a Pix. action: "pix_devolution" returns a received Pix to its original payer; with payment_direction: "outbound" it asks the rail to devolve a Pix the consumer sent. Poll pix_devolution_status, not status, until settled.

Arguments

The table mirrors the published schema for codespar_pay. action is required on every call.

Common

action: "pay"

action: "status"

DDA (dda_*)

DICT keys and claims (dict_*)

Pix devolution (pix_devolution*)

Errors and what to do

Money and mandate

action: "pay" and action: "pix_devolution" move real money. Every spend leaves the consumer's governed wallet under a signed mandate: per-currency caps, per-transaction caps, allowlists and expiry are checked server-side before dispatch. Two destinations are pinned by the mandate text itself:

• TED executes only when the mandate's signed withdrawal_allowlist names ted:<ispb>:<branch>:<account> (digits only). idempotency_key is required and checked before any money step, because the default correlation would make a second TED silently attach to the first. Every gate here is pre-dispatch and reports dispatch: "unsent"; an ambiguous provider outcome is never reported as unsent.
• DDA registration exposes the titular's boletos, so it needs the document both verified at onboarding and named in the mandate's signed dda_allowlist. Neither condition substitutes for the other. dda_unsubscribe needs no mandate, so withdrawing a document from a national register stays possible after the consumer revokes consent.

Every other action (status, boleto_quote, dda_status, dda_list_due, all dict_*, pix_devolution_status) is a read or an account-management call: no money moves. A devolution always goes back to the original payer (inbound) or to the consumer's own account (outbound); it cannot be redirected.

Related

• codespar_charge: the inbound counterpart, and the tool that issues boletos
• codespar_wallet: the balance this tool spends from; receive to fund it
• codespar_shop: the checkout whose checkout_session_id this tool settles
• Directed pay and mandates: what the signed mandate authorizes
• Async settlement: correlation chain and webhook flow
• Pix Payment Agent cookbook: simplest end-to-end example
• Marketplace Payout cookbook: split fee and seller payout

Notes

Rails and providers

The catalog carries 29 codespar_pay lines over 25 providers, but 10 of them (Mercado Pago and the nine bank /cob lines) are inbound charge lines the router refuses for a payout: 15 providers actually route outbound, across six countries (BR, MX, PE, CL, CO, US) plus the international corridors. The router fails over within a rail when the primary provider degrades (Pix BRL walks Asaas → the BaaS provider) and drops every line whose catalog entry declares money_in before scoring, so inbound lines are never picked and never reached by failover. Lines that declare no direction still pass; only Pix × BRL × BR has been adjudicated so far. See /dashboard/router for live failover telemetry, and cert auth for the banks' mTLS.

Operator setup. Each rail needs operator-stamped credentials in /dashboard/auth-configs: Asaas (API key; sandbox key for test, production key for live), Mercado Pago (access token, tied to a single seller account), Wompi / Conekta / Khipu / Transbank (per-provider API key and sandbox toggle). The dashboard wizard renders the right inputs from each server's auth_type in the catalog.

Async settlement. After codespar_pay returns, settlement happens via the provider webhook: the provider settles (seconds for Pix, hours-to-days for SPEI or wallet rails), POSTs a webhook, the backend correlates external_reference with idempotency_key, and session.paymentStatus(tool_call_id) reports succeeded with final_amount_minor and settled_at. See async settlement for per-provider idempotency-key shapes and SSE streaming for the streaming variant.

From the SDK. There is no typed wrapper for codespar_pay; call session.execute() with the same arguments as the MCP call. The executor output lives under data.

const result = await session.execute("codespar_pay", {
  action: "pay",
  amount: 2500,
  currency: "BRL",
  method: "pix",
  recipient: "payee@example.com",
  description: "Example payout",
  consumer_id: "consumer_0000",
  idempotency_key: "pay_0000",
});
console.log(result.tool_call_id, result.data);

result = session.execute("codespar_pay", {
    "action": "pay",
    "amount": 2500,
    "currency": "BRL",
    "method": "pix",
    "recipient": "payee@example.com",
    "description": "Example payout",
    "consumer_id": "consumer_0000",
    "idempotency_key": "pay_0000",
})
print(result["tool_call_id"], result["data"])

Result envelope (SDK), as previously documented. session.execute returns { success, data, error, tool_call_id, server }; for action: "pay" the page used to document data as { id, status, settled?, status_message?, amount?, currency?, method? } plus rail-specific extras (end_to_end_id on Pix; linha_digitavel, beneficiary, due_date on boleto), and action: "status" as { id, status, billing_type, value, due_date }. This revision did not re-verify those field lists against the runtime; the fields the tool document itself names are the ones in the Example above.

@codespar/types drifts. The package's copy of this schema (SHARED_META_TOOL_DEFINITIONS.codespar_pay) lags the API in both directions (ent#933): it still names usdc and sepa as methods, neither of which routes, and it lacks fields the API publishes. This page follows the API, which is what decides.