AlipayHKAlipayHKDOCS

Implement APIs

Pay & NotifyPayment Interface

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

To integrate with AlipayHK consumer-presented mode payment product

Step 1. Construct the request

The request that you need to construct is composed of four parts:

  • Request URL format: https://open.alipay.hk/aps/api/intl/wallet/v1/payments/pay
  • Method: POST
  • HTTP header: mainly contains fields such asClient-Id,Signature,Encrypt,Content-Type,Request-Time, andAgent-Token.
  • HTTP body: contains the detailed business request information in the JSON format and the business request information needs to be signed. For more information, see the pay interface.

The following example shows an HTTP body of a request for a consumer-presented mode payment. In this case, an Alipay HK user checks out for a total amount of 500 HKD.

copy
{
  "productCode": "IN_STORE_PAYMENT",
  "paymentNotifyUrl": "http://xmock.inc.alipay.net/api/Ipay/globalSite/automtion/paymentNotify.htm",
  "paymentRequestId": "pay_1089760038715669_102775745075669",
  "paymentFactor": {
    "inStorePaymentScenario": "PaymentCode"
  },
  "order": {
    "referenceOrderId": "102775745075669",
    "orderDescription": "Mi Band 3 Wrist Strap Metal Screwless Stainless SteelXiaomi MiBand 3 ",
    "orderAmount": {
      "currency": "HKD",
      "value": "50000"
    },
    "merchant": {
      "referenceMerchantId": "seller231117459@login.com",
      "merchantName": "cup Hu",
      "merchantMCC": "1234",
      "store": {
        "referenceStoreId": "S0000000001",
        "storeName": "UGG-2",
        "storeMcc": "1405"
      }
    }
  },
  "paymetAmount": {
    "currency": "HKD",
    "value": "50000"
  },
  "paymentMethod": {
    "paymentMethodType": "CONNECT_WALLET",
    "paymentMethodId": "281006020000000000125733"
  }
}

Notes:

Specify inStorePaymentScenario with PaymentCode in the payment interface for a consumer-presented mode payment. All transaction amount needs to be represented in the smallest unit of a currency. For example, $500.00 is represented as 50000.

Step 2. Submit the payment request to Alipay

Submit the request you constructed as suggested in Step 1 to Alipay

Note:

Stay open to the possibility that gateway addresses might change.

Step 3. Handle the payment result

The payment result can be synchronous notification, asynchronous notification, or both.

To handle the payment result notifications, you must:

  1. Process the payment resultresponse or notificationby verifying the signature of the notification.
  2. Return areceipt acknowledgment message to Alipay. This step isonlyrequired for asynchronous notification.

Verify the signature of the response or notification

The notification Alipay sends to the merchant is signed. The merchant needs to verify the signature to confirm whether the notification is sent from Alipay.

The following example shows typical notification headers and bodies.

Notification header:

copy
"Content-Type": "application/json",
"Request-Time": "2019-07-12T12:08:56.253+05:30",
"client-id": "T_111222333",
"Signature": "algorithm=RSA256,keyVersion=1,signature=jTOHqknjk%2fnDjEn8lfg%2beNODdoh2eHGJV%2blvrKaDwP782WxJ7ro49giqUu23MUM8sFVVNvhg32qHS3sd4O6uf5kAVLqztqNOPJFZcjw141EVi1vrs%2bIB4vU0%2fK%2f8z2GyWUByh2lHOWFsp%2b5QKCclXp%2bjacYqWYUur5IVbuebR1LoD5IiJ7u7J9qYriFxodkxmIAJYJyJs7mks2FWHh2YePLj3K%2f4B65idy7RBKqY1NN1XcvqnbQmlfCH8CIv75bg%2fr9sGmPE5a%2bYgL8N9Q41buGwMSq1IcNsbceMbyPhw5Z5HnJ7tPz12fvdSi0cEicPikDthQ2EQFmtpntXcAc%2fHA%3d%3d"

Notification body (for a successful payment that succeeds)：

copy
{
    "notifyType": "PAYMENT_RESULT",
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "success"
    },
    "paymentRequestId": "pay_test_1106_0002", //The unique ID that is assigned by a merchant to identify a payment request.
    "paymentId": "20200101234567890132", //The unique ID that is assigned by Alipay to identify a payment.
    "paymentAmount": { //The payment amount that merchant requests to receive in the order currency. 
        "value": "8000",
        "currency": "HKD"
    },
    "paymentCreateTime": "2020-01-01T12:01:00+08:30", //The date and time when the payment is created
    "paymentTime": "2020-01-01T12:01:01+08:30" //The date and time when the payment reaches a final state of success or failure
}

Notification body (for a failed payment):

copy
{
 "notifyType":"PAYMENT_RESULT",
 "result": {
    "resultCode":"USER_BALANCE_NOT_ENOUGH",
    "resultStatus":"F",
    "resultMessage":"user balance not enough"
 },
 "paymentRequestId":"pay_test_1106_0002", 
 "paymentId":"20200101234567890132",
 "paymentTime": "2020-01-01T12:01:01+08:30",
 "paymentAmount":{
    "value":"8000",
    "currency":"HKD"
 },
 "payToAmount":{
    "value":"8000",
    "currency":"HKD"
 }, 
 "customerId":"1234567",
 "paymentPromoInfo":{
   "paymentPromoDetails":[
     {
       "promoId": "2021011819050111540150009999900160350019673599",
       "promoName": "滿10減1夏日優惠券活動",
       "promoType": "CASHLESS_FIXED_VOUCHER",
       "savingsAmount": {
         "currency":"HKD",   
         "value":"100"
        }
     }
    ]
  }
}

Based on the above notification header and body, the content to be verified is as follows:

copy
POST {Use your notification address, such as /merchant/notify}
T_111222333.2019-07-12T12:08:56+05:30.{"notifyType":"PAYMENT_RESULT","result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"},"paymentRequestId":"pay_test_1106_0002","paymentId":"20200101234567890132","paymentAmount":{"value":"8000","currency":"EUR"},"actualPaymentAmount":{"value":"8000","currency":"EUR"},"paymentCreateTime":"2020-01-01T12:01:00+08:30","paymentTime":"2020-01-01T12:01:01+08:30"}

Receive notifications

You can use notifications to automate business processes. To process notifications, you must:

  1. Configure the server address to receive notifications from Alipay on the Alipay Developers Platform or in the payment interface.
  2. Accept notifications and acknowledge the notification with required response. To ensure that your server is properly accepting notifications, Alipay requires you to acknowledge every notification with a success response.
  3. If you use HTTPS to receive notifications, server certificates must be configured according to the authentication requirements. 

Acknowledge the notification with required response

After the customer payment succeeds, Alipay sends a payment result notification to the merchant. The address that is used to receive the notification is specified when sending the payment request. After receiving the notification, the merchant must return a receipt acknowledgment message to Alipay Connect.

If you do not reply to this notification, Alipay considers that the notification is not received and continues to send the notification. The response (a receipt acknowledgment message) sent to Alipay doesn't need to be signed. 

Note:

Only after receiving the Alipay payment success results notification, the payment can be considered successful and the merchant can proceed with the purchase process, for example, deliver goods. Do not rely on the payment results page to determine whether the payment succeeds because the customer might close the result page before the result arrives or an attacker-tampered information might be presented on the result page.

The following samples illustrate the response header and body that Merchant sends to Alipay:

Response header:

copy
"Content-Type": "application/json",
"response-time": "2019-07-12T12:08:56+05:30",
"client-id": "T_111222333",

Response body:

copy
{
 "result": {
     "resultCode":"SUCCESS",
     "resultStatus":"S",
     "resultMessage":"success"
    }
}

Exceptional case

The customer pays successfully, but the merchant does not receive the payment result notification.

In this case, the customer completes the payment and money is deducted. However, the merchant doesn't receive the payment result notification. Therefore, the transaction is failed.

Possible reasons:

  • After the payment of the customer reaches the final payment status (payment success or payment failure), Alipay does not notify the merchant in time.
  • Alipay notified the merchant, but the merchant did not get the payment result due to network reasons.

Actions：

The merchant is suggested to call the inquiryPayment interface to query the payment status before the transaction closing time. If a successful payment status is obtained, proceed with the transaction. If no clear payment status is returned, continue to retry the query request. If a failed payment status is obtained, or the transaction times out, call cancel interface to cancel the transaction.

Note:

The transaction closing time is determined by one of the following ways:

  • If the payment is not completed in time after the checkout page is presented, the transaction is to be closed by default.
  • The merchant can set the closing time by using the paymentExpireTime parameter in the pay interface, and the merchant can also call the cancel interface to close the unpaid transaction or cancel the paid transaction.
  • If the merchant does not specify the paymentExpireTime parameter, the transaction closing time defaults to the contract agreement.

InquiryPayment Interface

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

You can query the status of a transaction order by using the inquiryPayment interface. Call the inquiryPayment interface when one of the following cases is encountered:

  • No clear result of the payment result can be obtained.
  • The payment process times out and no payment result is obtained. 
  • A refund record related to the transaction needs to be checked.

Use the same paymentRequestId that is used in the pay API to inquire the payment transaction status. After Alipay processes the result, the payment or refund details are to be returned to the merchant synchronously. If no response from Alipay is received, retry the inquiry process.

Construct the request message

Construct the request message with the HTTP body as below:

copy
{
   "paymentRequestId": "pay_test_1106_0002"
}

Handle the response

Process the inquiry response by verifying the signature of the notification. The following example shows a typical response for an inquiry request:

copy
{
    "result":{
        "resultCode":"SUCCESS",
        "resultStatus":"S",
        "resultMessage":"success"
    },
    "paymentStatus": "Success",
    "paymentRequestId":"pay_test_1106_0002",
    "paymentId":"20190608114010800100188820200355883",
    "paymentAmount":{
        "value":"500",
        "currency":"USD"
    },
    "actualPaymentAmount":{
        "value":"500",
        "currency":"USD"
    },
    "paymentCreateTime":"2019-06-01T12:01:01+08:30",
    "paymentTime":"2019-06-01T12:01:01+08:30",
    "customerId":"1234567",
    "paymentPromoInfo":{
     "paymentPromoDetails":[
         {
             "promoId": "2021011819050111540150009999900160350019673599",
             "promoName": "滿10減1夏日優惠券活動",
             "promoType": "CASHLESS_FIXED_VOUCHER",
             "savingsAmount": {
                 "currency":"HKD",   
                 "value":"100"
             }
         }
       ]
     }
}

The following graphic shows the process of inquiring the transaction status:

image

Figure 1. Inquiry process

Note:

Here are details about the result status that might be returned for a query request:

  • S: indicates that the inquiry was successful and the merchant can get the payment status from the value of paymentStatus.
  • F: a system alert is to be triggered after getting a resultStatus of F. The merchant's technical support team must investigate the root cause. If the root cause is fixable and the order still exists in the Alipay system, the merchant needs to retry the inquiryPayment API until a result of S is obtained.
  • U: the merchant needs tocall the inquiryPayment API with the same parameters multiple times after getting a resultStatus of U, until a result of S or F is obtained. After the maximum number of retries, if still no S or F is returned, the merchant must call the cancel interface to cancel the transaction.

CancelPayment Interface

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

You can cancel a transaction if the transaction encounters technical issues during making the payment. The cancel interfacecan be used to roll back all the actions performed in the Alipay system regarding the specific transaction. The cancellable period is specified in the contract. If being out of the agreed cancellable period, the cancellation cannot be performed. 

Use the same paymentId that is used in the pay API to cancel the payment transaction. After Alipay processes the cancellation, the cancellation result is to be returned to the merchant synchronously. If no response from Alipay is received, retry the cancellation process.

Construct the request message

Construct the request message with the HTTP body as below:

copy
{
    "paymentId":"20190612184010800100188820200355884"
}

Handle the response

Process the cancellation response by verifying the signature of the notification. The following example shows a typical response for a cancellation request:

copy
{
    "result": 
    {
        "resultCode":"SUCCESS",
        "resultStatus":"S",
        "resultMessage":"success"
    },
    "paymentRequestId":"pay_2089760038715669_202775745075669",
    "paymentId":"20190612184010800100188820200355884",
    "cancelTime":"2019-06-12T19:07:11+08:00"
}

The following graphic shows the process of cancelling the transaction:

image

Figure 2. Cancellation process

Notes:

  1. Integrator might implement the store and forward logic in the gateway. If the cancel request reaches to gateway before the pay API request,the cancel request should not be relayed to the next hop. 
  2. Here are details about the result status that might be returned for a cancellation request:
    • S: indicates that the cancellation was successful.
    • F: a system alert is to be triggered after getting a resultStatus of F. The merchant's technical support team must investigate the root cause. If the root cause is fixable and the order still exists in the Alipay system, the merchant needs to retry the cancel API until a result of S is obtained.
    • U: the merchant needs tocall the cancel API with the same parameters multiple times after getting a resultStatus of U, until a result of S or F is obtained. After the maximum number of retries, if still no S or F is returned, the system alarm is to be triggered and the merchant's technical support team needs to be involved to solve the problem.

RefundPayment Interface

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

You can issue a refund by using the refund interface. The refund service is only applicable to a transaction that has been successfully paid and can be initiated any time after the transaction being paid and before the refund period expiration.

The refund of a transaction can be full or partial, that is, the refund amount can be the same as or less than the original transaction amount that has been paid. If a refund request encounters a failure, retry for a reasonable number of times and follow these suggestions:

  • Use the original refund request ID and retry the refund request. Alipay supports idempotency if a merchant uses the same refund request.
  • The maximum number for retires and the interval forsynchronous and asynchronous refund should be configured. 

No fee is charged for a refund transaction. Your contract with Alipay determines whether the transaction fee charged by Alipay will be refunded or not. After Alipay processes a refund request, the refund is settled by transferring funds to payer's funding instrument. It depends on a bank's policy to determine when a refund settlement can finish. If a payer makes a payment with a credit card and rejects to pay for the credit card's balance, the rejected amount cannot be refunded.

Construct the request message

Construct the request message with the HTTP body as below:

copy
{
 "paymentId":"201811291907410100070000001111",
 "refundRequestId":"201811291907410200070000001111",
 "refundAmount":{
   "value":"100",
    "currency":"USD"
    }
}

Handle the response

Process the cancellation response by verifying the signature of the notification. The following example shows a typical response for a refund request:

copy
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  },
 "refundAmount":{
    "value":"100",
    "currency":"USD"
 },
 "refundTime": "2020-10-10T12:01:01+08:30",
 "paymentId":"201811291907410100070000001111",
 "refundRequestId":"201811291907410200070000001111",
 "refundId":"401811291907410200070000001111"
}

The following graphic shows the process of using a refund service:

image

Figure 3. Refund process

Notes:

  1. After Alipay completes a refund, the transaction cannot be cancelled.
  2. Integrator might implement the store and forward logic in the gateway. If the refund request reaches to gateway before the gateway getting the success payment result, the refund request should not be relayed to the next hop.
  3. Here are details about the result status that might be returned for a refund request. The merchant must get a confirmative result status, either S or F for a refund request:  
    • S: indicates that the refund was successful.
    • F: indicates that a system alert is to be triggered after getting a resultStatus of F. The merchant's technical support team must investigate the root cause. If the root cause is fixable and the order still exists in the Alipay system, the merchant needs to retry the refund API one more time.
    • U: the merchant needs tocall the refund API multiple timesuntil a result of S or F is obtained. After the maximum number of retries, if still no S or F is obtained, the merchant should initialize an asynchronous refund request. After retrying the maximum number of async refund request, system alarm should be triggered and the merchant's technical support team needs to be involved to solve the problem.