Accept payments

2024-07-31 06:23

To make integration with Antom, you can use Antom-provided open SDKs or you can call APIs by yourself.

Use open SDKs

Antom Global Open SDK encapsulates the process to perform the integration, including the process of adding and validating 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 Antom Entry Code Payment product, payments can be accepted by asking the user to scan the entry code. The following graphic shows the interaction flow of accepting the payment from a customer:

Figure 1. Payment process of Entry Code Payment

The payment process consists of the following steps:

Customer opens the wallet and scans the entry code.

Merchant returns the cashier URL and the customer wallet is redirected to the merchant page.
Merchant presents the page to the customer

Customer enters the transaction amount.
Customer confirms the payment.

Merchant sends the payment request to Antom.
Antom returns the result.
Merchant arouses the wallet to initiate the payment.

Customers confirms to pay.

Antom notifies the payment result to merchant.
Merchant returns a receipt acknowledgement message to Antom.

Initiate a payment request

To integrate with Antom Entry Code Payment product, first go through the Development section to learn about how to invoke an interface in both sandbox and production environments and then 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 p ay interface.

The following example shows an HTTP body of a request for an Entry Code Payment:

copy
{
  "productCode": "IN_STORE_PAYMENT",
  "paymentNotifyUrl": "http://xmock.inc.alipay.net/api/Ipay/globalSite/automtion/paymentNotify.htm",
  "paymentRequestId": "102775745075669",
  "paymentFactor": {
    "inStorePaymentScenario": "EntryCode"
  },
  "order": {
    "orderDescription": "Mi Band 3 Wrist Strap Metal Screwless Stainless Steel For Xiaomi Mi Band 3 ",
    "orderAmount": {
      "currency": "USD",
      "value": "10"
    },
    "merchant": {
      "referenceMerchantId": "seller231117459@login.com",
      "merchantName": "cup Hu",
      "merchantMCC": "1234",
      "store": {
        "referenceStoreId": "S0000000001",
        "storeName": "UGG-2",
        "storeMcc": "1405"
      }
    },
    "env": {
      "userAgent": "Mozilla/5.0 (Linux; Android 9; LYA-AL00 Build/HUAWEILYA-AL00L; wv)  AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0  Chrome/70.0.3538.110  Mobile Safari/537.36 NebulaSDK/1.8.100112 Nebula  AlipayDefined(nt:WIFI,ws:360|0|3.0) AliApp(APHK/2.6.0.160)  AlipayClientHK/2.6.0.160 Language/zh-HK useStatusBar/true isConcaveScreen/true AlipayClient/10.1.32.600 Alipay Language/zh-Hans"
    }
  },
  "paymentAmount": {
    "currency": "USD",
    "value": "10"
  },
  "paymentMethod": {
    "paymentMethodType": "CONNECT_WALLET"
  }
}

Notes:

Specify inStorePaymentScenario with EntryCode in the payment interface for an Entry Code Payment.
All transaction amount needs to be represented in the smallest unit of a currency. For example, when currency code is USD, $5.99 is represented as 599. When 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:

Process the payment result response or notification by verifying the signature of the notification.
Return a receipt acknowledgment message to Antom. This step is only required for asynchronous notification.

Verify the signature of the 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:

Configure the server address to receive notifications.

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

Accept notifications and acknowledge the notification with required response.

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

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.

If you do not reply to this notification, Antom considers that the notification is not received and continues to send the notification. The response (a receipt acknowledgment 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",
"Signature": "algorithm=RSA256,keyVersion=1,signature=jTOHqknjk%2fnDjEn8lfg%2beNODdoh2eHGJV%2blvrKaDwP782WxJ7ro49giqUu23MUM8sFVVNvhg32qHS3sd4O6uf5kAVLqztqNOPJFZcjw141EVi1vrs%2bIB4vU0%2fK%2f8z2GyWUByh2lHOWFsp%2b5QKCclXp%2bjacYqWYUur5IVbuebR1LoD5IiJ7u7J9qYriFxodkxmIAJYJyJs7mks2FWHh2YePLj3K%2f4B65idy7RBKqY1NN1XcvqnbQmlfCH8CIv75bg%2fr9sGmPE5a%2bYgL8N9Q41buGwMSq1IcNsbceMbyPhw5Z5HnJ7tPz12fvdSi0cEicPikDthQ2EQFmtpntXcAc%2fHA%3d%3d"

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 doesn't receive the payment result notification. Therefore, the transaction is 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 interface 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 cancel interface 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 interface, and the merchant can also call the cancel interface 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