Chargebacks - Z2Pay Developers

Um chargeback acontece quando o portador do cartão contesta uma cobrança junto ao banco emissor. Quando a adquirente notifica a Z2Pay, abrimos automaticamente um chargeback e movemos o pagamento para um estado de contestação. Você pode acompanhar o caso, anexar provas (notas fiscais, comprovantes de entrega, contratos) e baixar os documentos já enviados.

Chargebacks não são criados pela API. Eles nascem de um webhook da adquirente. Pela API pública você só consulta casos e gerencia documentos de contestação. As transições de status (ganho / perdido) são decididas pela adquirente e aplicadas internamente.

Todas as requisições usam o header x-api-key (veja Autenticação).

Estados do chargeback

Status	Significado	O que você pode fazer
`opened`	Chargeback recém-criado a partir do webhook da adquirente.	Aguardar — o sistema move para `under_review` automaticamente.
`under_review`	Em análise. Janela aberta para envio de provas.	Enviar documentos de contestação (até o prazo `deadlineAt`).
`submitted`	Provas enviadas à adquirente; aguardando decisão.	Acompanhar.
`won`	Contestação ganha.	Caso encerrado.
`lost`	Contestação perdida.	Caso encerrado.

Efeito no pagamento e na carteira (wallet):

Ao entrar em under_review, o pagamento associado fica em contestação (in_protest) e o valor do chargeback é debitado da sua carteira (reserva), junto com a taxa de chargeback aplicável.
Se o chargeback for won (ganho), o pagamento volta para paid e o valor reservado é estornado (creditado de volta), inclusive a taxa.
Se o chargeback for lost (perdido), o pagamento vai para chargeback e pode incidir uma multa (penalty) configurável por empresa.

Os valores movimentados na carteira aparecem em Carteiras; a configuração de taxa/multa de chargeback está em Taxas.

Endpoints

Método	Rota	Descrição
GET	`/chargebacks`	Lista chargebacks com paginação e filtros.
GET	`/chargebacks/{id}`	Busca um chargeback por ID.
GET	`/chargebacks/transaction/{transactionId}`	Lista chargebacks de uma transação.
GET	`/chargebacks/payment/{paymentId}`	Lista chargebacks de um pagamento.
GET	`/chargebacks/{id}/documents`	Lista documentos de contestação enviados.
GET	`/chargebacks/{id}/documents/{documentId}/download`	Gera URL assinada para download de um documento.
POST	`/chargebacks/{id}/documents`	Envia um documento de contestação.

Listar chargebacks

GET /chargebacks

Retorna os chargebacks da sua empresa com paginação e filtros opcionais. Todos os filtros são query params.

status

string

Filtra por status. Aceita múltiplos valores separados por vírgula (ex.: opened,under_review). Valores válidos: opened, under_review, submitted, won, lost.

transactionId

string

Filtra pelos chargebacks de uma transação específica.

paymentId

string

Filtra pelos chargebacks de um pagamento específico.

string

Busca textual livre.

startDate

string

Data inicial do intervalo, em ISO 8601 com timezone (ex.: 2026-06-01T00:00:00-03:00). O campo de data filtrado é definido por dateField.

endDate

string

Data final do intervalo, em ISO 8601 com timezone (ex.: 2026-06-30T23:59:59-03:00).

dateField

string

Campo de data usado pelo filtro startDate/endDate. Valores: openedAt ou deadlineAt.

sortBy

string

Campo de ordenação. Valores: openedAt, amount, status, deadlineAt.

sortDir

string

Direção da ordenação. Valores: asc ou desc.

page

integer

padrão:"1"

Página (inteiro positivo).

limit

integer

padrão:"10"

Itens por página (inteiro positivo, máximo 100).

curl -G https://api.sandbox.z2pay.com/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 "sortBy=openedAt" \
  --data-urlencode "sortDir=desc" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=10"

{
  "data": [
    {
      "id": "cbk_8s2k1d9f0a3b4c5e6f7g",
      "companyId": "comp_3f9a2b1c8d7e6f5a4b3c",
      "transactionId": "txn_1a2b3c4d5e6f7g8h9i0j",
      "paymentId": "pay_9z8y7x6w5v4u3t2s1r0q",
      "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
  }
}

data

object[]

Lista de chargebacks da página.

data[].id

string

ID do chargeback (prefixo cbk_).

data[].transactionId

string

Transação associada (prefixo txn_).

data[].paymentId

string

Pagamento associado (prefixo pay_).

data[].externalId

string | null

Identificador do chargeback na adquirente. Pode ser null.

data[].amount

integer

Valor contestado em centavos (ex.: 14990 = R$ 149,90).

data[].currency

string

Moeda do valor. Padrão BRL.

data[].status

string

Status atual: opened, under_review, submitted, won ou lost.

data[].reasonCode

string | null

Código do motivo informado pela adquirente. Pode ser null.

data[].reason

string | null

Descrição do motivo. Pode ser null.

data[].deadlineAt

string | null

Prazo final para envio de provas, em ISO 8601. Pode ser null. Após esse instante, o upload de documentos é bloqueado.

data[].openedAt

string | null

Quando o chargeback foi aberto, em ISO 8601. Pode ser null.

data[].resolvedAt

string | null

Quando o caso foi resolvido (ganho/perdido), em ISO 8601. null enquanto não resolvido.

pagination

object

Metadados de paginação: page, limit, total e totalPages.

Buscar chargeback por ID

GET /chargebacks/{id}

string

obrigatório

ID do chargeback (prefixo cbk_).

curl https://api.sandbox.z2pay.com/chargebacks/cbk_8s2k1d9f0a3b4c5e6f7g \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "id": "cbk_8s2k1d9f0a3b4c5e6f7g",
  "companyId": "comp_3f9a2b1c8d7e6f5a4b3c",
  "transactionId": "txn_1a2b3c4d5e6f7g8h9i0j",
  "paymentId": "pay_9z8y7x6w5v4u3t2s1r0q",
  "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"
}

Retorna 404 se o chargeback não existir ou não pertencer à sua empresa. Veja Erros.

Chargebacks de uma transação

GET /chargebacks/transaction/{transactionId}

transactionId

string

obrigatório

ID da transação (prefixo txn_).

page

integer

padrão:"1"

Página (inteiro positivo).

limit

integer

padrão:"20"

Itens por página (inteiro positivo, máximo 100).

curl -G https://api.sandbox.z2pay.com/chargebacks/transaction/txn_1a2b3c4d5e6f7g8h9i0j \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

A resposta é uma lista paginada com o mesmo formato de chargeback descrito em Listar chargebacks.

Chargebacks de um pagamento

GET /chargebacks/payment/{paymentId}

paymentId

string

obrigatório

ID do pagamento (prefixo pay_).

page

integer

padrão:"1"

Página (inteiro positivo).

limit

integer

padrão:"20"

Itens por página (inteiro positivo, máximo 100).

curl -G https://api.sandbox.z2pay.com/chargebacks/payment/pay_9z8y7x6w5v4u3t2s1r0q \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

A resposta é uma lista paginada com o mesmo formato de chargeback descrito em Listar chargebacks.

Listar documentos do chargeback

GET /chargebacks/{id}/documents

Retorna os documentos de contestação já enviados para o chargeback.

string

obrigatório

ID do chargeback (prefixo cbk_).

curl https://api.sandbox.z2pay.com/chargebacks/cbk_8s2k1d9f0a3b4c5e6f7g/documents \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    {
      "id": "cbkd_0a1b2c3d4e5f6g7h8i9j",
      "chargebackId": "cbk_8s2k1d9f0a3b4c5e6f7g",
      "companyId": "comp_3f9a2b1c8d7e6f5a4b3c",
      "type": "delivery_proof",
      "contentType": "application/pdf",
      "size": 184320,
      "description": "Comprovante de entrega com assinatura",
      "uploadedBy": "comp_3f9a2b1c8d7e6f5a4b3c",
      "createdAt": "2026-06-24T11:00:00-03:00",
      "updatedAt": "2026-06-24T11:00:00-03:00"
    }
  ]
}

data

object[]

Lista de documentos.

data[].id

string

ID do documento (prefixo cbkd_).

data[].type

string

Tipo do documento: invoice, delivery_proof, signed_contract, screenshot ou other.

data[].contentType

string

MIME type detectado: application/pdf, image/jpeg, image/png ou image/webp.

data[].size

integer

Tamanho do arquivo em bytes.

data[].description

string | null

Descrição informada no envio. Pode ser null.

data[].uploadedBy

string

Identificador de quem enviou o documento.

Retorna 404 se o chargeback não existir ou não pertencer à sua empresa.

Download de documento

GET /chargebacks/{id}/documents/{documentId}/download

Gera uma URL assinada temporária para baixar o arquivo. A URL expira em 1 hora.

string

obrigatório

ID do chargeback (prefixo cbk_).

documentId

string

obrigatório

ID do documento (prefixo cbkd_).

curl https://api.sandbox.z2pay.com/chargebacks/cbk_8s2k1d9f0a3b4c5e6f7g/documents/cbkd_0a1b2c3d4e5f6g7h8i9j/download \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "url": "https://storage.sandbox.z2pay.com/chargebacks/comp_3f9a2b1c8d7e6f5a4b3c/cbk_8s2k1d9f0a3b4c5e6f7g/cbkd_0a1b2c3d4e5f6g7h8i9j.pdf?signature=..."
}

url

string

URL assinada para download direto do arquivo. Válida por tempo limitado.

Retorna 404 se o documento não existir ou não pertencer à sua empresa.

Upload de documento

POST /chargebacks/{id}/documents

Envia um documento de contestação para o chargeback. Responde com status 201 e o documento criado.

O upload só é permitido quando o chargeback está em under_review e o prazo deadlineAt ainda não expirou. Em qualquer outro caso, a API responde 409.

Este endpoint é idempotente. Envie o header Idempotency-Key com um valor único por requisição para evitar uploads duplicados em caso de retry. Veja Convenções.

Parâmetros de path

string

obrigatório

ID do chargeback (prefixo cbk_).

Corpo da requisição

type

string

obrigatório

Tipo do documento. Valores: invoice, delivery_proof, signed_contract, screenshot ou other.

file

string

obrigatório

Conteúdo do arquivo em base64. Aceita o prefixo data URI (ex.: data:application/pdf;base64,...) ou o base64 puro. Tipos aceitos: PDF, JPEG, PNG e WebP (detectados pelo conteúdo binário, não pela extensão). Tamanho máximo: 10 MB.

description

string

Descrição opcional do documento. Máximo de 500 caracteres. Pode ser omitido ou enviado como null.

curl -X POST https://api.sandbox.z2pay.com/chargebacks/cbk_8s2k1d9f0a3b4c5e6f7g/documents \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 7c2f9a1e-3b4d-4e5f-8a9b-0c1d2e3f4a5b" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "delivery_proof",
    "description": "Comprovante de entrega com assinatura",
    "file": "data:application/pdf;base64,JVBERi0xLjcKJ..."
  }'

{
  "id": "cbkd_0a1b2c3d4e5f6g7h8i9j",
  "chargebackId": "cbk_8s2k1d9f0a3b4c5e6f7g",
  "companyId": "comp_3f9a2b1c8d7e6f5a4b3c",
  "type": "delivery_proof",
  "contentType": "application/pdf",
  "size": 184320,
  "description": "Comprovante de entrega com assinatura",
  "uploadedBy": "comp_3f9a2b1c8d7e6f5a4b3c",
  "createdAt": "2026-06-24T11:00:00-03:00",
  "updatedAt": "2026-06-24T11:00:00-03:00"
}

Status e erros

Código	Quando ocorre
`201`	Documento enviado com sucesso.
`400`	Arquivo inválido: vazio, acima de 10 MB ou de tipo não aceito (apenas PDF/JPEG/PNG/WebP).
`404`	Chargeback não encontrado.
`409`	Upload não permitido no status atual (não está em `under_review`) ou prazo expirado.

Formato completo dos erros em Erros.

Testando no Sandbox

Como chargebacks só nascem de webhooks da adquirente, use o simulador do Sandbox para disparar um caso e então exercitar a consulta e o upload de documentos.

Crie um pagamento de teste

Gere uma transação/pagamento aprovado seguindo o Quickstart.

Simule o chargeback

Use a página Simular eventos para disparar o chargeback sobre o pagamento criado. O caso entra em under_review automaticamente.

Liste e envie provas

Liste o chargeback com GET /chargebacks e envie um documento via POST /chargebacks/{id}/documents enquanto estiver em under_review.

Veja também

Pagamentos

Estados do pagamento, incluindo a contestação.

Carteiras

Débitos, estornos e multas gerados pelos chargebacks.

Taxas

Configuração de taxa e multa de chargeback.

Simular eventos

Dispare chargebacks no ambiente de Sandbox.

​Estados do chargeback

​Endpoints

​Listar chargebacks

​Buscar chargeback por ID

​Chargebacks de uma transação

​Chargebacks de um pagamento

​Listar documentos do chargeback

​Download de documento

​Upload de documento

​Parâmetros de path

​Corpo da requisição

​Status e erros

​Testando no Sandbox

​Veja também

Pagamentos

Carteiras

Taxas

Simular eventos

Estados do chargeback

Endpoints

Listar chargebacks

Buscar chargeback por ID

Chargebacks de uma transação

Chargebacks de um pagamento

Listar documentos do chargeback

Download de documento

Upload de documento

Parâmetros de path

Corpo da requisição

Status e erros

Testando no Sandbox

Veja também