# Antom Payment Integration Checklist

This document summarizes general verification items for the Antom payment integration process, including only mandatory and high-risk items. After completing the integration, verify each item and output the verification results using the verification template. The verification results are for reference only; developers should refer to the latest documentation on the Antom Open Platform for accuracy.

---

## 1. Key and Security Verification

| Verification Item | Requirement | Description |
|---|---|---|
| Private Key Storage Location | Private keys must not be stored in client-side code | Transaction data construction and signing must be completed on the merchant server. Private keys must never be stored in the merchant's app client or downloaded from the server. Merchants must properly safeguard private keys. It is not recommended to store private keys in plain text in code or configuration; use encrypted configuration files or key management platforms |
| Private Key Log Security | Private keys must not appear in logs | Private keys have a higher confidentiality level than source code. Appearing in logs increases the risk of private key leakage |
| Private Key Repository Security | Private keys must not be uploaded to public repositories | Private key leakage will completely compromise the security of interactions between the application and Antom |

---

## 2. Asynchronous Notification Verification

| Verification Item | Requirement | Description |
|---|---|---|
| Signature Verification Required | Signature verification must be performed first after receiving asynchronous notifications | Ensures notifications come from Antom |
| Key Information Verification | Verify key merchant request parameters, such as `paymentRequestId`, `paymentAmount` | Prevents order forgery, amount tampering, etc. |
| Transaction Status Determination | Payment is successful only when `notifyType` is `PAYMENT_RESULT` and `resultStatus=S` | Other statuses do not indicate successful payment |
| Idempotent Processing | Must implement idempotent processing to filter duplicate notifications | The same order may receive multiple asynchronous notifications |
| Response Value | After successful processing, the merchant must respond in the specified format. Each notification request must receive this fixed format response: `{"result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"}}` | Otherwise, Antom will retry the notification |
| URL Format | notify_url cannot contain spaces and HTML tags | May cause notification failure |
| Redirect | notify_url cannot redirect | Redirects will cause Antom to not receive a successful response |
| Public Network Accessibility | notify_url must be accessible on the public network | Ensures Antom servers can access it |

### 2.1 One-time Payment Asynchronous Notification Verification

| Verification Item | Requirement | Description |
|---|---|---|
| Transaction Status Determination | Payment is successful only when `notifyType` is `PAYMENT_RESULT` and `resultStatus=S` | Other statuses do not indicate successful payment |

### 2.2 Tokenized Payment Asynchronous Notification Verification

| Verification Item | Requirement | Description |
|---|---|---|
| Transaction Status Determination | Authorization is successful only when `authorizationNotifyType` is `AUTHCODE_CREATED` or `TOKEN_CREATED`, and the `authState` matches the authState value specified in the consult interface request | Other statuses do not indicate successful authorization |
| authCode | When `authorizationNotifyType` is `AUTHCODE_CREATED`, authCode can be obtained from the notification; otherwise, it can be obtained from the redirect link | Prevents order forgery, amount tampering, etc. |
| Payment Status Determination | Payment is successful only when `notifyType` is `PAYMENT_RESULT` and `resultStatus=S` | Other statuses do not indicate successful payment |

### 2.3 Subscription Payment Asynchronous Notification Verification

| Verification Item | Requirement | Description |
|---|---|---|
| Key Information Verification | Verify key subscription parameters, such as `subscriptionRequestId`, `subscriptionStartTime`, `subscriptionEndTime`, `client_id`, `periodRule` | Prevents order forgery, subscription period tampering, etc. |
| Subscription Success | Subscription is activated only when `subscriptionStatus=ACTIVE` in the notification | The same subscription has multiple notification statuses: subscriptionNotificationType = CREATE (created), CHANGE (changed), UPDATE (updated) |
| Deduction Notification Verification | For first/subsequent subscription deductions, verify `subscriptionRequestId`, `subscriptionId`, `paymentAmount`, `phaseNo` (deduction period) are correct | Prevents order forgery, subscription ID and amount tampering |

---

## 3. Payment Result Processing Verification

| Verification Item | Requirement | Description |
|---|---|---|
| Frontend Sync Result Notes | Frontend sync redirect results are for display only and **cannot be used as proof of successful payment** | Must rely on asynchronous notifications or query interface results |
| Payment Success Determination | Payment is successful only when `paymentStatus` is `SUCCESS` | Other statuses do not indicate successful payment |
| No Asynchronous Notification Received | Must call the query interface to confirm order status | Network anomalies may cause notifications not to be received |
| Unknown Exception Handling | When network timeout or unknown exceptions occur, must call the query interface to confirm | Cannot simply assume success or failure |
| Merchant Loss Prevention | Do not rely on frontend sync results; use asynchronous notifications or query results | Prevents marking as successful when user has not paid |
| User Loss Prevention | Do not require user to repay before confirming payment result | Prevents marking as failed when user has paid, resulting in duplicate charges |

---

## 4. Capture Result Processing Verification (Required for Card Payments)

| Verification Item | Requirement | Description |
|---|---|---|
| Key Information Verification | Verify key merchant request parameters, such as `captureRequestId` or `paymentId`, `captureAmount` | Prevents order forgery, amount tampering, etc. |
| Capture Success Determination | When capture notification `notifyType=CAPTURE_RESULT` and `resultStatus=S` is received, the entire payment process is complete | This step only applies to card payments |

---

## 5. Refund Verification

| Verification Item | Requirement | Description |
|---|---|---|
| Refund Usage Scenario | All refund business must call the refund interface | The cancel interface cannot be used for refund business. The cancel interface is only for canceling transactions when the payment result is uncertain. If the cancellation period specified in the contract is exceeded, cancellation is not possible |
| Refund Success Determination | Refund is successful only when the refund query interface returns `refundStatus=SUCCESS` or the refund notification returns `resultStatus=S` | Other statuses do not indicate successful refund |
| Refund Idempotency Guarantee | When the interface has not successfully refunded and the transaction status is unclear, retries must ensure the refund request ID `refundRequestId` and request parameters remain consistent to avoid multiple refunds | Prevents multiple refunds |

---

## 6. Pre-launch Verification

| Verification Item | Requirement | Description |
|---|---|---|
| Gateway Address Confirmation | Select the correct regional gateway based on business coverage area | Must be modified before launch, see gateway addresses below |
| ClientId Switch | Use production environment ClientId | Different from sandbox ClientId |
| Key Switch | Use production environment user private key and Antom public key | Different from sandbox keys |
| Payment Method Activation Status | Confirm payment methods are activated in production environment | Sandbox does not require activation; production environment requires application for activation |
| Private Key Security | Private keys must not be stored in plain text in code, logs, or public repositories | Use secure methods to manage private keys |
| Log Security | Do not print sensitive information in logs (private keys, user information, etc.) | Prevents information leakage |
| HTTPS Communication | Production environment must use HTTPS | Ensures transmission security |

**Regional Gateway Addresses:**

| Region | Gateway Address |
|---|---|
| North America (US) | `https://open.antglobal-us.com` |
| North America (Non-US) | `https://open-na-global.alipay.com` |
| Asia | `https://open-sea-global.alipay.com` |
| Europe | `https://open-de-global.alipay.com` |

---

## 7. Integration Result Verification Template

> Copy the template below, fill in the verification results for each item, and output. Verification result descriptions:
> - ✅ Pass: Implemented and meets specifications
> - ❌ Fail: Not implemented or does not meet specifications, requires rectification
> - ⚠️ Partial Pass: Partially implemented, needs improvement
> - ➖ Not Applicable: Current integration scenario does not involve this item

### 1. Verification Conclusion

[Overall verification conclusion, output verification results and risk status]

---

### 2. Verification Checklist

| Verification Category | Verification Item | Verification Result | Not Applicable | Issue Description |
|---|---|---|---|---|
| Key and Security Verification | | | | |
| Asynchronous Notification Verification | | | | |
| Payment Result Processing Verification | | | | |
| Cancel and Refund Verification | | | | |
| Pre-launch Verification | | | | |
| **Total** | | | | |

---

### 3. Risk Description

[Risk description for items that did not pass verification (❌ Fail, ⚠️ Partial Pass). Remind users to complete rectification before release or confirm that risks are acceptable.]

---

> 📖 This document is compiled based on the official documentation of Antom Open Platform. Please refer to the official documentation for any updates.