Depositar Fiat - Blockradar

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.

Pré-requisitos

Antes de usar a API de Contas Virtuais, certifique-se de ter:

Chave de API

Obtenha sua chave de API no Dashboard do Blockradar. Acesse Developers para gerar uma.

Wallet criada

Crie uma wallet pela API de Criar Wallet ou pelo dashboard. Você precisará do walletId para as operações de conta virtual.

Compliance aprovado

Preencha o Formulário de Due Diligence (consulte os Requisitos de Compliance abaixo).

Recurso habilitado

Solicite a ativação do recurso de contas virtuais após a aprovação do compliance. Entre em contato com [email protected] ou use o chat ao vivo no dashboard.

Ambiente Mainnet

As contas virtuais estão disponíveis apenas em MAINNET. Os ambientes de testnet não suportam operações de conta virtual.

Suporte a Stablecoin

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

Criação de conta

Crie contas virtuais vinculadas a master wallets ou endereços filhos com as informações do cliente.

Recebimento de pagamento

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

Auto-Funding

Os pagamentos acionam automaticamente a emissão do valor equivalente em stablecoin.

Gerenciamento de fundos

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 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//virtual-accounts – Criar uma conta virtual para uma master wallet
GET /wallets//virtual-accounts – Listar todas as contas virtuais (paginado)
GET /wallets//virtual-accounts/ – Obter uma conta virtual específica
GET /wallets//virtual-accounts//transactions – Obter transações de uma conta virtual
PATCH /wallets//virtual-accounts/ – Atualizar o status de uma conta virtual
POST /wallets//virtual-accounts//regenerate – Regenerar uma 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 – Listar todas as contas virtuais (paginado)
GET /wallets//addresses//virtual-accounts/ – Obter uma conta virtual específica
GET /wallets//addresses//virtual-accounts//transactions – Obter transações de uma conta virtual
PATCH /wallets//addresses//virtual-accounts/ – Atualizar o status de uma conta virtual
POST /wallets//addresses//virtual-accounts//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 para master wallets ou a API de Criar Conta Virtual para endereços filhos.

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

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "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

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "phone": "+2348161846125",
  "bvn": "22345678901",
  "dateOfBirth": "1992-08-14"
}

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
}

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

{
  "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": "[email protected]",
        "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 ou a API de Obter Conta Virtual para endereços filhos.

Exemplo de resposta

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

{
  "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

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "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 ou a API de Atualizar Conta Virtual para endereços filhos.

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

{
  "isActive": false
}

Exemplo de resposta

{
  "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:

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

Exemplo de payload de Webhook

{
  "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.

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 - Converta cNGN para USDT, USDC ou outras stablecoins sob demanda
Auto-Settlement - 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

{
  "message": "Validation failed",
  "statusCode": 422,
  "error": "Unprocessable Entity"
}

Suporte

E-mail: [email protected]
Chat ao vivo: Disponível no dashboard
Referência da API: API de Contas Virtuais

Precisa de suporte para stablecoins ou moedas adicionais? Entre em contato com [email protected].

Começar

Carteiras

Receber Pagamentos

Enviar Pagamentos

Converter e Gerenciar

Conformidade e Recuperação

Integrações

Documentation Index

​Pré-requisitos

​Como funciona

Criação de conta

Recebimento de pagamento

Auto-Funding

Gerenciamento de fundos

​Fluxo de Auto-Funding

​1. Recebimento do pagamento

​2. Emissão automática

​3. Transferência na blockchain

​Requisitos de Compliance

​Documentos necessários

​Enviar solicitação

​Moeda suportada

​Endpoints da API

​Endpoints de Master Wallet

​Endpoints de Endereço Filho

​Criando Contas Virtuais

​Parâmetros da requisição para Master Wallet

​Exemplo de requisição para Master Wallet

​Parâmetros da requisição para Endereço Filho

​Exemplo de requisição para Endereço Filho

​Exemplo de resposta

​Múltiplas Contas Virtuais

​Listando Contas Virtuais

​Parâmetros de Query

​Exemplo de resposta

​Obtendo uma Conta Virtual única

​Exemplo de resposta

​Transações da Conta Virtual

​Parâmetros de Query

​Exemplo de resposta

​Regenerando Contas Virtuais

​Parâmetros de regeneração

​Exemplo de requisição

​Atualizando Contas Virtuais

​Comportamento de Auto-Funding

​Parâmetros de atualização

​Exemplo de requisição

​Exemplo de resposta

​Webhooks

​Eventos de Webhook

​Exemplo de payload de Webhook

​Casos de uso

​Pagamentos de E-commerce

​Serviços de assinatura

​Transações de marketplace

​Serviços de remessas

​Próximos passos

​Boas práticas

​Gerenciamento de contas

​Múltiplas contas

​Segurança

​Tratamento de erros

​Exemplo de resposta de erro

​Suporte

Pré-requisitos

Como funciona

Fluxo de Auto-Funding

1. Recebimento do pagamento

2. Emissão automática

3. Transferência na blockchain

Requisitos de Compliance

Documentos necessários

Enviar solicitação

Moeda suportada

Endpoints da API

Endpoints de Master Wallet

Endpoints de Endereço Filho

Criando Contas Virtuais

Parâmetros da requisição para Master Wallet

Exemplo de requisição para Master Wallet

Parâmetros da requisição para Endereço Filho

Exemplo de requisição para Endereço Filho

Exemplo de resposta

Múltiplas Contas Virtuais

Listando Contas Virtuais

Parâmetros de Query

Exemplo de resposta

Obtendo uma Conta Virtual única

Exemplo de resposta

Transações da Conta Virtual

Parâmetros de Query

Exemplo de resposta

Regenerando Contas Virtuais

Parâmetros de regeneração

Exemplo de requisição

Atualizando Contas Virtuais

Comportamento de Auto-Funding

Parâmetros de atualização

Exemplo de requisição

Exemplo de resposta

Webhooks

Eventos de Webhook

Exemplo de payload de Webhook

Casos de uso

Pagamentos de E-commerce

Serviços de assinatura

Transações de marketplace

Serviços de remessas

Próximos passos

Boas práticas

Gerenciamento de contas

Múltiplas contas

Segurança

Tratamento de erros

Exemplo de resposta de erro

Suporte