Contas Virtuais - Blockradar

A API de Contas Virtuais fornece endpoints para gerenciar contas bancárias virtuais vinculadas a carteiras mestras ou endereços filhos. Esta API permite que empresas criem contas virtuais para clientes receberem pagamentos, recuperem detalhes de contas virtuais e ativem/desativem contas virtuais.

Introdução

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. Isso preenche a lacuna entre o sistema bancário tradicional e os pagamentos em stablecoin, permitindo processamento de pagamento perfeito para seu negócio. Quando um cliente envia moeda fiat para uma conta virtual, o sistema pode automaticamente cunhar o equivalente em stablecoin e transferi-lo para a carteira ou endereço vinculado, fornecendo capacidades de processamento de pagamento em tempo real.

Como Funcionam as Contas Virtuais

Criação de Conta

Crie contas virtuais vinculadas a carteiras mestras ou endereços filhos com informações do cliente.

Recebimento de Pagamento

Clientes enviam pagamentos em fiat para a conta virtual usando transferências bancárias tradicionais.

Financiamento Automático

Para contas do tipo AUTO_FUNDING, os pagamentos acionam automaticamente a cunhagem da stablecoin.

Gerenciamento de Fundos

Stablecoins cunhadas são transferidas para a carteira ou endereço vinculado para uso imediato.

Tipos de Contas Virtuais

As contas virtuais suportam diferentes tipos com comportamentos variados:

AUTO_FUNDING (Padrão)

Cunha automaticamente stablecoin quando pagamentos em fiat são recebidos
Transfere stablecoin para a carteira/endereço vinculado imediatamente
Melhor para processamento de pagamento em tempo real
Fornece conversão instantânea de fiat para stablecoin

O fluxo de financiamento automático se aplica apenas a contas virtuais com tipo AUTO_FUNDING. Outros tipos têm comportamentos de processamento diferentes.

Como Funciona - Fluxo de Financiamento Automático

Quando um cliente envia moeda fiat para uma conta virtual com tipo AUTO_FUNDING:

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.

O fluxo de financiamento automático se aplica apenas a contas virtuais com tipo AUTO_FUNDING. Outros tipos têm comportamentos de processamento diferentes.

Pré-requisitos

Antes de criar contas virtuais, certifique-se de:

Requisitos de conformidade devem ser completados (veja a seção Requisitos de Conformidade abaixo)
Recurso de contas virtuais deve estar habilitado para seu negócio (entre em contato com [email protected] ou use o chat ao vivo no painel para habilitar o recurso após aprovação de conformidade)
Disponível apenas no ambiente MAINNET (não disponível na testnet)
Carteira Mestra deve suportar ativo stablecoin - Seu plano de conta deve incluir acesso a stablecoin (atualize em Painel → Configurações → Assinatura se necessário)

Ambiente: Contas virtuais estão disponíveis apenas no ambiente MAINNET. Ambientes de testnet não suportam criação ou operações de contas virtuais.

Requisitos de Conformidade

Antes de solicitar acesso ao recurso de contas virtuais, você deve completar o processo de integração de conformidade. Os seguintes documentos e informações são necessários:

Documentos Necessários

Certificado de Incorporação para seu negócio e uma lista de acionistas (por exemplo, documento MEMART do CAC nigeriano)
Conta de serviço público recente para confirmar o endereço comercial
Documentos de identidade dos UBO(s) (Beneficiários Finais) e Diretores
Certificado Fiscal/TIN
Política de KYC da Empresa
Política de AML/CFT/CPF da Empresa
Contas de serviço público recentes dos UBO(s) e Diretores

Enviando Documentos de Conformidade

Envie todos os documentos e informações necessários por e-mail para a equipe de conformidade:

E-mail: [email protected]
CC: [email protected], [email protected]

O processo de revisão de conformidade deve ser concluído antes que as contas virtuais possam ser habilitadas para seu negócio. Certifique-se de que todos os documentos estejam atualizados e devidamente formatados antes do envio.

Moeda Suportada

Fiat: NGN (Naira Nigeriana) - Transferências bancárias tradicionais
Stablecoin: cNGN - Cunhada automaticamente na blockchain (para tipo AUTO_FUNDING)

Endpoints da API

Abaixo estão os principais endpoints da API para operações de Contas Virtuais:

Endpoints da Carteira Mestra

POST /wallets//virtual-accounts – Criar uma conta virtual para uma carteira mestra
GET /wallets//virtual-accounts – Recuperar detalhes da conta virtual
PATCH /wallets//virtual-accounts/ – Atualizar status da conta virtual

Endpoints de Endereço Filho

POST /wallets//addresses//virtual-accounts – Criar uma conta virtual para um endereço filho
GET /wallets//addresses//virtual-accounts – Recuperar detalhes da conta virtual
PATCH /wallets//addresses//virtual-accounts/ – Atualizar status da 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 para carteiras mestras ou a API de Criar Conta Virtual para endereços filhos.

Parâmetros de Solicitação

Parâmetro	Tipo	Obrigatório	Descrição
`firstname`	string	Sim	Primeiro nome do cliente
`lastname`	string	Sim	Sobrenome do cliente
`email`	string	Sim	Endereço de e-mail do cliente (deve ser único por negócio)
`phone`	string	Sim	Número de telefone do cliente no formato: +234XXXXXXXXXX

Exemplo de Resposta

{
  "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": "[email protected]",
      "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
}

Recuperando Contas Virtuais

Para recuperar detalhes de contas virtuais, use a API de Obter Conta Virtual para carteiras mestras ou a API de Obter Conta Virtual para endereços filhos.

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 ou a API de Atualizar Conta Virtual para endereços filhos.

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

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. Para contas do tipo AUTO_FUNDING, 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 com tipo AUTO_FUNDING:

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.
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.
deposit.failed - Acionado se o processo de cunhagem ou transferência falhar em qualquer ponto.
deposit.cancelled - Acionado se a transação for cancelada antes da conclusão.

Payload do Webhook

O payload do webhook segue o formato padrão de webhook de depósito. O type da transação será DEPOSIT, e o campo status refletirá o estado atual (PROCESSING, SUCCESS, FAILED ou CANCELLED).

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.

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.

Melhores Práticas

Gerenciamento de Contas

Endereços de e-mail únicos: Certifique-se de que cada cliente tenha um endereço de e-mail único
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

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

Suporte e Recursos

Obtendo Ajuda

Suporte para mais stablecoins e moedas: Entre em contato com [email protected] para habilitar suporte para sua stablecoin e moeda
E-mail: [email protected]
Chat ao vivo: Disponível no painel
Referência da API: Contas Virtuais

As contas virtuais fornecem uma maneira poderosa de conectar o sistema bancário tradicional com pagamentos em blockchain. Comece criando contas para suas carteiras mestras, depois expanda para endereços filhos conforme seu caso de uso exigir. Sempre certifique-se de que suas carteiras suportam stablecoin para contas do tipo AUTO_FUNDING.

Bons hacks! ❤️

Começar

Essenciais

​Introdução

​Como Funcionam as Contas Virtuais

Criação de Conta

Recebimento de Pagamento

Financiamento Automático

Gerenciamento de Fundos

​Tipos de Contas Virtuais

​AUTO_FUNDING (Padrão)

​Como Funciona - Fluxo de Financiamento Automático

​1. Recebimento de Pagamento

​2. Cunhagem Automática

​3. Transferência na Blockchain

​Pré-requisitos

​Requisitos de Conformidade

​Documentos Necessários

​Enviando Documentos de Conformidade

​Moeda Suportada

​Endpoints da API

​Endpoints da Carteira Mestra

​Endpoints de Endereço Filho

​Criando Contas Virtuais

​Parâmetros de Solicitação

​Exemplo de Resposta

​Recuperando Contas Virtuais

​Atualizando Contas Virtuais

​Comportamento de Financiamento Automático

​Parâmetros de Atualização

​Webhooks

​Eventos de Webhook

​Payload do Webhook

​Casos de Uso

​Pagamentos de E-commerce

​Serviços de Assinatura

​Transações de Marketplace

​Serviços de Remessa

​Melhores Práticas

​Gerenciamento de Contas

​Segurança

​Suporte e Recursos

​Obtendo Ajuda

Introdução

Como Funcionam as Contas Virtuais

Tipos de Contas Virtuais

AUTO_FUNDING (Padrão)

Como Funciona - Fluxo de Financiamento Automático

1. Recebimento de Pagamento

2. Cunhagem Automática

3. Transferência na Blockchain

Pré-requisitos

Requisitos de Conformidade

Documentos Necessários

Enviando Documentos de Conformidade

Moeda Suportada

Endpoints da API

Endpoints da Carteira Mestra

Endpoints de Endereço Filho

Criando Contas Virtuais

Parâmetros de Solicitação

Exemplo de Resposta

Recuperando Contas Virtuais

Atualizando Contas Virtuais

Comportamento de Financiamento Automático

Parâmetros de Atualização

Webhooks

Eventos de Webhook

Payload do Webhook

Casos de Uso

Pagamentos de E-commerce

Serviços de Assinatura

Transações de Marketplace

Serviços de Remessa

Melhores Práticas

Gerenciamento de Contas

Segurança

Suporte e Recursos

Obtendo Ajuda