Merchant Creation Result Callback Notification

1. Notification Overview

After a primary merchant initiates a sub-merchant creation request, the creation result may not be determinable in the synchronous request. After the sub-merchant creation succeeds or fails, Adopay notifies the primary merchant of the final result via an HTTP callback.

Merchants should handle notification idempotency based on X-Merchant-Id, registrationNo, and createStatus, and use createStatus to determine the creation result. The same merchant creation request may receive multiple notifications due to retries.

2. Callback URL and Method

Item	Value
Method	POST
URL	{notifyUrl}
Content-Type	application/json
Purpose	Notify the final result of sub-merchant creation

{notifyUrl} is the merchant creation result callback URL provided by the primary merchant; it must be a full HTTP or HTTPS URL.

3. Request Headers

Field	Type	Required	Description
Content-Type	string	Yes	Fixed to application/json.
X-Merchant-Id	string	Yes	Primary merchant number that receives the notification.
X-Timestamp	string	Yes	Unix timestamp in seconds.
X-Nonce	string	Yes	Random string of this request, used for anti-replay.
Digest	string	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 final raw JSON bytes sent. Merchants must not re-serialize the JSON before verifying the signature.

4. Request Body Fields

Business status determination: status is an integer; status = 200 means the business succeeded, in which case msg = "sucesso". A non-200 value means a business error; see msg for the reason.

Field	Type	Length	Always Returned	Description
seqNo	string	64	Yes	Request sequence number. Corresponds to the seqNo of the creation endpoint.
subMerchantNo	string	64	Yes	Sub-merchant number; may be empty when creation failed or has not been generated yet.
subMerchantName	string	128	Yes	Sub-merchant name.
createStatus	string	16	Yes	Creation status: SUCCESS means created successfully, FAILED means creation failed.
errorMsg	string	128	No	Error message.
status	int	-	Yes	Response code
msg	string	128	Yes	Corresponds to status

Creation Status Description

createStatus	Meaning
SUCCESS	The sub-merchant was created successfully; subMerchantNo should return the created sub-merchant number.
FAILED	The sub-merchant creation failed; subMerchantNo may be empty.

5. Request Example

POST /notify/adopay/merchant/create 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",
  "seqNo":"1234234234234",
  "subMerchantNo": "92315566000200",
  "subMerchantName": "MERCHANT DEMO LTDA",
  "createStatus": "SUCCESS",
  "errorMsg": ""
}

6. Merchant Response Requirements

After completing idempotency processing, the merchant should return HTTP 200—299 with a response body strictly the plain text SUCCESS or OK:

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

SUCCESS

7. Notification Scenarios and Retry Counts

When the sub-merchant creation succeeds or fails, Adopay sends a callback notification to the primary merchant.

After the first delivery of each notification fails, it is retried at most 9 times, for a total of at most 10 deliveries. Once the merchant successfully receives the notification and returns the required success response, no more retries are made.

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

HTTP Status Code	Response Body	Result
200—299	Strictly equal to SUCCESS or OK after trimming surrounding whitespace	Notification succeeded, no more retries
200—299	Empty body, JSON, other text, or non-required casing	Notification failed, retry continues
Non-2xx	Any content	Notification failed, retry continues
No HTTP response	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 within 2xx, its response body is empty, so retries continue.

8. Integration Notes

1. It is recommended to implement idempotency using "primary merchant number + registration number + creation status" or an equivalent unique key; do not rely solely on the notification count to determine whether it is a duplicate.
2. When createStatus is SUCCESS, validate and save subMerchantNo; when it is FAILED, subMerchantNo may be empty.
3. Amounts are in the currency unit; handle monthlyTransactionAmount and averageOrderAmount with high-precision decimal types.
4. Merchant name, registration number, tax ID, website, and business information may contain sensitive or restricted information; store them masked in logs and audit systems according to data classification requirements.
5. Return the required success response only after signature verification, idempotency processing, and business data persistence have all succeeded, so that a wrongly acknowledged notification is not lost from retries.