# How to retrieve and list payment orders

An order is the payment transaction created when a shopper pays through a payment link. This guide shows how to list the orders for a link, retrieve the details of a specific order, and get its receipt.

## How it works

Once orders exist for a link, this API lets you read them in three independent ways, using the link's `link_id` as the entry point. Available operations:

- **List orders for a link**: retrieve all orders associated with a `link_id`. You can filter by status (`paid`, `pending`, `approved`, `refunded`, `denied`) and paginate the results with `limit` and `page`.
- **Retrieve a specific order**: get the full details of a single order by its `order_id`, including customer data, shipping, and the order's status `history`.
- **Retrieve the receipt for an order**: get the full receipt for an order, with merchant data, products, payment details (brand, installments, last four digits), and totals.

These are read operations you call as needed, there is no required order between them.

## Before you start

- Obtain an access token. See [Authentication](/en/payment-link-api/first-step-plk/authentication-token-plk).
- Have the `link_id` of the link whose orders you want to retrieve.

## List orders for a link

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

**Required fields**
| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `link_id` | String | Payment link ID | `9e5dcedc-1e5f-4e85-9b64-4d0b43d98c82` |

**Optional fields**
| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `status` | String | Filter by order status | `paid` |
| `limit` | Integer | Items per page |
| `page` | Integer | Page number |

> Possible order statuses: `paid`, `pending`, `approved`, `refunded`, `denied`.

#### Example of request

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

#### Example of response

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

## Retrieve a specific order

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

**Required fields**
| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `link_id` | String | Payment link ID | `76c3caa9-4c5b-243b-8fc5-a73381fcdf9b` |
| `order_id`| String |  Order ID | `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"
```

#### Example of response

The **200 OK** response includes all fields from the listing.

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

## Retrieve the receipt for an order

Returns the receipt for a payment order.

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

**Required fields**
| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `link_id` | String | Payment link ID | `76c3caa9-4c5b-243b-8fc5-a73381fcdf9b` |
| `order_id`| String |  Order ID | `b1c2d3e4-5678-9abc-def0-111213141516`|

#### Example of response

The **200 OK** response returns the full receipt.

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

## Next steps

- [How to manage the lifecycle of a link](/en/payment-link-api/payment-guides-plk/howto-manage-life-cicle-plk)