> ## 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. # Contas Virtuais > Crie e gerencie contas bancárias virtuais vinculadas a carteiras mestras ou endereços filhos para pagamentos fiat-para-stablecoin perfeitos Em resumo
As Contas Virtuais permitem que seus clientes recebam pagamentos em fiat através de transferências bancárias tradicionais, que são automaticamente convertidas em stablecoins na blockchain. Você pode criar múltiplas contas virtuais por carteira ou endereço, com suporte para rotulagem, 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 API no [Painel da Blockradar](https://dashboard.blockradar.co). Navegue até **Developers** para gerar uma. Crie uma carteira via [API Criar Carteira](/pt/api-reference/wallets/create-wallet) ou painel. Você precisará do `walletId` para operações de contas virtuais. Complete o [Formulário de Due Diligence](https://airtable.com/appsn5KFgmZhzQ9lh/pag8ytSkiF9k5w590/form) (veja [Requisitos de Conformidade](#requisitos-de-conformidade) abaixo). Solicite a ativação do recurso de contas virtuais após aprovação de conformidade. Contate [support@blockradar.co](mailto:support@blockradar.co) ou use o chat ao vivo no painel. Contas virtuais estão disponíveis apenas na **MAINNET**. Ambientes de testnet não suportam operações de contas virtuais. Certifique-se de que seu plano de conta inclua acesso a stablecoin. Atualize em **Painel → Configurações → Assinatura** se necessário. ## Como Funciona Crie contas virtuais vinculadas a carteiras mestras ou endereços filhos com informações do cliente. Clientes enviam pagamentos em fiat para a conta virtual usando transferências bancárias tradicionais. Os pagamentos acionam automaticamente a cunhagem do equivalente em stablecoin. Stablecoins cunhadas são transferidas para a carteira ou endereço vinculado para uso imediato. ## Fluxo de Financiamento Automático Todas as contas virtuais usam `AUTO_FUNDING`, que converte automaticamente fiat para stablecoin. Quando um cliente envia moeda fiat para uma conta virtual: ### **1. Recebimento de Pagamento** O pagamento é recebido na conta virtual através de transferência bancária tradicional. Um webhook `deposit.processing` é acionado nesta etapa. ### **2. Cunhagem Automática** O sistema cunha automaticamente o equivalente em stablecoin na blockchain. ### **3. Transferência na Blockchain** A stablecoin cunhada é transferida para a carteira ou endereço vinculado da conta virtual. Um webhook `deposit.success` é acionado após conclusão bem-sucedida. ## Requisitos de Conformidade Antes de acessar contas virtuais, complete o processo de integração de conformidade. ### **Documentos Necessários** * Certificado de Incorporação * ID para Diretores/Acionistas * Documento de Política KYC ### **Enviar Aplicação** Complete o [Formulário de Due Diligence](https://airtable.com/appsn5KFgmZhzQ9lh/pag8ytSkiF9k5w590/form) com os detalhes da sua empresa, informações de conformidade e upload de documentos. ## Moeda Suportada * **Fiat**: NGN (Naira Nigeriana) - Transferências bancárias tradicionais * **Stablecoin**: cNGN - Cunhada automaticamente na blockchain ## Endpoints da API Abaixo estão os principais endpoints da API para operações de Contas Virtuais: ### **Endpoints da Carteira Mestra** * [POST /wallets/{walletId}/virtual-accounts](/pt/api-reference/virtual-accounts/master-wallet-create) – Criar uma conta virtual para uma carteira mestra * [GET /wallets/{walletId}/virtual-accounts](/pt/api-reference/virtual-accounts/master-wallet-get-all) – Listar todas as contas virtuais (paginado) * [GET /wallets/{walletId}/virtual-accounts/{virtualAccountId}](/pt/api-reference/virtual-accounts/master-wallet-get-one) – Recuperar uma conta virtual específica * [GET /wallets/{walletId}/virtual-accounts/{virtualAccountId}/transactions](/pt/api-reference/virtual-accounts/master-wallet-transactions) – Obter transações de uma conta virtual * [PATCH /wallets/{walletId}/virtual-accounts/{virtualAccountId}](/pt/api-reference/virtual-accounts/master-wallet-update) – Atualizar status da conta virtual * [POST /wallets/{walletId}/virtual-accounts/{virtualAccountId}/regenerate](/pt/api-reference/virtual-accounts/master-wallet-regenerate) – Regenerar uma conta virtual ### **Endpoints de Endereço Filho** * [POST /wallets/{walletId}/addresses/{addressId}/virtual-accounts](/pt/api-reference/virtual-accounts/child-address-create) – Criar uma conta virtual para um endereço filho * [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts](/pt/api-reference/virtual-accounts/child-address-get-all) – Listar todas as contas virtuais (paginado) * [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}](/pt/api-reference/virtual-accounts/child-address-get-one) – Recuperar uma conta virtual específica * [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/transactions](/pt/api-reference/virtual-accounts/child-address-transactions) – Obter transações de uma conta virtual * [PATCH /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}](/pt/api-reference/virtual-accounts/child-address-update) – Atualizar status da conta virtual * [POST /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/regenerate](/pt/api-reference/virtual-accounts/child-address-regenerate) – Regenerar uma conta virtual ## Criando Contas Virtuais Você pode criar contas virtuais tanto para carteiras mestras quanto para endereços filhos, dependendo do seu caso de uso. Use a [API de Criar Conta Virtual](/pt/api-reference/virtual-accounts/master-wallet-create) para carteiras mestras ou a [API de Criar Conta Virtual para endereços filhos](/pt/api-reference/virtual-accounts/child-address-create). ### **Parâmetros de Solicitação para Carteira Mestra** | 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 | Endereço de 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 Solicitação para Carteira Mestra** ```json theme={null} { "firstname": "John", "lastname": "Doe", "email": "john.doe@example.com", "phone": "+2348161846125", "bvn": "22345678901", "dateOfBirth": "1992-08-14" } ``` ### **Parâmetros de Solicitaçã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 | Endereço de 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 Solicitaçã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 múltiplas contas virtuais por carteira ou endereço filho. Isso é útil quando: * Um cliente precisa de contas separadas para diferentes propósitos (ex.: poupança, pagamentos) * Você quer rastrear pagamentos de diferentes fontes separadamente * A conta virtual existente de um cliente precisa ser substituída mantendo o histórico Apenas uma conta virtual por e-mail de cliente pode estar ativa por vez. Criar uma nova conta virtual para o mesmo e-mail exigirá desativar a existente primeiro, ou usar o endpoint de regeneração. ## Listando Contas Virtuais O endpoint de listagem retorna uma lista paginada de todas as contas virtuais. Use parâmetros de consulta para filtrar e paginar resultados. ### **Parâmetros de Consulta** | 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", "label": null, "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 } } ``` ## Recuperando uma Conta Virtual Para recuperar uma conta virtual específica por ID, use a [API de Obter Conta Virtual para carteiras mestras](/pt/api-reference/virtual-accounts/master-wallet-get-one) ou a [API de Obter Conta Virtual para endereços filhos](/pt/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", "label": "Conta Principal", "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 de Conta Virtual Você pode recuperar todas as transações associadas a uma conta virtual específica usando o endpoint de transações. ### **Parâmetros de Consulta** | 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, nome da conta e a narração da transferência bancária. ## Regenerando Contas Virtuais O endpoint de regeneração permite criar uma nova conta virtual para um cliente enquanto desativa a existente. Isso é útil quando: * Os detalhes bancários de um cliente precisam mudar * 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 | Endereço de e-mail do cliente | | `phone` | string | Não | Número de telefone do cliente no formato: +234XXXXXXXXXX | | `reason` | string | Sim | Motivo para regenerar a conta virtual | | `label` | string | Não | Rótulo personalizado para a nova conta virtual | ### **Exemplo de Solicitação** ```json theme={null} { "firstname": "John", "lastname": "Doe", "email": "john.doe@example.com", "phone": "+2348161846125", "reason": "Cliente solicitou novo número de conta", "label": "Nova Conta Principal" } ``` 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 financiamento automático. Use a [API de Atualizar Conta Virtual para carteiras mestras](/pt/api-reference/virtual-accounts/master-wallet-update) ou a [API de Atualizar Conta Virtual para endereços filhos](/pt/api-reference/virtual-accounts/child-address-update). ### **Comportamento de Financiamento Automático** * **Contas ativas**: Pagamentos recebidos acionam cunhagem automática de stablecoin * **Contas inativas**: Pagamentos são recebidos mas o financiamento automático está desabilitado ### **Parâmetros de Atualização** | Parâmetro | Tipo | Obrigatório | Descrição | | ---------- | ------- | ----------- | ------------------------------------------ | | `isActive` | boolean | Sim | `true` para ativar, `false` para desativar | ### **Exemplo de Solicitaçã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", "label": "Conta Principal" } } ``` Quando uma conta virtual é desativada (`isActive: false`), os pagamentos ainda podem ser recebidos mas o processo automático de cunhagem e transferência de stablecoin é desabilitado. Você pode reativar a conta a qualquer momento para reabilitar o financiamento automático. ## Webhooks As contas virtuais acionam eventos de webhook quando os pagamentos são recebidos e processados. Você receberá notificações de webhook em cada etapa do fluxo de processamento de pagamento. ### **Eventos de Webhook** Quando um cliente envia pagamento em fiat para uma conta virtual: 1. **`deposit.processing`** - Acionado imediatamente quando o pagamento em fiat é recebido na conta virtual. Isso indica que o pagamento foi detectado e o processo de cunhagem está prestes a começar. 2. **`deposit.success`** - Acionado quando a stablecoin foi cunhada e transferida com sucesso para a carteira ou endereço vinculado. Isso confirma que todo o processo de financiamento automático está completo. 3. **`deposit.failed`** - Acionado se o processo de cunhagem ou transferência falhar em qualquer ponto. 4. **`deposit.cancelled`** - Acionado se a transação for cancelada antes da conclusão. ### **Exemplo de Payload do 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" } } } ``` Webhooks são acionados apenas para contas virtuais ativas (`isActive: true`). Se uma conta for desativada, os pagamentos ainda podem ser recebidos, mas eventos de webhook não serão enviados até que a conta seja reativada. Para mais informações sobre configuração de webhook, estrutura de payload e tratamento de eventos, veja a [documentação de Webhooks](/pt/essentials/webhooks). ## Casos de Uso ### **Pagamentos de E-commerce** Crie contas virtuais para clientes receberem pagamentos por produtos ou serviços. A conversão automática para stablecoins permite integração perfeita com seu sistema de pagamento baseado em blockchain. ### **Serviços de Assinatura** Vincule contas virtuais a assinaturas de clientes, permitindo pagamentos recorrentes através de transferências bancárias tradicionais que são automaticamente convertidas 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 carteira. ### **Serviços de Remessa** Forneça aos clientes contas virtuais para receber remessas em NGN, que são automaticamente convertidas em stablecoins para fáceis transferências transfronteiriças. ## Próximos Passos Uma vez que cNGN esteja na sua carteira: * **[Swap](/pt/essentials/swap)** - Converta cNGN para USDT, USDC ou outras stablecoins sob demanda * **[Auto-Settlement](/pt/essentials/auto-settlements)** - Converta automaticamente cNGN para USDT/USDC em cada depósito ## Melhores Práticas ### **Gerenciamento de Contas** * **Use rótulos descritivos**: Adicione rótulos significativos às contas virtuais (ex.: "Poupança", "Pagamentos") para fácil identificação * **Endereços de e-mail únicos**: Certifique-se de que cada cliente tenha um endereço de e-mail único por conta ativa * **Formato de número de telefone**: Sempre use o formato correto (+234XXXXXXXXXX) para números de telefone nigerianos * **Ativação de conta**: Ative contas apenas quando estiver pronto para processar pagamentos * **Monitore o status da conta**: Verifique regularmente o status da conta e trate contas inativas apropriadamente * **Documente motivos de regeneração**: Sempre forneça motivos claros ao regenerar contas para fins de auditoria ### **Múltiplas Contas** * **Planeje sua estrutura de contas**: Decida antecipadamente quantas contas cada cliente pode precisar * **Use rótulos consistentemente**: Estabeleça uma convenção de nomenclatura para rótulos em sua aplicação * **Rastreie histórico de contas**: Ao regenerar, mantenha referências aos IDs de contas anteriores para reconciliação de transações ### **Segurança** * **Verificação de cliente**: Verifique as informações do cliente antes de criar contas virtuais * **Validação de conta**: Valide os detalhes da conta antes de processar pagamentos * **Controle de acesso**: Implemente controles de acesso adequados para gerenciamento de contas virtuais ## Tratamento de Erros A API retorna códigos de status HTTP padrão e respostas de erro. Os erros comuns incluem: | Código de Status | Erro | Descrição | | ---------------- | -------------------- | ------------------------------------------------------------------------------------------------ | | `400` | Bad Request | Parâmetros de solicitação inválidos (ex.: formato de e-mail inválido, nome excede 29 caracteres) | | `401` | Unauthorized | Chave API ausente ou inválida | | `404` | Not Found | Conta virtual ou carteira não encontrada | | `409` | Conflict | O e-mail já existe para uma conta virtual ativa | | `422` | Unprocessable Entity | Validação falhou (ex.: campos obrigatórios ausentes) | ### **Exemplo de Resposta de Erro** ```json theme={null} { "message": "A virtual account with this email already exists", "statusCode": 409, "error": "Conflict" } ``` Quando você receber um erro `409` por e-mail duplicado, desative primeiro a conta virtual existente ou use o endpoint de regeneração para criar uma nova conta para o mesmo cliente. ## Suporte * **E-mail**: [support@blockradar.co](mailto:support@blockradar.co) * **Chat ao vivo**: Disponível no painel * **Referência da API**: [API de Contas Virtuais](/pt/api-reference/virtual-accounts/master-wallet-get-all) Precisa de suporte para stablecoins ou moedas adicionais? Contate [support@blockradar.co](mailto:support@blockradar.co).