Request and Response

Request Method

All requests use the POST method.

Request Headers

All APIs must include the following fields in the request headers:

Field Name	Type	Required	Description
content-type	string	Yes	application/json
x-api-key	string	Yes	Provided by Paydify, same as appId
x-api-timestamp	string	Yes	Timestamp in milliseconds
x-api-signature	string	Yes	Signature, see Signature Algorithm

Calling on Behalf of Sub-merchants (Partner Credentials)

x-api-key identifies the calling credential. With a merchant-owned credential, requests always operate on that merchant itself and no extra fields are needed.

A partner credential can operate on behalf of the sub-merchants authorized to it. In that case, pass the following fields in the request body of business APIs:

Field Name	Type	Required	Description
merchantId	string	Conditional	ID of the sub-merchant the order belongs to. Required for partner credentials; can be omitted with a merchant-owned credential (defaults to the credential owner)
merchantAppId	string	Conditional	App ID under the owner merchant — a different value from the caller credential appId carried in x-api-key. Required only when the credential covers multiple apps of that merchant; a single authorized app is resolved automatically

Requests referencing a merchant that is not authorized to the credential are rejected. Related error codes: MERCHANT_ID_REQUIRED, MERCHANT_APP_ID_REQUIRED, MERCHANT_GRANT_INVALID, MERCHANT_STATE_INVALID, see Error Codes.

Response Headers

All APIs will include the following fields in the response headers:

Field Name	Type	Required	Description
x-api-key	string	Yes	Provided by Paydify, same as appId
x-api-timestamp	string	Yes	Timestamp in milliseconds
x-api-signature	string	Yes	Signature, see Signature Algorithm

Response Format

All API responses follow this data structure:

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": {},
  "success": true
}

Response Field Descriptions

Field Name	Type	Description
code	string	Response code, SYS_SUCCESS indicates success
message	string	Response message
messageDetail	string	Detailed response message
data	object	Business data
success	boolean	Whether the request was successful