API Structure (v1)

2024-08-26 07:29

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

1. Request

1.1 HTTP Body Structure

copy
{
  "request": {
    "head": {
      headers
    },
    "body": {
      body
    }
  },
  "signature": signature
}

1.2 Basic Headers

Request headers should be included in the HTTP body instead of the HTTP 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
clientId required	An ID provided by AlipayHK, used to identify partner and application system.	String	"4Q5Y8W0WSG45P907917"
function required	The API interface specifications of this request.	String	"alipay.intl.oauth.auth.prepareForRedirect"
reqMsgId required	An unique request ID (uuid) to identify this API request.	String max: 64	"d1c221e1-5993-4162-bdbf-f06f33389472"
reserve required	A reserved field.	String	"{}"
version required	API version as per the respective API reference.	String	"2.0.0"

Request-only Headers

Name

Description

Type

Sample

reqTime

required

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

String

"2024-06-13T10:33:41+08:00"

Example

copy
{
  "request": {
    "head": {
      "clientId": "4Q5Y38882Y0QQKABCDE",
      "function": "alipay.intl.oauth.auth.prepareForRedirect",
      "reserve": "{}",
      "reqTime": "2024-06-13T10:33:41+08:00",
      "version": "2.0.0",
      "reqMsgId": "2f864a23-ddc6-40ec-8c8c-e007922baf85"
    },
    "body": {
      "authMerchantId": "2160120012345678",
      "authSite": "ALIPAY_HK",
      "merchantRedirectUrl": "https://www.alipayhk.com",
      "scopes": [
        "USER_POINTS"
      ],
      "terminalType": "WAP"
    }
  },
  "signature": "kaOjnulViGIEJKtjVimspOVgM9zI%2FNhmpgdA3ffiUwggROdOw%2FwkcBpWvXIR1K3a3zO1hleY9TwF%2B1QJohe29QUHWGFqxnMKiWhzgsW70w0Ug46D%2BxzxWTaAsadlZjatMCzNph0K%2F0i6xm1t5ACUOvBS4x7BINIBz%2B%2FnF5RYaacwk38rludlLMjLjfyYZjp35dak7vvC5J7lQnkiAxi8n40Ku6n3I%2BzqMqzNANeO%2FuwYTQjzcudKfKhU4EddoJ4%2FCIfNoN3vzx0tVIkoQ%2BnNc2El%2BR5%2F0%2BeP0MnScpnEmd7ljguf%2BNbcTcVcXwQxZtsXHMxwiONIac7FesKyhM%2FBEQ%3D%3D"
}

2. Response

2.1 HTTP Body Structure

copy
{
  "response": {
    "head": {
      headers
    },
    "body": {
      body
    }
  },
  "signature": signature
}

2.2 Basic Headers

Response headers are included in the HTTP body instead of the HTTP headers.

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

Response-only Headers

Name

Description

Type

Sample

respTime

required

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

String

"2024-06-13T10:33:41+08:00"

2.3 Basic Body

Name

Description

Type

Sample

resultInfo

required

A metadata object indicates the result of the request.

ResultInfo

See example below.

ResultInfo

Name	Description	Type	Sample
resultStatus required	The status of this request.	String	"S"
resultCode required	The result code of this request, used for troubleshooting.	String	"SUCCESS"
resultCodeId required	The result code ID of this request, used for troubleshooting.	String	"00000000"
resultMsg	A description message of the result.	String	"success"

Example

copy
{
  "response": {
    "head": {
      "clientId":"4Q5Y8W0WSG45P907917",
      "function":"alipay.intl.oauth.auth.prepareForRedirect",
      "respTime":"2024-06-13T10:33:41+08:00",
      "version":"2.0.0",
      "reqMsgId":"d1c221e1-5993-4162-bdbf-f06f33389472"
    },
    "body": {
      "resultInfo":{
        "resultStatus":"S",
        "resultCode":"SUCCESS",
        "resultCodeId":"00000000",
        "resultMsg":"result message"
      }
    }
  },
  "signature": "Cse89XBt5BWTASVXs1AKDcAdUSOemhZ15c%2FA5spTtxsAqPNyk2s95zNFvpprDdI6OFgrFo4GoSukD2rAnO4cNCBF8REJvruVnwkFAY35v8F7nHVkWKSC6Ei4mVnqMFK9CtB0LR%2Fvi2QuEafrighfAsaI6t8QvBWSnOFQvrfdSvWXJOeXbqZ3WkVvsyG6VeMwM6WO%2Fvi4C3TOJoZppsv5GjK5cTC0iRjf4rntDKVK%2FT1mtZaGLmzPtYp6hbqzGeDwp3e0hMcp3JzjpKh46i17nITh4KyEC3mWGFHFS%2FACrVRENgKxcXcuO5ez%2FIBAbcfYh6Vg61rXeVH1Z%2FpJoW%2Fq4Q%3D%3D"
}