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

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

[
  {
    "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": "[email protected]"
    },
    "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": "[email protected]"
    },
    "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`

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.

{
  "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": "[email protected]",
    "phone": "+5511999998888",
    "document_type": "CPF",
    "document_number": "12345678900"
  },
  "shipping": {
    "first_name": "João",
    "last_name": "Silva",
    "email": "[email protected]",
    "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.

{
  "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": "[email protected]",
    "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": "[email protected]",
    "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