Skip to main content
Todos os casos de uso
Pagamentos internacionaisMarketplaces

Pague vendedores no Brasil e no exterior, nos rails que existem.

Um marketplace paga seus vendedores. No Brasil, o codespar_pay envia um Pix para a chave do vendedor. No exterior, o codespar_crypto_pay envia USDC pela UnblockPay, que cota e paga a conta do destinatário: BRL por Pix, USD por wire, EUR por SEPA, MXN por SPEI. Isso exige uma conexão UnblockPay com o KYC inicial feito e, fora do Pix, a conta do destinatário cadastrada na UnblockPay. Argentina e Colômbia não são oferecidas, e escolher o rail mais barato por destino com câmbio ao vivo é uma proposta, não um recurso do produto.

AntesUm provedor fixo por país
DepoisPix no Brasil, o offramp em USDC no exterior
Pix · USDC
Brasil por Pix; exterior pelo offramp em USDC
Teste no Sandbox
Pix
Brasil
O codespar_pay envia um Pix para a chave do vendedor
USDC
Exterior
O codespar_crypto_pay envia USDC pela UnblockPay
BRL · USD · EUR · MXN
Moedas do offramp
BRL por Pix, USD por wire, EUR por SEPA, MXN por SPEI
FX
Rail mais barato por câmbio ao vivo
Uma proposta, não um recurso do produto
Exemplo ilustrativo · dados de demonstração

Um pagamento, no rail que o destino tem.

Um exemplo com dados de demonstração: um pagamento para um vendedor no México. O Brasil iria por Pix; o México vai pelo offramp em USDC para a conta do vendedor; a Argentina não tem rail aqui.

  • Brasil: um Pix com o codespar_pay
  • Exterior: USDC pela UnblockPay, cotado antes do pagamento
  • Nenhum rail para Argentina ou Colômbia

Pagar o vendedor Diego, no México.

O México não tem rail direto aqui: enviando USDC pelo offramp da UnblockPay para a conta cadastrada dele, depois de uma cotação.

codespar_pay · codespar_crypto_payBR · MX · AR
Pix para a chave do vendedor
codespar_pay · Brasil
Pix
disponível
Offramp em USDC para SPEIescolhido
codespar_crypto_pay · UnblockPay · cotação, depois pagamento para uma conta cadastrada
USDC → MXN
disponível
Sem rail
— · a Argentina não é oferecida
—
não oferecido
✓ ilustrativo · rails por destinotrace_demo
A dor

A conversa é a parte fácil.

Pagamento internacional é um problema de encanamento por país: cada mercado tem seu rail, seu spread de câmbio e sua janela de liquidação, e os times acabam fixando um provedor por país.

Mandar tudo em USD e perder o spread do câmbio

No Brasil, um Pix em BRL para a chave do vendedor

Integrar um provedor para cada país

No exterior, um offramp só: USDC para contas em BRL, USD, EUR ou MXN

Reenviar um pagamento depois de um timeout e pagar duas vezes

A chave de idempotência do codespar_pay devolve o primeiro resultado em vez de pagar de novo

Perder o controle do que cada pagamento fez

O codespar_pay action=status lê cada pagamento pelo id

Como o agente faz isso

Dois rails que existem, e uma proposta.

O codespar_pay paga um Pix para uma chave ou para dados bancários no Brasil. O codespar_crypto_pay com direction send paga no exterior pela UnblockPay: pede uma cotação à UnblockPay e depois paga a conta do destinatário em BRL, USD, EUR ou MXN; exige o KYC inicial do cliente UnblockPay e, fora do Pix, uma conta cadastrada na UnblockPay. Escolher entre rails pelo custo ao vivo por destino não é feito por você: o roteador escolhe um provedor dentro de um rail, por estimativas fixas de tarifa.

01
Lote
Marketplace

Pagamentos por destino

02
Brasil
codespar_pay

Pix para a chave do vendedor

codespar_pay
03
Cotação
codespar_crypto_pay

USDC para a moeda local

UnblockPay
04
Pagamento
codespar_crypto_pay

Para a conta cadastrada

UnblockPay
05
Status
codespar_pay

Cada pagamento lido pelo id

codespar_pay
Arquitetura

Os pagamentos no Brasil vão pelo codespar_pay via Pix; o roteador escolhe um provedor Pix que o projeto conectou, por estimativas fixas de tarifa. Os pagamentos no exterior vão pelo codespar_crypto_pay: o transform da UnblockPay pede uma cotação (USDC para a moeda de destino) e depois cria o pagamento para uma chave Pix e documento no Brasil ou para uma conta cadastrada na UnblockPay nos outros casos. Não há otimizador entre rails: qual rail um destino usa é escolha do seu código.

Em código

O código, e o que ele pressupõe.

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

Exemplo com o SDK publicado (@codespar/sdk 0.16.11). Os pré-requisitos estão nos comentários. Compilar não prova a integração: rode primeiro em modo de teste.

Ferramentas em destaque
codespar_pay

Paga um Pix para uma chave ou dados bancários no Brasil; action=status lê um pagamento pelo id.

codespar_crypto_pay

Com direction send, paga no exterior pela UnblockPay: uma cotação e depois o pagamento em BRL, USD, EUR ou MXN.

Ver a referência das meta-tools

Comece com uma chave de teste.

Chaves de teste são gratuitas. Abra o sandbox, conecte os provedores que o seu projeto usa e veja quais ferramentas ele pode chamar antes de construir.

Orquestrador de pagamentos internacionais — CodeSpar | CodeSpar