Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solutionDOCS

      Authorization and payment

      The following sections describe a typical API integration for the auto debit payment product. A wallet user needs to first complete the authorization and account binding before an authorized merchant can request payment for a wallet user without user's involvement.


      #Before you begin

      Go through the details under Development to be clear about how to invoke an interface, and how to retrieve the information that is required to implement the integration. 


      Request URL syntax is as follows:

      • Sandbox environment: https://<domain_name>/ams/sandbox/<endpoint>
      • Production environment: https://<domain_name>/ams/<endpoint> 

      where, 

      <domain_name> can be obtained from Alipay. See Integration preparation -> Viewing development information for more details. Currently, the following domain names are supported, and you can select one nearby. Plus, if you are not sure which domain to use, contact Alipay Technical support (overseas_support@service.alibaba.com) for help.

      • open-na.alipay.com: data center located in North America.
      • open-sea.alipay.com: data center located in Asia.


      In this document, assume that the domain name used in all code samples is open-na.alipay.com, and the user uses a GCash wallet app.


      #User authorization and account binding

      The following sections describe how to perform the user authorization and account binding. 


      #Process overview

      AD Auth and pay1.png

      Figure 1. User authorization process


      The user authorization process consists of the following steps:

      1. Merchant initiate a consult (/v1/authorizations/consult) request to obtain the authorization URL (step 1.1).
      2. User (the consumer) is redirected to the authorization URL to complete the authorization, and then is redirected to merchant page (the callback url) with authCode (step 2).
      3. Merchant initiate an applyToken (/v1/authorizations/applyToken) request with the authCode to obtain accessToken (step 3.1).
      4. Optional: Merchant initiate an inquiryUserInfo (/v1/users/inquiryUserInfo) request with accessToken to obtain the userId and the login name of the consumer. Note: If you use this service, the scope field of consult (/v1/authorizations/consult) must contain BASE_USER_INFO or USER_INFO.
      5. Merchant saves the mapping relationship of the user information, accessToken, and refreshToken. Now, the user account binding is completed (step 3.3,3.5).


      #Step 1: Call /v1/authorizations/consult to obtain an authorization url.

      In this API call, the product code needs to be specified as AGREEMENT_PAYMENT.

      Request URL: https://open-na.alipay.com/ams/sandbox/api/v1/authorizations/consult


      Header

      Replace the client-id T_111222333 with the clientId that is assigned to you. For more information, see Integration preparation.

      copy
      Content-Type:application/json; charset=UTF-8
original_host:open-na.alipay.com
Request-Time:2019-07-12T12:08:56+05:30
client-id:T_111222333
Signature:algorithm=RSA256,keyVersion=1,signature=TgpjpAzwmA7aWDloDEitOp


      Request Body

      copy
      {
  "customerBelongsTo": "GCASH",
  "authRedirectUrl":"https://www.alipay.com/",
  "scopes": ["AGREEMENT_PAYMENT"],
  "authState": "663A8FA9-D836-48EE-8AA1-1FF682989DC7",
  "terminalType": "APP",
  "osType": "IOS",
  "osVersion": "11.0.2"
}


      Response

      copy
      {
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."
    },
    "authUrl": "https://render.alipay.com/p/c/jzmcoal2?callback=https%3A%
    "resultInfo": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success." 
     }
}


      #Step 2: Launch user's wallet app or redirect to an H5 page.

      In the sandbox environment, only the H5 page experience is provided.


      1. Open the authorization url (authUrl = https://render.alipay.com/p/c/jzmcoal2?callback=https%3A%2F%2Fwww.alipay.com%2F&authState=663A8FA9-D836-48EE-8AA1-1FF682989DC7) returned in the response. You can see a sample with GCash wallet in the following section.


      1. Login with sandbox accounts and authorize.

      In the GCash flow, you can type in any 4 digits, it will take you to log in as a fixed pre-configured testing account.


      Once authorized, it will be redirected to the passed-in redirection link with auth code and state. For example:

      https://www.alipay.com/?authCode=d2f60253-ecdc-e9bc-27d1- 566970191040&authState=663A8FA9-D836-48EE-8AA1-1FF682989DC7

      #
      Step 3: Call /v1/authorizations/applyToken to obtain the accessToken and complete the account binding.


      Request URL:  

      https://open-na.alipay.com/ams/sandbox/api/v1/authorizations/applyToken

       

      Request

      Use the authCode value you obtained in step2, which is d2f60253-ecdc-e9bc-27d1-566970191040.

      copy
      {
  "grantType": "AUTHORIZATION_CODE",
  "customerBelongsTo": "GCASH",
  "authCode": "d2f60253-ecdc-e9bc-27d1-566970191040"
}


      Response

      copy
      {
    "accessTokenExpiryTime": "2019-09-04T13:41:39+0800",
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."     
    },
    "accessToken": "20190828054139156697089972935735984402094237jmfUWaepj
    "refreshTokenExpiryTime": "2019-09-11T13:41:39+0800",
    "resultInfo": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."      
    },
    "refreshToken": "20190828054139156697089972935735984402120180HYYGFvfs
}


      The accessToken is 20190828054139156697089972935735984402094237jmfUWaepjg.


      Optional: You can also revoke the authorization by using the Authorization Revocation (/v1/authorizations/revoke) interface with the accessToken. 


      #Create a payment 

      The following sections describe how to submit a payment request.


      #Process overview

      AD Auth and pay2.png

      Figure 2. Payment process


      When you submit a payment request:

      • Use the payment API (/v1/payments/pay) and the accessToken that is returned from the authorization process to send a payment request.
      • The paymentMethodId is assigned with the accessToken value that is returned in the ApplyToken call.


      Note:

      It is strongly recommended to integrate the Payment Inquiry interface in your system for auto debit payment. No notification of the payment result will be returned from Alipay for the auto debit payment. Therefore, if the payment is still in process when the payment response is returned, merchants need to call the Payment Inquiry interface to get the payment result. Besides, if the payment status is PROCESSING in the Payment Inquiry response, the Payment Inquiry interface needs to be called continuously for more than one minute until a final status of SUCCESS or FAIL in the paymentStatus field is returned. Then you can get the final result of the payment status.


      #Construct a payment request 

      Request URL:

      https://open-na.alipay.com/ams/sandbox/api/v1/payments/pay


      In the request body, the paymentMethodId is assigned with the accessToken value that is returned in the ApplyToken call 20190828054139156697089972935735984402094237jmfUWaepjg.


      Request Body

      copy
      {
  "productCode": "AGREEMENT_PAYMENT",
  "paymentRequestId": "pay_1089760038715669_102775745075656",
  "order": {
    "referenceOrderId": "102775745075669",
    "orderDescription": "Mi Band 3 Wrist Strap Metal Screwless Stainless
    "orderAmount": {
      "value": "800",
      "currency": "PHP"
    }
  },
  "paymentAmount": {
    "currency": "PHP",
    "value": "800"
  },
  "paymentMethod": {
    "paymentMethodType": "GCASH",
    "paymentMethodId": "20190828054139156697089972935735984402094237jmfUW
  }
}


      Response:

      copy
      {
    "result": {
        "resultStatus": "S",
        "resultCode": "Success",
    "resultMessage": "Success" 
    },
    "paymentId": "071329156697640993635741494609211863FOkUAZHdoQ201908280
    "paymentRequestId": "pay_1089760038715669_102775745075656",
    "pspCustomerInfo": {
        "displayCustomerId": "test***@xxx.com", 
        "pspCustomerId": "20881111111234",
        "pspName": "ALIPAY_CN" 
    },
    "paymentAmount": {
        "currency": "PHP",
        "value": "800"
    },
    "paymentTime": "2019-08-28 00:13:29",
    "resultInfo": {
        "resultStatus": "S",
        "resultCode": "Success",
    "resultMessage": "Success" 
    },
    "paymentCreateTime": "2019-08-28 00:13:29"
 }


      #Query a payment

      Merchants need to call the Payment Inquiry interface to get the payment result. The Payment Inquiry interface needs to be called for more than one minute until a final status of SUCCESS or FAIL in the paymentStatus field is returned.


      Note:

      Information about the payment result is displayed in the paymentStatus field of the Payment Inquiry response. The result field only shows whether the Payment Inquiry is processed successfully.


      Use the query (/v1/payments/inquiryPayment) API in one of the following methods:

      • Use paymentRequestId in the original payment API if there is a timeout during the payment request.
      • Call the payment interface again with the same paymentRequestId in the original payment request.
      • Use paymentId that is returned in the response of original payment API to query the final status of a payment.


      Request URL: https://open-na.alipay.com/ams/sandbox/api/v1/payments/inquiryPayment

      The value of paymentId is set to: 071329156697640993635741494609211863FOkUAZHdoQ201908280000008675.


      Request

      copy
      {
   "paymentRequestId": "pay_1089760038715669_102775745075656",
   "paymentId": "071329156697640993635741494609211863FOkUAZHdoQ201908280000
}


      Response

      The following example shows that the Payment Inquiry interface is processed successfully. Besides, the payment status is SUCCESS, which indicates the payment is completed successfully.

      copy
      {
    "result": {
    "resultStatus": "S",
    "resultCode": "Success",
    "resultMessage": "Success" 
    },
    "paymentResultCode": "SUCCESS",
    "paymentResultMessage": "success",
    "paymentStatus": "SUCCESS",
    "paymentId": "071329156697640993635741494609211863FOkUAZHdoQ201908280
    "paymentRequestId": "pay_1089760038715669_102775745075656",
    "paymentAmount": {
        "currency": "PHP",
        "value": "800"
    },
    "extendInfo": "payQuery result",
    "paymentTime": "2019-08-28 00:13:29",
    "resultInfo": {
        "resultStatus": "S", 
        "resultCode": "Success", 
        "resultMessage": "Success"
    },
    "paymentCreateTime": "2019-08-28 00:13:29", 
    "transactions":[]
}


      The following example shows that the Payment Inquiry interface is processed successfully. However, the payment status is PROCESSING, which indicates the payment is under process. You need to continue calling the Payment Inquiry interface for at least one minute until you get a final status of SUCCESS or FAIL.

      copy
      {
 "result":{
  "resultStatus":"S",
  "resultCode":"SUCCESS",
  "resultMessage":"success."
 },
 "paymentId":"20201123194010800100188400240882932",
 "paymentResultCode":"PAYMENT_IN_PROCESS",
 "paymentRequestId":"ACHLP2263824004132888625",
 "paymentResultMessage":"Payment is processing.",
 "paymentAmount":{
  "currency":"HKD",
  "value":"50000"
 },
 "paymentStatus":"PROCESSING"
}


      The following example shows that the Payment Inquiry interface is processed successfully. However, the payment status is FAIL, which indicates the payment is failed.

      copy
      {
 "result":{
  "resultStatus":"S",
  "resultCode":"SUCCESS",
  "resultMessage":"success."
 },
 "paymentId":"20201123194010800100188200241070318",
 "paymentResultCode":"PROCESS_FAIL",
 "paymentRequestId":"3cb72ff85fbbf033a5eb099797411b",
 "paymentResultMessage":"General business failure. No retry.",
 "paymentAmount":{
  "currency":"PHP",
  "value":"15000"
 },
 "paymentStatus":"FAIL"
}


      #Exceptional cases

      Authorization response timeout

      Initiate a retry.


      Authorization failure

      Take actions according to the error code returned by the consult (/v1/authorizations/consul), applyToken (/v1/authorizations/applyToken), or inquiryUserInfo (/v1/users/inquiryUserInfo) interface.


      Payment response timeout

      Before the order is closed, call inquiryPayment (/v1/payments/inquiryPayment) to query the payment status. If the payment succeeds, proceed with the transaction. If the payment fails, call cancelPayment (/v1/payments/cancel) to cancel the payment.


      Payment failure

      Take actions according to the error code returned by the payment (/v1/payments/pay) API.


      #More information

      Post payments

      Reports and reconciliation