How to retrieve and list 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 a link has orders, you can read them in three ways. Each operation uses the link's link_id as the entry point:
  • 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 data, and the order's status history (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-only operations. You can call them in any sequence, as needed.

Before you start

  • Obtain an access token. See Authentication.
  • Have the link_id of the link whose orders you want to retrieve.
Endpoint
GET /payment-links/{link_id}/orders
Required parameters
FieldTypeDescriptionExample
link_idStringPayment link ID9e5dcedc-1e5f-4e85-9b64-4d0b43d98c82
Optional parameters
FieldTypeDescriptionExample
statusStringFilter by order statuspaid
limitIntegerItems per page
pageIntegerPage number
information icon
Possible order statuses: paid, pending, approved, refunded, denied.

Example 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 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 parameters
FieldTypeDescriptionExample
link_idStringPayment link ID76c3caa9-4c5b-243b-8fc5-a73381fcdf9b
order_idStringOrder IDb1c2d3e4-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 response

The 200 OK response includes all the fields from the list operation.
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

This operation returns the receipt for an order.

Endpoint
GET /payment-links/{link_id}/orders-receipt/{order_id}
Required parameters
FieldTypeDescriptionExample
link_idStringPayment link ID76c3caa9-4c5b-243b-8fc5-a73381fcdf9b
order_idStringOrder IDb1c2d3e4-5678-9abc-def0-111213141516

Example response

The 200 OK response contains 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

On this page

How to retrieve and list orders