PIX Out Webhook

1. Background

After the partner initiates a PIX payout transaction, the final result may not be determinable within the synchronous request. Once the payout order succeeds or fails, Adopay notifies the partner of the final result via an HTTP asynchronous callback.

The partner must process notifications idempotently by platOrderNo or merchantOrderNo. 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 final PIX payout 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	Yes	Sub-merchant ID that owns this payout order.
attach	string	128	Yes	attach value the partner submitted when placing the original payout order; returned as-is if it was submitted, empty otherwise.
merchantOrderNo	string	64	Yes	Merchant order number the partner submitted when initiating the payout.
platOrderNo	string	64	Yes	Adopay payout platform order number.
orderStatus	string	16	Yes	Payout result: SUCCESS means the payout succeeded, FAILED means the payout failed.
e2eId	string	64	Yes	Bank E2E transaction number / external channel payout reference; may be empty when not yet generated.
amount	decimal	25,2	Yes	Merchant order amount.
receivedAmount	decimal	25,2	Yes	Amount actually credited to the payee.
fee	decimal	25,2	Yes	Merchant fee; 0 on failure.
fromIspb	string	16	Yes	ISPB code of the paying institution.
fromIspbName	string	512	Yes	Name of the paying institution.
fromCnpj	string	64	Yes	Payer's CNPJ.
fromName	string	128	Yes	Payer's name.
toPix	string	64	Yes	Payee's Pix key; sensitive information.
toIspb	string	16	Yes	ISPB code of the receiving institution; may be empty when unavailable.
toIspbName	string	512	Yes	Name of the receiving institution; may be empty when unavailable.
toName	string	128	Yes	Payee's name; sensitive information.
toCpfCnpj	string	64	Yes	Payee's CPF/CNPJ; sensitive information.
payTime	int	19	Yes	Payout completion time, Unix timestamp in seconds; 0 when unavailable.
status	int	-	Yes	Response code
msg	string	128	Yes	Message corresponding to status

Event and Status Mapping

event	orderStatus	Meaning
PIX_CASHOUT_SUCCESS	SUCCESS	Payout succeeded.
PIX_CASHOUT_ERROR	FAILED	Payout failed.

5. Request Example

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_SUCCESS",
  "subMerchantNo": "SUBMERCHANT0001",
  "attach": "merchant-data-001",
  "merchantOrderNo": "CASHOUT202608170001",
  "platOrderNo": "APS202608170000000001",
  "orderStatus": "SUCCESS",
  "e2eId": "E0000000020260817000000000000002",
  "amount": 100.00,
  "receivedAmount": 100.00,
  "fee": 1.50,
  "fromIspb": "87654321",
  "fromIspbName": "ADOX INSTITUICAO DE PAGAMENTO LTDA",
  "fromCnpj": "12345678000195",
  "fromName": "",
  "toPix": "maria.oliveira@example.com",
  "toIspb": "60701190",
  "toIspbName": "ITAÚ UNIBANCO S.A.",
  "toName": "MARIA OLIVEIRA",
  "toCpfCnpj": "12345678901",
  "payTime": 1786838460
}

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 the payout succeeds or fails, 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.
2. When a success notification arrives, re-verify amount, the payee, and the Pix key.
3. toPix, toName, fromCnpj, and toCpfCnpj are sensitive information and should be stored masked in logs and audit systems.