Skip to main content
All use cases
Cross-border payoutsMarketplaces

Pay sellers in Brazil and abroad, on the rails that exist.

A marketplace pays its sellers. In Brazil, codespar_pay sends a Pix to the seller's key. Abroad, codespar_crypto_pay sends USDC through UnblockPay, which quotes and pays the recipient's account: BRL by Pix, USD by wire, EUR by SEPA, MXN by SPEI. It needs an UnblockPay connection with its one-time KYC and, outside Pix, the recipient's account registered at UnblockPay. Argentina and Colombia are not offered, and picking the cheapest rail per destination from live FX is a proposal, not a product feature.

BeforeOne provider hard-coded per country
AfterPix in Brazil, the USDC offramp elsewhere
Pix · USDC
Brazil by Pix; abroad by the USDC offramp
Try it in the Sandbox
Pix
Brazil
codespar_pay sends a Pix to the seller's key
USDC
Abroad
codespar_crypto_pay sends USDC through UnblockPay
BRL · USD · EUR · MXN
Offramp currencies
BRL by Pix, USD by wire, EUR by SEPA, MXN by SPEI
FX
Cheapest rail by live FX
A proposal, not a product feature
Illustrative example · demo data

One payout, on the rail its destination has.

An example with demo data: a payout to a seller in Mexico. Brazil would go by Pix; Mexico goes by the USDC offramp to the seller's account; Argentina has no rail here.

  • Brazil: a Pix with codespar_pay
  • Abroad: USDC through UnblockPay, quoted before the payout
  • No rail for Argentina or Colombia

Pay seller Diego in Mexico.

Mexico has no direct rail here: sending USDC through the UnblockPay offramp to his registered account, after a quote.

codespar_pay · codespar_crypto_payBR · MX · AR
Pix to the seller's key
codespar_pay · Brazil
Pix
available
USDC offramp to SPEIchosen
codespar_crypto_pay · UnblockPay · quote, then payout to a registered account
USDC → MXN
available
No rail
— · Argentina is not offered
—
not offered
✓ illustrative · rails by destinationtrace_demo
The pain

The conversation is the easy part.

Cross-border payouts are a per-country plumbing problem: each market has its own rail, FX spread and settlement window, and teams end up hard-coding one provider per country.

Wire everything in USD and lose the FX spread

In Brazil, a Pix in BRL to the seller's key

Integrate a provider for every country

Abroad, one offramp: USDC to accounts in BRL, USD, EUR or MXN

Re-send a payout after a timeout and pay twice

codespar_pay's idempotency key returns the first result instead of paying again

Lose track of what each payout did

codespar_pay action=status reads each payment by id

How the agent does it

Two rails that exist, and a proposal.

codespar_pay pays a Pix to a key or to bank details in Brazil. codespar_crypto_pay with direction send pays abroad through UnblockPay: it asks UnblockPay for a quote, then pays the recipient's account in BRL, USD, EUR or MXN; it needs the UnblockPay customer's one-time KYC and, outside Pix, an account registered at UnblockPay. Choosing between rails by live cost per destination is not done for you: the router picks a provider within a rail, from static fee estimates.

01
Batch
Marketplace

Payouts by destination

02
Brazil
codespar_pay

Pix to the seller's key

codespar_pay
03
Quote
codespar_crypto_pay

USDC to the local currency

UnblockPay
04
Payout
codespar_crypto_pay

To the registered account

UnblockPay
05
Status
codespar_pay

Each payment read by id

codespar_pay
Architecture

Brazilian payouts go through codespar_pay over Pix; the router picks a Pix provider the project has connected, from static fee estimates. Payouts abroad go through codespar_crypto_pay: the UnblockPay transform asks for a quote (USDC to the target currency), then creates the payout to a Pix key and document in Brazil or to an account registered at UnblockPay elsewhere. There is no cross-rail optimizer: which rail a destination uses is your code's choice.

In code

The code, and what it assumes.

cross-border-payouts.ts
// Prerequisites: CODESPAR_API_KEY set to a test key (csk_test_…) and a Pix
// provider connected to the project (Asaas or Celcoin, for instance).
// Payouts abroad use codespar_crypto_pay with an UnblockPay connection, whose
// arguments depend on that connection: see the meta-tool reference.
import { CodeSpar } from "@codespar/sdk";

const session = await new CodeSpar().create("user_0000", { preset: "brazilian" });

const sellers = [
  { id: "1042", pixKey: "seller1042@example.com", amountMinor: 150_000 },
  { id: "1043", pixKey: "seller1043@example.com", amountMinor: 98_050 },
];

for (const s of sellers) {
  const res = await session.execute("codespar_pay", {
    action: "pay",
    method: "pix",
    recipient: s.pixKey,
    amount: s.amountMinor, // centavos
    currency: "BRL",
    description: `Payout · seller ${s.id}`,
    idempotency_key: `payout-${s.id}-2026-10`, // a retry returns the first result
  });
  console.log(s.id, res.success, res.data);
}

Example with the published SDK (@codespar/sdk 0.16.11). Its prerequisites are in the comments. Compiling does not prove the integration: run it in test mode first.

Featured tools
codespar_pay

Pays a Pix to a key or bank details in Brazil; action=status reads a payment by id.

codespar_crypto_pay

With direction send, pays abroad through UnblockPay: a quote, then a payout in BRL, USD, EUR or MXN.

See the meta-tool reference

Start with a test key.

Test keys are free. Open the sandbox, connect the providers your project uses and see which tools it can call before you build.

Cross-border payout orchestrator — CodeSpar | CodeSpar