Onramper Accounts: Fiat para Stablecoin Automatizado

Onramper Accounts permitem automatizar a conversão de fiat para stablecoin sem emitir uma chamada de API por transferência para cada depósito. Você cria uma conta bancária virtual para cada cliente (customer), e qualquer fiat depositado nessa conta é automaticamente convertido para a stablecoin vinculada e entregue na carteira on-chain do cliente — sem polling, sem etapa manual de conversão.

Onramper Accounts são um produto adicional. Elas usam endpoints diferentes da API de Transferências e não suportam a criação de conta bancária via API de Transferências.

Como funciona

Quando você cria um Onramper Account, o SpherePay provisiona uma conta bancária virtual dedicada vinculada a um endereço de carteira on-chain específico. O fluxo completo é:

Você cria um Onramper Account para um cliente, vinculando sua conta bancária virtual a uma carteira de destino.
Você compartilha os detalhes da conta bancária virtual (número da conta, código de roteamento, nome do beneficiário) com seu cliente.
O cliente faz um depósito fiat na conta virtual via ACH, Wire ou SEPA.
O SpherePay converte automaticamente o depósito para a stablecoin configurada.
A stablecoin convertida é entregue na carteira on-chain do cliente — sem chamadas adicionais de API.

Quando usar Onramper Accounts vs. a API de Transferências

Use Onramper Accounts quando quiser conversão totalmente automatizada e acionada por depósito, sem chamada de API por transferência. Use a API de Transferências quando precisar de controle explícito por transferência, webhooks ou um fluxo personalizado acionado pelo seu backend.

Uma conta por cliente

Um Onramper Account não tem atribuição por transferência. Se múltiplos clientes compartilharem uma única conta virtual, identificar quem enviou um depósito requer correspondência manual por valor, horário ou banco de origem — o que é propenso a erros. Sempre crie um Onramper Account por cliente, mesmo que compartilhem a mesma carteira de destino.

Rails e moedas suportados

Direção	Moeda	Rails
Fiat entrada	USD	ACH, Wire
Fiat entrada	EUR	SEPA
Stablecoin saída	USDC	Arbitrum, Avalanche, Base, Ethereum, Polygon, Solana
Stablecoin saída	USDT	Ethereum, Tron

Etapas de integração

Antes de começar, confirme que Onramper Accounts estão habilitados para sua aplicação SpherePay. Entre em contato com seu representante de vendas se precisar de acesso.

Cadastrar o cliente

Cada cliente deve ser registrado via API Criar Cliente, ter aceito os Termos de Serviço, concluído o KYC (para pessoas físicas) ou KYB (para empresas), e ter status de cliente approved.

Criar um Onramper Account

Chame POST /v2/virtual-account com o ID do cliente, moeda de origem, stablecoin de destino, rede e endereço de carteira.

{
  "customerId": "customer_1ab2c3d4",
  "sourceCurrency": "USD",
  "destinationCurrency": "USDC",
  "network": "ethereum",
  "walletAddress": "0x1234...abcd"
}

A resposta inclui as instruções de depósito da conta bancária virtual e a configuração de destino.

{
  "id": "virtualAccount_987xyz654",
  "active": true,
  "fees": {
    "totalBpsRate": "20",
    "integratorFee": {
      "bpsRate": "10"
    },
    "platformFee": {
      "bpsRate": "10"
    }
  },
  "depositInstructions": {
    "currency": "USD",
    "bankName": "Bank of Example",
    "bankAccountNumber": "000123456789",
    "bankRoutingNumber": "1234567890",
    "bankBeneficiaryName": "John Doe",
    "bankBeneficiaryAddress": "123 Main St, Anytown, USA"
  },
  "destination": {
    "currency": "USDC",
    "walletAddress": "0x1234...abcd",
    "network": "ethereum"
  },
  "created": "2025-04-20T21:49:46.697Z",
  "updated": "2025-04-20T21:50:18.854Z"
}

Recuperar detalhes da conta

Use GET /v2/virtual-account/{virtual_account_id} para recuperar a conta virtual e confirmar que as instruções de depósito estão corretas antes de compartilhá-las com seu cliente.

Compartilhar detalhes da conta bancária com seu cliente

Forneça ao cliente as depositInstructions da resposta: número da conta, código de roteamento, nome do beneficiário e endereço do beneficiário. Instrua-o a usar esses dados ao fazer uma transferência fiat do seu banco.

Cliente faz um depósito fiat

Assim que seu cliente depositar fiat na conta virtual, o SpherePay converte automaticamente os fundos e entrega a stablecoin no endereço de carteira configurado. Nenhuma chamada de API adicional é necessária da sua parte.

A conversão é instantânea assim que os fundos chegam à conta virtual. O tempo de transferência do banco do cliente para a conta virtual depende do rail (ACH, Wire ou SEPA).

Operações adicionais de API

Além de criar e recuperar contas virtuais, a API suporta:

PATCH /v2/virtual-account/{id} — atualizar a carteira de destino ou moeda
GET /v2/virtual-account — listar todas as contas virtuais
PATCH /v2/virtual-account/{id}/deactivate — desativar uma conta virtual
PATCH /v2/virtual-account/{id}/reactivate — reativar uma conta desativada

Para verificar o status de transferências individuais, use o endpoint Listar Transferências de Conta Virtual.

Verificação de conta

Algumas plataformas externas, como bancos, provedores de folha de pagamento ou aplicativos de pagamento, podem exigir que os clientes verifiquem a propriedade de sua conta virtual antes de vinculá-la. Essas plataformas podem iniciar a verificação por microdepósito ou depósito de desafio enviando um ou mais depósitos pequenos à Onramper Account. O SpherePay não conclui a verificação em nome do cliente. Quando um depósito de verificação chega, o SpherePay o registra como uma transferência com type: microdeposit e expõe o valor pela API de Transferências. O cliente conclui a verificação na plataforma externa que iniciou o fluxo confirmando o(s) valor(es) exato(s) do(s) depósito(s). Padrões comuns:

Verificação por micro-depósito — um ou mais depósitos pequenos, muitas vezes abaixo de US$ 1, são enviados à conta virtual.
Verificação por depósito de desafio — um ou mais depósitos pequenos são feitos, e o cliente confirma o(s) valor(es) exato(s) na plataforma externa.

Use GET /v2/transfer?type=microdeposit para listar depósitos de verificação.

Regiões suportadas

Onramper Accounts estão disponíveis para usuários finais globalmente, exceto em regiões sancionadas ou de outra forma proibidas por lei. Entre em contato com o SpherePay para uma lista atual de regiões restritas.

​Como funciona

​Quando usar Onramper Accounts vs. a API de Transferências

​Uma conta por cliente

​Rails e moedas suportados

​Etapas de integração

​Operações adicionais de API

​Verificação de conta

​Regiões suportadas

Como funciona

Quando usar Onramper Accounts vs. a API de Transferências

Uma conta por cliente

Rails e moedas suportados

Etapas de integração

Operações adicionais de API

Verificação de conta

Regiões suportadas