Cashin Webhook

1. Background

After the partner initiates a cashin transaction, the final result may not be determinable within the synchronous request. When the payment succeeds, Adopay notifies the partner of the successful result via an HTTP asynchronous callback; no callback is sent for failed payments.

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 PIX cashin payment success result

{notifyUrl} is the partner-provided cashin 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	Variable	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 cashin order.
attach	string	128	Yes	attach value the partner submitted when placing the original payment order; returned as-is if it was submitted, empty otherwise.
merchantOrderNo	string	64	Yes	Merchant order number the partner submitted when placing the order.
platOrderNo	string	64	Yes	Adopay cashin platform order number.
orderStatus	string	16	Yes	Order result, fixed to SUCCESS, meaning the payment succeeded.
amount	decimal	25,2	Yes	Merchant order amount; the partner should validate this field.
payAmount	decimal	25,2	Yes	Amount actually paid.
fee	decimal	25,2	Yes	Fee.
payTime	int	19	Yes	Payment completion time, Unix timestamp in seconds; 0 when unavailable.
e2eId	string	64	Yes	Bank E2E transaction number / external channel payment reference; may be empty when not yet generated.
payerName	string	128	No	Payer's name, usually returned on success.
payerTaxNo	string	64	No	Payer's tax ID (CPF/CNPJ), usually returned on success.
status	int	-	Yes	Response code
msg	string	128	Yes	Message corresponding to status

Event and Status Mapping

event	orderStatus	Meaning
QR_CODE_COPY_AND_PASTE_PAID	SUCCESS	PIX QR code cashin/acquiring — payment succeeded.

5. Request Example

POST /notify/adopay/cashin HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1786838400
X-Nonce: 8f6e17d07f8b4fe19318d9c4dd6fc001
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": "QR_CODE_COPY_AND_PASTE_PAID",
  "subMerchantNo": "SUB00000001",
  "attach": "order-source=checkout",
  "merchantOrderNo": "CASHIN202608170001",
  "platOrderNo": "BAS202608170000000001",
  "orderStatus": "SUCCESS",
  "amount": 100.25,
  "payAmount": 100.25,
  "fee": 1.25,
  "payTime": 1786838400,
  "e2eId": "E0000000020260817000000000000001",
  "payerName": "JOAO DA SILVA",
  "payerTaxNo": "12345678901"
}

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

Adopay sends this callback notification only when the payment succeeds. Failed payments do not trigger a callback; for refund notifications see Refund Webhook.

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. Validate that event is QR_CODE_COPY_AND_PASTE_PAID and orderStatus is SUCCESS.
2. When a success notification arrives, re-verify amount.
3. payerName and payerTaxNo are sensitive information and should be stored masked in logs and audit systems.