Alipay+ Super App PlatformAlipay+ Super App Platform

externalInfoSync

POST /amsin/commercial/certificate/accept

The externalInfoSync API is utilized by merchants or ISVs (independent software vendors) to synchronize external information, such as transaction details, which is essential for commission fee calculations with ASAP.

Structure

API requests and responses consist of two parts: the header and the body. Refer to the following sections for detailed information.

Request header

The request header mainly contains the following fields:

Note: Field names are case-insensitive.

Field name

Data type

Required

Description

Code sample

Client-Id

String

Yes

A unique ID to identify a client and is associated with the keys that are used for the signature.

Client-Id: 211020000000000000044

Signature

String

Yes

Signature contains key-value pairs that are separated by commas (,). Each key-value pair is an equation, which is a key joined with its value by an equal sign (=).

Signature: algorithm=sha256withrsa,keyVersion=2,signature=****

Request-Time

String

Yes

The time when the request is sent.

Request-Time: 2019-10-22T01:19:50+08:00

Content-Type

String

Yes

The media type of the request body.

Content-Type: application/json; charset=UTF-8

Request Body

The request body mainly contains the following fields:

Field name

Data type

Required

Description

merchantId

String

Yes

The merchant ID registered on the acquirer side.

merchantName

String

No

The merchant name registered on the acquirer side.

merchantCategory

String

No

The category of the merchant based on industry-standard classifications, not those defined by ASAP.

subMerchantId

String

No

The sub-merchant ID registered on the acquirer side.

subMerchantName

String

No

The sub-merchant name registered on the acquirer side.

subMerchantCategory

String

No

The category of the sub-merchant based on industry-standard classifications, not those defined by ASAP.

storeId

String

No

The unique ID for the store.

storeName

String

No

The name of the store.

storeCategory

String

No

The category of the store based on industry-standard classifications, not those defined by ASAP.

requestId

String

Yes

The unique ID for a request.

This field serves as an API idempotency key. When the value of transType is transaction, you are recommended to specify the value of outTransId as the requestId.

outTransId

String

Yes

The unique ID of the transaction assigned by the merchant or ISV's system. The system will record this value in transaction details for reconciliation and auditing purposes.

transId

String

No

The unique ID of a transaction assigned by AlipayHK.

entityId

String

No

The unique identifier for an entity.

  • If the value of entityType is userId, the entity ID is the user ID.
  • If the value of entityType is phone, the entity ID is the user's phone number.
  • If the value of entityType is email, the entity ID is the user's email address.

entityType

String

Yes

The type of identifier for an entity.

Valid values are:

  • userId: The unique ID of a user.
  • phone: The user's phone number.
  • email: The user's email address.

originTransId

String

No

If the value of transDirection is pay, leave this field empty.

If the value of transDirection is refund, assign the corresponding payment transaction's outTransId to this field.

transType

String

Yes

The type of the transaction. Specify this parameter as transaction.

transStatus

String

No

The status of the transaction. Specify this parameter as SUCCESS.

transDirection

String

No

The flow direction of funds in a transaction process. Defaults to pay if not specified.

Valid values are:

  • pay: Funds flow from the customer to the merchant, typically representing a purchase or payment.
  • refund: Funds are returned to the customer by the merchant, typically associated with refunds.

transDate

String

Yes

The time when the transaction occurs.

The value follows the ISO 8601 standard format. For example, 2025-11-27T12:01:01+08:00.

tradeAmt

price

No

The amount of the transaction.

extendInfo

extendInfo

No

The extended information.

Data Model

extendInfo

Field name

Data type

Required

Description

goodsInfoList

goodsInfo

No

The list of goods information. A maximum of 10 items of goods information can be specified in the list.

goodsInfo

Field name

Data type

Required

Description

goodsId

String

No

A unique ID assigned by ASAP for specific goods.

goodsCode

String

Yes

A code representing the type of goods. Valid values are:

  • RENEWAL: The renewal of a contract.
  • NEW_CONTRACT: A new contract.

goodsName

String

No

The name of the goods.

goodsPrice

price

Yes

The price of the goods.

price

Field name

Data type

Required

Description

currency

String

Yes

The currency code of the amount. Specify this parameter as HKD.

value

String

Yes

The value of the amount as a natural number. By default, the value of this parameter is in the smallest currency unit. For example, if the currency is HKD and the amount is 1.00 HKD, set the value of this parameter to 100.

Response header

The response header mainly contains the following fields:

Field name

Data type

Required

Description

Field name

Client-Id

String

Yes

A unique ID to identify a client and is associated with the keys that are used for the signature.

Client-Id: 211020000000000000044

Signature

String

Yes

Signature contains key-value pairs that are separated by commas (,). Each key-value pair is an equation, which is a key joined with its value by an equal sign (=).

Signature: algorithm=sha256withrsa,keyVersion=2,signature=****

Response-Time

String

Yes

The time when the response is returned.

Response-Time: 2019-10-22T01:19:50+08:00

Content-Type

String

Yes

The media type of the response body.

Content-Type: application/json; charset=UTF-8

Response Body

The response header mainly contains the following fields:

Note: Field names are case-insensitive.

Field name

Data type

Required

Description

success

Boolean

Yes

The result of the business processing. If the result is true, the information is returned successfully. If the result is false, the information failed to return.

invokeResult

String

Yes

The result of the API request. If the value is SUCCESS, the call was successful; if it is FAILED, the call failed.

errorCode

String

No

The error code that indicates the detailed processing result.

errorContext

String

No

The error message that describes the error code in detail.

Sample

Request

copy
{
    "merchantId": "2160120033934460",
    "subMerchantId": "3858195171",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "outTransId": "2160120033934460_RENEWAL20250909105104279487",
    "transId": "",
    "entityId": "12345678900",
    "entityType": "phone",
    "transType": "transaction",
    "transDate": "2025-04-05T06:30:00Z",
    "transStatus": "SUCCESS",
    "tradeAmt": "{\"currency\":\"HKD\",\"value\":\"24800\"}",
    "extendInfo": "{\"goodsInfoList\":[{\"goodsId\":\"2160120033934460_RENEWAL20250909105104279487\",\"goodsCode\":\"RENEWAL\",\"goodsName\":\"\u8054\u901a\u5408\u7ea6\u7eed\u7ea6\",\"goodsPrice\":{\"currency\":\"HKD\",\"value\":\"24800\"}}]}"
}

Response

copy
{
            "success": true,
            "invokeResult": "SUCCESS"
 }

Error code

Code

Message

Further Action

ORDER_NOT_EXIST

The original transaction information does not exist.

Please confirm that the transaction ID is correct and call the API again.

ORDER_STATUS_INVALID

You cannot update the product information as the commission for the current transaction is either still processing or has already been assigned.

For any errors in the transmitted transaction information, please contact the ASAP team.

CURRENCY_NOT_SUPPORT

Only HKD is currently supported.

N/A

INVALID_AMOUNT

The cost amount must not be significantly greater than the transaction amount.

The current threshold is 2000 HKD. For any adjustments, please contact the ASAP team.

INVALID_MERCHANT

The merchant information must match that in the transaction.

Please verify the merchant information and recall the API.

INVALID_CONTRACT

The commission contract is not within the validity period

Please check if the currently signed CPS contract is still within its validity period.

SYSTEM_ERROR

System exception.

It is recommended that you contact ASAP team to troubleshoot the issue.

REQUEST_PARAM_ILLEGAL

Parameter exception.

Check the parameter values in the request message and recall the API.

IDEMPOTENCY_EXCEPTION

Repeated requests are inconsistent.

N/A

GOODS_CALL_BACK_TIME_LIMIT

The goods information return time exceeds the maximum limit.

This transaction will not be processed. If you have questions, please contact the ASAP team.

TRANS_CALL_BACK_TIME_LIMIT

The transaction information return time exceeds the maximum time limit.

The default time limit is 6 months.

This transaction will not be processed. If you have questions, please contact the ASAP team.