Kiot Analytics

# Payoo Payment Gateway for WooCommerce

Transform your WooCommerce store with seamless Payoo payment integration. Payoo Payment Gateway is a professional WordPress plugin that enables your customers to pay via ATM cards, QR codes, Visa/Mastercard, and popular Vietnamese e-wallets through Payoo’s secure payment infrastructure.

## Overview

Payoo Payment Gateway seamlessly integrates Payoo’s multi-channel payment system into your WooCommerce store. Built with WordPress best practices and following WooCommerce payment gateway standards, this plugin provides a secure, reliable, and user-friendly online payment solution for Vietnamese customers. Supports both Redirect (hosted page) and IPN (server-to-server notification) payment flows.

## Key Features

### Payment Methods

– **ATM / Internet Banking**: Accept payments from all major Vietnamese bank cards

– **QR Code Payment**: Support QR-based payment through banking apps

– **Visa / Mastercard**: International credit and debit card acceptance

– **E-wallets**: Support popular Vietnamese e-wallets (MoMo, ZaloPay, ShopeePay, etc.)

– **One-stop Checkout**: All payment methods available through a single Payoo hosted page

### Payment Gateway Features

– **WooCommerce Integration**: Full WooCommerce payment gateway standard compliance

– **HPOS Compatible**: High-Performance Order Storage (Custom Order Tables) fully supported

– **Secure Checksum Validation**: All transactions verified via industry-standard checksum

– **IPN (Instant Payment Notification)**: Server-to-server payment status notification

– **Redirect Callback**: Customer redirect after payment completion with status verification

– **Sandbox & Production Modes**: Test your integration safely before going live

– **Auto Order Status Update**: Orders automatically updated on payment success/failure

– **Duplicate Transaction Prevention**: Built-in protection against double processing

– **Configurable Success Status**: Choose between “Processing” or “Completed” for successful payments

### Admin Features

– **Easy Configuration**: Simple setup through WooCommerce → Settings → Payments

– **Credential Management**: Secure storage of merchant API credentials

– **Webhook URL Display**: Automatic IPN and Return URL generation for Payoo dashboard

– **Export / Import Settings**: Back up and restore plugin settings with one click

– **API Connection Ready**: Environment switching between sandbox and production

– **Comprehensive Logging**: Detailed transaction and error logs via WooCommerce Logger

– **Uninstall Management**: Option to keep or delete data on plugin removal

### Security Features

– **Checksum Validation**: Every request/response verified with HMAC checksum

– **Input Sanitization & Output Escaping**: Follows WordPress WPCS security standards

– **Nonce Verification**: CSRF protection for all admin actions and AJAX requests

– **SSL Enforcement**: SSL required in production; auto-disabled in sandbox mode

– **Capability Checks**: Admin-only access for all sensitive settings

– **No Sensitive Data Leakage**: Internal errors logged separately, user-friendly messages displayed

## Technical Specifications

### Requirements

– **WordPress**: 6.4 or higher

– **WooCommerce**: 8.0 or higher

– **PHP**: 8.2 or higher

– **SSL Certificate**: Required for production environment

– **Payoo Merchant Account**: Active Payoo merchant account with API credentials

### Technology Stack

– **Framework**: WordPress Plugin API + WooCommerce Payment Gateway Standard

– **Namespace**: PSR-4 autoloading (`TheninePayooGateway`)

– **API Integration**: Payoo Hosted Payment Model (PayooHosted API)

– **Database**: WordPress database abstraction ($wpdb) — HPOS compatible

– **Security**: Nonce verification, data sanitization, checksum validation, output escaping

– **Logging**: WooCommerce Logger (WC_Logger)

### API Features

– **Payment URL Generation**: Create a Payoo hosted payment URL for each order

– **Redirect Callback Verification**: Validate return URL checksum for customer redirect

– **IPN Callback Verification**: Verify server-to-server SecureHash for payment notifications

– **Multi-environment Support**: Separate sandbox and production API endpoints

– **SSL-aware HTTP client**: SSL verification enabled in production, disabled in sandbox

### Plugin Architecture

– `src/Gateway/PayooGateway.php` — Main payment gateway class

– `src/API/Client.php` — Payoo API HTTP client

– `src/Webhooks/RedirectHandler.php` — Handles customer return after payment

– `src/Webhooks/IPNHandler.php` — Handles server-to-server IPN notifications

– `src/Admin/SettingsManager.php` — Export/Import settings, admin scripts

– `src/Includes/Logger.php` — WooCommerce-based logging utility

– `src/Includes/Validator.php` — Input validation utility

– `uninstall.php` — Safe data cleanup on plugin removal

## Installation & Setup

### Quick Start

1. Upload the plugin folder to `/wp-content/plugins/thenine-payoo-gateway/`

2. Activate the plugin through **WordPress Admin → Plugins**

3. Navigate to **WooCommerce → Settings → Payments**

4. Enable **Payoo Payment Gateway**

5. Configure your Payoo merchant credentials

6. Copy IPN URL and Return URL and configure them in your Payoo merchant dashboard

7. Test in Sandbox mode

8. Switch to Production when ready

### Configuration Steps

1. **Obtain Payoo Credentials**:

– Register at [Payoo Developers Portal](https://developers.payoo.vn/)

– Obtain: Business Username, Shop ID, Shop Title, Checksum Key

– Obtain API credentials: API Username, API Password (for BizAPI)

2. **Configure Plugin Settings**:

– Enable the payment gateway

– Enter all API credentials

– Choose Sandbox or Production environment

– Set display title and description for checkout page

3. **Configure Webhooks in Payoo Dashboard**:

– Copy the **IPN URL (Notify URL)** from plugin settings

– Copy the **Return URL (Redirect URL)** from plugin settings

– Paste both into your Payoo merchant dashboard → API settings

4. **Test Integration**:

– Enable Test Mode

– Use Payoo sandbox credentials

– Create a test order and complete payment

– Verify order status updates correctly

5. **Go Live**:

– Switch to Production environment

– Update to production API credentials

– Monitor transactions via WooCommerce → Status → Logs

## Payment Flow

### Customer Checkout Flow

1. Customer selects **Payoo** at WooCommerce checkout

2. Customer is redirected to Payoo hosted payment page

3. Customer selects payment method (ATM, QR, Visa/Master, e-wallet) and completes payment

4. Customer is redirected back to the shop with payment status (Redirect callback)

5. Separately, Payoo sends a server-to-server IPN notification to confirm payment

### IPN (Server-to-Server) Flow

1. Payoo sends POST request to IPN URL

2. Plugin verifies SecureHash/checksum for authenticity

3. Plugin updates order status based on payment result

4. Plugin sends acknowledgement response back to Payoo

> **Important**: Always rely on the IPN notification as the authoritative payment confirmation, not the customer redirect callback.

## Perfect For

– **E-commerce Stores** selling to Vietnamese customers

– **Retail Businesses** needing multi-channel payment acceptance

– **Service Providers** accepting online payments in Vietnam

– **International Businesses** targeting the Vietnamese market

– **B2C Online Stores** requiring ATM, QR, and card payment options

– **Mobile Commerce** — fully mobile-optimized Payoo payment page

## Benefits

✅ **Increase Sales** — Accept all popular Vietnamese payment methods in one gateway

✅ **Higher Conversion** — Familiar Payoo checkout reduces payment friction

✅ **Secure Transactions** — Bank-level security via Payoo’s trusted infrastructure

✅ **Easy Integration** — Simple setup, no custom coding required

✅ **HPOS Ready** — Future-proof with WooCommerce High-Performance Order Storage

✅ **Developer Friendly** — Clean PSR-4 namespaced codebase, fully documented

✅ **Reliable Notifications** — Dual confirmation via IPN + Redirect callback

## Security & Compliance

– **WordPress Coding Standards (WPCS)**: Full compliance

– **Data Sanitization**: All inputs sanitized on entry

– **Output Escaping**: All output escaped before rendering

– **SQL Injection Prevention**: Uses `$wpdb->prepare()` for all queries

– **Nonce Verification**: CSRF protection for all admin forms and AJAX

– **Secure API Communication**: HTTPS-only API endpoints (SSL enforced in production)

– **Checksum Validation**: All Payoo requests/responses verified with HMAC checksum

– **Capabilities Check**: `manage_woocommerce` capability required for admin access

– **No Debug Code in Production**: Error logging conditional on `WP_DEBUG`

## Supported Payment Methods via Payoo

– **ATM / Debit Cards** — All major Vietnamese banks

– **QR Code** — VietQR-compatible banking apps

– **Visa / Mastercard** — International cards

– **E-wallets** — MoMo, ZaloPay, ShopeePay, and more

– **Banking Apps** — Mobile banking of supported banks

## Support & Documentation

– **Documentation**: Included in plugin package (see `payoo-integration-guide.pdf`)

– **Payoo API Reference**: [https://developers.payoo.vn/](https://developers.payoo.vn/)

– **Support Email**: support@thenine.store

– **Website**: [https://thenine.store](https://thenine.store)

– **GitHub**: [https://github.com/thenine-ltd/payoo-payment-gateway](https://github.com/thenine-ltd/payoo-payment-gateway)

## What’s Included

– Complete plugin source code (PSR-4, namespaced, WPCS compliant)

– Payoo Hosted Payment API integration

– Multi-method payment support (ATM, QR, Visa/Master, e-wallets)

– IPN + Redirect dual callback handling

– HPOS-compatible order management

– Admin settings export/import system

– Comprehensive WooCommerce logging

– Sandbox and production environment support

– Internationalization support (i18n ready, `.pot` file included)

– Safe uninstall with data preservation option

– English documentation + Payoo integration guide PDF

## Use Cases

### Scenario 1: Vietnamese Online Retailer

1. Enable Payoo gateway in WooCommerce

2. Configure merchant credentials from Payoo dashboard

3. Customers pay via ATM card, QR code, or e-wallet at checkout

4. Orders are automatically updated to “Processing” on successful payment

5. Track all transactions in WooCommerce orders

### Scenario 2: International Brand Entering Vietnam

1. Enable production mode with Payoo credentials

2. Accept Visa/Mastercard for international customers

3. Also accept local ATM and QR payments for Vietnamese customers

4. Monitor payment logs via WooCommerce → Status → Logs

### Scenario 3: High-Volume Store

1. Use IPN for authoritative order fulfillment triggers

2. Export settings for backup before updates

3. Enable WP_DEBUG for detailed logging during testing

4. Switch to “Completed” status immediately after payment for digital goods

## Changelog

### Version 1.0.0

– Initial release

– Payoo Hosted Payment Model integration

– ATM, QR, Visa/Master, E-wallet support

– IPN and Redirect callback handling

– HPOS compatibility

– Settings Export/Import

– Configurable success order status (Processing / Completed)

– Sandbox and Production modes

– WooCommerce Logger integration

– Full WPCS compliance

– English language UI + Vietnamese translation ready

## Get Started Today

Integrate Payoo’s trusted payment infrastructure into your WooCommerce store. Accept ATM cards, QR codes, Visa/Mastercard, and Vietnamese e-wallets — all through a single, secure, and easy-to-configure payment gateway. Install Payoo Payment Gateway for WooCommerce and start accepting payments today!

—

**Plugin Name**: Payoo Payment Gateway for WooCommerce

**Version**: 1.0.0

**Author**: The Nine

**Author URI**: https://thenine.store

**Plugin URI**: https://thenine.store/payoo-payment-gateway

**License**: GPL v2 or later

**Requires**: WordPress 6.4+, WooCommerce 8.0+, PHP 8.2+

**Payoo Integration**: Hosted Payment Model (PayooHosted API)

**Text Domain**: thenine-payoo-gateway