> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Listar checkout links
> Lista paginada dos seus templates de cobrança, com filtros por status, tipo e nome de item.
`GET /checkout/links`
Faz parte do recurso [Links](/pt-BR/checkout/links) — o conceito e os estados estão lá.
Devolve os templates da sua conta, do mais recente para o mais antigo, em páginas de 20 por padrão
(máximo 100). Os filtros são opcionais e se somam: quem envia mais de um recebe só os Links que
atendem a todos. Cada item traz o mesmo objeto de
[`GET /checkout/links/{id}`](/pt-BR/checkout/links/get), incluindo a `url` pronta para divulgar.
**Arquivados não somem da listagem.** Sem filtro, a resposta traz `active` e `archived` juntos —
arquivar muda o estado, não remove o registro. Para ver só o que está no ar, use
`?status=active`.
**`status` aceita mais de um valor**, separados por vírgula: `?status=active,archived`. Um valor
fora da lista responde `400` com os aceitos.
**A listagem não diz se o Link vende.** O filtro `status` enxerga só a sua decisão de arquivar. Um
Link `active` com `sellable: false` continua aparecendo como qualquer outro — é preciso ler o
campo `sellable` de cada item. Veja
[Do Link à Session](/pt-BR/checkout/links#do-link-à-session).
## Exemplo
```bash theme={null}
curl -G https://api.sandbox.z2pay.com/v1/checkout/links \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-d status=active \
-d itemName=curso \
-d page=1 \
-d limit=20
```
```json Resposta 200 theme={null}
{
"data": [
{
"id": "chk_byd8p3p79re859jpkmr0j65n3",
"name": "Curso de Backend",
"status": "active",
"sellable": true,
"mode": "payment",
"currency": "BRL",
"url": "https://pay.sandbox.z2pay.com/c/chk_byd8p3p79re859jpkmr0j65n3",
"createdAt": "2026-06-24T12:00:00.000Z",
"updatedAt": "2026-06-24T12:00:00.000Z"
}
],
"pagination": { "page": 1, "limit": 20, "total": 12, "totalPages": 1 }
}
```
## OpenAPI
````yaml openapi/checkout.json GET /checkout/links
openapi: 3.0.3
info:
title: Z2Pay Checkout API
version: 1.0.0
description: >-
API pública dedicada do Checkout. Autenticação via header x-api-key com a
API key unificada da conta (z2_{live|test}_{sk|pk}_...). Endpoints privados
exigem uma key secret (sk); endpoints públicos aceitam a key publishable
(pk) consumida pelo frontend do comprador.
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Checkout Links
description: Checkout Links (integração API via sk_)
- name: Checkout Sessions
description: Checkout Sessions (integração API via sk_)
- name: Vendas rápidas
description: Cobrança individual sem Link — Sessions ad-hoc criadas com a chave secreta
paths:
/checkout/links:
get:
tags:
- Checkout Links
summary: Listar checkout links
description: Retorna lista paginada de CheckoutLinks.
operationId: CheckoutLinkApiController_list
parameters:
- name: page
in: query
required: false
description: 'Página da listagem. Padrão: 1.'
schema:
type: integer
minimum: 1
default: 1
description: 'Página da listagem. Padrão: 1.'
- name: limit
in: query
required: false
description: 'Itens por página. Padrão: 20. Máximo: 100.'
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: 'Itens por página. Padrão: 20. Máximo: 100.'
- name: status
in: query
required: false
description: >-
Situação do Link: `active` ou `archived`. Aceita vários valores,
separados por vírgula ou repetindo o parâmetro. Um valor inválido
responde 400 com a lista dos aceitos.
schema:
type: array
items:
type: string
enum:
- active
- archived
description: >-
Situação do Link: `active` ou `archived`. Aceita vários valores,
separados por vírgula ou repetindo o parâmetro. Um valor inválido
responde 400 com a lista dos aceitos.
- name: mode
in: query
required: false
description: >-
Tipo do Link: `payment` (cobrança única) ou `subscription`
(assinatura). Omitido, traz os dois.
schema:
type: string
enum:
- payment
- subscription
description: >-
Tipo do Link: `payment` (cobrança única) ou `subscription`
(assinatura). Omitido, traz os dois.
- name: itemName
in: query
required: false
description: >-
Links que tenham algum item cujo nome case **parcialmente** com o
texto. Filtra o Link, não o item.
schema:
type: string
maxLength: 255
description: >-
Links que tenham algum item cujo nome case **parcialmente** com o
texto. Filtra o Link, não o item.
- name: trial
in: query
required: false
description: >-
Apenas Links de assinatura com período de teste (`true`) ou apenas
sem (`false`). Omitido, traz os dois.
schema:
type: string
enum:
- 'true'
- 'false'
description: >-
Apenas Links de assinatura com período de teste (`true`) ou apenas
sem (`false`). Omitido, traz os dois.
- name: sortBy
in: query
required: false
description: 'Campo de ordenação: `createdAt` ou `name`. Default: `createdAt`.'
schema:
type: string
enum:
- createdAt
- name
description: 'Campo de ordenação: `createdAt` ou `name`. Default: `createdAt`.'
- name: sortDir
in: query
required: false
description: 'Direção da ordenação: `asc` ou `desc`. Default: `desc`.'
schema:
type: string
enum:
- asc
- desc
description: 'Direção da ordenação: `asc` ou `desc`. Default: `desc`.'
responses:
'200':
description: Lista paginada
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: Identificador único do registro.
slug:
type: string
nullable: true
description: Slug único global usado na URL pública /c/{slug}.
status:
type: string
description: Estado atual do registro.
mode:
type: string
description: >-
Modo do checkout: 'payment' (pagamento único) ou
'subscription' (assinatura).
currency:
type: string
description: 'Moeda no padrão ISO 4217 (ex.: BRL).'
locale:
type: string
description: 'Idioma do checkout (ex.: pt-BR, en-US, es-ES).'
name:
type: string
nullable: true
description: Nome de exibição do registro.
description:
type: string
nullable: true
description: Descrição exibida no checkout.
sellable:
type: boolean
description: >-
Se o Link pode vender agora. É false quando um
recebedor do splits, ou o dono da conta, não está
ativo no PSP — o comprador vê uma página de
indisponível. Independente do status.
config:
type: object
description: >-
Snapshot da configuração do checkout (formas de
pagamento, itens e personalização visual).
requiredFields:
type: array
items:
type: string
nullable: true
description: >-
Campos do comprador exigidos no checkout (ex.:
email, document, phone, address).
customFields:
type: array
items:
type: object
nullable: true
description: >-
Definições dos campos personalizados solicitados no
checkout.
successUrl:
type: string
nullable: true
description: >-
URL de redirecionamento após o pagamento ser
concluído com sucesso.
cancelUrl:
type: string
nullable: true
description: >-
URL de redirecionamento quando o comprador cancela o
checkout.
metadata:
type: object
nullable: true
description: >-
Metadados livres (pares chave-valor) para uso do
integrador; não afeta o processamento.
expirationMinutes:
type: integer
nullable: true
description: Tempo de validade da sessão de checkout, em minutos.
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: >-
Data e hora da última atualização do registro (ISO
8601).
url:
type: string
description: >-
URL pública do checkout para o comprador finalizar o
pagamento.
description: Lista de registros retornados nesta página.
pagination:
type: object
properties:
page:
type: integer
description: Página atual retornada.
limit:
type: integer
description: Quantidade de itens por página.
total:
type: integer
description: Total de itens que atendem ao filtro.
totalPages:
type: integer
description: Total de páginas disponíveis.
description: >-
Metadados de paginação do resultado (página, limite e
totais).
example:
data:
- id: chk_byd8p3p79re859jpkmr0j65n3
slug: curso-marketing-digital
status: active
mode: payment
currency: BRL
locale: pt-BR
name: Curso de Marketing Digital
description: Acesso vitalício ao curso completo
sellable: true
config:
items:
- name: Curso de Marketing Digital
quantity: 1
unitAmount: 49700
chargeType: one_time
paymentMethods:
card:
enabled: true
pix:
enabled: true
requiredFields:
- email
- document
- phone
customFields: null
successUrl: https://academia.com/obrigado
cancelUrl: null
metadata: null
expirationMinutes: 1440
createdAt: '2025-06-29T13:45:30.000Z'
updatedAt: '2025-06-29T13:45:30.000Z'
url: https://pay.z2pay.com/c/curso-marketing-digital
pagination:
page: 1
limit: 20
total: 1
totalPages: 1
'400':
description: >-
Requisição inválida — algum parâmetro ou campo do corpo não passou
na validação
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
issues:
type: array
description: >-
Um item por campo rejeitado. Nunca vem vazio: se há
400 de validação, há pelo menos um.
items:
type: object
properties:
path:
type: string
description: >-
Campo que falhou. Vem vazio quando o erro é do
corpo como um todo.
message:
type: string
description: O que há de errado com esse campo.
example:
error:
code: VALIDATION_ERROR
message: Validation failed
issues:
- path: status
message: >-
Status inválido. Valores aceitos: pending,
waiting_payment, paid, refused, canceled, refunded
- path: startDate
message: >-
Data deve ser ISO 8601 com timezone (ex.:
2026-06-24T00:00:00Z)
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
'403':
description: >-
A chave é válida, mas não tem permissão para esta operação — é o
caso de usar uma publishable key (pk) onde a rota exige uma secret
key (sk)
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: FORBIDDEN
message: Forbidden — insufficient permissions
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: >-
API key unificada (z2_{live|test}_{sk|pk}_...) — secret (sk) para
integração backend, publishable (pk) para uso no frontend público
````