curl --request GET \
--url https://api.sandbox.z2pay.com/v1/checkout/charges \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/checkout/charges', 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/charges"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"data": [
{
"id": "cs_02f232c4dcf8eec4c29e0f3748476d1339b63c0e7ffab1dc",
"linkId": null,
"status": "created",
"mode": "payment",
"currency": "BRL",
"locale": "pt-BR",
"config": {
"paymentMethods": {
"card": {
"enabled": true,
"installments": {
"maxInstallments": 12,
"freeInstallments": 3
}
},
"pix": {
"enabled": true,
"expiresIn": 3600
},
"boleto": {
"enabled": true,
"dueDateDays": 3
}
},
"description": "Curso de Marketing Digital"
},
"customer": {
"name": "Maria Souza",
"email": "maria.souza@example.com",
"document": "12345678909",
"documentType": "cpf",
"phone": "+5511988887777"
},
"customFieldValues": null,
"paymentMethodSelected": null,
"subtotal": 19900,
"discountTotal": 0,
"amount": 19900,
"discounts": [],
"paymentAttempts": 0,
"transactionId": null,
"subscriptionId": null,
"invoiceId": null,
"metadata": null,
"createdAt": "2025-06-29T13:45:30.000Z",
"updatedAt": "2025-06-29T13:45:30.000Z",
"openedAt": null,
"paidAt": null,
"canceledAt": null,
"expiresAt": "2025-06-30T13:45:30.000Z",
"url": "https://checkout.z2pay.com.br/c/s/cs_02f232c4dcf8eec4c29e0f3748476d1339b63c0e7ffab1dc"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"totalPages": 1
}
}{
"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)"
}
]
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}{
"error": {
"code": "FORBIDDEN",
"message": "Forbidden — insufficient permissions"
}
}Listar vendas rápidas
Lista paginada das cobranças individuais — as Sessions sem Link.
curl --request GET \
--url https://api.sandbox.z2pay.com/v1/checkout/charges \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/checkout/charges', 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/charges"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"data": [
{
"id": "cs_02f232c4dcf8eec4c29e0f3748476d1339b63c0e7ffab1dc",
"linkId": null,
"status": "created",
"mode": "payment",
"currency": "BRL",
"locale": "pt-BR",
"config": {
"paymentMethods": {
"card": {
"enabled": true,
"installments": {
"maxInstallments": 12,
"freeInstallments": 3
}
},
"pix": {
"enabled": true,
"expiresIn": 3600
},
"boleto": {
"enabled": true,
"dueDateDays": 3
}
},
"description": "Curso de Marketing Digital"
},
"customer": {
"name": "Maria Souza",
"email": "maria.souza@example.com",
"document": "12345678909",
"documentType": "cpf",
"phone": "+5511988887777"
},
"customFieldValues": null,
"paymentMethodSelected": null,
"subtotal": 19900,
"discountTotal": 0,
"amount": 19900,
"discounts": [],
"paymentAttempts": 0,
"transactionId": null,
"subscriptionId": null,
"invoiceId": null,
"metadata": null,
"createdAt": "2025-06-29T13:45:30.000Z",
"updatedAt": "2025-06-29T13:45:30.000Z",
"openedAt": null,
"paidAt": null,
"canceledAt": null,
"expiresAt": "2025-06-30T13:45:30.000Z",
"url": "https://checkout.z2pay.com.br/c/s/cs_02f232c4dcf8eec4c29e0f3748476d1339b63c0e7ffab1dc"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"totalPages": 1
}
}{
"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)"
}
]
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}{
"error": {
"code": "FORBIDDEN",
"message": "Forbidden — insufficient permissions"
}
}GET /checkout/charges
Faz parte do recurso Vendas rápidas — a relação com Link e Session está
lá.
Devolve só as Sessions sem linkId, da mais recente para a mais antiga, 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ó as
cobranças que atendem a todos.
GET /checkout/sessions, com o filtro
já embutido. Lá aparecem as compras de Link e as avulsas juntas; aqui, só as avulsas. Se você
precisa das duas, use a listagem de Sessions.status aceita mais de um valor, separados por vírgula: ?status=paid,failed. Um valor fora
da lista responde 400 com os aceitos.2026-08-01T00:00:00-03:00). Para saber quando a cobrança foi paga, o caminho é a transação
ligada pelo transactionId.Exemplo
curl -G https://api.sandbox.z2pay.com/v1/checkout/charges \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-d status=paid \
-d page=1 \
-d limit=20
{
"data": [
{
"id": "cs_50b0abc54b632e7c57de3a73815413ace1d545dcd16da95c",
"linkId": null,
"status": "paid",
"amount": 30000,
"currency": "BRL",
"transactionId": "txn_ebgsvfsb4151nmbgvj4sek6ol",
"createdAt": "2026-06-24T12:00:00.000Z",
"expiresAt": "2026-06-25T12:00:00.000Z"
}
],
"pagination": { "page": 1, "limit": 20, "total": 8, "totalPages": 1 }
}
Authorizations
API key unificada (z2_{live|test}{sk|pk}...) — secret (sk) para integração backend, publishable (pk) para uso no frontend público
Query Parameters
Página da listagem. Padrão: 1.
x >= 1Itens por página. Padrão: 20. Máximo: 100.
1 <= x <= 100Situação da venda rápida. Aceita vários valores, separados por vírgula ou repetindo o parâmetro. Um valor inválido responde 400 com a lista dos aceitos.
created, opened, filling, paying, partially_paid, paid, failed, abandoned, expired, canceled Canal da venda rápida: link (paga pelo cliente na página) ou pos (intenção capturada no app Z2Pay). Omitido, traz as duas.
link, pos Transação vinculada. Correspondência parcial: 4151 encontra txn_ebgsvfsb4151nmbgvj4sek6ol.
Descrição da venda rápida. Correspondência parcial, sem diferenciar maiúsculas.
Vendas criadas a partir desta data, em ISO 8601 com fuso. Filtra a criação, não o pagamento.
Vendas criadas até esta data, em ISO 8601 com fuso. Filtra a criação, não o pagamento.