Cashin Webhook

Asynchronous payment status notification.

Endpoint

POST /merchant-callback-url

Authentication

Merchant Credential. See Authentication.

1. Notification Background

After a merchant initiates a cashin transaction, the final result may not be determinable in the synchronous request. When the cashin succeeds, Adopay notifies the merchant of the successful result through an HTTP asynchronous callback; no callback notification is sent when the cashin fails.

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 cashin 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	Variable	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 cashin order was created; returned as-is if provided at order creation, empty otherwise.
merchantOrderNo	string	64	Yes	Merchant order number passed by the merchant at order creation.
platOrderNo	string	64	Yes	Adopay cashin platform order number.
orderStatus	string	16	Yes	Order result, fixed to SUCCESS, meaning the cashin succeeded.
amount	decimal	25,2	Yes	Merchant order amount; the merchant should verify this field.
payAmount	decimal	25,2	Yes	Actual paid amount.
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 number; may be empty when not generated.
payerName	string	128	No	Payer name; usually returned on success.
payerTaxNo	string	64	No	Payer tax ID (CPF/CNPJ); usually returned on success.
status	int	-	Yes	Response code
msg	string	128	Yes	Corresponds to status

Event and Status Mapping

event	orderStatus	Meaning
QR_CODE_COPY_AND_PASTE_PAID	SUCCESS	Pix QR code cashin / acquiring — cashin 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",
  "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. 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 this callback notification only when the cashin succeeds. No callback is sent when the cashin fails; for refund notifications, see the cashin Refund Webhook.

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