Pular para o conteúdo principal
Use o SpherePay para facilitar trading de moedas entre pares fiat usando stablecoins como camada de liquidação. O padrão é o mesmo em todos os corredores — um “sanduíche” de stablecoin roteia o trade através de USDC (ou outra stablecoin), com o SpherePay cuidando de ambas as pernas fiat. Este é o padrão correto para corretoras de câmbio, plataformas de câmbio de moedas, liquidação de câmbio B2B e qualquer produto que precise converter um fiat em outro de forma rápida e previsível.

​
O padrão em um só modelo

Cada corredor abaixo segue o mesmo modelo de três etapas:
  1. On-ramp do fiat de origem para USDC.
  2. Bridge do USDC entre redes se necessário (de uma carteira para outra).
  3. Off-ramp do USDC para o fiat de destino.
A implementação mais limpa usa um Offloader Wallet para a etapa 3 — o Sphere converte automaticamente USDC para o fiat de destino e envia por wire para uma conta bancária, eliminando a necessidade de uma segunda chamada de API de transferência.
Ambas as pernas fiat requerem perfis de verificação separados no cliente (um por moeda). Consulte cada corredor abaixo para os perfis específicos necessários.

​
Corredores suportados

Expanda um corredor abaixo para o tutorial completo de integração passo a passo.
O corredor mais comum do Sphere hoje. Move fundos entre Reais Brasileiros (via PIX) e Dólares Americanos (via wire ou ACH) com USDC como moeda de ponte.Casos de uso comuns:
  • Pagamentos de importação/exportação — importadores brasileiros pagando faturas USD a fornecedores internacionais, ou exportadores recebendo receitas em USD.
  • Pagamentos de empréstimos — devedores com BRL pagando dívidas denominadas em USD.
  • Transações imobiliárias — compradores ou vendedores em negócios imobiliários brasileiros liquidando em USD.
  • Remessas — remetentes brasileiros, destinatários nos EUA.

​
Pré-requisitos

O cliente deve ser aprovado em ambos os perfis de verificação:
  • kyc_profile_a / kyb_profile_a — obrigatório para transferências USD
  • kyc_profile_b / kyb_profile_b — obrigatório para transferências BRL/PIX
Consulte KYC Individual e KYB Empresarial para configuração.
Passar "network": "sol" em uma transferência BRL resultará em uma requisição rejeitada. Use ethereum, polygon, arbitrum, base ou avalanche para USDC. USDT suporta ethereum ou tron.

​
Fluxo

​
Etapa 1 — Criar uma conta bancária USD

POST https://api.spherepay.co/v2/bank-account
{
  "customerId": "{{customer_id}}",
  "bankName": "Chase",
  "accountName": "My USD Account",
  "accountOwner": "Alice Johnson",
  "currency": "usd",
  "accountDetails": {
    "accountNumber": "1234567890",
    "routingNumber": "021000021",
    "accountType": "checking"
  },
  "networks": ["wire"]
}

​
Etapa 2 — Criar um Offloader Wallet

POST https://api.spherepay.co/v2/offloader-wallet
{
  "customerId": "{{customer_id}}",
  "currency": "usdc",
  "network": "polygon",
  "destination": {
    "bankAccountId": "{{usd_bank_account_id}}",
    "currency": "usd",
    "network": "wire"
  }
}
Armazene o address retornado como {{offloader_address}}.

​
Etapa 3 — Registrar o endereço do Offloader como carteira

POST https://api.spherepay.co/v2/wallet
{
  "customerId": "{{customer_id}}",
  "network": "polygon",
  "address": "{{offloader_address}}"
}
Armazene o id retornado como {{wallet_id}}. As etapas 1–3 só precisam ser feitas uma vez por cliente — reutilize {{wallet_id}} para todas as transferências futuras de BRL → USD.

​
Etapa 4 — Criar uma conta bancária BRL

POST https://api.spherepay.co/v2/bank-account
{
  "currency": "brl",
  "bankName": "Banco do Brasil",
  "accountName": "My BRL Account",
  "accountDetails": {
    "pixKey": "alice@example.com",
    "pixKeyType": "email"
  },
  "accountOwner": {
    "accountHolderName": "Alice Johnson",
    "address": {
      "line1": "Rua das Flores 123",
      "city": "São Paulo",
      "state": "SP",
      "postalCode": "01310-100",
      "country": "BRA"
    }
  },
  "networks": ["pix"]
}
pixKeyType aceita email, phone, cnpj ou random.

​
Etapa 5 — Criar a transferência BRL → USDC

POST https://api.spherepay.co/v2/transfer
{
  "customer": "{{customer_id}}",
  "amount": "100.00",
  "source": {
    "type": "bank_account",
    "id": "{{brl_bank_account_id}}",
    "currency": "brl",
    "network": "pix"
  },
  "destination": {
    "type": "wallet",
    "id": "{{wallet_id}}",
    "currency": "usdc",
    "network": "polygon"
  },
  "integratorBpsFeeRate": "50"
}
Restrições BRL: integratorBpsFeeRate é obrigatório (taxas fixas não suportadas), limites por transferência R1,00–R 1,00–R 7.500,00, Solana não suportada. Consulte Rails suportados.

​
Etapa 6 — Financiar a transação

A resposta inclui um instructions.pixKey — apresente-o ao seu usuário final. Assim que ele enviar o BRL via PIX:
  1. O Sphere recebe o BRL e o converte para USDC.
  2. USDC é entregue ao Offloader Wallet.
  3. O Offloader Wallet converte automaticamente USDC para USD e envia por wire para a conta bancária USD registrada.

​
Direção inversa — USD → BRL

Para a direção oposta, inverta o padrão: registre um Offloader Wallet BRL (USDC → BRL via PIX), depois faça on-ramp de USD → USDC nele. Mesmos primitivos, mesmo número de chamadas de API.

​
Tratamento de erros

CenárioO que aconteceO que fazer
On-ramp falhaBRL devolvido via PIX. Nenhum USDC emitido.Tente novamente ou exiba ao usuário.
On-ramp tem sucesso, conversão do Offloader falhaUSDC fica no Offloader Wallet. Nenhum USD enviado.Entre em contato com o suporte SpherePay.
Cliente envia valor PIX erradoUSDC parcial ou em excesso chega ao Offloader Wallet.A carteira converte o que chegar — reconcilie do seu lado.
Converta entre Dólares Americanos (via ACH ou wire) e Euros (via SEPA) com USDC ou EURC como ponte. O SEPA liquida no mesmo/próximo dia útil; o SEPA Instant é quase instantâneo onde suportado.Casos de uso comuns:
  • Importadores americanos pagando fornecedores europeus.
  • Plataformas europeias aceitando receita em USD e liquidando em EUR.
  • Tesouraria internacional — empresas operando em ambas as regiões gerenciando exposição cambial.
  • Corretoras de câmbio oferecendo conversão de USD/EUR para varejo.

​
Pré-requisitos

O cliente deve ser aprovado em ambos os perfis de verificação USD e EUR. Ambos os rails fiat se enquadram em kyc_profile_a / kyb_profile_a (nenhum perfil separado é necessário para EUR, ao contrário do BRL).Todas as redes USDC padrão são suportadas, incluindo Solana. Para EURC, as redes suportadas são Base, Ethereum e Solana.

​
Fluxo

​
Etapa 1 — Criar uma conta bancária EUR

POST https://api.spherepay.co/v2/bank-account
{
  "customerId": "{{customer_id}}",
  "bankName": "Deutsche Bank",
  "accountName": "EUR settlement",
  "accountOwner": "Acme GmbH",
  "currency": "eur",
  "accountDetails": {
    "iban": "DE89370400440532013000",
    "bic": "DEUTDEFFXXX"
  },
  "networks": ["sepa"]
}
Use sepaInstant em networks se precisar de liquidação quase instantânea e o banco destinatário suportar.

​
Etapa 2 — Criar um Offloader Wallet para USDC → EUR

POST https://api.spherepay.co/v2/offloader-wallet
{
  "customerId": "{{customer_id}}",
  "currency": "usdc",
  "network": "ethereum",
  "destination": {
    "bankAccountId": "{{eur_bank_account_id}}",
    "currency": "eur",
    "network": "sepa"
  }
}
Escolha a rede de origem com base em onde você receberá USDC. Solana é a mais barata e rápida; Ethereum e Base são comuns para fluxos institucionais.Armazene o address retornado como {{offloader_address}}.

​
Etapa 3 — Registrar o endereço do Offloader como carteira

POST https://api.spherepay.co/v2/wallet
{
  "customerId": "{{customer_id}}",
  "network": "ethereum",
  "address": "{{offloader_address}}"
}
Armazene o id retornado como {{wallet_id}}.

​
Etapa 4 — Criar uma conta bancária USD

POST https://api.spherepay.co/v2/bank-account
{
  "customerId": "{{customer_id}}",
  "bankName": "Chase",
  "accountName": "USD source",
  "accountOwner": "Acme Inc",
  "currency": "usd",
  "accountDetails": {
    "accountNumber": "1234567890",
    "routingNumber": "021000021",
    "accountType": "checking"
  },
  "networks": ["ach", "wire"]
}

​
Etapa 5 — Criar a transferência USD → USDC

POST https://api.spherepay.co/v2/transfer
{
  "customer": "{{customer_id}}",
  "amount": "10000.00",
  "source": {
    "type": "bank_account",
    "id": "{{usd_bank_account_id}}",
    "currency": "usd",
    "network": "wire"
  },
  "destination": {
    "type": "wallet",
    "id": "{{wallet_id}}",
    "currency": "usdc",
    "network": "ethereum"
  }
}
Escolha wire para liquidação no mesmo dia, ach para mais barato mas mais lento (1–2 dias úteis).

​
Etapa 6 — Liquidação

Assim que USD chegar ao SpherePay:
  1. O Sphere converte USD → USDC.
  2. USDC é entregue ao Offloader Wallet.
  3. O Offloader Wallet converte automaticamente USDC → EUR e envia via SEPA.
Tempo total: minutos (wire) a ~1 dia útil (ACH + SEPA), dependendo das escolhas de rail.

​
Direção inversa — EUR → USD

Mesmos primitivos, invertidos. Registre um Offloader Wallet USD (USDC → USD), faça on-ramp de EUR → USDC nele.

​
Usando EURC em vez de USDC

Para fluxos pesados em EUR, o EURC pode reduzir o slippage. Defina currency: "eurc" e network para um de base, ethereum ou solana no Offloader Wallet. A moeda de ponte passa a ser EURC em vez de USDC; o resto da integração é idêntico.

​
O que você cuida vs. o que o SpherePay cuida

ResponsabilidadeResponsável
Criar os objetos de cliente, conta bancária e carteiraVocê (integrador)
Criar e gerenciar o Offloader WalletVocê (integrador)
Iniciar a transferência de on-rampVocê (integrador)
Coleta de fiat e conversão de fiat de origem para USDCSpherePay
Conversão de USDC para fiat de destino e liquidaçãoSpherePay (via Offloader Wallet)
Tratamento de falhas em qualquer pernaVocê (integrador)

​
Restrições comuns a todos os corredores

  • Cada perna é cobrada como uma transferência separada.
  • Offloader Wallets não suportam webhooks atualmente — consulte GET /v2/transfer/{id} para rastrear o status do on-ramp.
  • Os perfis de verificação do fiat de origem e destino devem estar aprovados antes de qualquer transferência ser iniciada.

​
Perspectiva — transferências de câmbio com uma única chamada

Hoje cada corredor requer configurar um Offloader Wallet mais uma chamada separada de API de transferência on-ramp. O SpherePay está trabalhando para uma API de transferência de câmbio com uma única chamada que abstrai completamente o salto de stablecoin — você enviaria uma requisição com as moedas de origem e destino, e o SpherePay cuidaria do roteamento internamente. Quando isso for lançado, os padrões neste guia ainda funcionarão, mas você terá a opção de consolidar para uma única chamada.

​
Relacionados

Offloader Wallets

Como funciona a conversão automática de stablecoin para fiat.

API de Transferências

Referência completa de criação e rastreamento de transferências.

Rails suportados

Compatibilidade de rede e rail por moeda.

Financiamento de comércio internacional

Padrões de pagamento multipartidário.
Última modificação em 18 de junho de 2026