AlipayHKAlipayHKDOCS

API fundamentals

AlipayHK adopts API standards along with digital signature and data encryption, please check below information for the API structure.

1. Request

image

1.1 Basic Headers

General Headers

Below basic headers apply on both request and response, for headers information specific to request, please check the document of specific request.

Name

Description

Type

Sample

Client-Id

required

An ID provided by AlipayHK, used to identify partner and application system.

String

4Q5Y8W0WSG45P907917

Content-Type
required

The RFC 2616 media type of the request body, the charset should be as same as the one used for cryptographic operations. 

String

application/json; charset=UTF-8

Signature
required

A key-value pairs string separated by commas (,), which keys and values are joined by equal signs (key=value). 

Valid keys include: 

  • algorithm: The digital signature algorithm used in generating the signature, RSA256 or ECC224, uses RSA256 by default. 
  • keyVersion: The key version of the signing key configured with Client-Id, uses the latest version by default. 
  • signature: The signature value of this request. 

String

algorithm=RSA256, keyVersion=1, signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGR rWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrT pMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3Jr bRFvcowQwt0lP1XkoPmSLGpBevDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD% 2FFYDAwSd%2B6%2FEOFo9UbdlKcmodJwjKlQoxZZIzmF8w%3D%3D

Agent-Token

An authorized token of current client obtained with AlipayHK.

String

Encrypt

conditional

required when message content needs to be encrypted. 

A key-value pairs string separated by commas (,), which keys and values are joined by equal signs (key=value). 

Valid keys include: 

  • algorithm: The symmetric key algorithm used in encryptingthe signature, only RSA_AES is supported. 
  • keyVersion: The key version of the signing key configured with Client-Id, uses the latest version by default.
  • symmetricKey: The encrypted symmetric key.

String

algorithm=RSA, keyVersion=1, symmetricKey=bqS8HSmdaRrpKSuPy7CqUlyd8lJurG93

Request-only Headers

Name

Description

Type

Sample

Request-Time

required

The ISO-8601 datetime of this API request with timezone.

String

2024-05-22T06:42:21+05:30

1.2 Basic Body

URL Encoding

For URL data, perform URL encoding first before transmitting.

Example:

Before

After

https://www.merchant.com/authorizationResult

https%3A%2F%2Fwww.merchant.com%2FauthorizationResult

2. Response

image

2.1 Basic Headers

Please refer to the request basic headers for the general basic headers.

Response-only Headers

Name

Description

Type

Sample

Response-Time
required

The ISO-8601 datetime of this API response with timezone.

String

2024-05-22T06:42:21+05:30

TracerId

required

An unique system id for tracing.

String

645864f51556420636666454470556

2.2 Basic Body

Name

Description

Type

Sample

result
required

A metadata object indicates the result of the request.

Result

See example below.

Result

Name

Description

Type

Sample

resultCode

required

The status code of this result, used for troubleshooting.

String

"SUCCESS"

resultStatus

required

The status of this request.

String

"S"

resultMessage

A description message of the result.

String

"success"

Example

copy
{ 
    "resultStatus": "S", 
    "resultCode":"SUCCESS", 
    "resultMsg": "success"
}