Skip to main content
Todos los casos de uso
Payouts transfronterizosMarketplaces

Paga a vendedores en Brasil y en el exterior, en los rieles que existen.

Un marketplace paga a sus vendedores. En Brasil, codespar_pay envía un Pix a la clave del vendedor. En el exterior, codespar_crypto_pay envía USDC por UnblockPay, que cotiza y paga la cuenta del destinatario: BRL por Pix, USD por wire, EUR por SEPA, MXN por SPEI. Requiere una conexión de UnblockPay con su KYC inicial y, fuera de Pix, la cuenta del destinatario registrada en UnblockPay. Argentina y Colombia no se ofrecen, y elegir el riel más barato por destino con tipo de cambio en vivo es una propuesta, no una función del producto.

AntesUn proveedor fijo por país
DespuésPix en Brasil, el offramp en USDC en el exterior
Pix · USDC
Brasil por Pix; el exterior por el offramp en USDC
Pruébalo en el Sandbox
Pix
Brasil
codespar_pay envía un Pix a la clave del vendedor
USDC
Exterior
codespar_crypto_pay envía USDC por UnblockPay
BRL · USD · EUR · MXN
Monedas del offramp
BRL por Pix, USD por wire, EUR por SEPA, MXN por SPEI
FX
Riel más barato por tipo de cambio en vivo
Una propuesta, no una función del producto
Ejemplo ilustrativo · datos de demostración

Un payout, en el riel que tiene su destino.

Un ejemplo con datos de demostración: un payout a un vendedor en México. Brasil iría por Pix; México va por el offramp en USDC a la cuenta del vendedor; Argentina no tiene riel aquí.

  • Brasil: un Pix con codespar_pay
  • Exterior: USDC por UnblockPay, cotizado antes del payout
  • Ningún riel para Argentina o Colombia

Pagarle al vendedor Diego, en México.

México no tiene riel directo aquí: enviando USDC por el offramp de UnblockPay a su cuenta registrada, después de una cotización.

codespar_pay · codespar_crypto_payBR · MX · AR
Pix a la clave del vendedor
codespar_pay · Brasil
Pix
disponible
Offramp en USDC a SPEIelegido
codespar_crypto_pay · UnblockPay · cotización, luego payout a una cuenta registrada
USDC → MXN
disponible
Sin riel
— · Argentina no se ofrece
—
no ofrecido
✓ ilustrativo · rieles por destinotrace_demo
El problema

La conversación es la parte fácil.

El payout transfronterizo es un problema de plomería por país: cada mercado tiene su riel, su spread cambiario y su ventana de liquidación, y los equipos terminan fijando un proveedor por país.

Enviar todo en USD y perder el spread cambiario

En Brasil, un Pix en BRL a la clave del vendedor

Integrar un proveedor por cada país

En el exterior, un solo offramp: USDC a cuentas en BRL, USD, EUR o MXN

Reenviar un payout tras un timeout y pagar dos veces

La clave de idempotencia de codespar_pay devuelve el primer resultado en lugar de pagar de nuevo

Perder el rastro de lo que hizo cada payout

codespar_pay action=status lee cada pago por su id

Cómo lo hace el agente

Dos rieles que existen, y una propuesta.

codespar_pay paga un Pix a una clave o a datos bancarios en Brasil. codespar_crypto_pay con direction send paga en el exterior por UnblockPay: le pide una cotización a UnblockPay y luego paga la cuenta del destinatario en BRL, USD, EUR o MXN; requiere el KYC inicial del cliente de UnblockPay y, fuera de Pix, una cuenta registrada en UnblockPay. Elegir entre rieles por costo en vivo por destino no se hace por ti: el ruteador elige un proveedor dentro de un riel, con estimaciones fijas de tarifa.

01
Lote
Marketplace

Payouts por destino

02
Brasil
codespar_pay

Pix a la clave del vendedor

codespar_pay
03
Cotización
codespar_crypto_pay

USDC a la moneda local

UnblockPay
04
Payout
codespar_crypto_pay

A la cuenta registrada

UnblockPay
05
Estado
codespar_pay

Cada pago leído por su id

codespar_pay
Arquitectura

Los payouts en Brasil van por codespar_pay vía Pix; el ruteador elige un proveedor Pix que el proyecto conectó, con estimaciones fijas de tarifa. Los payouts en el exterior van por codespar_crypto_pay: el transform de UnblockPay pide una cotización (USDC a la moneda de destino) y luego crea el payout a una clave Pix y documento en Brasil o a una cuenta registrada en UnblockPay en los demás casos. No hay optimizador entre rieles: qué riel usa un destino es decisión de tu código.

En código

El código, y lo que supone.

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);
}

Ejemplo con el SDK publicado (@codespar/sdk 0.16.11). Los requisitos están en los comentarios. Compilar no prueba la integración: ejecútalo primero en modo de prueba.

Herramientas destacadas
codespar_pay

Paga un Pix a una clave o datos bancarios en Brasil; action=status lee un pago por su id.

codespar_crypto_pay

Con direction send, paga en el exterior por UnblockPay: una cotización y luego el payout en BRL, USD, EUR o MXN.

Ver la referencia de meta-tools

Empieza con una clave de prueba.

Las claves de prueba son gratuitas. Abre el sandbox, conecta los proveedores que usa tu proyecto y mira qué herramientas puede llamar antes de construir.

Orquestador de payouts transfronterizos — CodeSpar | CodeSpar