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

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 from a wallet user without the 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/api/<endpoint>
  • Production environment: https://<domain_name>/ams/api/<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

image

Figure 1. User authorization process

The user authorization process consists of the following steps:

  1. Merchant initiates 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 the merchant's page (the callback URL) with authCode (step 2.2). Alipay sends the authorization notification to the merchant at the same time (Step 3).
  3. Merchant initiates an applyToken (/v1/authorizations/applyToken) request with the authCode to obtain accessToken (step 4.1).
  4. Merchant saves the mapping relationship of accessToken, and refreshToken. Now, the user account binding is completed (step 4.3).

Step 1: Call the consult interface 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 a WAP page.

In the sandbox environment, only the WAP 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

  1. After the user completes the authorization successfully, the merchant can get the authorization result notification sent by Alipay if you provide a notification URL to Alipay. The address used to receive the notification is configured by the merchant on Alipay Developer Center. You can go to Integration Settings > Notification URL > alipay.ams.authorizations.notify > Edit Notification URL to configure. See the following figure for details.

image

Figure 2. Configure the notification URL

The example below shows an authorization notification body from Alipay to notify a success authorization result:

copy
{
  "authorizationNotifyType ": "AUTHCODE_CREATED ",
  "authState": "489767958497 ",
  "authCode": "28100113_1631148338197000019ba74",
  "resultInfo ": {
    "resultCode ": "SUCCESS ",
    "resultMessage ": "success ",
    "resultStatus ": "S "
  }
}

Upon receipt of the notification, you must return a receipt acknowledgment message to Alipay. The example below shows the body of the receipt acknowledgment message you send to Alipay:

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

Step 3: Call the applyToken interface 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.

Note: You need to integrate the revoke (/v1/authorizations/revoke) interface so that you can revoke the authorization with the accessToken by using the interface. 

Auto debit payment 

The following sections describe how to submit a payment request.

Process overview

Payment process.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 inquiryPayment interface in your system for the 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 inquiryPayment interface to get the payment result. Besides, if the payment status is PROCESSING in the inquiryPayment response, the inquiryPayment 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.

Call the pay interface

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"
 }

Get notified of the payment result

After the user completes the payment successfully, you can get the payment result notification sent by Alipay if you provide a payment notification URL to Alipay. There are two ways to provide the payment notification URL to Alipay:

  • Specify the paymentNotifyUrl field when you send the pay request (v1/payments/pay)
  • Set the payment notification URL in Alipay Developer Center

If the payment notification URL is specified in both the request and Alipay Developer Center, the value specified in the pay request takes precedence.

The example below shows a payment notification body from Alipay to notify a payment result of failure:

copy
{
 "notifyType":"PAYMENT_RESULT",
 "result": {
    "resultCode":"USER_BALANCE_NOT_ENOUGH",
    "resultStatus":"F",
    "resultMessage":"user balance not enough"
 },
 "paymentRequestId":"pay_test_1106_0002", 
 "paymentId":"20200101234567890132"
}

Upon receipt of the notification, you must take the following actions:

  1. Verify the signature of the notification.
  2. Return a receipt acknowledgment message to Alipay.

The example below shows the body of the receipt acknowledgement message you send to Alipay:

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

Note: To obtain accurate payment results, the merchant must integrate the asynchronous notification and payment result inquiry services. Because some wallets might not return any notification when the payment fails, integrating both the asynchronous notification and payment result inquiry services will ensure the payment result being obtained from any wallet.

Call the inquiryPayment interface

Merchants need to call the inquiryPayment interface to get the payment result. The inquiryPayment 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 Status Inquiry response. The result field only shows whether the Payment Status Inquiry is processed successfully.

Use the inquiryPayment (/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 the 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 inquiryPayment 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 inquiryPayment interface is processed successfully. However, the payment status is PROCESSING, which indicates the payment is under process. You need to continue calling the inquiryPayment 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 inquiryPayment 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/consult), 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 cancel (/v1/payments/cancel) to cancel the payment.

Payment failure

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

More information

Post-payment services

Reports and reconciliation