pay (Order Code Payment)
Use this API to initiate a payment to Antom and process payment results according to the status and operation instructions returned by Antom.
Structure
A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see：
Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:
- If the data type of a field is Integer and its value is 20, set it as "20".
- If the data type of a field is Boolean and its value is true, set it as "true".
Request parameters
productCode String REQUIRED
The payment product that the merchant can use, based on the contract between the merchant and Antom. For Order Code Payment, the value is fixed as IN_STORE_PAYMENT.
paymentRequestId String REQUIRED
The unique ID that is assigned by a merchant to identify a payment request. Antom uses this field for idempotence control.
More information:
- This field is an API idempotency field.The merchant uses the paymentRequestId field for idempotency control. For payment requests that are initiated with the same value of paymentRequestId and reach a final status (S or F), the same result is to be returned for the request.
- Maximum length: 64 characters
order Order REQUIRED
Order information, such as buyer information, merchant information, order description, and order amount.
The parameter is also used for risk control, supervision, reporting, user payment result display, and so on.
paymentAmount Amount REQUIRED
The payment amount that the merchant requests to receive in the order currency.
paymentMethod PaymentMethod REQUIRED
The payment method that is used to collect the payment by the merchant or acquirer.
paymentExpiryTime Datetime
The payment expiration time is a specific time after which the payment will expire. After the payment expiration time, the acquirer or merchant must terminate the order processing. A default payment expiration time is determined by the contract. If you want to use a payment expiration time that differs from the default time, specify this field.
Note: Usually for User-Presented Mode Payment, the default payment expiration time in the contract is 3 minutes after the payment request is sent. For example, the request is sent when the time is 2019-11-27T12:00:01+08:30, the payment expiration time is 2019-11-27T12:03:01+08:30.
More information:
- The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
paymentRedirectUrl URL
More information:
- Maximum length: 2048 characters
paymentNotifyUrl URL REQUIRED
More information:
- Maximum length: 2048 characters
paymentFactor PaymentFactor
Indicates the payment scenario.
settlementStrategy SettlementStrategy
The settlement strategy for the payment request.
Note: Specify this field when one of the following conditions are met:
- Multiple settlement contracts are signed and more than one settlement contract supports this transaction. In this case, use this field to specify the settlement currency so that the settlement contract to be used for this transaction can be selected from all the signed settlement contracts.
- When the value of paymentMethodType is
CONNECT_WALLET.
merchantRegion String
The country or region where the merchant or secondary merchant operates the business. The 2-letter country/region code that follows ISO 3166 Country Codes standard. Only US, JP, PK, SG are supported now.
Note: This field is required when you use Antom Global Gateway (GGW) product.
More information:
- Maximum length: 2 characters
Response parameters
result Result REQUIRED
The request result contains information such as status and error codes.
paymentRequestId String
The unique ID that is assigned by a merchant to identify a payment request.
More information:
- Maximum length: 64 characters
paymentId String
The unique ID that is assigned by Antom to identify a payment.
More information:
- Maximum length: 64 characters
paymentAmount Amount
The payment amount that the merchant requests to receive in the order currency.
paymentTime Datetime
The date and time when the payment reaches a final state of success or failure.
More information:
- The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
paymentCreateTime Datetime
The date and time when the payment is created.
More information:
- The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
pspCustomerInfo PspCustomerInfo
The customer information of the Alipay+ payment methods.
Note: Alipay+ Mobile Payment Provider, is a Mobile Payment Partner participating in Alipay+ Core or other user- or issuer-facing payment service provider cooperating with a member of Ant Group to enable payments.
challengeActionForm ChallengeActionForm
Provides information about the challenge action when the payment result is not in a final state of success or failure.
redirectActionForm RedirectActionForm
Information about the redirection action：
- When the method used for user redirection is
GET(method=GET), the value of redirectUrl is a complete URL that can be used for user redirection. - When the method used for user redirection is
POST(method=POST), the value of redirectUrl is part of a complete URL where the user is to be redirected to. Other parameters needed for a complete URL is provided in the parameters field.
Note: This field is returned when the API is called successfully.
orderCodeForm OrderCodeForm REQUIRED
Provides information about the order code.
grossSettlementAmount Amount
Gross settlement amount, which equals to the transaction amount multiplied by the value of settlementQuote.
Note: This field is empty when the settlement currency is the same as the transaction currency.
settlementQuote Quote
The exchange rate between the settlement currency and transaction currency at the time of the transaction, which is provided only in the locked-in rate case.
Note: This field is empty when the settlement currency is the same as the transaction currency.
Request
Response
More information
This section gives additional information about other parameters. See the following parameters for details:
• productCode:
The value of this parameter is the payment product that the merchant uses for collecting payments, based on the contract between the merchant and Antom. When the merchant can use multiple products, this parameter is required.
• order:
The order parameter contains order information, such as Merchant, Goods, logistic, and purchase environment. During the payment process, the order information is mainly used by Antom for risk control or anti-money laundering. After the payment is completed, the information is used to display consumption records, regulatory reporting, and other purposes.
However, Antom does not verify the consistency of the amount in order and the amount in the payment request. The order information is not applied in fund operations either. Use the env field if the risk control capability provided by Antom is needed.
• paymentMethod:
The value of paymentMethod is CONNECT_WALLET, indicating that Antom collects money from the order code that was generated by Antom.
• paymentExpiryTime:
The payment executor must ensure that the payment will not succeed after the expiration time. If this parameter is not specified in the request, the expiration time is then decided by the payment executor.
• paymentFactor:
The value of paymentFactor.inStorePaymentScenario is OrderCode, indicating that Antom needs to generate an order code in this payment.
• paymentId:
If this field is not returned in the response, you can use the paymentRequestId field to initiate inquiryPayment and cancel requests.
Result process logic
After calling a pay (Order Code Payment) interface, the following results might be returned from Antom:
- Antom returns that result.resultStatus is
S, which indicates the merchant needs to display the payment information to the user by using the parameters in a form that the user can proceed. - Antom returns that result.resultStatus is F, the payment request fails.
- Antom returns that result.resultStatus is U, the merchant needs to call the pay (Order Code Payment) interface again.
Result/Error codes
| Code | Value | Message | Further action |
|---|---|---|---|
| SUCCESS | S | Success | The payment is successful, no further action is needed. |
| ACCESS_DENIED | F | Access is denied. | Contact Antom Technical Support for detailed reasons. |
| INVALID_API | F | The called API is invalid or not active. | Contact Antom Technical Support to resolve the issue. |
| CLIENT_INVALID | F | The client ID is invalid. <span>Antom</span> has restrictions on client ID. | Check whether the client ID is correct, or contact Antom Technical Support for detailed reasons. |
| CURRENCY_NOT_SUPPORT | F | The currency is not supported. | Contact Antom Technical Support for detailed reasons. |
| INVALID_CONTRACT | F | The parameter values in the contract do not match those in the current transaction. | Check whether the parameter values in the contract match those in the current transaction. If the values match, contact Antom Technical Support to troubleshoot the issue. |
| INVALID_MERCHANT_STATUS | F | The merchant status is abnormal because restrictions exist. | Contact Antom Technical Support for detailed reasons. |
| INVALID_SIGNATURE | F | The signature is not validated. The private key used to sign a request does not match the public key of <span>Antom</span> Developer Center. | Check whether the private key used to sign a request matches the public key of Antom Developer Center. The following signature references are useful:
|
| KEY_NOT_FOUND | F | The private key or public key of <span>Antom</span> or the merchant is not found. | Check whether the private key or public key exists. If not, upload the private key in Antom Developer Center. |
| MEDIA_TYPE_NOT_ACCEPTABLE | F | The server does not implement the media type that is acceptable to the client. | Check whether the media type is correct and use a media type that is accepted by Antom. |
| MERCHANT_KYB_NOT_QUALIFIED | F | The payment failed because of the merchant's KYB status. The merchant is either not KYB compliant, or the KYB status is not qualified for this transaction. | Contact Antom Technical Support for detailed reasons. |
| MERCHANT_NOT_REGISTERED | F | The merchant is not registered. | Please register the merchant by using the registration interface. Contact Antom Technical Support if failed to call the registration interface. |
| METHOD_NOT_SUPPORTED | F | The server does not implement the requested HTTP method. Only the POST method is supported. | Ensure the HTTP method is POST. |
| NO_INTERFACE_DEF | F | API is not defined. | Check whether the URL is correct. Please refer to the endpoint in the API documentation. |
| NO_PAY_OPTIONS | F | The currency is not supported for the transaction. | Check whether the currency is supported by the wallet, or check whether the wallet and currency are consistent with the contract. Contact Antom Technical Support for detailed reasons. |
| ORDER_IS_CANCELED | F | The request you initiated has the same paymentRequestId as the previously paid transaction, which is canceled. | Use a new paymentRequestId to initiate the payment again. |
| ORDER_IS_CLOSED | F | The request you initiated has the same paymentRequestId as that of the existed transaction, which is closed. | Use a new paymentRequestId to initiate the payment again. |
| PARAM_ILLEGAL | F | The required parameters are not passed, or illegal parameters exist. For example, a non-numeric input, an invalid date, or the length and type of the parameter are wrong. | Check and verify whether the required request fields (including the header fields and body fields) of the current API are correctly passed and valid. |
| PAYMENT_AMOUNT_EXCEED_LIMIT | F | The payment amount is greater than the maximum amount allowed by the contract or wallet. | Check whether the payment amount exceeds the limit or use a lower amount and try again. Contact Antom technical support to know the specific limitation. |
| PAYMENT_COUNT_EXCEED_LIMIT | F | The maximum number of payments exceeds the limit that is specified by the wallet. | Contact Antom Technical Support to know the specific limitation. |
| PAYMENT_NOT_QUALIFIED | F | The merchant is not qualified to pay because the merchant is not registered, or is forbidden to make a payment. | Contact Antom Technical Support for detailed reasons. |
| PROCESS_FAIL | F | A general business failure occurred. | Do not retry. Human intervention is usually needed. It is recommended that you contact Antom Technical Support to troubleshoot the issue. |
| REPEAT_REQ_INCONSISTENT | F | The amount or currency is different from the previous request. | Ensure all the fields in the requests are the same or use a new paymentRequestId to initiate the payment again. |
| RISK_REJECT | F | The request is rejected because of the risk control. | Prompt the user that the request is rejected because the risk control failed. |
| SYSTEM_ERROR | F | A system error occurred. | Do not retry, and contact Antom Technical Support for more details. |
| USER_NOT_EXIST | F | The user does not exist on the wallet side. | Contact Antom Technical Support for detailed reasons. |
| PAYMENT_IN_PROCESS | U | The payment is being processed. | Use a new paymentRequestId to initiate the payment again. |
| REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. | Call the interface again to resolve the issue. If not resolved, contact Antom Technical Support. |
| UNKNOWN_EXCEPTION | U | An API call has failed, which is caused by unknown reasons. | Call the interface again to resolve the issue. If not resolved, contact Antom Technical Support. |