notifyPayment
Antom uses this API to send the payment result of each subscription period to the merchant when the payment reaches a final state of success or failure.
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
result Result REQUIRED
Details about the payment result, such as payment status, result code, and result message.
paymentId String REQUIRED
The unique ID assigned by Antom to identify a payment for each subscription period.
More information:
- Maximum length: 64 characters
paymentAmount Amount REQUIRED
The payment amount of each subscription period.
paymentCreateTime Datetime REQUIRED
The date and time when the payment of each subscription period 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 of each subscription period reaches a final state of success.
This parameter is returned when the value of result.resultStatus is S.
subscriptionRequestId String REQUIRED
The unique ID assigned by a merchant to identify a subscription request.
More information:
- Maximum length: 64 characters
subscriptionId String REQUIRED
The unique ID assigned by Antom to identify a subscription.
More information:
- Maximum length: 64 characters
periodStartTime Datetime REQUIRED
The start date and time of the current subscription period.
More information:
- The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
periodEndTime Datetime REQUIRED
The end date and time of the current subscription period.
More information:
- The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
phaseNo String REQUIRED
Indicates the current phase of the subscription period. For example, if the subscription begins in May and operates on a monthly cycle for one year, then June represents the second phase, with phaseNo = "2".
More information:
- Maximum length: 64 characters
Response parameters
result Result REQUIRED
A fixed value, which is sent to Antom to acknowledge that the notification is received.
Request
Response
Result process logic
Send the following message with fixed values to Antom after receiving the notification, to acknowledge that the notification from Antom is received:
If no such message is returned to Antom due to operation issues or network issues, Antom will intermittently send the notification until the required message is returned by the merchant. Resending of the notification will be performed within 24 hours after the first notification is sent. The notification will be resent up to eight times, with an interval of 0s, 2min, 10min, 10min, 1h, 2h, 6h, and 15h.
Note: In the sandbox environment, if you do not return information in the specified format, Antom will not resend asynchronous notifications to you.
Result/Error codes
| Code | Value | Message | Further action |
|---|---|---|---|
| SUCCESS | S | Success |
The interface is called successfully. |
| ACCESS_DENIED | F | Access is denied. |
Contact Antom Technical Support for detailed reasons. |
| INVALID_ACCESS_TOKEN | F | The access token is expired, revoked, or does not exist. |
Contact Antom Technical Support for detailed reasons. |
| CURRENCY_NOT_SUPPORT | F | The currency is not supported. |
Contact Antom Technical Support for detailed reasons. |
| ORDER_IS_CLOSED | F | The transaction is closed and cannot be paid again. |
Contact Antom Technical Support for detailed reasons. |
| 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. |
| 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. |
| MERCHANT_BALANCE_NOT_ENOUGH | F | The merchant balance is not enough. |
Call the interface again after the merchant has sufficient balance. |
| 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. |
| SYSTEM_ERROR | F | A system error occurred. |
Do not retry, and contact Antom Technical Support for more details. |
| USER_BALANCE_NOT_ENOUGH | F | The user's balance is insufficient for the payment. |
Contact Antom Technical Support for detailed reasons. |
| USER_STATUS_ABNORMAL | F | The user status is abnormal on the payment method side. |
Contact Antom Technical Support to know the specific reasons. |