inquiryPayment
Use this API to query for information about a previously submitted payment request or accept the asynchronous processing result for a payment.
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
paymentRequestId String
The unique ID that is assigned by a merchant to identify a payment request. paymentRequestId and paymentId cannot both be null. If both paymentRequestId and paymentId are specified, paymentId takes precedence.
More information:
- Maximum length: 64 characters
paymentId String
The unique ID that is assigned by Antom to identify a payment. paymentRequestId and paymentId cannot both be null. A one-to-one correspondence between paymentId and paymentRequestId exists. If both paymentRequestId and paymentId are specified, paymentId takes precedence.
More information:
- Maximum length: 64 characters
Response parameters
result Result REQUIRED
The request result contains information such as status and error codes.
Note: This field doesn't indicate the payment result. This field only indicates whether the inquiryPayment interface is called successfully.
paymentStatus String
Indicates the final status of Antom payment. Valid values are:
SUCCESS: Indicates the transaction is successful.FAIL: Indicates the transaction is failed.PROCESSING: Indicates the transaction is under processing.CANCELLED: Indicates the transaction is canceled.
paymentResultCode String REQUIRED
Payment result codes.
More information:
- Maximum length: 64 characters
paymentResultMessage String REQUIRED
Payment result message.
More information:
- Maximum length: 256 characters
paymentRequestId String REQUIRED
The unique ID that is assigned by a merchant to identify a payment request.
More information:
- Maximum length: 64 characters
paymentId String REQUIRED
The unique ID that is assigned by Antom to identify a payment.
More information:
- Maximum length: 64 characters
paymentAmount Amount REQUIRED
The payment amount that the merchant requests to receive in the order currency.
authExpiryTime Datetime
Authorization expiration time.
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".
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".
pspCustomerInfo PspCustomerInfo
The customer information of digital wallets.
Note: This field is returned when the digital wallet can provide the related information.
redirectActionForm RedirectActionForm
Provides information of the redirection action.
transactions Array<Transaction>
Information about the transaction.
More information:
- Maximum size: Unlimited
grossSettlementAmount Amount
The total 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.
receiptInfo ReceiptInfo
Receipt information.
Note: This parameter is returned when you use in-store card payments.
acquirerInfo AcquirerInfo
The information of the acquirer that processes the payment.
Note: This parameter is returned when you use in-store card payments.
acquirerReferenceNo String
The unique ID assigned by the non-Antom acquirer for the transaction.
Note: Specify this parameter when the transaction is settled by the non-Antom acquirer.
More information:
- Maximum length: 64 characters
actualPaymentAmount Amount REQUIRED
Actual payment amount.
cardInfo CardInfo
Card information.
Note: This parameter is returned when the value of paymentMethodType in the createPaymentSession API is
CARDfor specific merchants in specific regions.
paymentResultInfo PaymentResultInfo
The information of payment results.
Note: This parameter is returned when the value of paymentMethodType in the createPaymentSession API is
CARDfor specific merchants in specific regions.
Request
Response
More information
This section provides additional information about key parameters. See the following list for details:
The successful execution time of this payment by Antom, that is, the date and time when the payment reaches a final state of success or failure. This value is used as the start time of the subsequent revocable and refundable time. For example, if the refundable time is 6 months, the final time to accept the refund is paymentTime plus 6 months.
The unique payment processing ID. For polling the same payment, this field must be unique; for polling different payments, this field must be different. This value can be used for further actions like inquiry, cancellation, or refund.
To decide when to use paymentRequestId or paymentId, follow these rules:
- If the cancel API calling returns an unknown exception or times out, the merchant can use either paymentId or paymentRequestId of the original payment to query the cancel result.
- If the refund API calling returns an unknown exception or times out, the merchant can use either paymentId or paymentRequestId of the original payment to query the refund result. But using refundRequestId is not supported.
Result process logic
For different request results, different actions are to be performed. See the following list for details:
- If the value of result.resultStatus is
S, payment result inquiry succeeds. - If the value of result.resultStatus is
F, payment inquiry fails. - If the value of result.resultStatus is
U, then the request result is unknown. Use the same request parameters to retry the inquiry request.
Result/Error codes
| Code | Value | Message | Further action |
|---|---|---|---|
| SUCCESS | S | Success | Call the interface successfully. Obtain the order status by paymentStatus. |
| ACCESS_DENIED | F | Access is denied. | Contact Antom Technical Support for detailed reasons. |
| CURRENCY_NOT_SUPPORT | F | The currency is not supported. | 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. |
| NO_PAY_OPTIONS | F | No payment options are available. | Contact Antom Technical Support for detailed reasons. |
| 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. |
| 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. |
| USER_KYC_NOT_QUALIFIED | F | Payment failed because of the user's KYC status. The user is either not KYC compliant, or the KYC status is not qualified for this transaction (for example, limitations on the payment amount or product information). | Prompt the user to complete KYC. |
| PAYMENT_IN_PROCESS | U | The payment is being processed. | For in-store payment, the request you initiated has the same paymentRequestId as that of the existed transaction, which might be a successful or in-process transaction. Check whether redirectActionForm.redirectUrl is returned in the response. If returned, redirect the user to the address specified by redirectUrl to complete the payment. If not, the payment might already be completed. See Result process logic for details; If not returned, the payment might be processed. Wait for the asynchronous notification or call the inquiryPayment API to query the final payment status. |
| UNKNOWN_EXCEPTION | U | An API call has failed, which is caused by unknown reasons. | For in-store payment , call the inquiryPayment API to query the final payment status. If the issue is not resolved, contact Antom Technical Support. |
| DO_NOT_HONOR | F | The payment is declined by the issuing bank. | Retry the payment using a different card or contact the issuing bank. |
| ORDER_NOT_EXIST | F | The order does not exist. | Check whether paymentId is correct. |
| CLIENT_INVALID | F | The client is invalid. | Check whether clientId is correct. |
| METHOD_NOT_SUPPORTED | F | The server does not implement the requested HTTP method. | Check whether the HTTP method is correct. |
| 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. |