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

Accept payments

To integrate with Antom, you can use Antom-provided open SDKs or call APIs on your own.

Use open SDKs

Antom Global Open SDK encapsulates the process of performing the integration, including the adding and validating of signatures for calling Antom APIs. For more details, see Alipay SDK for Java, Alipay SDK for PHP, Alipay SDK for Python, and Alipay SDK for .Net.

API integration

After integrating with the Antom User-presented Payment Product, payments can be accepted by scanning the customer's payment code. The following graphic shows the interaction flow of accepting the payment from a customer:

image.png
Figure 1. Payment process of User-presented Mode Payment

The payment process consists of the following steps:

  1. The user presents the payment code to the merchant.
  2. The merchant scans the payment code of the user.
  3. The merchant initiates a payment request to Antom.

3.1 Antom returns the payment result.

3.2 Antom returns the asynchronous notification to the merchant.

3.3 The merchant sends Antom an acknowledgement message to confirm that the payment notification is received.

Initiate a payment request

Before you start integrating with Antom User-Presented Mode Payment product, go through the Development section to learn how to invoke APIs in both the sandbox and production environments. Then proceed to complete the following steps:

Step 1: Construct the request

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

  • Request URL format: https://open-sea-global.alipay.com/ams/api/v1/payments/pay
  • Method: POST
  • HTTP header: mainly contains fields such as Client-Id, Signature, Encrypt, Content-Type, Request-Time, and Agent-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 API. 

The following example shows an HTTP body of a request for a User-presented Mode Payment. In this case, an Alipay CN user checks out for a total amount of 500 CNY.

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": "USD",
      "value": "50000"
    },
    "merchant": {
      "referenceMerchantId": "seller231117459@login.com",
      "merchantName": "cup Hu",
      "merchantMCC": "1234",
      "store": {
        "referenceStoreId": "S0000000001",
        "storeName": "UGG-2",
        "storeMcc": "1405"
      }
    }
  },
  "paymetAmount": {
    "currency": "USD",
    "value": "50000"
  },
  "paymentMethod": {
    "paymentMethodType": "CONNECT_WALLET",
    "paymentMethodId": "281006020000000000125733"
  }
}

Notes: 

  • Specify inStorePaymentScenario with PaymentCode in the payment API for a User-presented Mode Payment.
  • All transaction amount needs to be represented in the smallest unit of a currency. For example, when the currency code is USD, $5.99 is represented as 599. When the currency code is JPY, ￥599 is represented as 599.  See ISO 4217 Currency Codes for details.

Step 2: Submit the payment request to Antom

Submit the request you constructed as suggested in Step 1 to Antom with the following gateway addresses:

  • open-na.alipay.com: for merchants in North America.
  • open-sea.alipay.com: for merchants in Asia.
  • open-eu.alipay.com: for merchants in Europe.

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 result response or notification by verifying the signature of the notification.
  2. Return a receipt acknowledgment message to Antom. This step is only required for asynchronous notification.

Verify the signature of the response or notification

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

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": "EUR"
    },
    "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"
}

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.

Configure the server address to receive notifications from Antom on the Antom Developer Platform or in the payment API.

  1. Accept notifications and acknowledge the notification with a required response.

To ensure that your server is properly accepting notifications, Antom requires you to acknowledge every notification with a success response.

  1. Apply your business logic.

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, Antom 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 Antom Connect.

If you do not reply to this notification, Antom considers that the notification is not received and continues to send the notification. The response (an acknowledgment receipt message) sent to Antom does not need to be signed. 

Note: Only after receiving the Antom 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 Antom:

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 does not receive the payment result notification. Therefore, the transaction failed.

Possible reasons:

  • After the payment of the customer reaches the final payment status (payment success or payment failure), Antom does not notify the merchant in time.
  • Antom 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 API 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 the cancel API 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 API, and the merchant can also call the cancel API 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.

More information

Post-payment services

Settlement and reconciliation