inquiryPayment

2022-01-04 06:53

1. Overview

Endpoint: https://open.alipay.hk/aps/api/intl/wallet/v1/payments/inquiryPayment

Use this interface to query the payment result.

2. Sample

Issuing Participantsends the inquiry request to AlipayHK.

copy
{
 "acquirerId": "1022188000000000001",
 "pspId":"1022172000000000001",
 "paymentRequestId":"20200101234567890132"
}

AlipayHK returns the inquiry result to Issuing Participant.

copy
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  },
 "paymentResult": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
 },
 "paymentId":"20200101234567890133333", 
 "paymentTime": "2020-01-01T12:01:01+08:30",
 "paymentAmount":{
    "value":"100",
    "currency":"JPY"
 },
 "payToAmount":{
    "value":"1000",
    "currency":"KRW"
 }, 
 "customerId":"1234567",
 "paymentPromoInfo":{
  "paymentPromoDetails":[
    {
      "promoId": "2021011819050111540150009999900160350019673599",
      "promoName": "滿10減1夏日優惠券活動",
      "promoType": "CASHLESS_FIXED_VOUCHER",
      "savingsAmount": {
        "currency":"HKD",   
        "value":"100"
       }
    }
   ]
 }
}

3. Structure

3.1 Request

No.	Field	Description
1	acquirerId	MANDATORY String (64) The unique ID that is assigned by AlipayHK to identify an Acquirer.
2	pspId	MANDATORY String (64) The unique ID that is assigned by AlipayHK to identify a Issuing Participant.
3	paymentRequestId	MANDATORY String (64) The unique ID that is assigned by the payment initiator to identify an order payment

3.2 Response

No.	Field	Description
1	result	MANDATORY Result Request result, which contains information such as status and error codes. See Result for details.
2	paymentResult	OPTIONAL Result The payment result. See Result for details.
3	paymentRequestId	OPTIONAL String (64) The unique ID that is assigned by the payment initiator to identify an order payment
4	paymentId	OPTIONAL String (64) The unique ID that is assigned by the payment executor to identify a payment
5	paymentAmount	OPTIONAL Amount The amount that is collected by the payment executor. See Amount for details.
6	payToAmount	OPTIONAL Amount The amount that is paid by the payment executor. See Amount for details.
7	paymentTime	OPTIONAL Datetime The date and time when the payment reaches a final state of success or failure
8	customerId	OPTIONAL String (64) The unique ID that is assigned by Issuing Participant to identify a customer.
9	paymentPromoInfo	OPTIONAL PaymentPromoInfo Payment promotion information. See PaymentPromoInfo for details.
10	passThroughInfo	OPTIONAL String (2048) Passthrough information in the set of key-value pairs that is transmitted between AlipayHK and participants.

4. More information

Response conditionality:

paymentResult: The payment result, which is returned only when result.resultStatus is S. The paymentResult.resultStatus field reflects the payment status, with S representing success and F representing failure.
paymentAmount: Must be returned for successful payments when paymentResult.resultStatus is S.
payToAmount: Must be returned for successful payments when paymentResult.resultStatus is S and payToAmount is not equal to paymentAmount.
paymentTime: Must be returned for successful payments when paymentResult.resultStatus is S.
customerId: Must be returned for successful payments when paymentResult.resultStatus is S.
paymentId: Must be returned for successful payments when paymentResult.resultStatus is S.

Result processing logic:

For the query request initiated by AlipayHK to the Issuing Participant,, AlipayHK takes the same processing strategy as that for Acquirer. Issuing Participant, needs to take the following processing strategy:

If the payment is successful, Issuing Participant, must return a result.resultStatus of S and a paymentResult.resultStatus of S.
If the payment is failed, Issuing Participant, needs to return a result.resultStatus of S and paymentResult.resultStatus of F.
If the payment is processing, Issuing Participant, needs to return a result.resultStatus of S and a paymentResult.resultStatus of U.
If the payment doesn't exist, Issuing Participant, needs to return a result.resultStatus of F and a result.resultCode of ORDER_NOT_EXIST.
If system or network issues exist, Issuing Participant, can return a result.resultStatus of U, and AlipayHK will retry.

5. Result code

No.	resultCode	resultStatus	resultMessage
1	SUCCESS	S	Success
2	ORDER_NOT_EXIST	F	The order doesn't exist.
3	PROCESS_FAIL	F	A general business failure occurred. Don't retry.
4	PARAM_ILLEGAL	F	Illegal parameters exist. For example, a non-numeric input, or an invalid date.
5	KEY_NOT_FOUND	F	The key is not found.
6	ACCESS_DENIED	F	The access is denied.
7	REQUEST_TRAFFIC_EXCEED_LIMIT	U	The request traffic exceeds the limit.
8	INVALID_API	F	The called API is invalid or not active.
9	INVALID_CLIENT	F	The client is invalid.
10	INVALID_SIGNATURE	F	The signature is invalid.
11	METHOD_NOT_SUPPORTED	F	The server does not implement the requested HTTP method.
12	MEDIA_TYPE_NOT_ACCEPTABLE	F	The server does not implement the media type that is acceptable to the client.
13	UNKNOWN_EXCEPTION	U	An API calling is failed, which is caused by unknown reasons.

6. Payment result

No.	resultCode	resultStatus	resultMessage
1	SUCCESS	S	Success
2	INVALID_CONTRACT	F	The contract is invalid.
3	INVALID_CODE	F	The code is invalid.
4	INVALID_TOKEN	F	The access token is invalid.
5	EXPIRED_CODE	F	The code is expired.
6	CURRENCY_NOT_SUPPORT	F	The currency is not supported.
7	USER_BALANCE_NOT_ENOUGH	F	The user balance is not enough for the payment.
8	USER_NOT_EXIST	F	The user does not exist.
9	USER_STATUS_ABNORMAL	F	The user status is abnormal.
10	USER_AMOUNT_EXCEED_LIMIT	F	The payment amount exceeds the user payment limit.
11	PAYMENT_AMOUNT_EXCEED_LIMIT	F	The payment amount exceeds the limit.
12	PAYMENT_COUNT_EXCEED_LIMIT	F	The number of payments exceeds the limit.
13	ORDER_IS_CLOSED	F	The order is closed.
14	BUSINESS_NOT_SUPPORT	F	The payment business is not supported.
15	RISK_REJECT	F	The request is rejected because of the risk control.
16	PROCESS_FAIL	F	A general business failure occurred. Don't retry.
17	PAYMENT_IN_PROCESS	U	The payment is being processed.