AlipayHKAlipayHKDOCS

Gift Card

POST /api/open/alipay/v1/merchant/order/sync

Use this interface to issue a gift card for the user.


General Headers

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

Encrypt

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_AES,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

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

Tracer-Id

An ID for tracing this request.

String

abcdefg135202000000000263818

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"

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

Tracer-Id

An ID for tracing this request.

String

abcdefg135202000000000263818



Request parameters

requestId string  REQUIRED

An unique request ID (uuid) to identify this API request.

merchantBizNo string  REQUIRED

Order ID of your system.

Must be consistent, we use this to reference the same order.

orderStatus string  REQUIRED

Status of the order.


Order Status

Description

Card Wallet Display

TICKETED

When the gift card is issued.

Issue gift card in Card Wallet.

image.png


Please refer to each business scenario.

userId string  

ID of AlipayHK user.

REQUIRED to provide either one openId or userId.

openId string  

Authorization ID of AlipayHK user for merchant.

REQUIRED to provide either one openId or userId.

merchantBizType string  REQUIRED

Type of order service.

  • ALIPAY_COUPON: Gift card.

orderCreateTime number  REQUIRED

Creation timestamp of first business event occurrence timestamp, should be consistent.

orderModifyTime number  REQUIRED

Business event occurrence timestamp, used for sequential control of order status or rapidly changing data to prevent disorder, should be new for each update.

merchantId string  

Secondary merchant ID provided by AlipayHK after contract signed.

Provide when you are not the direct merchant (i.e. ISV)

tinyAppId string  

ID of the miniprogram.

tradeNo string  

The transaction number provided by Alipay.

amount object  

The original amount of this order.

Show child parameters

payAmount object  

The actual amount user paid for this order.

Show child parameters

extInfo object  REQUIRED

Show child parameters

Response parameters

result object  REQUIRED

Result of response

Show child parameters

orderId string  REQUIRED

The order ID from AlipayHK

orderStatus string  REQUIRED

Refer 'Order Status' tab above.

distributeResult Array<OrderDataDistributeInfo>  REQUIRED

Business result

Show child parameters
API Explorer

Request

Case
Gift Card
Request Body

Response

Response Body

Result/Error codes

CodeValueMessageFurther action
SUCCESSSsuccess

success

PARAM_ILLEGALFRequest is invalid, usually missing parameters.
ORDER_STATUS_INVALIDFThe order status is illegal. The status is not matched or the state machine does not support changes to this status
UNKNOWN_EXCEPTIONUUnknown error. Merchants can try later first & contact with AlipayHK
UN_SUPPORT_BUSINESSFThe service is not supported. eg: The merchant is not onboard & the API is offline