curl --request GET \
--url https://api.sandbox.z2pay.com/v1/chargebacks \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/chargebacks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.sandbox.z2pay.com/v1/chargebacks"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"data": [
{
"id": "cbk_v5wylkgvv2rls5tihmuybrz9v",
"transactionId": "txn_aqbcw2lky42xfidw5pcdss8h1",
"paymentId": "pay_jxt9b5qv1x0h0h8ustleqjgr8",
"externalId": "ch_mw198ybczrn8y2fd6y7dnznft",
"amount": 14990,
"currency": "BRL",
"status": "under_review",
"reasonCode": "4853",
"reason": "Produto ou serviço não recebido",
"deadlineAt": "2025-07-06T23:59:59.000Z",
"openedAt": "2025-06-29T10:00:00.000Z",
"resolvedAt": null,
"createdAt": "2025-06-29T10:00:05.000Z",
"updatedAt": "2025-06-29T10:00:10.000Z"
}
],
"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"
}
}Listar chargebacks
Lista paginada de contestações, com filtros por etapa, transação, pagamento e período.
curl --request GET \
--url https://api.sandbox.z2pay.com/v1/chargebacks \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/chargebacks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.sandbox.z2pay.com/v1/chargebacks"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"data": [
{
"id": "cbk_v5wylkgvv2rls5tihmuybrz9v",
"transactionId": "txn_aqbcw2lky42xfidw5pcdss8h1",
"paymentId": "pay_jxt9b5qv1x0h0h8ustleqjgr8",
"externalId": "ch_mw198ybczrn8y2fd6y7dnznft",
"amount": 14990,
"currency": "BRL",
"status": "under_review",
"reasonCode": "4853",
"reason": "Produto ou serviço não recebido",
"deadlineAt": "2025-07-06T23:59:59.000Z",
"openedAt": "2025-06-29T10:00:00.000Z",
"resolvedAt": null,
"createdAt": "2025-06-29T10:00:05.000Z",
"updatedAt": "2025-06-29T10:00:10.000Z"
}
],
"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"
}
}GET /chargebacks
Faz parte do recurso Chargebacks — as etapas do caso e o objeto de
resposta estão lá.
Retorna uma lista paginada. Todos os filtros são opcionais e podem ser combinados. As datas seguem
ISO 8601 com timezone (veja Convenções).
?status=xpto responde 400 com
error.issues[] apontando o campo e os valores aceitos.O formato do erro e a lista de códigos estão em Erros.status aceita uma lista separada por vírgula, e o resultado
traz as contestações em qualquer uma das etapas: ?status=opened,under_review.?transactionId= e
?paymentId= fazem correspondência exata, e aceitam status, período e ordenação na mesma
consulta — ?transactionId=txn_123&status=under_review&dateField=deadlineAt.dateField decide sobre qual data o período incide. Com openedAt (o padrão) você pergunta
“o que foi contestado neste mês”; com deadlineAt, “o que vence neste mês”. A segunda é a que
responde a pergunta operacional — quais casos ainda dá tempo de defender.?dateField=deadlineAt&startDate=2026-07-01T00:00:00-03:00&endDate=2026-07-31T23:59:59-03:00&status=opened,under_review
Exemplo
curl -G https://api.sandbox.z2pay.com/v1/chargebacks \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
--data-urlencode "status=opened,under_review" \
--data-urlencode "dateField=openedAt" \
--data-urlencode "startDate=2026-06-01T00:00:00-03:00" \
--data-urlencode "endDate=2026-06-30T23:59:59-03:00" \
--data-urlencode "sortDir=desc" \
--data-urlencode "limit=10"
{
"data": [
{
"id": "cbk_sadcdemslpvvxfn87kpzgjgy2",
"transactionId": "txn_zbivi7anej6en8lu8fxnv0mgq",
"paymentId": "pay_v9amuqt179u31q34g6nyipf5y",
"externalId": "chb_pgmto_abc123",
"amount": 14990,
"currency": "BRL",
"status": "under_review",
"reasonCode": "4853",
"reason": "Produto não recebido",
"deadlineAt": "2026-07-01T23:59:59-03:00",
"openedAt": "2026-06-24T10:12:00-03:00",
"resolvedAt": null,
"createdAt": "2026-06-24T10:12:01-03:00",
"updatedAt": "2026-06-24T10:12:03-03:00"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 1,
"totalPages": 1
}
}
Authorizations
API Key da Credential (gerada no Backoffice)
Query Parameters
Página da listagem. Padrão: 1.
x >= 1Itens por página. Padrão: 20. Máximo: 100.
1 <= x <= 100Retorna as contestações desta transação. Correspondência exata.
Retorna as contestações deste pagamento. Correspondência exata.
Etapa da contestação: opened (aberta), under_review (em análise), submitted (defesa enviada), won (ganha) ou lost (perdida). Aceita vários valores separados por vírgula.
opened, under_review, submitted, won, lost Início do período (ISO 8601 com timezone), inclusive. Aplica-se ao campo indicado em dateField.
Fim do período (ISO 8601 com timezone), inclusive. Aplica-se ao campo indicado em dateField.
Campo a que startDate e endDate se aplicam: openedAt (abertura da contestação) ou deadlineAt (prazo de defesa). Default: openedAt.
openedAt, deadlineAt Campo de ordenação: openedAt (abertura) ou deadlineAt (prazo de defesa). Default: openedAt.
openedAt, deadlineAt Direção da ordenação: asc ou desc. Default: desc.
asc, desc