> ## Documentation Index > Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt > Use this file to discover all available pages before exploring further. # Depositar Fiat > Crie e gerencie contas bancárias virtuais vinculadas a master wallets ou endereços filhos para pagamentos fluidos de fiat para stablecoin Em resumo
As Contas Virtuais permitem que seus clientes recebam pagamentos em fiat por meio de transferências bancárias tradicionais, que são automaticamente convertidos em stablecoins na blockchain. Você pode criar várias contas virtuais por wallet ou endereço, com suporte a paginação e regeneração de contas. Contas Virtuais ## Pré-requisitos Antes de usar a API de Contas Virtuais, certifique-se de ter: Obtenha sua chave de API no [Dashboard do Blockradar](https://dashboard.blockradar.co). Acesse **Developers** para gerar uma. Crie uma wallet pela [API de Criar Wallet](/en/api-reference/wallets/create-wallet) ou pelo dashboard. Você precisará do `walletId` para as operações de conta virtual. Preencha o [Formulário de Due Diligence](https://airtable.com/appsn5KFgmZhzQ9lh/pag8ytSkiF9k5w590/form) (consulte os [Requisitos de Compliance](#requisitos-de-compliance) abaixo). Solicite a ativação do recurso de contas virtuais após a aprovação do compliance. Entre em contato com [support@blockradar.co](mailto:support@blockradar.co) ou use o chat ao vivo no dashboard. As contas virtuais estão disponíveis apenas em **MAINNET**. Os ambientes de testnet não suportam operações de conta virtual. Depositar fiat e convertê-lo em uma stablecoin é um recurso pago. Verifique se o seu plano inclui acesso a stablecoins. Atualize em **Dashboard → Configurações → Assinatura**. ## Como funciona Crie contas virtuais vinculadas a master wallets ou endereços filhos com as informações do cliente. Os clientes enviam pagamentos em fiat para a conta virtual usando transferências bancárias tradicionais. Os pagamentos acionam automaticamente a emissão do valor equivalente em stablecoin. As stablecoins emitidas são transferidas para a wallet ou endereço vinculado para uso imediato. ## Fluxo de Auto-Funding Todas as contas virtuais utilizam `AUTO_FUNDING`, que converte automaticamente fiat em stablecoin. Quando um cliente envia moeda fiat para uma conta virtual: ### **1. Recebimento do pagamento** O pagamento é recebido na conta virtual por meio de transferência bancária tradicional. Nesta etapa é acionado um webhook `deposit.processing`. ### **2. Emissão automática** O sistema emite automaticamente o equivalente em stablecoin na blockchain. ### **3. Transferência na blockchain** A stablecoin emitida é transferida para a wallet ou endereço vinculado à conta virtual. Quando concluído com sucesso, é acionado um webhook `deposit.success`. ## Requisitos de Compliance Antes de acessar as contas virtuais, conclua o processo de onboarding de compliance. ### **Documentos necessários** * Certificado de Constituição * Documento de identidade dos Diretores/Acionistas * Documento da Política KYC ### **Enviar solicitação** Preencha o [Formulário de Due Diligence](https://airtable.com/appsn5KFgmZhzQ9lh/pag8ytSkiF9k5w590/form) com os dados da sua empresa, informações de compliance e o envio de documentos. ## Moeda suportada * **Fiat**: NGN (Naira nigeriano) - Transferências bancárias tradicionais * **Stablecoin**: cNGN - Emitida automaticamente na blockchain ## Endpoints da API Abaixo estão os principais endpoints da API para operações de Contas Virtuais: ### **Endpoints de Master Wallet** * [POST /wallets/{walletId}/virtual-accounts](/en/api-reference/virtual-accounts/master-wallet-create) – Criar uma conta virtual para uma master wallet * [GET /wallets/{walletId}/virtual-accounts](/en/api-reference/virtual-accounts/master-wallet-get-all) – Listar todas as contas virtuais (paginado) * [GET /wallets/{walletId}/virtual-accounts/{virtualAccountId}](/en/api-reference/virtual-accounts/master-wallet-get-one) – Obter uma conta virtual específica * [GET /wallets/{walletId}/virtual-accounts/{virtualAccountId}/transactions](/en/api-reference/virtual-accounts/master-wallet-transactions) – Obter transações de uma conta virtual * [PATCH /wallets/{walletId}/virtual-accounts/{virtualAccountId}](/en/api-reference/virtual-accounts/master-wallet-update) – Atualizar o status de uma conta virtual * [POST /wallets/{walletId}/virtual-accounts/{virtualAccountId}/regenerate](/en/api-reference/virtual-accounts/master-wallet-regenerate) – Regenerar uma conta virtual ### **Endpoints de Endereço Filho** * [POST /wallets/{walletId}/addresses/{addressId}/virtual-accounts](/en/api-reference/virtual-accounts/child-address-create) – Criar uma conta virtual para um endereço filho * [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts](/en/api-reference/virtual-accounts/child-address-get-all) – Listar todas as contas virtuais (paginado) * [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}](/en/api-reference/virtual-accounts/child-address-get-one) – Obter uma conta virtual específica * [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/transactions](/en/api-reference/virtual-accounts/child-address-transactions) – Obter transações de uma conta virtual * [PATCH /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}](/en/api-reference/virtual-accounts/child-address-update) – Atualizar o status de uma conta virtual * [POST /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/regenerate](/en/api-reference/virtual-accounts/child-address-regenerate) – Regenerar uma conta virtual ## Criando Contas Virtuais Você pode criar contas virtuais tanto para master wallets quanto para endereços filhos, dependendo do seu caso de uso. Use a [API de Criar Conta Virtual](/en/api-reference/virtual-accounts/master-wallet-create) para master wallets ou a [API de Criar Conta Virtual para endereços filhos](/en/api-reference/virtual-accounts/child-address-create). ### **Parâmetros da requisição para Master Wallet** | Parâmetro | Tipo | Obrigatório | Descrição | | ------------- | ------ | ----------- | -------------------------------------------------------- | | `firstname` | string | Sim | Primeiro nome do cliente (máx. 29 caracteres) | | `lastname` | string | Sim | Sobrenome do cliente (máx. 29 caracteres) | | `email` | string | Sim | E-mail do cliente (deve ser único por negócio) | | `phone` | string | Não | Número de telefone do cliente no formato: +234XXXXXXXXXX | | `bvn` | string | Sim | Bank Verification Number do cliente | | `dateOfBirth` | string | Sim | Data de nascimento do cliente no formato `yyyy-MM-dd` | ### **Exemplo de requisição para Master Wallet** ```json theme={null} { "firstname": "John", "lastname": "Doe", "email": "john.doe@example.com", "phone": "+2348161846125", "bvn": "22345678901", "dateOfBirth": "1992-08-14" } ``` ### **Parâmetros da requisição para Endereço Filho** | Parâmetro | Tipo | Obrigatório | Descrição | | ------------- | ------ | ----------- | -------------------------------------------------------- | | `firstname` | string | Sim | Primeiro nome do cliente (máx. 29 caracteres) | | `lastname` | string | Sim | Sobrenome do cliente (máx. 29 caracteres) | | `email` | string | Sim | E-mail do cliente (deve ser único por negócio) | | `phone` | string | Não | Número de telefone do cliente no formato: +234XXXXXXXXXX | | `bvn` | string | Sim | Bank Verification Number do cliente | | `dateOfBirth` | string | Sim | Data de nascimento do cliente no formato `yyyy-MM-dd` | ### **Exemplo de requisição para Endereço Filho** ```json theme={null} { "firstname": "John", "lastname": "Doe", "email": "john.doe@example.com", "phone": "+2348161846125", "bvn": "22345678901", "dateOfBirth": "1992-08-14" } ``` ### **Exemplo de resposta** ```json theme={null} { "data": { "id": "8180309e-1ead-4a72-a013-b5674600ce4c", "accountName": "John Doe", "accountNumber": "9018927611", "bankName": "Polaris Bank", "bankCode": "076", "currency": "NGN", "type": "AUTO_FUNDING", "isActive": true, "status": "ACTIVE", "reference": "20", "customer": { "id": "caa17eb8-4da8-45b4-a866-81dd0a1df613", "name": "John Doe", "email": "john.doe@example.com", "phone": "+2348161846125", "status": "ACTIVE", "network": "mainnet" }, "wallet": { "id": "35e964a6-436a-424f-bf3a-618cc060feea", "name": "Base Wallet", "address": "0xD8582C57E56Ef45f9fe82870aDF63d9baB89e1F7" }, "createdAt": "2025-11-06T18:30:34.286Z", "updatedAt": "2025-11-06T18:30:34.286Z" }, "message": "Virtual account created successfully", "statusCode": 201 } ``` ## Múltiplas Contas Virtuais Você pode criar várias contas virtuais por wallet ou endereço filho. Isso é útil quando: * Um cliente precisa de contas separadas para finalidades distintas (por exemplo, poupança, pagamentos) * Você deseja rastrear pagamentos de fontes diferentes separadamente * A conta virtual existente de um cliente precisa ser substituída mantendo o histórico ## Listando Contas Virtuais O endpoint de listagem retorna uma lista paginada de todas as contas virtuais. Use os parâmetros de query para filtrar e paginar os resultados. ### **Parâmetros de Query** | Parâmetro | Tipo | Descrição | | ---------- | ------- | -------------------------------------------- | | `page` | number | Número da página (padrão: 1) | | `limit` | number | Resultados por página (padrão: 10) | | `isActive` | boolean | Filtrar por status ativo (`true` ou `false`) | ### **Exemplo de resposta** ```json theme={null} { "message": "Virtual accounts retrieved successfully", "statusCode": 200, "data": [ { "id": "597ef702-f096-4f8a-a542-29e8757ba208", "reference": "172", "accountNumber": "9012271961", "accountName": "John Doe", "bankName": "Polaris Bank", "bankCode": "076", "currency": "NGN", "isActive": true, "status": "ACTIVE", "type": "AUTO_FUNDING", "createdAt": "2025-01-21T22:15:55.746Z", "updatedAt": "2025-01-21T22:15:55.746Z", "customer": { "id": "3082e278-557a-44f0-9205-c2639560cd5a", "name": "John Doe", "email": "john.doe@example.com", "phone": "+2346112768485", "status": "ACTIVE", "network": "mainnet" }, "wallet": { "id": "35e964a6-436a-424f-bf3a-618cc060feea", "name": "Base Wallet", "address": "0xD8582C57E56Ef45f9fe82870aDF63d9baB89e1F7" }, "address": null } ], "meta": { "totalItems": 4, "itemCount": 4, "itemsPerPage": 10, "totalPages": 1, "currentPage": 1 } } ``` ## Obtendo uma Conta Virtual única Para obter uma conta virtual específica por ID, use a [API de Obter Conta Virtual para master wallets](/en/api-reference/virtual-accounts/master-wallet-get-one) ou a [API de Obter Conta Virtual para endereços filhos](/en/api-reference/virtual-accounts/child-address-get-one). ### **Exemplo de resposta** ```json theme={null} { "message": "Virtual account retrieved successfully", "statusCode": 200, "data": { "id": "597ef702-f096-4f8a-a542-29e8757ba208", "reference": "172", "accountNumber": "9012271961", "accountName": "John Doe", "bankName": "Polaris Bank", "bankCode": "076", "currency": "NGN", "isActive": true, "status": "ACTIVE", "type": "AUTO_FUNDING", "createdAt": "2025-01-21T22:15:55.746Z", "updatedAt": "2025-01-21T22:15:55.746Z", "customer": { "id": "3082e278-557a-44f0-9205-c2639560cd5a", "name": "John Doe", "email": "john.doe@example.com", "phone": "+2348161846125", "status": "ACTIVE", "network": "mainnet" }, "wallet": { "id": "35e964a6-436a-424f-bf3a-618cc060feea", "name": "Base Wallet", "address": "0xD8582C57E56Ef45f9fe82870aDF63d9baB89e1F7" }, "address": null } } ``` ## Transações da Conta Virtual Você pode obter todas as transações associadas a uma conta virtual específica usando o endpoint de transações. ### **Parâmetros de Query** | Parâmetro | Tipo | Descrição | | --------- | ------ | ---------------------------------- | | `page` | number | Número da página (padrão: 1) | | `limit` | number | Resultados por página (padrão: 10) | ### **Exemplo de resposta** ```json theme={null} { "message": "Virtual account transactions retrieved successfully", "statusCode": 200, "data": [ { "id": "ad3ce9a3-3e1c-43dc-bb7f-2c570fc7bfdc", "reference": "auto-funding-09026725110701402449700167083590131815", "senderAddress": "0xD2b6be31932E0294F2ebD14a008C3f1E05B47BC4", "recipientAddress": "0xbaD4E4B5e6660AcD138F776a992b566e8Bf3bb15", "amount": "50.0", "amountPaid": "50.0", "amountUSD": "0.03382", "currency": "NGN", "status": "SUCCESS", "type": "DEPOSIT", "note": "Auto funding of 50.0 cNGN to 0xbaD4E4B5e6660AcD138F776a992b566e8Bf3bb15", "network": "mainnet", "metadata": { "autoFunding": { "narration": "NIBSS:9018927611:SULEIMAN, ABDULFATAI:Sending:090267251107014024497001670835", "sessionId": "09026725110701402449700167083590131815", "senderBankName": "KUDA MFB", "senderAccountName": "SULEIMAN, ABDULFATAI" } }, "createdAt": "2025-01-22T22:29:28.679Z", "asset": { "name": "cNGN", "symbol": "cNGN", "currency": "NGN" }, "blockchain": { "name": "base", "slug": "base" } } ], "meta": { "totalItems": 1, "itemCount": 1, "itemsPerPage": 10, "totalPages": 1, "currentPage": 1 } } ``` O campo `metadata.autoFunding` contém detalhes sobre a origem do pagamento em fiat, incluindo o nome do banco do remetente, o nome da conta e a narração da transação da transferência bancária. ## Regenerando Contas Virtuais O endpoint de regeneração permite criar uma nova conta virtual para um cliente desativando a existente. Isso é útil quando: * Os dados bancários de um cliente precisam ser alterados * A conta virtual foi comprometida * Você precisa migrar um cliente para um banco diferente ### **Parâmetros de regeneração** | Parâmetro | Tipo | Obrigatório | Descrição | | ----------- | ------ | ----------- | -------------------------------------------------------- | | `firstname` | string | Sim | Primeiro nome do cliente (máx. 29 caracteres) | | `lastname` | string | Sim | Sobrenome do cliente (máx. 29 caracteres) | | `email` | string | Sim | E-mail do cliente | | `phone` | string | Não | Número de telefone do cliente no formato: +234XXXXXXXXXX | | `reason` | string | Sim | Motivo da regeneração da conta virtual | ### **Exemplo de requisição** ```json theme={null} { "firstname": "John", "lastname": "Doe", "email": "john.doe@example.com", "phone": "+2348161846125", "reason": "Customer requested new account number" } ``` A operação de regeneração desativará a conta virtual existente e criará uma nova. O histórico de transações da conta original é preservado e ainda pode ser consultado. ## Atualizando Contas Virtuais Você pode ativar ou desativar contas virtuais para controlar o comportamento de auto-funding. Use a [API de Atualizar Conta Virtual para master wallets](/en/api-reference/virtual-accounts/master-wallet-update) ou a [API de Atualizar Conta Virtual para endereços filhos](/en/api-reference/virtual-accounts/child-address-update). ### **Comportamento de Auto-Funding** * **Contas ativas**: Os pagamentos recebidos acionam a emissão automática de stablecoin * **Contas inativas**: Os pagamentos são recebidos, mas o auto-funding é desabilitado ### **Parâmetros de atualização** | Parâmetro | Tipo | Obrigatório | Descrição | | ---------- | ------- | ----------- | ------------------------------------------ | | `isActive` | boolean | Sim | `true` para ativar, `false` para desativar | ### **Exemplo de requisição** ```json theme={null} { "isActive": false } ``` ### **Exemplo de resposta** ```json theme={null} { "message": "Virtual account updated successfully", "statusCode": 200, "data": { "id": "597ef702-f096-4f8a-a542-29e8757ba208", "accountNumber": "9012271961", "accountName": "John Doe", "bankName": "Polaris Bank", "isActive": false, "status": "INACTIVE", "type": "AUTO_FUNDING" } } ``` Quando uma conta virtual é desativada (`isActive: false`), os pagamentos ainda podem ser recebidos, mas o processo automático de emissão e transferência de stablecoin é desabilitado. Você pode reativar a conta a qualquer momento para reativar o auto-funding. ## Webhooks As contas virtuais acionam eventos de webhook quando os pagamentos são recebidos e processados. Para contas do tipo `AUTO_FUNDING`, você receberá notificações por webhook em cada etapa do fluxo de processamento do pagamento. ### **Eventos de Webhook** Quando um cliente envia um pagamento em fiat para uma conta virtual: 1. **`deposit.processing`** - Acionado imediatamente quando o pagamento em fiat é recebido na conta virtual. Indica que o pagamento foi detectado e o processo de emissão está prestes a começar. 2. **`deposit.success`** - Acionado quando a stablecoin foi emitida e transferida com sucesso para a wallet ou endereço vinculado. Confirma que todo o processo de auto-funding foi concluído. 3. **`deposit.failed`** - Acionado se o processo de emissão ou transferência falhar em algum momento. 4. **`deposit.cancelled`** - Acionado se a transação for cancelada antes da conclusão. ### **Exemplo de payload de Webhook** ```json theme={null} { "event": "deposit.success", "data": { "id": "ad3ce9a3-3e1c-43dc-bb7f-2c570fc7bfdc", "reference": "auto-funding-09026725110701402449700167083590131815", "amount": "50.0", "currency": "NGN", "status": "SUCCESS", "type": "DEPOSIT", "network": "mainnet", "metadata": { "autoFunding": { "sessionId": "09026725110701402449700167083590131815", "senderBankName": "KUDA MFB", "senderAccountName": "SULEIMAN, ABDULFATAI" } }, "virtualAccount": { "id": "597ef702-f096-4f8a-a542-29e8757ba208", "accountNumber": "9012271961", "bankName": "Polaris Bank" }, "wallet": { "id": "35e964a6-436a-424f-bf3a-618cc060feea", "name": "Base Wallet" } } } ``` Os webhooks são acionados apenas para contas virtuais ativas (`isActive: true`). Se uma conta estiver desativada, os pagamentos ainda podem ser recebidos, mas os eventos de webhook não serão enviados até que a conta seja reativada. Para mais informações sobre a configuração de webhooks, a estrutura do payload e o tratamento de eventos, consulte a [documentação de Webhooks](/en/essentials/webhooks). ## Casos de uso ### **Pagamentos de E-commerce** Crie contas virtuais para que os clientes recebam pagamentos por produtos ou serviços. A conversão automática para stablecoins permite uma integração fluida com o seu sistema de pagamentos baseado em blockchain. ### **Serviços de assinatura** Vincule contas virtuais às assinaturas dos clientes, permitindo pagamentos recorrentes por meio de transferências bancárias tradicionais que são automaticamente convertidos em stablecoins. ### **Transações de marketplace** Habilite transações peer-to-peer onde os clientes podem enviar pagamentos em fiat que são instantaneamente convertidos em stablecoins e creditados em sua wallet. ### **Serviços de remessas** Forneça aos clientes contas virtuais para receber remessas em NGN, que são automaticamente convertidas em stablecoins para facilitar transferências internacionais. ## Próximos passos Assim que houver cNGN em sua wallet: * **[Swap](/en/essentials/swap)** - Converta cNGN para USDT, USDC ou outras stablecoins sob demanda * **[Auto-Settlement](/en/essentials/auto-settlements)** - Converta automaticamente cNGN para USDT/USDC em cada depósito ## Boas práticas ### **Gerenciamento de contas** * **Use o mesmo payload de criação em ambas as rotas**: A criação de contas virtuais para master wallet e endereço filho usa os mesmos dados do cliente (`firstname`, `lastname`, `email`, `phone`, `bvn`, `dateOfBirth`) * **Formato do número de telefone**: Para a criação de contas virtuais, use sempre o formato correto (`+234XXXXXXXXXX`) para números de telefone nigerianos * **Ativação de contas**: Ative as contas somente quando estiver pronto para processar pagamentos * **Monitore o status das contas**: Verifique regularmente o status das contas e gerencie as contas inativas adequadamente * **Documente os motivos da regeneração**: Sempre forneça motivos claros ao regenerar contas para fins de auditoria ### **Múltiplas contas** * **Planeje a estrutura das suas contas**: Decida desde o início quantas contas cada cliente pode precisar * **Acompanhe o histórico das contas**: Ao regenerar, mantenha as referências aos IDs das contas anteriores para a reconciliação de transações ### **Segurança** * **Verificação do cliente**: Verifique as informações do cliente antes de criar contas virtuais * **Validação de conta**: Valide os dados da conta antes de processar pagamentos * **Controle de acesso**: Implemente controles de acesso adequados para o gerenciamento de contas virtuais ## Tratamento de erros A API retorna códigos de status HTTP padrão e respostas de erro. Erros comuns incluem: | Código de status | Erro | Descrição | | ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------ | | `400` | Bad Request | Parâmetros de requisição inválidos (por exemplo, formato de telefone inválido ou detalhes de conta mal formatados) | | `401` | Unauthorized | Chave de API ausente ou inválida | | `404` | Not Found | Conta virtual ou wallet não encontrada | | `422` | Unprocessable Entity | Validação falhou (por exemplo, faltam campos obrigatórios) | ### **Exemplo de resposta de erro** ```json theme={null} { "message": "Validation failed", "statusCode": 422, "error": "Unprocessable Entity" } ``` ## Suporte * **E-mail**: [support@blockradar.co](mailto:support@blockradar.co) * **Chat ao vivo**: Disponível no dashboard * **Referência da API**: [API de Contas Virtuais](/en/api-reference/virtual-accounts/master-wallet-get-all) Precisa de suporte para stablecoins ou moedas adicionais? Entre em contato com [support@blockradar.co](mailto:support@blockradar.co).