> ## 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.
# Buscar session
> Retorna uma compra pelo cs_ — estado, valor congelado, dados do comprador e a transação ligada.
`GET /checkout/sessions/{id}`
Faz parte do recurso [Links](/pt-BR/checkout/links) — o que é uma Session e os estados dela estão
lá.
Devolve a Session com o snapshot congelado na criação: itens, `amount`, métodos e branding, mais o
`customer` até onde o comprador preencheu, o `metadata` que você gravou e o `transactionId`.
**`transactionId` só existe a partir de `paying`.** Antes disso a compra ainda não virou
transação, e o campo vem `null`. É por ele que se puxam os detalhes de processamento em
[`GET /transactions/{id}`](/pt-BR/transactions/get) — e, no sentido inverso, o
`referenceCode` da transação é o próprio `cs_`. Veja
[Reconciliação](/pt-BR/checkout/links#reconciliação).
**Session de venda rápida também é encontrada aqui.** O que muda é o `linkId`, que vem `null`
quando não houve template.
## Exemplo
```bash theme={null}
curl https://api.sandbox.z2pay.com/v1/checkout/sessions/cs_9ffa51de3b60209c426388fbbd5ae4dc56980b13406d93b7 \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX"
```
```json Resposta 200 theme={null}
{
"id": "cs_9ffa51de3b60209c426388fbbd5ae4dc56980b13406d93b7",
"linkId": "chk_byd8p3p79re859jpkmr0j65n3",
"status": "paid",
"amount": 49900,
"currency": "BRL",
"customer": {
"name": "Maria Souza",
"email": "maria@example.com",
"document": "12345678909",
"documentType": "cpf"
},
"transactionId": "txn_ebgsvfsb4151nmbgvj4sek6ol",
"metadata": { "campaign": "instagram-bio-2026-05" },
"createdAt": "2026-06-24T13:10:00.000Z",
"expiresAt": "2026-06-25T13:10:00.000Z",
"url": "https://pay.sandbox.z2pay.com/c/cs_9ffa51de3b60209c426388fbbd5ae4dc56980b13406d93b7"
}
```
## OpenAPI
````yaml openapi/checkout.json GET /checkout/sessions/{id}
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/sessions/{id}:
get:
tags:
- Checkout Sessions
summary: Buscar session
description: Retorna os dados da Session, incluindo `metadata` e a URL de pagamento.
operationId: CheckoutSessionApiController_getById
parameters:
- name: id
in: path
required: true
description: ID da Session (cs_*)
schema:
type: string
responses:
'200':
description: Session encontrada
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Identificador único do registro.
linkId:
type: string
nullable: true
description: >-
Identificador do link de checkout que originou o registro;
nulo em sessões ad-hoc.
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).'
config:
type: object
description: >-
Snapshot da configuração do checkout (formas de pagamento,
itens e personalização visual).
customer:
type: object
nullable: true
description: >-
Dados do comprador (nome, e-mail, documento e demais
informações).
customFieldValues:
type: object
nullable: true
description: >-
Valores preenchidos nos campos personalizados, indexados
pela key de cada campo.
paymentMethodSelected:
type: string
nullable: true
description: >-
Forma de pagamento selecionada pelo comprador na sessão
(ex.: credit_card, pix, boleto).
subtotal:
type: integer
description: Soma dos itens antes dos descontos, em centavos.
discountTotal:
type: integer
description: Total de descontos aplicados, em centavos.
amount:
type: integer
description: Valor total a ser cobrado, em centavos.
discounts:
type: array
items:
type: object
nullable: true
description: Descontos aplicados ao valor da sessão.
paymentAttempts:
type: integer
description: >-
Quantidade de tentativas de pagamento realizadas na
sessão.
transactionId:
type: string
nullable: true
description: >-
Identificador da transação gerada pelo pagamento da
sessão; nulo até haver pagamento.
subscriptionId:
type: string
nullable: true
description: >-
Identificador da assinatura criada a partir da sessão;
nulo até a ativação.
metadata:
type: object
nullable: true
description: >-
Metadados livres (pares chave-valor) para uso do
integrador; não afeta o processamento.
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).
openedAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que a sessão foi aberta pelo comprador (ISO
8601); nula se ainda não aberta.
paidAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que o pagamento foi confirmado (ISO 8601);
nula se não pago.
canceledAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora do cancelamento (ISO 8601); nula se não
cancelado.
expiresAt:
type: string
format: date-time
description: Data e hora de expiração (ISO 8601).
url:
type: string
description: >-
URL pública do checkout para o comprador finalizar o
pagamento.
example:
id: cs_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
linkId: chk_byd8p3p79re859jpkmr0j65n3
status: paid
mode: subscription
currency: BRL
locale: pt-BR
config:
paymentMethods:
card:
enabled: true
subscriptionConfig:
planId: plan_edz8m3vbxbvobrom0qlxbq68h
recurrence:
interval: 1
unit: month
currency: BRL
trialDays: 7
customer:
name: Maria Souza
email: maria@example.com
document: '98765432100'
documentType: cpf
customFieldValues: null
paymentMethodSelected: credit_card
subtotal: 9900
discountTotal: 0
amount: 9900
discounts: null
paymentAttempts: 1
transactionId: txn_tjqtumilg7mf1j5w8duqiaj4k
subscriptionId: sub_d8lrg5j964f8k1qpvdc3ndmvn
metadata:
source: api
createdAt: '2025-06-29T10:00:00.000Z'
updatedAt: '2025-06-29T10:05:00.000Z'
openedAt: '2025-06-29T10:01:00.000Z'
paidAt: '2025-06-29T10:05:00.000Z'
canceledAt: null
expiresAt: '2025-06-30T10:00:00.000Z'
url: >-
https://pay.z2pay.com/c/cs_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
'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
'404':
description: Session não encontrada
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: NOT_FOUND
message: Session not found
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
````