> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Ordens de Pagamento

> Liste e acompanhe as ordens de pagamento de contas virtuais de uso único, da criação até a liquidação

<Note>
  Em resumo<br />
  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.
</Note>

## Pré-requisitos

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

<Steps>
  <Step title="API Key">
    Obtenha sua API key no [Painel da Blockradar](https://dashboard.blockradar.co). Acesse **Developers** para gerar uma.
  </Step>

  <Step title="Wallet criada">
    Crie uma wallet via [API Create Wallet](/en/api-reference/wallets/create-wallet) ou pelo painel. Você precisará do `walletId` para as operações de ordens de pagamento.
  </Step>

  <Step title="Conformidade aprovada">
    Conclua o processo de due diligence no Painel: My wallets > Settings > Compliance
  </Step>

  <Step title="Recurso habilitado">
    Solicite a ativação do recurso de contas virtuais após a aprovação de conformidade. Entre em contato com [support@blockradar.co](mailto:support@blockradar.co) ou use o chat ao vivo no painel.
  </Step>

  <Step title="Ambiente mainnet">
    As contas virtuais estão disponíveis apenas na **MAINNET**. Ambientes testnet não oferecem suporte a operações com contas virtuais.
  </Step>

  <Step title="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**.
  </Step>
</Steps>

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

<CardGroup cols={2}>
  <Card title="Ordem criada" icon="plus">
    Uma ordem é gerada com uma referência, um valor esperado e sua via de cobrança.
  </Card>

  <Card title="Conta emitida" icon="building-columns">
    Para a via de conta virtual de uso único, uma conta bancária de uso único é anexada em `paymentInstructions`.
  </Card>

  <Card title="Pagamento recebido" icon="credit-card">
    O cliente paga a conta antes de `expiresAt`; a ordem passa para `processing` e depois para `paid`.
  </Card>

  <Card title="Liquidação" icon="wallet">
    A stablecoin equivalente é emitida e liquidada na wallet ou endereço filho vinculado.
  </Card>
</CardGroup>

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

## 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**

```json theme={null}
{
  "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**

```json theme={null}
{
  "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.                                                          |

<Note>
  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.
</Note>

***

## Referência da API

### Descoberta e configuração

| Endpoint                                                                                                | Descrição                                                              |
| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [Get Supported Assets](/en/api-reference/deposit-fiat/get-supported-assets)                             | Listar os ativos stablecoin disponíveis para depósitos em fiat         |
| [Get Supported Currencies](/en/api-reference/deposit-fiat/get-supported-currencies)                     | Listar as moedas fiat disponíveis para depósitos                       |
| [Get Supported Rails](/en/api-reference/deposit-fiat/get-supported-rails)                               | Listar as vias de cobrança em fiat suportadas                          |
| [Resolve Payment Order Requirements](/en/api-reference/deposit-fiat/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](/en/api-reference/deposit-fiat/master-wallet-get-quote)                       | Obter uma cotação antes de criar uma ordem                          |
| [Master Wallet Create Payment Order](/en/api-reference/deposit-fiat/master-wallet-create-payment-order) | Criar uma ordem de pagamento para uma master wallet                 |
| [List Payment Orders](/en/api-reference/deposit-fiat/master-wallet-list-payment-orders)                 | Listar as ordens de pagamento de uma master wallet                  |
| [Get Payment Order](/en/api-reference/deposit-fiat/master-wallet-get-payment-order)                     | Recuperar uma única ordem de pagamento pelo seu identificador       |
| [Refresh Payment Order](/en/api-reference/deposit-fiat/master-wallet-refresh-payment-order)             | Atualizar uma ordem para obter o status e os detalhes mais recentes |
| [Cancel Payment Order](/en/api-reference/deposit-fiat/master-wallet-cancel-payment-order)               | Cancelar uma ordem de pagamento pendente                            |

### Endereço filho

| Endpoint                                                                                                | Descrição                                           |
| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| [Get Child Address Quote](/en/api-reference/deposit-fiat/child-address-get-quote)                       | Obter uma cotação antes de criar uma ordem          |
| [Create Child Address Payment Order](/en/api-reference/deposit-fiat/child-address-create-payment-order) | Criar uma ordem de pagamento para um endereço filho |
| [List Child Address Payment Orders](/en/api-reference/deposit-fiat/child-address-list-payment-orders)   | Listar as ordens de pagamento de um endereço filho  |

<Note>
  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.
</Note>