Alipay+ DocsAlipay+ Docs

Accept payment

To integrate the Merchant-presented Mode Payment Entry Code Payment, the Acquiring Service Provider (ACQP) needs to complete the following steps.

Merchant registration

In certain countries or regions, for legal or compliance reasons, the merchant information that is related to this payment must be registered before a payment can be processed. The merchant registration process only needs to be performed once.

The following figure illustrates the merchant registration flow:

商户报备流程图.png

Figure 2. Merchant registration flow

Processing logic

When processing merchant registration requests, Mobile Payment Provider must pay attention to the following items:

  • Batch operations are not supported. Each time, only one merchant or store can be registered.
  • For the cashier payment scenario, at least the merchant information must be registered.
  • The response of the merchant registration request only indicates that the registration request is successfully accepted.
  • Mobile Payment Provider returns the registration status to Alipay+ asynchronously (normally within 7 days), the ACQP can obtain the registration result by using inquiryRegistrationStatus interface.
  • Alipay+ will notify the ACQP of the merchant registration status via notifyRegistrationStatus interface if the ACQP integrates this interface.

Sample

Alipay+ sends merchant registration request to Mobile Payment Provider.

copy
{
  "registrationRequestId": "202009181105860200000600142****",
  "merchantInfo": {
    "referenceMerchantId": "218812000019****",
    "merchantDisplayName": "Example",
    "merchantMCC": "5735",
    "logo": {
      "logoUrl": "www.example.com",
      "logoName": "Example Inc"
    },
    "merchantAddress": {
      "region": "CN",
      "address1": "浙江省杭州市..."
    },
    "registrationDetail": {
      "legalName": "Example.com",
      "contactInfo": [{
        "contactNo": "abc@example.com",
        "contactType": "EMAIL"
      }, {
        "contactNo": "9326*****56",
        "contactType": "MOBILE_PHONE"
      }],
      "registrationType": "ENTERPRISE_REGISTRATION_NO",
      "registrationNo": "RN1**",
      "registrationEffectiveDate": "2019-01-01T12:08:55+08:00",
      "registrationExpireDate": "2020-01-01T12:08:55+08:00",
      "registrationAddress": {
        "region": "CN",
        "address1": "浙江省杭州市"
      },
      "websites": [{
        "url": "http://electrolibs.com",
        "websiteType": "WEB"
      }],
      "businessType": "ENTERPRISE"
    },
    "shareholderName": "Zhangsan",
    "shareholderId": "69833444422"
  },
  "storeInfo": {
    "referenceStoreId": "218812****",
    "storeName": "Example",
    "storeMCC": "5735",
    "storeAddress": {
      "region": "CN",
      "address1": "浙江省杭州市..."
    }
  },
  "productCodes": ["IN_STORE_PAYMENT"]
}

Mobile Payment Provider returns result to Alipay+.

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

More information

For more information about how to use the APIs (such as the field description), see registration.

Create an entry code

The Entry code is a static QR code which in fact is an encoded URL pointing to an WAP page. Users can enter an order amount on this WAP page. The following rules apply:

  • Ensure that the WAP pages can only be accessed by using the HTTPS protocol.
  • On the WAP page, the ACQP needs to provide fields to collect information such as payment amount.
  • Transfer the WAP page address (URL)  into a QR Code, which is to be printed and presented in Merchants' stores.

Note: The ACQP's WAP server must be able to identify Alipay+ supported digital wallets and retrieve other information through user-agent information in HTTPS requests.

Create a payment

A customer uses an Alipay+ supported digital wallet to scan the Entry Code and open an WAP page, and then enters the payment amount. The ACQP retrieves the payment order details form the Entry Code WAP page, and then sends a payment request to Alipay+ by using the pay interface. In response, Alipay+ returns paymentUrl to the ACQP.

The ACQP redirects the user to the page that links to paymentUrl. The user authorizes and completes the payment.

Processing logic

When you call the pay interface, pay attention to the following items:

  • To enable the merchant page to be opened in the supported wallet, the ACQP must provide the domain of the merchant page to the Alipay+ technical team for registration.
  • Check the user agent in the Entry Code WAP page request. Identify where the request comes from and decide whether to call the pay interface or route the order to other wallets. See Route the order for details.
  • Monitor the payment result notifications sent from Alipay+, or use the inquiryPayment interface to query payment results.
  • The ACQP can prepare a payment result page and configure the URL in the parameter paymentRedirectUrl, which must be an HTTPS URL. After the user confirms the payment, the user is redirected to this page, where you can present the payment result retrieved from the notifyPayment or inquiryPayment interface.

Sample

The ACQP sends a request to Alipay+.

copy
{
    "paymentExpiryTime": "2019-06-01T12:01:01+08:30",
    "paymentNotifyUrl": "http://xmock.inc.alipay.net/api/Ipay/globalSite/automtion/paymentNotify.htm",
    "paymentRequestId": "pay_1089760038715669_102775745075669",
    "paymentFactor": {
        "isInStorePayment": "true",
        "isCashierPayment": "true",
    "inStorePaymentScenario":"EntryCode"
    },
    "order": {
        "referenceOrderId": "102775745075669",
        "orderDescription": "Mi Band 3 Wrist Strap Metal Screwless Stainless Steel For Xiaomi Mi Band 3 ",
        "orderAmount": {
            "currency": "JPY",
            "value": "100"
        },
        "merchant": {
            "referenceMerchantId": "M00000000001",
            "merchantName": "cup Hu",
            "merchantMCC": "1405",
            "merchantAddress": {
                "region": "JP",
                "city": "xxx"
            },
            "store": {
                "referenceStoreId": "S00000000001",
                "storeName": "UGG-2",
                "storeMcc": "1405"
            }
        },
    "env":{
        "userAgent":"Mozilla/5.0 (Linux; Android 9; SM-G977N Build/PPR1.180610.011; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/75.0.3770.143 Mobile Safari/537.36;kakaotalk 1908470"
    }
    },
    "settlementStrategy": {
        "settlementCurrency": "USD"
    },
    "paymentAmount": {
        "currency": "JPY",
        "value": "100"
    },
    "paymentMethod": {
        "paymentMethodType": "CONNECT_WALLET"
    }
}

Alipay+ returns a response to the ACQP.

copy
{
    "acquirerId": "2021228100000000",
    "result": {
        "resultCode": "PAYMENT_IN_PROCESS",
        "resultMessage": "The payment in process.",
        "resultStatus": "U"
   },
    "paymentId": "20190608114010800100188820200355883",
    "paymentAmount": {
        "value": "100",
        "currency": "JPY"
    },
  "paymentUrl": "https://render.alipay.com/p/w/ac-fe-adaptor/?ACCodeValue=281666040098X5mI31LFMzSfInzT2Ts2sO5o&loadingUrl=https%3a%2f%2frender.alipay.com%2fp%2fw%2fac-loading-page%2f"
}

More information

For more information about how to use the interface (such as the field description), see pay.

Handle payment result notifications

Alipay+ calls the notifyPayment interface to notify the ACQP about the payment result when payment reaches a final state of success or failure. After that, the ACQP needs to notify the merchant of the result accordingly.

Processing logic

Accept notifications

For a successful payment transaction, an HTTP POST is fired once the transaction is successfully completed. The HTTP request is sent in the raw JSON, of which the Content-Type request header is specified as application/json. Ensure that you can access the HTTP body accordingly.

For more information about what the request header, the successful payment notification request body and the failed payment notification body look like, see the samples below.

Verify the signature

The notification request that Alipay+ sends to the ACQP is signed. The merchant needs to verify the signature to confirm whether the notification is sent from Alipay+. For how to validate a signature, see Validate a signature.

After the notification is delivered successfully, verify whether the values of the paymentAmount and paymentRequestId parameters are as you expect (for example, the amount that you have calculated for the order that you are going to ship).

Acknowledge the notification with the required response

After receiving the notification, no matter whether the order processing succeeds or fails, you must return a receipt acknowledgment message to Alipay+. Meanwhile, the required response must also be signed.

For more information about what the header and body of the response look like, see the samples below.

Note: The notifyPayment interface cannot accept the failure that is caused by business reasons, for example, risk control validation failure. If the payment fails due to some business reasons, the ACQP must firstly accept the payment notification and return SUCCESS to Alipay+, and then call the cancelPayment interface to perform a refund.

Retrial mechanism

After receiving the notification, you must respond with an HTTP status code of 200 and send an acknowledgement with result.resultStatus of S to indicate that your server received and processed the call. If you respond with other status codes, or acknowledge with other values, Alipay+ takes the notification delivery as unsuccessful. Therefore, Alipay+ will retry the notification sending.

  • The interval between two adjacent times is: 2m, 10m, 10m, 1h, 2h, 6h, 15h
  • 7 times - up to 24 hours 22 minutes

Samples

Alipay+ sends a request to the ACQP.

  • Request 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%2f4B65"
  • Successful payment notification body:
copy
{
 "acquirerId": "1111088000000000002",
 "pspId":"1022172000000000001",
 "paymentResult": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
 },
 "paymentRequestId":"pay_1089760038715669_102775745075669", 
 "paymentId":"20200101234567890134567", 
 "paymentTime": "2020-01-01T12:01:01+08:30",
 "paymentAmount":{
    "value":"100",
    "currency":"JPY"
 },
 "customerId":"1235678",
 "walletBrandName":"KAKAOPAY"
}
  • Failed payment notification request body:
copy
{
"acquirerId":"1022165000000000001",
"customerId":"210220900020254424845",
"paymentAmount": {
"currency":"THB",
"value":"565900"
 },
"paymentId":"2021032919074101000220016046283",
"paymentRequestId":"2021032989031300002162325476274",
"paymentResult": {
"resultCode":"PROCESS_FAIL",
"resultMessage":"General business failure. No retry.",
"resultStatus":"F"
 },
"paymentTime":"2021-03-29T11:00:52+08:00",
"pspId":"2021226300000000"
}

The ACQP returns a response to Alipay+.

  • Response header:
copy
"Content-Type": "application/json",
"response-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%2f4B65"
  • Response body
copy
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"Success"
 }
}

More information

For more information about how to use the interface (such as the field description), see notifyPayment.

Learn more about

Home
Get Support
Need more help?