**[English](README.md)** | **[中文](../zh/README.md)**

# Antom Payments for WooCommerce

> One click to integrate 300+ payment methods around the globe — from major cards, to global digital wallets, to hundreds of top local payment methods worldwide.

**Plugin Name:** Antom Payments
**Version:** 2.0.8
**Requires at least:** WordPress 5.3
**Tested up to:** WordPress 6.9
**Requires PHP:** 7.2+
**WC tested up to:** 9.0.0
**Requires Plugins:** WooCommerce
**License:** GPLv2 or later

---

## 🌏 About

Antom's AI-powered payment platform helps businesses grow globally with optimized payment experience and digitalization services. This plugin integrates Antom's payment gateway into WooCommerce, supporting 300+ payment methods across US, APAC, Latam, and the Middle East — Alipay, GCash, KakaoPay, PayPay, PIX, and many more.

## 📖 Documentation Index

| Document | Description |
|---|---|
| [Installation Guide](installation.md) | Step-by-step installation and setup instructions |
| [Configuration Guide](configuration.md) | Core settings, per-method settings, and webhook configuration |
| [Architecture Overview](architecture.md) | Code architecture, layers, and data flow |
| [Payment Methods](payment-methods.md) | Complete list of supported payment methods and currencies |
| [Webhook & API Reference](webhook-api.md) | Webhook handling, payment inquiry, and SDK API reference |
| [Development Guide](development.md) | Build tools, linting, and contribution guidelines |
| [FAQ](faq.md) | Frequently asked questions |
| [Changelog](changelog.md) | Version history |

## ✨ Key Features

- **Dual Checkout Mode** — Supports both WooCommerce Classic Checkout and Block Checkout
- **Antom Elements** — PCI-DSS compliant card payment with embedded card fields (RSA + AES encryption)
- **Hosted Checkout (CKP)** — Cashier Payment page with aggregated local payment methods
- **Sandbox / Live Mode** — Built-in test mode with separate credentials
- **Auto Currency Filtering** — Payment methods display based on store currency
- **Webhook Notification** — Real-time payment result via async notification
- **Payment Inquiry** — Fallback inquiry for edge-case payment status confirmation
- **Refund Support** — Full and partial refunds via Antom API
- **HPOS Compatible** — Supports WooCommerce High-Performance Order Storage

## 📁 Project Structure

```
woo-antom-paymnets/
├── antom-payments-gateway.php              # Plugin entry point (hooks, filters, asset loading)
├── package.json                             # Node dependencies & build scripts
├── webpack.config.js                        # Webpack config for Block JS
├── changelog.txt                            # WordPress.org format changelog
├── readme.txt                               # WordPress.org plugin readme
│
├── includes/                                # PHP backend logic
│   ├── functions.php                        # Common functions, AJAX handlers, session creation
│   ├── class-antom-admin.php                # Admin settings, order filters, save logic
│   ├── class-antom-frontend.php             # Frontend gateway filtering & display
│   ├── antom-payment-gateway-settings.php   # Settings page rendering & payment methods registry
│   ├── antom-payment-gateway-form-api.php   # Form API for payment configuration
│   ├── antom-payment-gateways-statement.php # Constants & API endpoints
│   │
│   ├── gateways/                            # WooCommerce gateway classes
│   │   ├── class-wc-gateway-antom-common.php    # Shared base gateway logic
│   │   ├── class-wc-gateway-antom-payments.php  # CKP (Cashier Payment) gateway
│   │   ├── class-wc-gateway-antom-card.php      # Card payment gateway (Elements)
│   │   └── class-wc-gateway-antom-{method}.php  # Per-method gateway classes
│   │
│   ├── blocks/                              # WooCommerce Block Checkout support
│   │   ├── class-wc-gateway-antom-block-support-common.php
│   │   └── class-wc-gateway-antom-{method}-block-support.php
│   │
│   ├── sdk/                                 # Antom API SDK
│   │   ├── antom-alipay-client.php              # HTTP client (RSA signature + request)
│   │   ├── antom-signature-tool.php             # RSA signature generation/verification
│   │   ├── antom-http-rpc-result.php            # RPC response model
│   │   ├── sdk-antom-alipay-request.php         # Base request builder
│   │   ├── sdk-antom-alipay-online-request.php  # Online payment request builder
│   │   └── sdk-antom-alipay-inquiry-request.php # Payment inquiry request builder
│   │
│   ├── model/                               # Data models
│   │   ├── antom-model-trait.php                # Shared model trait
│   │   ├── order/                               # Order sub-models
│   │   │   ├── antom-order-model.php
│   │   │   ├── antom-order-amount-model.php
│   │   │   ├── antom-order-buyer-model.php
│   │   │   ├── antom-order-env-model.php
│   │   │   ├── antom-order-name-model.php
│   │   │   ├── antom-order-payment-method-model.php
│   │   │   └── antom-order-settlement-strategy-model.php
│   │   └── refund/
│   │       └── antom-refund-model.php
│   │
│   └── utils/                               # Utility functions
│       ├── antom-payment-gateways-options.php   # Options CRUD (singleton pattern)
│       └── antom-payment-request-checker.php    # Payment request ID management
│
├── resource/                                # Frontend source (development)
│   ├── blocks/                              # React components per payment method
│   ├── components/                          # Shared React components
│   │   ├── antom-card-fields.js             # Card fields (Antom Elements SDK)
│   │   ├── card-pay-fields.js               # Card pay integration
│   │   ├── custom-label.js / dynamic-label.js
│   │   ├── default-content.js
│   │   └── test-mode-warning.js
│   ├── hooks/
│   │   └── useAntomPaymentsSettings.js      # React hook for settings
│   └── css/                                 # SCSS source files
│
└── assets/                                  # Build output (compiled static assets)
    ├── blocks/                              # Compiled Block JS + asset.php manifests
    ├── css/                                 # Compiled CSS + source maps
    ├── js/                                  # JS libraries & frontend/backend scripts
    │   ├── admin/AntomPayments.js           # Admin settings React app
    │   ├── frontend/new-antom-payments-gateway-frontend.js
    │   ├── crypto-js.min.js                 # AES encryption (card fields)
    │   ├── jsencrypt.min.js                 # RSA encryption (card fields)
    │   ├── credit-card-type.min.js          # Card brand detection
    │   └── sweetalert2.all.min.js           # Confirmation dialogs
    └── images/                              # Payment method logos & UI icons
        └── CKP/                             # Cashier Payment method logos
```

## 🚀 Quick Start

1. Install and activate the plugin via **Plugins → Add New** in WordPress admin
2. Go to **WooCommerce → Settings → Checkout → Antom Payment Gateway**
3. Configure your **Client ID**, **Private Key**, and **Public Key**
4. Set up the **Webhook URL** in your [Antom Merchant Portal](https://dashboard.alipay.com/global-payments/home)

See the [Installation Guide](installation.md) for detailed instructions.

## 📞 Support

- **Documentation:** [Antom WooCommerce Integration Guide](https://global.alipay.com/docs/ac/plugins/woocommerce)
- **Antom Dashboard:** [dashboard.alipay.com](https://dashboard.alipay.com/global-payments/home)
- **Register:** [Sign up for Antom](https://dashboard.antom.com/global-payments/account/register?bizMode=ISV&isvBizScene=ISO_COMMON&registrationSource=WooCommerce)
- **Email:** global.service@alipay.com

## 📄 License

GPLv2 or later — [http://www.gnu.org/licenses/gpl-2.0.html](http://www.gnu.org/licenses/gpl-2.0.html)