Depositar Fiat - Blockradar

v2 · Recomendado
v1 · Legacy

Em resumo
As Contas Virtuais permitem que seus clientes recebam fiat por meio de transferências bancárias tradicionais, que são automaticamente convertidas em stablecoins na blockchain. O fluxo v2 descobre os ativos e as moedas disponíveis para a sua wallet, retorna um schema descrevendo exatamente o que cada corredor exige e cria contas virtuais vinculadas a uma master wallet ou child address em várias moedas e stablecoins.

Os requisitos v2 retornam um JSON Schema descrevendo as informações que um corredor precisa. Quando additionalDataRequired é true, use o guia Formulários Dinâmicos para coletar, validar e enviar os campos como additionalData. O fluxo v1 está disponível na aba v1 · Legacy, mas não é mais recomendado.

Pré-requisitos

Antes de usar as Contas Virtuais, certifique-se de ter:

Chave de API

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

Wallet criada

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

Compliance aprovado

Conclua o processo de Due Diligence no Dashboard: My Wallets → Settings → Compliance. Os requisitos de conformidade e os processos de aprovação variam por região, então você só precisa concluir os que se aplicam aos rails locais que seu produto usa.

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 → Settings → Subscription.

Como funciona

Descobrir opções

Consulte os ativos e as moedas disponíveis para a sua wallet.

Obter requisitos

Recupere o schema que descreve o que o corredor selecionado precisa.

Criar conta

Crie uma conta virtual com additionalData e um label opcional.

Auto-Funding

O fiat recebido emite automaticamente a stablecoin equivalente na wallet ou endereço vinculado.

Moedas fiat suportadas

As moedas variam por corredor e provedor. Sempre obtenha o que está disponível para a sua wallet com o endpoint de descoberta em vez de fixar a lista no código. A tabela abaixo mostra as stablecoins e blockchains que cada moeda suportada abrange:

Moeda Fiat	Blockchains USDC	Blockchains USDT	Blockchains EURC
COP	Ethereum, Polygon	Ethereum	—
GHS	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
INR	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
KES	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
NGN	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
TZS	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
UGX	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base

Fluxo de Auto-Funding

Todas as contas virtuais utilizam AUTO_FUNDING, que converte automaticamente fiat em stablecoin. Quando um cliente envia fiat para uma conta virtual:

1. Recebimento do pagamento

O pagamento é recebido na conta virtual por meio de uma transferência bancária. 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. Um webhook deposit.success é acionado após a conclusão bem-sucedida.

Ativos e moedas suportados

O v2 suporta várias stablecoins e moedas. Em vez de assumir um par fixo, obtenha o que está disponível para a sua wallet com o endpoint de descoberta. Por exemplo, transferências bancárias em NGN podem auto-financiar cNGN, enquanto outros corredores liquidam em USDC ou outros ativos suportados.

Endpoints da API

Endpoints de Master Wallet

Operação	Endpoint
Descobrir opções	`GET /v2/wallets/{id}/virtual-accounts/discovery`
Obter requisitos	`GET /v2/wallets/{id}/virtual-accounts/requirements`
Criar	`POST /v2/wallets/{id}/virtual-accounts`
Listar	`GET /v2/wallets/{id}/virtual-accounts`
Obter uma	`GET /v2/wallets/{id}/virtual-accounts/{virtualAccountId}`
Atualizar status	`PATCH /v2/wallets/{id}/virtual-accounts/{virtualAccountId}`
Regenerar	`POST /v2/wallets/{id}/virtual-accounts/{virtualAccountId}/regenerate`

Endpoints de Child Address

Operação	Endpoint
Criar	`POST /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts`
Listar	`GET /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts`
Obter uma	`GET /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}`
Transações	`GET /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/transactions`
Atualizar status	`PATCH /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}`
Regenerar	`POST /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/regenerate`

Etapa 1: Descobrir opções

Consulte os ativos e as moedas disponíveis para a sua wallet para contas virtuais.

curl --request GET \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/virtual-accounts/discovery' \
  --header 'x-api-key: <api-key>'

Discovery Response

{
  "statusCode": 200,
  "message": "Successful",
  "data": {
    "assets": [
      {
        "asset": {
          "id": "ae455f23-3824-4125-baab-d158315cbcbd",
          "name": "USD Coin",
          "symbol": "USDC",
          "logoUrl": "https://cdn.example.com/assets/usdc.svg",
          "blockchain": {
            "id": "7773c3f9-f35d-4a36-9d85-5f4c537cd097",
            "name": "Ethereum",
            "symbol": "ETH",
            "slug": "ethereum",
            "tokenStandard": "ERC20",
            "logoUrl": "https://cdn.example.com/blockchains/ethereum.svg"
          }
        },
        "currencies": ["NGN"]
      }
    ],
    "currencies": {
      "NGN": {
        "code": "NGN",
        "currency": "NGN",
        "shortName": "Naira",
        "name": "Nigerian Naira",
        "symbol": "₦"
      }
    }
  }
}

Etapa 2: Obter requisitos

Obtenha o schema que descreve o que a moeda selecionada (e, opcionalmente, o ativo) exige. Interprete-o e preencha-o com Formulários Dinâmicos.

Parâmetro	Em	Obrigatório	Descrição
`currency`	query	Sim	Código de moeda ISO 4217
`assetId`	query	Não	Ativo stablecoin que recebe as liquidações
`customerId`	query	Não	Identificador de cliente existente, quando o provedor exige um
`provider`	query	Não	Slug do provedor. Omita para deixar a Blockradar rotear automaticamente

curl --request GET \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/virtual-accounts/requirements?currency=NGN&assetId=ae455f23-3824-4125-baab-d158315cbcbd' \
  --header 'x-api-key: <api-key>'

Requirements Response

{
  "statusCode": 200,
  "message": "Successful",
  "data": {
    "supported": true,
    "unlocked": true,
    "additionalDataRequired": true,
    "additionalDataSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "title": "Bank account details",
      "properties": {
        "bvn": { "type": "string", "title": "BVN", "minLength": 11, "maxLength": 11 },
        "dateOfBirth": { "type": "string", "title": "Date of birth", "format": "date" }
      },
      "required": ["bvn", "dateOfBirth"],
      "additionalProperties": false
    },
    "provider": "example-provider"
  }
}

Se additionalDataRequired for false, você pode pular a coleta de additionalData e criar a conta diretamente. Use o provider retornado aqui ao criar a conta.

Etapa 3: Criar uma conta virtual

Crie uma conta virtual para uma master wallet ou child address. Envie o objeto additionalData validado, construído a partir do schema de requisitos.

Parâmetro	Tipo	Obrigatório	Descrição
`provider`	string	Sim	Slug do provedor resolvido a partir do fluxo de requisitos
`currency`	string	Sim	Moeda da conta virtual ISO 4217
`assetId`	string	Não	Ativo stablecoin que recebe as liquidações
`customerId`	string	Não	Identificador de cliente existente, quando o provedor exige um
`additionalData`	object	Não	Valores coletados e validados contra `additionalDataSchema`
`label`	string	Não	Seu rótulo de exibição para a conta virtual (máx. 100 caracteres)

curl --request POST \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/virtual-accounts' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "provider": "example-provider",
    "currency": "NGN",
    "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
    "label": "Ada collection account",
    "additionalData": {
      "bvn": "12345678901",
      "dateOfBirth": "1992-04-18"
    }
  }'

curl --request POST \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "provider": "example-provider",
    "currency": "NGN",
    "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
    "label": "Ada collection account",
    "additionalData": {
      "bvn": "12345678901",
      "dateOfBirth": "1992-04-18"
    }
  }'

Exemplo de resposta

{
  "statusCode": 201,
  "message": "Virtual account created successfully",
  "data": {
    "created": true,
    "virtualAccount": {
      "id": "3e8fcd73-4067-4386-8c1e-9929e6a768d7",
      "reference": "va_01J2X8JQ4V9N0P7K2M6C3F5R8T",
      "accountNumber": "0123456789",
      "accountName": "Acme Ltd / Ada Okafor",
      "bankName": "Example Bank",
      "bankCode": "999",
      "currency": "NGN",
      "institutionAddress": null,
      "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
      "providerId": "1128dd40-2c94-4c16-a6bf-fbbc6afee52c",
      "isActive": true,
      "status": "active",
      "type": "AUTO_FUNDING",
      "label": "Ada collection account",
      "createdAt": "2026-07-19T12:30:00.000Z",
      "updatedAt": "2026-07-19T12:30:00.000Z"
    }
  }
}

Listando Contas Virtuais

O endpoint de listagem retorna uma lista paginada de contas virtuais. Use parâmetros de query para pesquisar, filtrar por estado de ativação e filtrar por intervalo de datas.

Parâmetros de Query

Parâmetro	Tipo	Descrição
`isActive`	boolean	Filtrar por estado de ativação (`true` ou `false`)
`search`	string	Pesquisar por referência, rótulo, nome da conta ou número da conta
`startDate`	string	Data de início ISO 8601 inclusiva. Obrigatória apenas quando `endDate` é fornecida
`endDate`	string	Data de término ISO 8601 inclusiva. Obrigatória apenas quando `startDate` é fornecida
`page`	integer	Número da página começando em 1 (padrão: 1)
`limit`	integer	Registros por página, máx. 100 (padrão: 10)

Response Example

{
  "statusCode": 200,
  "message": "Virtual accounts retrieved successfully",
  "data": [
    {
      "id": "3e8fcd73-4067-4386-8c1e-9929e6a768d7",
      "reference": "va_01J2X8JQ4V9N0P7K2M6C3F5R8T",
      "accountNumber": "0123456789",
      "accountName": "Acme Ltd / Ada Okafor",
      "bankName": "Example Bank",
      "bankCode": "999",
      "currency": "NGN",
      "institutionAddress": null,
      "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
      "providerId": "1128dd40-2c94-4c16-a6bf-fbbc6afee52c",
      "isActive": true,
      "status": "active",
      "type": "AUTO_FUNDING",
      "label": "Ada collection account",
      "createdAt": "2026-07-19T12:30:00.000Z",
      "updatedAt": "2026-07-19T12:30:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 10,
    "pageCount": 1,
    "hasPreviousPage": false,
    "hasNextPage": false
  }
}

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 child addresses.

Transações da Conta Virtual

Recupere as transações associadas a uma conta virtual usando o endpoint de transações de child address. Cada evento de auto-funding também é entregue via webhooks.

Parâmetros de Query

Parâmetro	Tipo	Descrição
`page`	integer	Número da página começando em 1 (padrão: 1)
`limit`	integer	Registros por página, máx. 100 (padrão: 10)

Response Example

{
  "statusCode": 200,
  "message": "Virtual account transactions retrieved successfully",
  "data": [
    {
      "id": "ad3ce9a3-3e1c-43dc-bb7f-2c570fc7bfdc",
      "reference": "auto-funding-09026725110701402449700167083590131815",
      "senderAddress": "0xD2b6be31932E0294F2ebD14a008C3f1E05B47BC4",
      "recipientAddress": "0xbaD4E4B5e6660AcD138F776a992b566e8Bf3bb15",
      "tokenAddress": "0x46C85152bFe9f96829aA94755D9f915F9B10EF5F",
      "amount": "50.0",
      "amountPaid": "50.0",
      "amountUSD": "50.0",
      "rateUSD": "1.0",
      "currency": "NGN",
      "hash": "0xbe0c9a4dd314b6220c4eaae218003e753e948ce6183b5b92c764501e1b4e7c0a",
      "confirmed": true,
      "status": "SUCCESS",
      "processingStatus": "SUCCESS",
      "type": "DEPOSIT",
      "note": "Auto funding of 50.0 cNGN",
      "createdAt": "2026-01-22T22:29:28.679Z",
      "updatedAt": "2026-01-22T23:15:21.849Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 10,
    "pageCount": 1,
    "hasPreviousPage": false,
    "hasNextPage": false
  }
}

Atualizando Contas Virtuais

Ative ou desative uma conta virtual 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 child addresses.

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

Request Example

{
  "isActive": false
}

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.

Regenerando Contas Virtuais

O endpoint de regeneração cria uma nova conta virtual para um cliente enquanto desativa 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 provedor diferente

Parâmetros de regeneração

Parâmetro	Tipo	Obrigatório	Descrição
`provider`	string	Sim	Slug do provedor para a conta de substituição
`currency`	string	Sim	Moeda da conta virtual ISO 4217
`reason`	string	Sim	Motivo pelo qual uma conta de substituição é necessária
`assetId`	string	Não	Ativo stablecoin que recebe as liquidações
`customerId`	string	Não	Identificador de cliente existente
`additionalData`	object	Não	Valores validados contra o schema de requisitos
`label`	string	Não	Seu rótulo de exibição para a conta virtual

Request Example

{
  "provider": "example-provider",
  "currency": "NGN",
  "reason": "The previous account was closed by the institution.",
  "label": "Ada collection account"
}

A operação de regeneração desativa a conta virtual existente e cria uma nova. O histórico de transações da conta original é preservado e ainda pode ser consultado.

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 em cada etapa do fluxo de pagamento.

Eventos de Webhook

deposit.processing — Acionado imediatamente quando o pagamento em fiat é recebido. O processo de emissão está prestes a começar.
deposit.success — Acionado quando a stablecoin foi emitida e transferida para a wallet ou endereço vinculado.
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",
    "virtualAccount": {
      "id": "3e8fcd73-4067-4386-8c1e-9929e6a768d7",
      "accountNumber": "0123456789",
      "bankName": "Example Bank"
    },
    "wallet": {
      "id": "4465468a-3c36-4536-918a-91d689e18a74",
      "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 configuração de webhooks, estrutura do payload e tratamento de eventos, consulte a documentação de Webhooks.

Próximos passos

Assim que a stablecoin estiver em sua wallet:

Swap — Converta para USDT, USDC ou outras stablecoins sob demanda
Auto-Settlement — Converta automaticamente para USDT/USDC em cada depósito

Casos de uso

Pagamentos de E-commerce

Crie contas virtuais para que os clientes recebam pagamentos por produtos ou serviços, automaticamente convertidos em stablecoins para o seu sistema de pagamentos baseado em blockchain.

Serviços de assinatura

Vincule contas virtuais às assinaturas dos clientes, permitindo transferências bancárias recorrentes que são automaticamente convertidas em stablecoins.

Transações de marketplace

Habilite transações onde os clientes enviam 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 moeda local, automaticamente convertidas em stablecoins para transferências internacionais.

Boas práticas

Gerenciamento de contas

Use o schema de requisitos: Colete apenas os campos no schema de requisitos atual. Não fixe campos de onboarding no código — consulte Formulários Dinâmicos.
Reutilize o provedor retornado: Crie com o provider retornado pela requisição de requisitos.
Rotule suas contas: Defina um label para tornar as contas pesquisáveis e fáceis de reconciliar.
Ativação de contas: Desative as contas que você ainda não está pronto para financiar; reative quando estiver pronto.
Documente os motivos da regeneração: Sempre forneça um reason claro ao regenerar para fins de auditoria.

Segurança

Verificação do cliente: Verifique as informações do cliente antes de criar contas virtuais.
Preserve as strings: Envie identificadores e códigos como strings para evitar perda de precisão.
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.

Código de status	Erro	Descrição
`400`	Bad Request	Parâmetros de requisição inválidos ou `additionalData` malformado
`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

{
  "statusCode": 400,
  "message": "Invalid additional data for bvn: bvn does not match the expected format"
}

Referência da API

v2 (Recomendado)

Endpoint	Descrição
Discover Options	Listar ativos e moedas disponíveis
Get Requirements	Obter o schema de campos para um corredor
Master Wallet Create	Criar uma conta virtual para uma master wallet
Master Wallet List	Listar contas virtuais de uma master wallet
Master Wallet Get One	Obter uma conta virtual específica
Master Wallet Update	Ativar ou desativar uma conta virtual
Master Wallet Regenerate	Regenerar uma conta virtual
Child Address Create	Criar uma conta virtual para uma child address
Child Address List	Listar contas virtuais de uma child address
Child Address Get One	Obter uma conta virtual específica
Child Address Transactions	Listar transações de uma conta virtual
Child Address Update	Ativar ou desativar uma conta virtual
Child Address Regenerate	Regenerar uma conta virtual

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].

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

Conclua o processo de Due Diligence no Painel: My wallets > Settings > Compliance

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.

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

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

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].

​Pré-requisitos

​Como funciona

Descobrir opções

Obter requisitos

Criar conta

Auto-Funding

​Moedas fiat suportadas

​Fluxo de Auto-Funding

​1. Recebimento do pagamento

​2. Emissão automática

​3. Transferência na blockchain

​Ativos e moedas suportados

​Endpoints da API

​Endpoints de Master Wallet

​Endpoints de Child Address

​Etapa 1: Descobrir opções

​Etapa 2: Obter requisitos

​Etapa 3: Criar uma conta virtual

​Exemplo de resposta

​Listando Contas Virtuais

​Parâmetros de Query

​Obtendo uma Conta Virtual única

​Transações da Conta Virtual

​Parâmetros de Query

​Atualizando Contas Virtuais

​Comportamento de Auto-Funding

​Parâmetros de atualização

​Regenerando Contas Virtuais

​Parâmetros de regeneração

​Webhooks

​Eventos de Webhook

​Exemplo de payload de Webhook

​Próximos passos

​Casos de uso

​Pagamentos de E-commerce

​Serviços de assinatura

​Transações de marketplace

​Serviços de remessas

​Boas práticas

​Gerenciamento de contas

​Segurança

​Tratamento de erros

​Exemplo de resposta de erro

​Referência da API

​v2 (Recomendado)

​Suporte

​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

​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

Pré-requisitos

Como funciona

Moedas fiat suportadas

Fluxo de Auto-Funding

1. Recebimento do pagamento

2. Emissão automática

3. Transferência na blockchain

Ativos e moedas suportados

Endpoints da API

Endpoints de Master Wallet

Endpoints de Child Address

Etapa 1: Descobrir opções

Etapa 2: Obter requisitos

Etapa 3: Criar uma conta virtual

Exemplo de resposta

Listando Contas Virtuais

Parâmetros de Query

Obtendo uma Conta Virtual única

Transações da Conta Virtual

Parâmetros de Query

Atualizando Contas Virtuais

Comportamento de Auto-Funding

Parâmetros de atualização

Regenerando Contas Virtuais

Parâmetros de regeneração

Webhooks

Eventos de Webhook

Exemplo de payload de Webhook

Próximos passos

Casos de uso

Pagamentos de E-commerce

Serviços de assinatura

Transações de marketplace

Serviços de remessas

Boas práticas

Gerenciamento de contas

Segurança

Tratamento de erros

Exemplo de resposta de erro

Referência da API

v2 (Recomendado)

Suporte

Pré-requisitos

Como funciona

Fluxo de Auto-Funding

1. Recebimento do pagamento

2. Emissão automática

3. Transferência na blockchain

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