Accept payments

The following paragraph describes the payment flow of the Cashier Payment product. In this flow, a wallet user is redirected to a checkout page or his wallet app is launched where the user can be authenticated and complete the payment before being redirected to the merchant site or merchant app. 

Figure 1. Payment process of cashier payment 

The payment process consists of the following steps:

1. User places an order on the merchant platform and then selects a wallet of Alipay to pay.
2. After receiving the client request, merchant initiates a Payment (/v1/payments/pay) request (step 1.1) from the server side. From the result returned from Alipay, merchant can obtain the wallet cashier URL returned by Alipay (step 1.2).
3. Merchant passes the URL to the client side and redirects the user to the wallet cashier (step 1.3).
4. After the wallet cashier guides the user to complete the payment, the user is redirected to the payment result page of the Merchant (step 3).
5. Alipay notifies the merchant of the payment result by using Payment Result Notification interface (/v1/payments/notifyPayment). Merchant receives the notification and updates the internal payment status of the order (steps 4 and 4.1).
6. Merchant server sends an acknowledge receipt to confirm that the payment result is received (step 4.2).

The main steps are described as follows.

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 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. 

You can use Alipay Global Open SDK, which encapsulates the processing of adding and validating signatures, to call Alipay API. For details, refer to the SDK readme.

Request URL:

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

Parameter description:

In the Cashier Payment scenario, specify the product code value as CASHIER_PAYMENT. 

paymentRequestId is used for idempotent control.

Request sample:

{
    "productCode": "CASHIER_PAYMENT",
    "paymentRequestId": "pay_1089760038715669_102775745075669",
    "order": {
        "referenceOrderId": "102775745075669",
        "orderDescription": "XXX Hotel,10 Days",
        "orderAmount": {
            "value": "50000",
            "currency": "PHP"
        },
        "env": {
            "terminalType": "APP",
            "osType": "IOS"
        }
    },
    "paymentAmount": {
        "currency": "PHP",
        "value": "50000"
    },
    "paymentMethod": {
          "paymentMethodType": "GCASH"
    },
    "paymentRedirectUrl": "https://www.merchant.com/paymentResult.htm?orderId=pay_1089760038715669_102775745075669",
    "paymentNotifyUrl":"https://www.merchant.com/payNotify"
}

Response sample: 

You can find wallet cashier URL in: RedirectActionForm

The following sample assumes that the payment is in process and waiting for the user to confirm payment from Wallet Checkout flow.

{
    "result": {
        "resultStatus": "U",
        "resultCode": "PAYMENT_IN_PROCESS",
        "resultMessage": "Payment is processing."
    },
    "paymentId": "212302615674274268857659685498868097avhIBxVMMX201909020000024285",
    "paymentRequestId": "pay_1029760066716669_102775765079666",
    "paymentAmount": {
        "currency": "PHP",
        "value": "800"
    },
    "RediretActionForm": {
        "redirectUrl": "https://payments.gcash.com/gcashapp/gcash-cashier-web/1.2.1/index.html#/confirm?bizNo=111111111111111",
        "method": "GET"
    }
}

Merchant passes the wallet cashier URL retrieved from the /v1/payments/pay response to client side and launches user's wallet app or redirects user to an H5 page (step 1.3).

Note:

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

1. Open the checkout URL (https://render.alipay.com/p/c/jzmcoal2/igg-checkout-counter.html?paymentId=212302615674274268857659685498868097avhIBxVMMX201909020000024285&callback=https%3A%2F%2Fwww.alipay.com) provided in the response of the pay request.
2. Login with test accounts and complete the payment. After payment succeeds, you will be redirected to the passed in redirect page. 

After customer's payment succeeds, Alipay sends a payment result notification to the merchant. The address that is used to receive the notification is specified by paymentNotifyUrl when you send the payment request (v1/payments/pay). Upon receipt of the notification, merchant needs to return a receipt acknowledgment message to Alipay.

The notification Alipay sends to the merchant is also signed, so it is recommended that the merchant verify the signature to confirm whether the notification is sent from Alipay. For sample code of verifying signatures, please refer to SignatureTool.verify in the Open-SDK.

Sample notification header

"Content-Type": "application/json",
"Request-Time": "2019-07-12T12:08:56+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"

Sample notification body (payment succeeds):

{
    "notifyType": "PAYMENT_RESULT",
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "success"
    },
    "paymentRequestId": "pay_test_1106_0002", //The ID assigned by Merchant to identify the payment transaction
    "paymentId": "20200101234567890132", //The ID assigned by Alipay to identify the payment transaction
    "paymentAmount": { //The amount of the payment order, 80 EUR
        "value": "8000",
        "currency": "EUR"
    },
    "paymentCreateTime": "2020-01-01T12:01:00+08:30", //Time when the payment transaction is created
    "paymentTime": "2020-01-01T12:01:01+08:30" //Time when the payment is completed
}

Sample notification body (payment fails):

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

Content example

Based on the notification header and body:

POST {your_notification_endpoint/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"}

Verify the signature by using SDK

Use the preceding content example, the signature enclosed in the header (the part after "signature=") "jTOHqknjk%2fnDjEn8lf....", and the Alipay public key as parameters of SignatureTool.verify.

boolean isSuccess = SignatureTool.verify(httpMethod, path, clientId, rspTimeStr, rspBody, signature, alipayPublicKey);

Process payment notifications and return a receipt acknowledgment message to Alipay. If this notification is not replied, Alipay will take it as the merchant does not receive the notification and will continue to send the notification.

Note:

The response (a receipt acknowledgment message) sent to Alipay does not need to be signed. 

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

Response header:

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

Response body:

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

After receiving server-side payment success results notification from Alipay, merchant can fulfill the purchase, for example, deliver goods. Do not to rely only on the payment results page as a basis for the success of the order, which users may close early, or that an attacker might use this page to pretend completing the payment.

For the repeatedly received payment notifications from Alipay for one payment request, the merchant needs to record the processed notifications and handle the idempotence properly.

Method 1: Call /v1/payments/pay to obtain the payment result. 

Call this interface with the SAME paymentRequestId that you used in the original pay API (/v1/payments/pay) will return the final payment status if available when the previous payment call's result is payment in processing status. 

Sample /v1/payments/pay request with a same paymentRequestId: 

{
    "productCode": "CASHIER_PAYMENT",
    "paymentRequestId": "pay_1029760066716669_102775765079666",
    "order": {
    "referenceOrderId": "102775765075669",
    "orderDescription": "Mi Band 3 Wrist Strap Metal Screwless Stainless Steel For Xiaomi Mi Band 3",
    "orderAmount": {
    "value": "800",
    "currency": "PHP"
    },
  "env":{
    "terminalType":"APP",
    "osType":"IOS"
  },
  "merchant":{
    "referenceMerchantId": "seller12345678@login.com",
    "merchantName": "merchantName1234",
    "merchantMCC": "1234",
    "store": {
      "referenceStoreId": "S0000000001",
      "storeName": "storeName",
      "storeMcc": "1405"
    }
  }
    },
    "paymentAmount": {
    "value": "800",
    "currency": "PHP"
    },
    "paymentMethod": {
    "paymentMethodType": "GCASH",
    },
    "paymentRedirectUrl": "https://www.alipay.com",
    "paymentNotifyUrl": "https://www.merchant.com/notify.html"
}

Response: 

{
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."
    },
    "paymentId": "212302615674274268857659685498868097avhIBxVMMX201909020000024285",
    "paymentRequestId": "pay_1029760066716669_102775765079666",
    "paymentAmount": {
        "currency": "PHP",
        "value": "800"
    },
    "RediretActionForm": {
        "redirectUrl": "https://payments.gcash.com/gcashapp/gcash-cashier-web/1.2.1/index.html#/confirm?bizNo=111111111111111",
        "method": "GET"
    }
}

The response shows that the payment is already completed successfully.

Method 2: Call /v1/payments/inquiryPayment if paymentId is known

With paymentId or paymentRequestId, you can query the result of a payment by using query API /v1/payments/inquiryPayment.

Request URL:

• Sandbox environment: https://open-na.alipay.com/ams/sandbox/api/v1/payments/inquiryPayment
• Production environment: https://open-na.alipay.com/ams/api/v1/payments/inquiryPayment

{
    "paymentId": "212302615674274268857659685498868097avhIBxVMMX201909020000024285"
}

Response: 

{
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."
    },
    "paymentResultCode": "SUCCESS",
    "paymentResultMessage": "success",
    "paymentStatus": "SUCCESS",
    "paymentId": "212302615674274268857659685498868097avhIBxVMMX201909020000024285",
    "paymentRequestId": "pay_1029760066716669_102775765079666",
    "paymentAmount": {
        "currency": "PHP",
        "value": "800"
    },
    "RediretActionForm": {
        "redirectUrl": "https://payments.gcash.com/gcashapp/gcash-cashier-web/1.2.1/index.html#/confirm?bizNo=111111111111111",
        "method": "GET"
    },
    "transactions":[]
}

Payment response timeout

Initiate a retry. The payment result is returned if the retry succeeds. Alipay supports payment idempotence, therefore, a repeated payment does not cause payment result confusion.

Payment failed

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

Post payments

Reports and reconciliation