Request a Chargeback by Cash In Transaction

Requests a full or partial refund of a PIX cash in you received. The refund is processed asynchronously and its progress can be followed through the chargeback status endpoint.

POSThttps://api.saq.digital/v2/finance/chargeback

curl --request POST \
  --url 'https://api.saq.digital/v2/finance/chargeback' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'hmac: <HMAC_SIGNATURE>' \
  --header 'Content-Type: application/json' \
  --data '{
  "transaction_id": 987654,
  "information": "Order cancelled by the customer",
  "amount": 100.5
}'

Response200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "end_to_end_id": "E12345678202604251234567890AB12345",
  "amount": 100.5,
  "status": "PENDING"
}

Endpoint

POST /v2/finance/chargeback

Headers

Parameter	Type	Description	Example
Authorization	String	Bearer + Access_token	Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo
hmac	String	HMAC (Hash-based Message Authentication Code) is an authentication algorithm that combines a private key with a message to create a Message Authentication Code (MAC).	hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b99f4081ff231b87f82118c1e77a959e1f40eacf690a8fa61a827a9ba01d546f6

Body Details

{
  "transaction_id": 987654,
  "information": "Order cancelled by the customer",
  "amount": 100.50
}

Field	Type	Description	Required or Optional
transaction_id	Integer	Identifier of the PIX cash in to be refunded. This is the `id` returned by the Find a PIX Cash In by EndToEndId endpoint.	required
information	String	Reason or description of the refund. This text is sent along with the refund and is useful for your own reconciliation.	required
amount	Decimal	Amount to be refunded, with up to 2 decimal places. Must be greater than 0 and can be lower than the original amount for partial refunds.	required

Request Examples

Full refund:

POST /v2/finance/chargeback
Authorization: Bearer <access_token>
hmac: <computed_hmac>
Content-Type: application/json

{
  "transaction_id": 987654,
  "information": "Order cancelled by the customer",
  "amount": 100.50
}

Partial refund:

POST /v2/finance/chargeback
Authorization: Bearer <access_token>
hmac: <computed_hmac>
Content-Type: application/json

{
  "transaction_id": 987654,
  "information": "Partial cancellation - one item returned",
  "amount": 40.00
}

Response Details

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "end_to_end_id": "E12345678202604251234567890AB12345",
  "amount": 100.50,
  "status": "PENDING"
}

Field	Type	Description
id	String	Unique identifier of the chargeback request (UUID). Use this value to check the chargeback status.
end_to_end_id	String	EndToEndId of the refund operation. Returned as an empty string while the refund has not been assigned one yet.
amount	Float	Amount being refunded.
status	String	Current status of the chargeback request. See the Chargeback Status table below.

Chargeback Status

Status	Description
PENDING	The refund was accepted and is being settled. This is the initial status when the payer is at another institution.
SUCCESS	The refund was completed and the funds were returned to the payer. Refunds to payers in the same institution are settled immediately and already come back as `SUCCESS`.
REJECTED	The refund could not be completed.

Error Responses

HTTP Code	Error Message	Description
400	Transaction not found	No PIX cash in was found for the informed `transaction_id`, or it is not available for the account you can access.
400	Chargeback period (90 days) has expired	The original cash in is older than 90 days and can no longer be refunded.
400	Cannot process chargeback for closed account	The account that received the original cash in is closed.
400	Cannot process chargeback for closed destination account	The payer's account is closed and cannot receive the refund.
400	Destination account in the process of closing cannot receive chargeback	The payer's account is being closed and cannot receive the refund.
400	There is a refund in processing	Another refund for this same cash in is still being processed. Wait for it to finish before requesting a new one.
400	Amount is greater than the value of transaction	The requested amount, added to what has already been refunded, exceeds the original cash in amount.
400	Amount is greater than the value of the QR Code	For payments received through a QR Code, the requested amount, added to what has already been refunded, exceeds the QR Code amount.
400	Insufficient balance	The account does not have enough balance to cover the refund.
400	QR Code not found	The QR Code linked to this cash in could not be found.
400	QR Code is not paid	The QR Code linked to this cash in is not in a refundable state.
400	Transaction Cashout not found	The counterpart transaction of the original cash in could not be found.
400	Chargeback failed	The refund could not be completed.
400	HMAC header required for API audience	The `hmac` header was not sent.
400	HMAC invalid	The `hmac` header does not match the request body. Recompute the signature over the exact JSON body being sent.
400	Company not have hmac key	No HMAC key is configured for your credentials. Contact support.
400	Company not found	Your credentials are not linked to an active registration.
400	field: message	Request validation failed. The detail names the offending field, e.g. `amount: Input should be greater than 0`.
400	provider message	The refund was refused by the payment system. The detail carries the message returned by it.
401	Not authenticated	Missing, malformed or expired Bearer token.

All errors are returned in the standard error envelope:

{
  "worked": false,
  "detail": "There is a refund in processing",
  "message": "There is a refund in processing",
  "data": null
}

Business Rules

Validations:

amount must be greater than 0 and have at most 2 decimal places
transaction_id must reference a PIX cash in you received; transfers you sent cannot be refunded through this endpoint
The sum of all refunds made for the same cash in cannot exceed the original amount
For cash ins received through a PIX QR Code, the QR Code must have been paid (it stays refundable after a previous partial refund) and the sum of all refunds cannot exceed the QR Code amount
Only one refund can be in processing at a time for the same cash in
The account must have enough available balance at the moment of the request

Limits:

A cash in can only be refunded within 90 days of the date it was received

Important Notes:

Partial refunds are supported: send an amount lower than the original value and repeat the request as many times as needed, respecting the original amount
When the payer is at another institution the response comes back as PENDING and the refund is settled asynchronously
When the payer is in the same institution the refund is settled right away and the response already comes back as SUCCESS
Use the Check PIX Cash In Chargeback Status endpoint with the returned id to follow the outcome
The end_to_end_id may come back as an empty string in this response and be filled in later, once the refund is assigned one

curl --request POST \
  --url 'https://api.saq.digital/v2/finance/chargeback' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'hmac: <HMAC_SIGNATURE>' \
  --header 'Content-Type: application/json' \
  --data '{
  "transaction_id": 987654,
  "information": "Order cancelled by the customer",
  "amount": 100.5
}'

Response200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "end_to_end_id": "E12345678202604251234567890AB12345",
  "amount": 100.5,
  "status": "PENDING"
}