Chargebacks - Z2Pay Developers

A chargeback occurs when a cardholder disputes a charge with their issuing bank. When the acquirer notifies Z2Pay, we automatically open a chargeback and move the payment to a disputed state. You can monitor the case, attach evidence (invoices, proof of delivery, contracts), and download previously submitted documents.

Chargebacks are not created via the API. They originate from an acquirer webhook. Through the public API you can only retrieve cases and manage dispute documents. Status transitions (won / lost) are decided by the acquirer and applied internally.

All requests use the x-api-key header (see Authentication).

Chargeback statuses

Status	Meaning	What you can do
`opened`	Chargeback just created from the acquirer webhook.	Wait — the system moves it to `under_review` automatically.
`under_review`	Under review. Window is open for submitting evidence.	Submit dispute documents (up to the `deadlineAt` deadline).
`submitted`	Evidence sent to the acquirer; awaiting decision.	Monitor the case.
`won`	Dispute won.	Case closed.
`lost`	Dispute lost.	Case closed.

Effect on the payment and wallet:

When moving to under_review, the associated payment enters a disputed state (in_protest) and the chargeback amount is debited from your wallet (reserve), along with the applicable chargeback fee.
If the chargeback is won, the payment returns to paid and the reserved amount is reversed (credited back), including the fee.
If the chargeback is lost, the payment moves to chargeback and a configurable penalty may be applied per company.

The wallet movements appear under Wallets; the chargeback fee/penalty configuration is described in Fees.

Endpoints

Method	Route	Description
GET	`/chargebacks`	List chargebacks with pagination and filters.
GET	`/chargebacks/{id}`	Retrieve a chargeback by ID.
GET	`/chargebacks/transaction/{transactionId}`	List chargebacks for a transaction.
GET	`/chargebacks/payment/{paymentId}`	List chargebacks for a payment.
GET	`/chargebacks/{id}/documents`	List submitted dispute documents.
GET	`/chargebacks/{id}/documents/{documentId}/download`	Generate a signed URL to download a document.
POST	`/chargebacks/{id}/documents`	Submit a dispute document.

List chargebacks

GET /chargebacks

Returns your company’s chargebacks with pagination and optional filters. All filters are query params.

status

string

Filter by status. Accepts multiple comma-separated values (e.g., opened,under_review). Valid values: opened, under_review, submitted, won, lost.

transactionId

string

Filter chargebacks by a specific transaction.

paymentId

string

Filter chargebacks by a specific payment.

string

Free-text search.

startDate

string

Start of the date range, in ISO 8601 with timezone (e.g., 2026-06-01T00:00:00-03:00). The date field being filtered is defined by dateField.

endDate

string

End of the date range, in ISO 8601 with timezone (e.g., 2026-06-30T23:59:59-03:00).

dateField

string

Date field used by the startDate/endDate filter. Values: openedAt or deadlineAt.

sortBy

string

Sort field. Values: openedAt, amount, status, deadlineAt.

sortDir

string

Sort direction. Values: asc or desc.

page

integer

default:"1"

Page number (positive integer).

limit

integer

default:"10"

Items per page (positive integer, maximum 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[]

List of chargebacks on the current page.

data[].id

string

Chargeback ID (prefix cbk_).

data[].transactionId

string

Associated transaction (prefix txn_).

data[].paymentId

string

Associated payment (prefix pay_).

data[].externalId

string | null

Chargeback identifier at the acquirer. May be null.

data[].amount

integer

Disputed amount in cents (e.g., 14990 = $149.90).

data[].currency

string

Currency of the amount. Default BRL.

data[].status

string

Current status: opened, under_review, submitted, won, or lost.

data[].reasonCode

string | null

Reason code provided by the acquirer. May be null.

data[].reason

string | null

Reason description. May be null.

data[].deadlineAt

string | null

Deadline for submitting evidence, in ISO 8601. May be null. After this point, document uploads are blocked.

data[].openedAt

string | null

When the chargeback was opened, in ISO 8601. May be null.

data[].resolvedAt

string | null

When the case was resolved (won/lost), in ISO 8601. null while still unresolved.

pagination

object

Pagination metadata: page, limit, total, and totalPages.

Retrieve chargeback by ID

GET /chargebacks/{id}

string

required

Chargeback ID (prefix 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"
}

Returns 404 if the chargeback does not exist or does not belong to your company. See Errors.

Chargebacks for a transaction

GET /chargebacks/transaction/{transactionId}

transactionId

string

required

Transaction ID (prefix txn_).

page

integer

default:"1"

Page number (positive integer).

limit

integer

default:"20"

Items per page (positive integer, maximum 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"

The response is a paginated list using the same chargeback format described in List chargebacks.

Chargebacks for a payment

GET /chargebacks/payment/{paymentId}

paymentId

string

required

Payment ID (prefix pay_).

page

integer

default:"1"

Page number (positive integer).

limit

integer

default:"20"

Items per page (positive integer, maximum 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"

The response is a paginated list using the same chargeback format described in List chargebacks.

List chargeback documents

GET /chargebacks/{id}/documents

Returns the dispute documents already submitted for the chargeback.

string

required

Chargeback ID (prefix 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[]

List of documents.

data[].id

string

Document ID (prefix cbkd_).

data[].type

string

Document type: invoice, delivery_proof, signed_contract, screenshot, or other.

data[].contentType

string

Detected MIME type: application/pdf, image/jpeg, image/png, or image/webp.

data[].size

integer

File size in bytes.

data[].description

string | null

Description provided at upload time. May be null.

data[].uploadedBy

string

Identifier of who uploaded the document.

Returns 404 if the chargeback does not exist or does not belong to your company.

Download a document

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

Generates a temporary signed URL to download the file. The URL expires in 1 hour.

string

required

Chargeback ID (prefix cbk_).

documentId

string

required

Document ID (prefix 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

Signed URL for direct file download. Valid for a limited time.

Returns 404 if the document does not exist or does not belong to your company.

Upload a document

POST /chargebacks/{id}/documents

Submits a dispute document for the chargeback. Responds with status 201 and the created document.

Uploads are only allowed when the chargeback is in under_review and the deadlineAt deadline has not yet expired. In any other case, the API responds with 409.

This endpoint is idempotent. Send the Idempotency-Key header with a unique value per request to prevent duplicate uploads on retry. See Conventions.

Path parameters

string

required

Chargeback ID (prefix cbk_).

Request body

type

string

required

Document type. Values: invoice, delivery_proof, signed_contract, screenshot, or other.

file

string

required

File content encoded as base64. Accepts the data URI prefix (e.g., data:application/pdf;base64,...) or plain base64. Accepted types: PDF, JPEG, PNG, and WebP (detected by binary content, not file extension). Maximum size: 10 MB.

description

string

Optional description for the document. Maximum 500 characters. May be omitted or sent as 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 codes and errors

Code	When it occurs
`201`	Document submitted successfully.
`400`	Invalid file: empty, exceeds 10 MB, or unsupported type (only PDF/JPEG/PNG/WebP).
`404`	Chargeback not found.
`409`	Upload not allowed in the current status (not `under_review`) or deadline has passed.

Full error format described in Errors.

Testing in the Sandbox

Since chargebacks only originate from acquirer webhooks, use the Sandbox simulator to trigger a case and then exercise retrieval and document uploads.

Create a test payment

Generate an approved transaction/payment by following the Quickstart.

Simulate the chargeback

Use the Simulate events page to trigger a chargeback on the payment you created. The case enters under_review automatically.

List and submit evidence

List the chargeback with GET /chargebacks and submit a document via POST /chargebacks/{id}/documents while it is in under_review.

Payments

Payment statuses, including the disputed state.

Wallets

Debits, reversals, and penalties generated by chargebacks.

Fees

Chargeback fee and penalty configuration.

Simulate events

Trigger chargebacks in the Sandbox environment.

​Chargeback statuses

​Endpoints

​List chargebacks

​Retrieve chargeback by ID

​Chargebacks for a transaction

​Chargebacks for a payment

​List chargeback documents

​Download a document

​Upload a document

​Path parameters

​Request body

​Status codes and errors

​Testing in the Sandbox

​See also

Payments

Wallets

Fees

Simulate events

Chargeback statuses

Endpoints

List chargebacks

Retrieve chargeback by ID

Chargebacks for a transaction

Chargebacks for a payment

List chargeback documents

Download a document

Upload a document

Path parameters

Request body

Status codes and errors

Testing in the Sandbox

See also