Accept payments

2024-12-18 06:00

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 Order Code Payment product, payments can be accepted by asking the user to scan the order code. The following figure shows the interaction flow of accepting the payment from a customer:

Figure 1. Payment process of Order Code Payment product

The payment process consists of the following steps:

The merchant sends a request to Antom to ask for an order code generation.

1.1 Antom returns the order code to the merchant.

1.2 Antom notifies the payment result to the merchant. (After the customer completes the payment.)

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

The merchant presents the order code to the customer.
The customer opens the e-wallet and scans the order code. The merchant scans the wallet to initiate the payment.
The customer confirms to pay.
ISV sends the payment request to Antom.

Initiate a payment request

Before you start integrating with Antom's Order Code 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 p ay API.

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

copy
{
  "productCode": "IN_STORE_PAYMENT",
  "paymentNotifyUrl": "http://xmock.inc.alipay.net/api/Ipay/globalSite/automtion/paymentNotify.htm",
  "paymentRequestId": "102775745075669",
  "paymentFactor": {
    "inStorePaymentScenario": "OrderCode"
  },
  "order": {
    "referenceOrderId": "102775745075669",
    "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"
      }
    }
  },
  "paymentAmount": {
    "currency": "USD",
    "value": "10"
  },
  "paymentMethod": {
    "paymentMethodType": "CONNECT_WALLET"
  }
}

Notes:
Specify inStorePaymentScenario with OrderCode in the p ay API for an Order Code 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:

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 p ay API.

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.

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 solely rely on the payment results page to determine whether the payment succeeds. The customer might have closed the result page before the result arrived, or maliciously-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 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