# Como consultar e listar ordens de pagamento

Uma ordem (order) é a transação de pagamento criada quando um shopper paga através de um payment link. Este guia mostra como listar as ordens de um link, consultar os detalhes de uma ordem específica e obter seu recibo.

## Como funciona

Depois que existem ordens para um link, esta API permite consultá-las de três formas independentes, usando o `link_id` do link como ponto de entrada. Operações disponíveis:

- **Listar ordens de um link**: recupera todas as ordens associadas a um `link_id`. Você pode filtrar por status (`paid`, `pending`, `approved`, `refunded`, `denied`) e paginar os resultados com `limit` e `page`.
- **Consultar uma ordem específica**: obtém os detalhes completos de uma única ordem pelo `order_id`, incluindo dados do cliente, envio (shipping) e o `history` de status da ordem.
- **Consultar o recibo de uma ordem**: obtém o recibo completo de uma ordem, com dados do estabelecimento, produtos, detalhes do pagamento (bandeira, parcelas, últimos quatro dígitos) e totais.

Essas são operações de leitura que você chama conforme necessário; não há uma sequência obrigatória entre elas.

## Antes de começar

- Obtenha um token de acesso. Veja [Authentication](/pt/payment-link-api/first-step-plk/authentication-token-plk).
- Tenha o `link_id` do link cujas ordens deseja consultar.

## Listar ordens de um link

Endpoint|
---|
`GET /payment-links/{link_id}/orders`|

**Campos obrigatórios**
| Campo | Tipo | Descrição | Exemplo |
| --- | --- | --- | --- |
| `link_id` | String | ID do link de pagamento | `9e5dcedc-1e5f-4e85-9b64-4d0b43d98c82` |

**Campos opcionais**
| Campo | Tipo | Descrição | Exemplo |
| --- | --- | --- | --- |
| `status` | String | Filtra por status da ordem | `paid` |
| `limit` | Integer | Itens por página |
| `page` | Integer | Número da página |

> Status possíveis de uma ordem: `paid`, `pending`, `approved`, `refunded`, `denied`.

#### Exemplo de requisição

```json
curl -X GET "${API_URL}/payment-links?status=ACTIVE&limit=10" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "x-seller-id: ${SELLER_ID}" \
-H "country: BR" \
-H "tenant: santander"
```

#### Exemplo de resposta

```json
[
  {
    "order_id": "b1c2d3e4-5678-9abc-def0-111213141516",
    "link_id": "76c3caa9-4c5b-243b-8fc5-a73381fcdf9b",
    "currency": "BRL",
    "amount": 9990,
    "reference_code": "BF2026-001",
    "checkout_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "customer": {
      "first_name": "João",
      "last_name": "Silva",
      "email": "joao.silva@email.com"
    },
    "shipping": null,
    "status": "paid",
    "created_at": "2026-06-10T14:00:00.000Z",
    "updated_at": "2026-06-10T14:02:30.000Z"
  },
  {
    "order_id": "a2b3c4d5-6789-0abc-def1-212223242526",
    "link_id": "76c3caa9-4c5b-243b-8fc5-a73381fcdf9b",
    "currency": "BRL",
    "amount": 9990,
    "reference_code": "BF2026-002",
    "checkout_id": "e38bd20a-47bb-4361-b456-1d13a2b3c468",
    "customer": {
      "first_name": "Maria",
      "last_name": "Santos",
      "email": "maria.santos@email.com"
    },
    "shipping": null,
    "status": "pending",
    "created_at": "2026-06-10T15:30:00.000Z",
    "updated_at": "2026-06-10T15:30:00.000Z"
  }
]
```

## Consultar uma ordem específica

Endpoint|
---|
`GET /payment-links/{link_id}/orders/{order_id}`

**Campos obrigatórios**
| Campo | Tipo | Descrição | Exemplo |
| --- | --- | --- | --- |
| `link_id` | String | ID do link de pagamento | `76c3caa9-4c5b-243b-8fc5-a73381fcdf9b` |
| `order_id`| String |  ID da ordem | `b1c2d3e4-5678-9abc-def0-111213141516`|

```json
curl -X GET "${API_URL}/payment-links/${LINK_ID}" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "x-seller-id: ${SELLER_ID}" \
-H "country: BR" \
-H "tenant: santander"
```

#### Exemplo de resposta

A resposta **200 OK** inclui todos os campos da listagem.

```json
{
  "order_id": "b1c2d3e4-5678-9abc-def0-111213141516",
  "link_id": "76c3caa9-4c5b-243b-8fc5-a73381fcdf9b",
  "currency": "BRL",
  "amount": 9990,
  "reference_code": "BF2026-001",
  "checkout_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "customer": {
    "first_name": "João",
    "last_name": "Silva",
    "email": "joao.silva@email.com",
    "phone": "+5511999998888",
    "document_type": "CPF",
    "document_number": "12345678900"
  },
  "shipping": {
    "first_name": "João",
    "last_name": "Silva",
    "email": "joao.silva@email.com",
    "phone": "+5511999998888",
    "address": {
      "street": "Rua Exemplo",
      "number": "100",
      "complement": "Apto 42",
      "district": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "postal_code": "01001000"
    }
  },
  "status": "paid",
  "history": [
    {
      "status": "pending",
      "created_at": "2026-06-10T14:00:00.000Z"
    },
    {
      "status": "paid",
      "created_at": "2026-06-10T14:02:30.000Z"
    }
  ],
  "created_at": "2026-06-10T14:00:00.000Z",
  "updated_at": "2026-06-10T14:02:30.000Z"
}
```

## Consultar o recibo de uma ordem

Retorna o recibo de uma ordem de pagamento.

Endpoint|
---|
`GET /payment-links/{link_id}/orders-receipt/{order_id}`

**Campos obrigatórios**
| Campo | Tipo | Descrição | Exemplo |
| --- | --- | --- | --- |
| `link_id` | String | ID do link de pagamento | `76c3caa9-4c5b-243b-8fc5-a73381fcdf9b` |
| `order_id`| String |  ID da ordem | `b1c2d3e4-5678-9abc-def0-111213141516`|

#### Exemplo de resposta

A resposta **200 OK** retorna o recibo completo.

```json
{
  "order_id": "7b22a6b5-d24d-4d6e-90e5-5b06cf41d0a1",
  "link_id": "9e5dcedc-1e5f-4e85-9b64-4d0b43d98c82",
  "authorization_code": "012345",
  "country": "BR",
  "merchant_name": "Loja Exemplo",
  "merchant_document": "12345678000190",
  "transaction_date": "2025-06-20T14:30:00.000Z",
  "customer": {
    "first_name": "João",
    "last_name": "Silva",
    "name": "João Silva",
    "email": "joao.silva@email.com",
    "document_type": "cpf",
    "document_number": "12345678900",
    "phone_number": "+5511999999999",
    "billing_address": {
      "street": "Rua Exemplo",
      "number": "100",
      "complement": "Apto 42",
      "district": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "postal_code": "01001000"
    }
  },
  "products": [
    {
      "product_type": "physical",
      "title": "Camiseta Premium",
      "description": "Camiseta 100% algodão",
      "quantity": 2,
      "value": 5990,
      "order_prefix": "PED"
    }
  ],
  "shipping": {
    "first_name": "João",
    "name": "João Silva",
    "email": "joao.silva@email.com",
    "phone_number": "+5511999999999",
    "shipping_amount": 1500,
    "address": {
      "street": "Rua Exemplo",
      "number": "100",
      "complement": "Apto 42",
      "district": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "postal_code": "01001000"
    }
  },
  "payment": {
    "currency": "BRL",
    "amount": 11980,
    "total_amount": 13480,
    "operation": "credit",
    "brand": "VISA",
    "transaction_id": "abc123def456",
    "installment": {
      "schema": "plan_lojista",
      "type": "no_interest",
      "number": 3,
      "interest_rate": 0,
      "increase_rate": 0
    },
    "last_four_digits": "1234"
  },
  "soft_descriptor": "LOJA EXEMPLO",
  "reference_code": "REF-2025-001",
  "created_at": "2025-06-20T14:30:05.000Z",
  "updated_at": "2025-06-20T14:30:05.000Z"
}
```

## Próximos passos

- [Como gerenciar o ciclo de vida de um link](/pt/payment-link-api/payment-guides-plk/howto-manage-life-cicle-plk)