curl --request GET \
--url https://api.sandbox.z2pay.com/v1/checkout/sessions/{id} \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/checkout/sessions/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.sandbox.z2pay.com/v1/checkout/sessions/{id}"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"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",
"invoiceId": null,
"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"
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}{
"error": {
"code": "FORBIDDEN",
"message": "Forbidden — insufficient permissions"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Session not found"
}
}Buscar session
Retorna uma compra pelo cs_ — estado, valor congelado, dados do comprador e a transação ligada.
curl --request GET \
--url https://api.sandbox.z2pay.com/v1/checkout/sessions/{id} \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/checkout/sessions/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.sandbox.z2pay.com/v1/checkout/sessions/{id}"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"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",
"invoiceId": null,
"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"
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}{
"error": {
"code": "FORBIDDEN",
"message": "Forbidden — insufficient permissions"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Session not found"
}
}GET /checkout/sessions/{id}
Faz parte do recurso 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} — e, no sentido inverso, o
referenceCode da transação é o próprio cs_. Veja
Reconciliação.linkId, que vem null
quando não houve template.Exemplo
curl https://api.sandbox.z2pay.com/v1/checkout/sessions/cs_9ffa51de3b60209c426388fbbd5ae4dc56980b13406d93b7 \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX"
{
"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"
}
Authorizations
API key unificada (z2_{live|test}{sk|pk}...) — secret (sk) para integração backend, publishable (pk) para uso no frontend público
Path Parameters
ID da Session (cs_*)
Response
Session encontrada
Identificador único do registro.
Identificador do link de checkout que originou o registro; nulo em sessões ad-hoc.
Estado atual do registro.
Modo do checkout: 'payment' (pagamento único) ou 'subscription' (assinatura).
Moeda no padrão ISO 4217 (ex.: BRL).
Idioma do checkout (ex.: pt-BR, en-US, es-ES).
Snapshot da configuração do checkout (formas de pagamento, itens e personalização visual).
Dados do comprador (nome, e-mail, documento e demais informações).
Valores preenchidos nos campos personalizados, indexados pela key de cada campo.
Forma de pagamento selecionada pelo comprador na sessão (ex.: credit_card, pix, boleto).
Soma dos itens antes dos descontos, em centavos.
Total de descontos aplicados, em centavos.
Valor total a ser cobrado, em centavos.
Descontos aplicados ao valor da sessão.
Quantidade de tentativas de pagamento realizadas na sessão.
Identificador da transação gerada pelo pagamento da sessão; nulo até haver pagamento.
Identificador da assinatura criada a partir da sessão; nulo até a ativação.
Fatura gerada pela venda com data de cobrança (scheduledAt), criada quando o comprador aceita. Nula em toda outra venda — pagamento no ato não gera fatura.
Metadados livres (pares chave-valor) para uso do integrador; não afeta o processamento.
Data e hora de criação do registro (ISO 8601).
Data e hora da última atualização do registro (ISO 8601).
Data e hora em que a sessão foi aberta pelo comprador (ISO 8601); nula se ainda não aberta.
Data e hora em que o pagamento foi confirmado (ISO 8601); nula se não pago.
Data e hora do cancelamento (ISO 8601); nula se não cancelado.
Data e hora de expiração (ISO 8601).
URL pública do checkout para o comprador finalizar o pagamento.