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

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

[
  {
    "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"
  }
]

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`

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.

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

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.

{
  "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 passos

Como gerenciar o ciclo de vida de um link