Ordens de Pagamento

Em resumo
Uma ordem de pagamento representa um único recebimento de fiat esperado. Quando você usa a via de conta virtual de uso único, cada ordem é lastreada por uma conta bancária dedicada, válida para apenas um pagamento. Os endpoints de Ordens de Pagamento permitem listar e acompanhar cada ordem no nível da master wallet ou restritas a um endereço filho específico.

Pré-requisitos

Antes de usar a API de Ordens de Pagamento, garanta que você tenha:

API Key

Obtenha sua API key no Painel da Blockradar. Acesse Developers para gerar uma.

Wallet criada

Crie uma wallet pelo painel (consulte Criar uma Carteira Principal). Você precisará do walletId para as operações de ordens de pagamento.

Conformidade aprovada

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 de conformidade. Entre em contato com [email protected] ou use o chat ao vivo no painel.

Ambiente mainnet

As contas virtuais estão disponíveis apenas na MAINNET. Ambientes testnet não oferecem suporte a operações com contas virtuais.

Suporte a stablecoin

Depositar fiat e convertê-lo em stablecoin é um recurso pago. Garanta que seu plano inclua acesso a stablecoins. Faça upgrade em Painel → Settings → Subscription.

Como funciona

Uma ordem de pagamento é criada sempre que um cliente inicia um depósito em fiat. Para a via one_time_virtual_account, a Blockradar emite uma nova conta bancária virtual vinculada a essa ordem e ao seu conjunto de valores. Assim que o cliente paga, a ordem avança por seu ciclo de vida e a stablecoin correspondente é emitida e liquidada na wallet ou endereço vinculado.

Ordem criada

Uma ordem é gerada com uma referência, um valor esperado e sua via de cobrança.

Conta emitida

Para a via de conta virtual de uso único, uma conta bancária de uso único é anexada em paymentInstructions.

Pagamento recebido

O cliente paga a conta antes de expiresAt; a ordem passa para processing e depois para paid.

Liquidação

A stablecoin equivalente é emitida e liquidada na wallet ou endereço filho vinculado.

Status da ordem

Cada ordem informa seu status atual no ciclo de vida. Use o parâmetro de consulta status para filtrar os resultados.

Status	Descrição
`pending`	Ordem criada e aguardando o pagamento do cliente.
`processing`	Pagamento recebido e em processo de confirmação/liquidação.
`paid`	Pagamento confirmado e liquidado com sucesso.
`expired`	A ordem não foi paga antes de `expiresAt`.
`failed`	O pagamento ou a liquidação não puderam ser concluídos.
`cancelled`	A ordem foi cancelada antes do pagamento.

Vias de cobrança

O campo rail identifica como a ordem é cobrada. As contas virtuais de uso único utilizam a via one_time_virtual_account.

Via	Descrição
`one_time_virtual_account`	Uma conta bancária dedicada válida para um único pagamento.
`payment_link`	Um link de pagamento hospedado.
`qr_code`	Um código QR escaneável.

Fluxo de criação vinculado à sessão

Comece a criação da ordem de pagamento solicitando uma cotação com assetId, currency, amount e rail. Quando o depósito pertencer a um cliente existente, inclua também customerId para que o KYC salvo do provedor possa ser reutilizado. O adaptador do provedor infere o corredor de KYC a partir da moeda fiat selecionada. A cotação retorna um sessionId e um sessionExpiresAt. A sessão vincula a wallet, o ativo da wallet, a moeda fiat, o valor, a via, o provedor, a rota de conversão, o cliente e o corredor de KYC por 20 minutos. Recomendamos usar o sessionId retornado em todas as requisições seguintes:

Inicialize o formulário com additionalDataRequirements.data quando não for null. Ele contém valores reutilizáveis já salvos para o cliente, o provedor e o corredor.
Colete todos os valores ausentes exigidos por additionalDataRequirements.schema.
Se o esquema contiver um x-resolution, chame POST /v1/wallets/{id}/deposit/fiat/payment-order-requirements/resolve com o sessionId e o additionalData atual.
Mescle os valores resolvidos em additionalData.
Crie a ordem com sessionId, additionalData e quaisquer campos opcionais da ordem, como reference ou metadata.

Quote request

{
  "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
  "currency": "NGN",
  "amount": "100.00",
  "rail": "one_time_virtual_account",
  "customerId": "18d2f159-e0cd-4a45-b735-e9dfe0f7520a"
}

Quote session

{
  "sessionId": "13a36c1c-f4a6-4e49-a582-2ecded2559bc",
  "sessionExpiresAt": "2026-09-15T15:20:00.000Z",
  "additionalDataRequirements": {
    "schema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "title": "Refund account and customer KYC"
    },
    "data": null
  }
}

Apenas os campos de nível superior do esquema são mostrados acima, por brevidade; renderize o JSON Schema completo específico do provedor retornado pela API.

Resolve requirements

{
  "sessionId": "13a36c1c-f4a6-4e49-a582-2ecded2559bc",
  "additionalData": {
    "institutionIdentifier": "OPAYNGPC",
    "accountIdentifier": "8034007516",
    "kyc": {
      "entityType": "person",
      "personDetails": {
        "fullName": "Ada Okafor",
        "birthDate": "1992-04-18",
        "idDocument": {
          "number": "12345678901"
        },
        "taxId": {
          "value": "10987654321"
        }
      }
    }
  }
}

Create payment order

{
  "sessionId": "13a36c1c-f4a6-4e49-a582-2ecded2559bc",
  "additionalData": {
    "institutionIdentifier": "OPAYNGPC",
    "accountIdentifier": "8034007516",
    "accountName": "Ada Okafor",
    "kyc": {
      "entityType": "person",
      "personDetails": {
        "fullName": "Ada Okafor",
        "birthDate": "1992-04-18",
        "idDocument": {
          "number": "12345678901"
        },
        "taxId": {
          "value": "10987654321"
        }
      }
    }
  },
  "reference": "dep_20260915_001"
}

O exemplo acima é um perfil de pessoa física da Paycrest para NGN: idDocument.number é o NIN de 11 dígitos do cliente e taxId.value é o BVN de 11 dígitos do cliente. Os requisitos variam por provedor, corredor e tipo de entidade, portanto sempre renderize o esquema retornado pela cotação em vez de fixar esses campos no código. Quando a ordem é criada com KYC inline, a Blockradar o salva vinculado ao cliente da empresa, ao provedor selecionado e ao corredor. Uma cotação posterior com o mesmo customerId e corredor retorna o KYC salvo em additionalDataRequirements.data. Enviar um KYC alterado em uma ordem posterior atualiza o perfil salvo do corredor; nenhum endpoint de KYC separado é necessário.

Não reutilize uma sessão com valores de ativo, moeda, valor, via ou provedor vindos de outra cotação. Se a API retornar FIAT_DEPOSIT_SESSION_EXPIRED, FIAT_DEPOSIT_SESSION_MISMATCH ou FIAT_DEPOSIT_SESSION_UNAVAILABLE, solicite uma nova cotação e reinicie a resolução de requisitos.

Para manter a compatibilidade com versões anteriores, sessionId é opcional. Se você omiti-lo, envie os valores originais de assetId, currency, amount e rail nas requisições de resolução de requisitos e de criação da ordem. Quando sessionId estiver presente, os valores armazenados na sessão prevalecem.

Listar ordens de pagamento da master wallet

Retorna uma lista paginada de todas as ordens de pagamento criadas sob uma master wallet. Use os parâmetros de consulta para filtrar por status, via, moeda, ativo, intervalo de datas ou busca por texto livre. GET /v1/wallets/{id}/deposit/fiat/orders

Parâmetros de consulta

Parâmetro	Tipo	Descrição
`status`	enum	Filtrar por status da ordem: `pending`, `paid`, `processing`, `expired`, `failed`, `cancelled`.
`rail`	enum	Filtrar por via de cobrança: `one_time_virtual_account`, `payment_link`, `qr_code`.
`currency`	string	Código de moeda fiat ISO 4217 (3 caracteres), ex.: `NGN`.
`assetId`	string	Identificador do ativo stablecoin (UUID).
`search`	string	Buscar por referência, rótulo, nome da conta ou número da conta.
`startDate`	string	Data de início ISO 8601 inclusiva. Obrigatória junto com `endDate`.
`endDate`	string	Data de término ISO 8601 inclusiva. Obrigatória junto com `startDate`.
`page`	number	Número de página com base 1 (padrão: 1).
`limit`	number	Registros por página (padrão: 10, intervalo: 1–100).

Exemplo de resposta

{
  "statusCode": 200,
  "message": "Successful",
  "data": [
    {
      "id": "80ea45ab-38b9-4506-b213-52da8bc7e825",
      "type": "deposit",
      "rail": "one_time_virtual_account",
      "reference": "dep_20260719_001",
      "status": "pending",
      "currency": "NGN",
      "amount": "100.00",
      "amountFiat": "155000.00",
      "feeFiat": "1500.00",
      "amountFiatPayable": "156500.00",
      "expiresAt": "2026-07-19T13:00:00.000Z",
      "paymentInstructions": {
        "type": "one_time_virtual_account",
        "bank": {
          "name": "Example Bank",
          "code": "999",
          "accountName": "Blockradar / Acme Ltd",
          "accountNumber": "0123456789"
        }
      },
      "asset": {
        "id": "ae455f23-3824-4125-baab-d158315cbcbd",
        "symbol": "USDC",
        "name": "USD Coin"
      },
      "wallet": {
        "id": "4465468a-3c36-4536-918a-91d689e18a74",
        "address": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a"
      },
      "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
  },
  "analytics": {
    "totalOrdersCount": 1,
    "totalPendingOrdersCount": 1,
    "totalPaidOrdersCount": 0
  }
}

Listar ordens de pagamento do endereço filho

Retorna as ordens de pagamento restritas a um único endereço filho. A resposta inclui os mesmos campos da ordem, além de detalhes adicionais de liquidação, provedor e cliente. GET /v1/wallets/{walletId}/addresses/{addressId}/deposit/fiat/orders

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`walletId`	string	Sim	Identificador da wallet (UUID).
`addressId`	string	Sim	Identificador do endereço filho (UUID).

Parâmetros de consulta

Parâmetro	Tipo	Descrição
`status`	enum	Filtrar por status da ordem: `pending`, `paid`, `processing`, `expired`, `failed`, `cancelled`.
`rail`	enum	Filtrar por via de cobrança: `one_time_virtual_account`, `payment_link`, `qr_code`.
`currency`	string	Código de moeda fiat ISO 4217 (3 caracteres), ex.: `NGN`.
`assetId`	string	Identificador do ativo stablecoin (UUID).
`search`	string	Buscar por referência, rótulo, nome da conta ou número da conta.
`startDate`	string	Data de início ISO 8601 inclusiva. Obrigatória junto com `endDate`.
`endDate`	string	Data de término ISO 8601 inclusiva. Obrigatória junto com `startDate`.

Exemplo de resposta

{
  "statusCode": 200,
  "message": "Successful",
  "data": [
    {
      "id": "80ea45ab-38b9-4506-b213-52da8bc7e825",
      "type": "deposit",
      "rail": "one_time_virtual_account",
      "reference": "dep_20260719_001",
      "providerReference": "provider_order_839201",
      "transactionId": null,
      "status": "pending",
      "currency": "NGN",
      "amount": "100.00",
      "amountFiat": "155000.00",
      "feeFiat": "1500.00",
      "amountFiatPayable": "156500.00",
      "amountFiatReceived": null,
      "amountSettled": null,
      "expiresAt": "2026-07-19T13:00:00.000Z",
      "paymentInstructions": {
        "type": "one_time_virtual_account",
        "bank": {
          "name": "Example Bank",
          "code": "999",
          "accountName": "Blockradar / Acme Ltd",
          "accountNumber": "0123456789"
        },
        "paymentLink": null,
        "qrCode": null,
        "expiresAt": "2026-07-19T13:00:00.000Z",
        "metadata": null
      },
      "metadata": {
        "checkoutId": "checkout_123"
      },
      "provider": {
        "id": "1128dd40-2c94-4c16-a6bf-fbbc6afee52c",
        "slug": "example-provider",
        "name": "Example Provider"
      },
      "wallet": {
        "id": "4465468a-3c36-4536-918a-91d689e18a74",
        "address": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a"
      },
      "address": null,
      "asset": {
        "id": "ae455f23-3824-4125-baab-d158315cbcbd",
        "symbol": "USDC",
        "name": "USD Coin"
      },
      "customer": {
        "id": "18d2f159-e0cd-4a45-b735-e9dfe0f7520a"
      },
      "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
  },
  "links": {
    "first": "https://api.blockradar.co/v1/wallets/.../deposit/fiat/orders?page=1&limit=10",
    "previous": null,
    "next": null,
    "last": "https://api.blockradar.co/v1/wallets/.../deposit/fiat/orders?page=1&limit=10"
  },
  "analytics": {
    "totalOrdersCount": 1,
    "totalPendingOrdersCount": 1,
    "totalPaidOrdersCount": 0,
    "totalProcessingOrdersCount": 0,
    "totalExpiredOrdersCount": 0,
    "totalFailedOrdersCount": 0,
    "totalCancelledOrdersCount": 0
  }
}

Campos de resposta

Campo	Descrição
`id`	Identificador único da ordem de pagamento.
`type`	Tipo da ordem. `deposit` para recebimentos em fiat.
`rail`	Via de cobrança utilizada para a ordem.
`reference`	Sua referência para a ordem.
`status`	Status atual da ordem no ciclo de vida.
`currency`	Moeda fiat ISO 4217 do pagamento esperado.
`amount`	Valor de stablecoin a ser emitido.
`amountFiat`	Valor em fiat da ordem antes das taxas.
`feeFiat`	Taxa cobrada em fiat.
`amountFiatPayable`	Valor total em fiat que o cliente deve pagar (`amountFiat` + `feeFiat`).
`expiresAt`	Carimbo de data/hora após o qual uma ordem não paga expira.
`paymentInstructions`	Como o cliente paga. Contém os dados do `bank` de uso único para a via `one_time_virtual_account`.
`asset`	O ativo stablecoin no qual a ordem é liquidada.
`wallet`	A master wallet à qual a ordem pertence.
`meta`	Metadados de paginação do conjunto de resultados.
`analytics`	Contagens agregadas de ordens por status.

Os campos amountFiatReceived, amountSettled, providerReference, provider e customer são retornados no endpoint de endereço filho e são preenchidos à medida que a ordem avança pela liquidação.

Referência da API

Descoberta e configuração

Endpoint	Descrição
Get Supported Assets	Listar os ativos stablecoin disponíveis para depósitos em fiat
Get Supported Currencies	Listar as moedas fiat disponíveis para depósitos
Get Supported Rails	Listar as vias de cobrança em fiat suportadas
Resolve Payment Order Requirements	Resolver os campos exigidos para criar uma ordem em uma via específica

Master Wallet

Endpoint	Descrição
Master Wallet Get Quote	Obter uma cotação antes de criar uma ordem
Master Wallet Create Payment Order	Criar uma ordem de pagamento para uma master wallet
List Payment Orders	Listar as ordens de pagamento de uma master wallet
Get Payment Order	Recuperar uma única ordem de pagamento pelo seu identificador
Refresh Payment Order	Atualizar uma ordem para obter o status e os detalhes mais recentes
Cancel Payment Order	Cancelar uma ordem de pagamento pendente

Endereço filho

Endpoint	Descrição
Get Child Address Quote	Obter uma cotação antes de criar uma ordem
Create Child Address Payment Order	Criar uma ordem de pagamento para um endereço filho
List Child Address Payment Orders	Listar as ordens de pagamento de um endereço filho

Recuperar, atualizar e cancelar uma ordem exigem apenas o ID da ordem, portanto não há equivalente para endereços filhos. Use os endpoints da master wallet acima para qualquer ordem, inclusive as criadas contra um endereço filho.A API também expõe uma operação Find Fiat Deposit (POST /v1/wallets/{id}/deposit/fiat/finder) que localiza um depósito em fiat e seus detalhes de processamento a partir de uma referência de pagamento. É útil para conciliar um pagamento que um cliente afirma ter enviado com a ordem à qual ele pertence.

Começar

Carteiras

Receber Pagamentos

Enviar Pagamentos

Converter e Gerenciar

Conformidade e Recuperação

Integrações

Pré-requisitos

Como funciona

Ordem criada

Conta emitida

Pagamento recebido

Liquidação

Status da ordem

Vias de cobrança

Fluxo de criação vinculado à sessão

Listar ordens de pagamento da master wallet

Parâmetros de consulta

Exemplo de resposta

Listar ordens de pagamento do endereço filho

Parâmetros de caminho

Parâmetros de consulta

Exemplo de resposta

Campos de resposta

Referência da API

Descoberta e configuração

Master Wallet

Endereço filho

​Pré-requisitos

​Como funciona

Ordem criada

Conta emitida

Pagamento recebido

Liquidação

​Status da ordem

​Vias de cobrança

​Fluxo de criação vinculado à sessão

​Listar ordens de pagamento da master wallet

​Parâmetros de consulta

​Exemplo de resposta

​Listar ordens de pagamento do endereço filho

​Parâmetros de caminho

​Parâmetros de consulta

​Exemplo de resposta

​Campos de resposta

​Referência da API

​Descoberta e configuração

​Master Wallet

​Endereço filho

Pré-requisitos

Como funciona

Status da ordem

Vias de cobrança

Fluxo de criação vinculado à sessão

Listar ordens de pagamento da master wallet

Parâmetros de consulta

Exemplo de resposta

Listar ordens de pagamento do endereço filho

Parâmetros de caminho

Parâmetros de consulta

Exemplo de resposta

Campos de resposta

Referência da API

Descoberta e configuração

Master Wallet

Endereço filho