Chargeback API

Overview

The Chargeback API allows you to request and track refunds (chargebacks) for paid PIX QR Codes. Chargebacks can be full or partial, and the API provides asynchronous processing with status tracking.

What is a Chargeback?

A chargeback is a reversal of a PIX QR Code payment, returning funds from the receiver back to the original payer. Chargebacks are commonly used for:

🔄 Customer refunds (order cancellations, returns)
❌ Transaction errors
⚠️ Disputed charges
💸 Partial refunds (partial order cancellations)

Chargeback Types

Full Chargeback

Amount equals the total value of the QR Code.

Example: QR Code value: R$ 100,00 → Chargeback: R$ 100,00

Partial Chargeback

Amount is less than the total value of the QR Code.

Example: QR Code value: R$ 100,00 → Chargeback: R$ 50,00

Multiple Chargebacks

Multiple partial chargebacks can be created as long as the sum doesn't exceed the original QR Code value.

Example:

QR Code value: R$ 100,00
First chargeback: R$ 30,00
Second chargeback: R$ 50,00
Available balance: R$ 20,00

Processing Types

Internal Chargeback (Same Institution)

✅ Synchronous processing
✅ Immediate SUCCESS status
⚡ Instant refund completion

External Chargeback (Other Institutions)

⏳ Asynchronous processing
🕐 Initial PENDING status
📊 Use Chargeback Status endpoint to track completion
⏱️ Typically completes within 5-10 minutes

Authentication

All endpoints require Bearer token authentication:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Endpoints

1. Create PIX QR Code Chargeback

POST /v2/finance/chargebacks-pix-copy-and-paste

Request a full or partial chargeback for a paid PIX QR Code.

View Full Documentation →

2. Check Chargeback Status

GET /v2/finance/chargebacks-pix-copy-and-paste/status

Query the status of a previously created chargeback using ID or E2E ID.

View Full Documentation →

Business Rules

Validations

✅ Required:

QR Code must exist and belong to your account
QR Code status must be PAID or CHARGEBACK (partially refunded)
All required fields provided (qr_code_id, amount, information)
Amount > 0 with exactly 2 decimal places

❌ Not Allowed:

Cannot create chargeback if there's already a PENDING chargeback for this QR Code
Amount cannot exceed remaining refundable balance
Associated account cannot be closed

Workflow

Create Chargeback → Returns chargeback id and initial status
Processing → System processes refund (async for external, sync for internal)
Track Status → Query status using chargeback id or end_to_end_id
Complete → Status becomes SUCCESS or REJECTED

Common Use Cases

Full Refund

POST /v2/finance/chargebacks-pix-copy-and-paste
{
  "qr_code_id": 12345,
  "information": "Full refund - customer canceled order",
  "amount": 100.00
}

Partial Refund

POST /v2/finance/chargebacks-pix-copy-and-paste
{
  "qr_code_id": 12345,
  "information": "Partial refund - returned 1 of 2 items",
  "amount": 50.00
}

Check Status

GET /v2/finance/chargebacks-pix-copy-and-paste/status?id=98765

Webhooks

Chargeback events trigger webhooks for real-time notifications:

QR_CODE_COPY_AND_PASTE_REFUNDED - Chargeback successfully completed
QR_CODE_COPY_AND_PASTE_REFUNDED_ERROR - Chargeback failed

Error Handling

Error Code	Description
400	QR Code not found, not paid, or invalid parameters
401	Invalid or missing authentication token
422	Validation error (incorrect format, missing fields)

Best Practices

1. Implement Webhooks

Instead of polling the status endpoint, use webhooks for real-time chargeback completion notifications.

2. Handle Pending Status

For external chargebacks, expect PENDING status. Poll every 30 seconds or wait for webhook notification.

3. Provide Clear Information

Always include a descriptive information field explaining the reason for the chargeback (aids customer support and compliance).

4. Track Chargeback IDs

Store the returned chargeback id for future status queries and reconciliation.