> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Onramper Accounts: Fiat para Stablecoin Automatizado
> Onramper Accounts dão a cada cliente uma conta bancária virtual dedicada que converte automaticamente depósitos fiat em stablecoins on-chain.
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 é:
1. Você cria um Onramper Account para um cliente, vinculando sua conta bancária virtual a uma carteira de destino.
2. Você compartilha os detalhes da conta bancária virtual (número da conta, código de roteamento, nome do beneficiário) com seu cliente.
3. O cliente faz um depósito fiat na conta virtual via ACH, Wire ou SEPA.
4. O SpherePay converte automaticamente o depósito para a stablecoin configurada.
5. 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.
Cada cliente deve ser registrado via API [Criar Cliente](/pt-BR/api-reference/customer/post), 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`.
Chame `POST /v2/virtual-account` com o ID do cliente, moeda de origem, stablecoin de destino, rede e endereço de carteira.
```json theme={"dark"}
{
"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.
```json theme={"dark"}
{
"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"
}
```
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.
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.
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](/pt-BR/api-reference/virtual-account/list-transfers).
## 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.