Cashout Webhook

Asynchronous payout status notification.

Endpoint

POST /callback_url

Authentication

Merchant Credential. See Authentication.

1. Notification Background

After a merchant initiates a Pix payout transaction, the final result may not be determinable in the synchronous request. Once the cashout order succeeds or fails, Adopay notifies the merchant of the final result through an HTTP asynchronous callback.

The merchant should process notifications idempotently based on platOrderNo or merchantOrderNo. The same order may receive multiple notifications due to retries.

2. Callback URL and Request Method

Adopay sends JSON notifications via POST to the cashout callback URL provided by the merchant, with Content-Type set to application/json. The callback URL must be a complete HTTP or HTTPS URL. For signature verification and success response requirements, see the Webhook Specification.

3. Request Header Fields

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

Both Digest and Authorization are computed over the raw JSON bytes actually sent. When verifying the signature, the merchant must not re-serialize the JSON first.

4. Request Body Fields

Business status: status is an integer; status = 200 indicates the business 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.
attach	string	128	Yes	The attach value passed by the merchant when the original cashout order was created; returned as-is if provided at order creation, empty otherwise.
merchantOrderNo	string	64	Yes	Merchant order number passed by the merchant when initiating the cashout.
platOrderNo	string	64	Yes	Adopay cashout platform order number.
orderStatus	string	16	Yes	cashout result: SUCCESS means the cashout succeeded, FAILED means the cashout failed.
e2eId	string	64	Yes	Bank E2E transaction number / external channel cashout reference number; may be empty when not 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 CNPJ.
fromName	string	128	Yes	Payer name.
toPix	string	64	Yes	Payee Pix Key; sensitive information.
toIspb	string	16	Yes	ISPB code of the receiving institution; may be empty when not available.
toIspbName	string	512	Yes	Name of the receiving institution; may be empty when not available.
toName	string	128	Yes	Payee name; sensitive information.
toCpfCnpj	string	64	Yes	Payee CPF/CNPJ; sensitive information.
payTime	int	19	Yes	cashout completion time, Unix timestamp in seconds; 0 when unavailable.
status	int	-	Yes	Response code
msg	string	128	Yes	Corresponds to status

Event and Status Mapping

event	orderStatus	Meaning
PIX_CASHOUT_SUCCESS	SUCCESS	cashout succeeded.
PIX_CASHOUT_ERROR	FAILED	cashout 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",
  "attach": "merchant-data-001",
  "merchantOrderNo": "CASHOUT202608170001",
  "platOrderNo": "APS202608170000000001",
  "orderStatus": "SUCCESS",
  "e2eId": "E0000000020260817000000000000002",
  "amount": 100,
  "receivedAmount": 100,
  "fee": 1.5,
  "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. Merchant Response Requirements

After completing idempotency processing, the merchant should return HTTP 200—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 Counts

Adopay sends a callback notification to the merchant when the cashout succeeds or fails.

After the first delivery attempt of a notification fails, Adopay retries at most 9 times, for a total of at most 10 delivery attempts. Once the merchant receives the notification successfully and returns the required success response, no further retries are made.

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

HTTP Status Code	Response Body	Result
200—299	Exactly SUCCESS or OK after trimming leading and trailing whitespace	Notification succeeded; no more retries
200—299	Empty body, JSON, other text, or casing other than the required one	Notification failed; retries continue
Not 2xx	Any content	Notification failed; retries continue
No HTTP response received	Network timeout or connection failure	Notification failed; retries continue

SUCCESS and OK are case-sensitive. For example, success, Success, or {"status":"SUCCESS"} will not be recognized as a success response. HTTP 204 is a 2xx status, but because the response body is empty, retries continue.

8. Integration Notes

1. Determine the transaction result from event together with orderStatus; do not rely on event alone to decide success or failure.
2. When a success notification is received, 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.