post
https://api.cartwavehub.com.br/v2/finance/chargebacks-pix-copy-and-paste/
This API allows you to request a chargeback (full or partial) for a paid PIX QR Code. The chargeback processing is asynchronous and the status can be consulted later through the Chargeback Status API.
Headers
| Parameter | Type | Description | Example |
|---|---|---|---|
| Authorization | String | Bearer + Access_token | Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo |
Body Details
{
"qr_code_id": 12345,
"information": "Customer requested refund for order cancellation",
"amount": 50.00
}
| Field | Type | Description | Required or Optional |
|---|---|---|---|
| qr_code_id | Integer | ID of the PIX QR Code to be refunded. This is the unique identifier of the QR Code transaction. | required |
| information | String | Reason/information for the chargeback. This is a descriptive text field to document why the chargeback is being requested. | required |
| amount | Decimal | Chargeback amount (must be greater than 0, with 2 decimal places). The amount can be equal to or less than the QR Code value. | required |
Request Examples
Full Chargeback:
POST /chargebacks-pix-copy-and-paste
Authorization: Bearer <access_token>
Content-Type: application/json
{
"qr_code_id": 12345,
"information": "Full refund - customer canceled order",
"amount": 100.00
}
Partial Chargeback:
POST /chargebacks-pix-copy-and-paste
Authorization: Bearer <access_token>
Content-Type: application/json
{
"qr_code_id": 12345,
"information": "Partial refund - returned 1 of 2 items",
"amount": 50.00
}
Response Details
{
"worked": true,
"id": 98765,
"end_to_end_id": "E6070119020210521123456789012345678",
"amount": 50.00,
"status": "PENDING",
"fee": 0.00
}
| Field | Type | Description |
|---|---|---|
| worked | Boolean | Always true for successful requests. |
| id | Integer | Unique chargeback identifier. This value can be used to query the chargeback status later. |
| end_to_end_id | String | End-to-End ID of the refund transaction. This identifier can be used for reconciliation purposes. May be empty for pending chargebacks. |
| amount | Decimal | The chargeback amount requested. |
| status | String | PENDING - Chargeback is being processed. The status should be consulted later using the Chargeback Status endpoint. SUCCESS - Chargeback successfully completed (typically for internal transfers). REJECTED - Chargeback was rejected. The refund could not be completed. |
| fee | Decimal | Transaction fee. Usually 0.00 for chargebacks. |
Error Responses
| HTTP Code | Error Message | Description |
|---|---|---|
| 400 | QR Code not found | The QR Code was not found or does not belong to your account. Verify the qr_code_id. |
| 400 | QR Code is not paid | The QR Code has not been paid yet. Only paid QR Codes (status PAID or CHARGEBACK) can be refunded. |
| 400 | There is a refund in processing | There is already a pending chargeback for this QR Code. Wait for the current chargeback to complete before creating a new one. |
| 400 | Amount is greater than the value of the QR Code | The chargeback amount exceeds the available balance. Check the original QR Code value and subtract any previous chargebacks. |
| 400 | Cannot process chargeback for closed account | The account associated with this QR Code is closed. Chargebacks cannot be processed for closed accounts. |
| 400 | [Bank error descriptor] | External chargeback failed. Error message from the payment processor. |
| 401 | Unauthorized | Invalid or missing authentication token. Ensure you are sending a valid Bearer token. |
| 422 | Validation error | Request validation failed. Ensure all required fields are present, amount is greater than 0 with 2 decimal places, and fields are in correct format. |
Business Rules
Authentication:
- Requires valid authentication token
- User must be authenticated
Validations:
- QR Code must exist and belong to your account
- QR Code status must be PAID or CHARGEBACK (already partially refunded)
- Cannot create chargeback if there's already a PENDING chargeback for this QR Code
- Amount must be greater than 0 with exactly 2 decimal places
- Amount cannot exceed the remaining refundable balance (QR Code value minus previous chargebacks)
- The associated account cannot be closed
- All required fields (qr_code_id, amount, information) must be provided
Chargeback Types:
- Full Chargeback: Amount equals the total value of the QR Code
- Partial Chargeback: Amount is less than the total value of the QR Code
- Multiple Chargebacks: Multiple partial chargebacks can be created as long as the sum does not exceed the original QR Code value
Processing:
- Internal Chargeback (same institution): May have synchronous processing with immediate
SUCCESSstatus - External Chargeback (other institutions): Asynchronous processing with
PENDINGstatus. Use the Chargeback Status endpoint to track completion - Cannot create a new chargeback while a previous one is still PENDING for the same QR Code