Payout Refund Webhook

1. Background

A refund has occurred on the Adopay side; after Adopay completes processing the refund, it notifies the partner of the refund result.

The partner must process notifications idempotently by platOrderNo. The same order may be notified multiple times due to retries.

2. Callback Endpoint and Method

Item	Value
Method	POST
URL	{notifyUrl}
Content-Type	application/json
Purpose	Notify the PIX payout refund result

{notifyUrl} is the partner-provided payout callback URL; it must be a complete HTTP or HTTPS URL.

3. Request Headers

Field	Type	Length	Required	Description
Content-Type	string	16	Yes	Fixed to application/json.
X-Merchant-Id	string	64	Yes	Merchant ID that receives 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 actually sent. When verifying the signature, the partner must not re-serialize the JSON first.

4. Request Body Fields

Business status: status is an integer; status = 200 means the business call succeeded, 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.
subMerchantNo	string	64	No	Sub-merchant ID.
attach	string	128	Yes	This payout refund was not initiated by the merchant; the field comes from the original payout order corresponding to origPlatOrderNo, and is the attach value the partner submitted when calling the payout creation API. Returned as-is if it was submitted with the original payout order, 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 payout order number.
origPlatOrderNo	string	64	Yes	Original platform payout order number.
origAmount	decimal(25,2)	25,2	Yes	Original payout order amount.
origTotalRefundAmount	decimal(25,2)	25,2	Yes	As of the completion of this refund, the accumulated principal refunded for the original payout order, excluding fees.
origTotalFeeRefundAmount	decimal(25,2)	25,2	Yes	As of the completion of this refund, the accumulated fees refunded for the original payout order, excluding the refund principal.
refundAmount	decimal(25,2)	25,2	Yes	Principal amount successfully refunded in this request, excluding the fee; for the fee refunded, see feeRefundAmount.
feeRefundAmount	decimal(25,2)	25,2	Yes	Fee amount refunded in this request; 0 when no fee is refunded.
currency	string	3	Yes	Refund currency, identical to the original order's currency, for example BRL.
e2eId	string	64	No	PIX end-to-end transaction ID; may be empty when the channel has not returned it.
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	Message corresponding to status

Event and Status Mapping

event	orderStatus	Meaning
PIX_CASHOUT_REFUND	SUCCESS	Refund succeeded.

5. Request Example

The following example shows a first refund on the original order: principal 200.00 and fee 2.50 refunded in this request; accumulated refund principal on the original order 200.00; accumulated refunded fees 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",
  "subMerchantNo": "SUB10000000001",
  "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. Partner Response Requirements

After completing idempotent processing, the partner should return HTTP 200—299 with a response body of exactly the plain text SUCCESS or OK:

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

SUCCESS

7. Notification Scenarios and Retries

When a payout refund succeeds, Adopay sends a callback notification to the partner.

After the first delivery attempt of a notification fails, Adopay retries at most 9 times, for at most 10 deliveries in total. Once the partner receives the notification successfully and returns the required success response, no further retries occur.

Whether to retry is determined jointly by the HTTP status code and the response body:

HTTP Status Code	Response Body	Result
200—299	Strictly equal to SUCCESS or OK after trimming leading and trailing whitespace	Notification delivered; no more retries
200—299	Empty body, JSON, other text, or wrong 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 is a 2xx status, its body is empty, so retries continue.

8. Integration Notes

1. Determine the transaction result from event together with orderStatus; do not rely on event alone to judge success or failure.