# Cómo recuperar y listar órdenes de pago

Una orden es la transacción de pago que se crea cuando un comprador paga a través de un enlace de pago. Esta guía muestra cómo listar las órdenes de un enlace, recuperar los detalles de una orden específica y obtener su recibo.

## Cómo funciona

Una vez que existen órdenes para un enlace, esta API te permite leerlas de tres formas independientes, usando el `link_id` del enlace como punto de entrada. Operaciones disponibles:

- **Listar órdenes de un enlace**: recupera todas las órdenes asociadas a un `link_id`. Puedes filtrar por estado (`paid`, `pending`, `approved`, `refunded`, `denied`) y paginar los resultados con `limit` y `page`.
- **Recuperar una orden específica**: obtén los detalles completos de una orden individual por su `order_id`, incluyendo los datos del cliente, el envío y el `history` de estados de la orden.
- **Recuperar el recibo de una orden**: obtén el recibo completo de una orden, con datos del comercio, productos, detalles del pago (marca, cuotas, últimos cuatro dígitos) y totales.

Estas son operaciones de lectura que llamas según lo necesites; no existe una secuencia requerida entre ellas.

## Antes de empezar

- Obtén un token de acceso. Consulta [Autenticación](/es/payment-link-api/first-step-plk/authentication-token-plk).
- Ten el `link_id` del enlace cuyas órdenes deseas recuperar.

## Lista las órdenes de un enlace

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

**Campos obligatorios**
| Campo | Tipo | Descripción | Ejemplo |
| --- | --- | --- | --- |
| `link_id` | String | ID del enlace de pago | `9e5dcedc-1e5f-4e85-9b64-4d0b43d98c82` |

**Campos opcionales**
| Campo | Tipo | Descripción | Ejemplo |
| --- | --- | --- | --- |
| `status` | String | Filtrar por estado de la orden | `paid` |
| `limit` | Integer | Elementos por página |
| `page` | Integer | Número de página |

> Estados posibles de la orden: `paid`, `pending`, `approved`, `refunded`, `denied`.

#### Ejemplo de solicitud

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

#### Ejemplo de respuesta

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

## Recupera una orden específica

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

**Campos obligatorios**
| Campo | Tipo | Descripción | Ejemplo |
| --- | --- | --- | --- |
| `link_id` | String | ID del enlace de pago | `76c3caa9-4c5b-243b-8fc5-a73381fcdf9b` |
| `order_id`| String |  ID de la orden | `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"
```

#### Ejemplo de respuesta

La respuesta **200 OK** incluye todos los campos del listado.

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

## Recupera el recibo de una orden

Devuelve el recibo de una orden de pago.

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

**Campos obligatorios**
| Campo | Tipo | Descripción | Ejemplo |
| --- | --- | --- | --- |
| `link_id` | String | ID del enlace de pago | `76c3caa9-4c5b-243b-8fc5-a73381fcdf9b` |
| `order_id`| String |  ID de la orden | `b1c2d3e4-5678-9abc-def0-111213141516`|

#### Ejemplo de respuesta

La respuesta **200 OK** devuelve el 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 pasos

- [Cómo gestionar el ciclo de vida de un enlace](/es/payment-link-api/payment-guides-plk/howto-manage-life-cicle-plk)