Outbound transfers — money leaving the merchant to a recipient. Routes Pix BRL via Asaas / Mercado Pago; future SPEI MX, Wompi CO, Khipu CL, Transbank CL.

codespar_pay

Meta-tool

codespar_pay is the outbound counterpart to codespar_charge. Use it whenever money leaves the merchant — vendor payouts, marketplace seller settlement, refunds, mass payouts. The agent specifies the recipient and the amount; CodeSpar picks the rail.

Pay is async. The call returns immediately with a tool_call_id and idempotency_key; settlement is correlated by the async settlement chain. Poll paymentStatus(toolCallId) or stream paymentStatusStream(toolCallId) until terminal.

Rails

Rail	Currency	Country	Provider	Notes
Pix	BRL	BR	Asaas	Default — instant settlement, lowest fees on most batches
Pix	BRL	BR	Mercado Pago	Failover when Asaas degrades; uses `external_reference` + `X-Idempotency-Key`
SPEI	MXN	MX	Wompi / Conekta	Pilot — next batch
Khipu	CLP	CL	Khipu	Pilot — next batch
Transbank	CLP	CL	Transbank	Pilot — next batch

The router falls back through this list if the primary rail is degraded. See /dashboard/router for live failover telemetry.

Direct execute

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

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"

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

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

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 for the full correlation chain and per-provider idempotency-key shapes (Asaas externalReference, Mercado Pago X-Idempotency-Key header, etc.). Streaming variant: SSE streaming.

codespar_pay

codespar_pay

Rails

Direct execute

Args shape

Result shape

Operator setup

Async settlement

See also

On this page