Payment Refund Result Callback Notification to Merchant

1. Notification Background

After Adopay processes a payment refund and completes it, Adopay notifies the merchant of the refund result via an HTTP asynchronous callback.

Merchants should handle notifications idempotently based on platOrderNo. The same order may receive multiple notifications due to retries.

2. Callback URL and Request Method

Item	Content
Request method	POST
Request URL	{notifyUrl}
Content-Type	application/json
Purpose	Notify the Pix cashout refund result

{notifyUrl} is the payment callback URL provided by the merchant and must be a complete HTTP or HTTPS URL.

3. Request Header Fields

Field	Type	Length	Required	Description
Content-Type	string	16	Yes	Fixed as application/json.
X-Merchant-Id	string	64	Yes	Merchant number receiving the notification.
X-Timestamp	string	19	Yes	Unix timestamp in seconds.
X-Nonce	string	64	Yes	Random string for this request, used for anti-replay.
Digest	string	52	Yes	Digest of the raw request body, in the format SHA-256=<Base64(SHA256(body_bytes))>.
Authorization	string	-	Yes	ES256 HTTP Signature information.

Both Digest and Authorization are computed over the raw JSON bytes that are finally sent. Merchants must not re-serialize the JSON before performing signature verification.

4. Request Body Fields

Business status: status is an integer; status = 200 indicates business success, in which case msg = "sucesso". Any value other than 200 indicates a business error; see msg for the reason.

Field	Type	Length	Returned	Description
event	string	64	Yes	See the event enum below.
attach	string	128	Yes	This cashout refund was not initiated by the merchant; the field is taken from the original payment order corresponding to origPlatOrderNo and equals the attach value passed when the merchant called the payment order creation API. It is returned as-is if it was provided when the original payment order was created, and is empty otherwise.
merchantOrderNo	string	64	Yes	Merchant refund order number of this refund.
platOrderNo	string	64	Yes	Platform refund order number of this refund.
origMerchantOrderNo	string	64	Yes	Original merchant payment order number.
origPlatOrderNo	string	64	Yes	Original platform payment order number.
origAmount	decimal(25,2)	25,2	Yes	Original payment order amount.
origTotalRefundAmount	decimal(25,2)	25,2	Yes	As of the completion of this refund, the cumulative principal amount refunded on the original cashout order, excluding fees.
origTotalFeeRefundAmount	decimal(25,2)	25,2	Yes	As of the completion of this refund, the cumulative fee amount refunded on the original cashout order, excluding the refund principal.
refundAmount	decimal(25,2)	25,2	Yes	Principal amount successfully refunded this time, excluding fees; see feeRefundAmount for the fee refunded this time.
feeRefundAmount	decimal(25,2)	25,2	Yes	Fee amount refunded this time; 0 when no fee is refunded.
currency	string	3	Yes	Refund currency, identical to the original order currency, e.g. BRL.
e2eId	string	64	No	Pix end-to-end transaction ID; may be empty when the channel has not returned it yet.
refundTime	int	19	No	Refund time, Unix timestamp in seconds.
orderStatus	string	16	Yes	Current status of the refund order.
status	int	-	Yes	Response code
msg	string	128	Yes	Corresponds to status

Event and Status Mapping

event	orderStatus	Meaning
PIX_CASHOUT_REFUND	SUCCESS	Refund successful.

5. Request Example

The following example shows the first refund of the original order: this refund returns principal 200.00 and fee 2.50; the cumulative refunded principal on the original order is 200.00, and the cumulative refunded fee is 2.50.

POST /notify/adopay/cashout HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1786838460
X-Nonce: 4de901987ca14b25acf2639056ac6002
Digest: SHA-256=<REQUEST_BODY_SHA256_BASE64>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

{
  "status": 200,
  "msg": "sucesso",
  "event": "PIX_CASHOUT_REFUND",
  "attach": "merchant-data-001",
  "merchantOrderNo": "MR20260825000001",
  "platOrderNo": "PR20260825000001",
  "origMerchantOrderNo": "MO20260824000001",
  "origPlatOrderNo": "PO20260824000001",
  "origAmount": 1000.00,
  "origTotalRefundAmount": 200.00,
  "origTotalFeeRefundAmount": 2.50,
  "refundAmount": 200.00,
  "feeRefundAmount": 2.50,
  "currency": "BRL",
  "e2eId": "D1234567820260825123456789012345",
  "refundTime": 1786887025,
  "orderStatus": "SUCCESS"
}

6. Merchant Response Requirements

After completing idempotent processing, the merchant should return HTTP 200 to 299 with a response body that is strictly the plain text SUCCESS or OK:

HTTP/1.1 200 OK
Content-Type: text/plain

SUCCESS

7. Notification Scenarios and Retry Count

When a payment refund succeeds, Adopay sends a callback notification to the merchant.

If the first delivery of a notification fails, it is retried at most 9 times, for at most 10 deliveries in total. Once the merchant successfully receives the notification and returns the required success response, no more retries are made.

HTTP Status Code	Response Body	Result
200 to 299	Strictly equals SUCCESS or OK after trimming leading and trailing whitespace	Notification successful, no more retries
200 to 299	Empty body, JSON, other text, or non-standard casing	Notification failed, retry continues
Non-2xx	Any content	Notification failed, retry continues
No HTTP response received	Network timeout or connection failure	Notification failed, retry continues

SUCCESS and OK are case-sensitive. For example, success, Success, or {"status":"SUCCESS"} are not recognized as success responses. Although HTTP 204 belongs to 2xx, its response body is empty, so retries continue.

8. Integration Notes

1. It is recommended to determine the transaction result from event and orderStatus; do not rely on event alone to determine success or failure.
2. Upon receiving a successful notification, re-verify refundAmount, feeRefundAmount, the currency, and the original order information.