Release/v5.0.0 #397

New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
lalit-swain-cko merged 90 commits into master from release/v5.0.0
Dec 17, 2025
README.md
            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -1,63 +1,318 @@
  
    [![N|Solid](https://cdn.checkout.com/img/checkout-logo-online-payments.jpg)](https://checkout.com/)

    # Checkout.com WooCommerce Plugin - Flow Integration

    # Woocommerce Extension

    [Checkout.com](https://www.checkout.com "Checkout.com") is a software platform that has integrated 100% of the value chain to create payment infrastructures that truly make a difference.

    Checkout.com Payment Gateway plugin for WooCommerce with Flow integration support.

    This extension allows shop owners to process online payments (card / alternative payments) using:

      - **Frames.js** - Customisable payment form, embedded within your website

      - **Apple Pay & Google Pay** - Shoppers can pay using mobile wallets

      - **Alternative payments** - Shoppers can pay using local payment options (Sofort, iDEAL, Boleto ... etc.)

    ## Version

    # Installation

    You can find a full installation guide [here](https://github.com/checkout/checkout-woocommerce-plugin/wiki/Installation)

    **Current Version:** 5.0.0

    # Initial Setup

    If you do not have an account yet, simply go to [checkout.com](https://checkout.com/) and hit the "Get Test Account" button.

    ## Features

    # Keys

    There are 3 keys to configure in the module:

    - **Secret Key**

    - **Public Key**

    - **Private Shared Key** (not required if using v4.2.0+ of our WooCommerce plugin)

    ### Flow Integration

    - **Checkout.com Flow** - Modern, secure payment processing using Checkout.com's Flow Web Components

    - **Saved Cards** - Customers can save payment methods for future use

    - **3D Secure (3DS)** - Full support for 3D Secure authentication

    - **Card Validation** - Real-time card validation before order creation

    - **Webhook Processing** - Reliable webhook handling with queue system

    - **Order Management** - Automatic order status updates based on payment status

    > The Private Shared Key is generated when you [configure the Webhook URL](https://docs.checkout.com/the-hub/manage-webhooks) in the Checkout HUB.

    ### Payment Methods Supported

    - Credit/Debit Cards (via Flow)

    - Saved Payment Methods

    - Apple Pay

    - Google Pay

    - PayPal

    - Alternative Payment Methods (APMs)

    # Webhook

    In order to keep WooCommerce order statuses in sync you need to configure the following webhook URL in your Checkout HUB (where _example.com_ is your store URL):

    ## Installation

    > The following URL format is for plugins versions 4.X or newer; click [here](https://github.com/checkout/checkout-woocommerce-plugin/wiki/URLs--2.x) to get the URLs for older plugin versions

    1. Download the plugin zip file: `checkout-com-unified-payments-api.zip`

    2. Go to WordPress Admin → Plugins → Add New → Upload Plugin

    3. Upload the zip file

    4. Activate the plugin

    5. Configure your Checkout.com credentials in WooCommerce → Settings → Payments → Checkout.com Payment

    ## Configuration

    | URL Example | API Version | Events |

    | ------ | ------ | ------ |

    | _example.com_**/?wc-api=wc_checkoutcom_webhook** &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | 2.0 | All |

    ### Required Settings

    > You can see a guide on how to manage webhooks in the HUB [here](https://docs.checkout.com/the-hub/manage-webhooks) ; You can find test card details [here](https://docs.checkout.com/testing)

    1. **Secret Key** - Your Checkout.com secret key

    2. **Public Key** - Your Checkout.com public key

    3. **Webhook URL** - Configure in Checkout.com Hub:

       ```

       https://your-site.com/?wc-api=wc_checkoutcom_webhook

       ```

    # Going LIVE

    ### Flow Integration Settings

    Upon receiving your live credentials from your account manager, here are the required steps to start processing live transactions:

    - Enable Flow payment method

    - Configure Flow appearance and behavior

    - Set up saved cards functionality

    - Configure 3DS settings

    - In the plugin settings, input your **Live** keys

    - Switch the _Endpoint URL mode_ to **Live**.

    ## Flow Integration Details

    # Development environment Setup

    ### Overview

    - Clone the repository to in `wp-content/plugins` folder with the name `woocommerce-gateway-checkout-com`

      `git clone git@github.com:checkout/checkout-woocommerce-plugin.git woocommerce-gateway-checkout-com`

      or

      `git clone https://github.com/checkout/checkout-woocommerce-plugin.git woocommerce-gateway-checkout-com`

    - Use required `npm` version by executing `nvm use`.

    - Install the `npm` packages using `npm install`.

    - Install the `composer` packages using `composer install`.

    - During pushing the committing the code the PHPCS check will run at pre-commit hook. **So, till the PHPCS errors are not fixed for during commit we have to use `--no-verify` option in the git commit command.**

    The Flow integration provides a modern, secure payment experience using Checkout.com's Flow Web Components. This integration ensures reliable payment processing with comprehensive validation, webhook handling, and order management.

    ### How Flow Integration Works

    # Reference

    The payment flow follows these steps:

    You can find our complete Documentation [here](http://docs.checkout.com/).

    If you would like to be assigned an account manager, please contact us at sales@checkout.com

    For help during the integration process you can contact us at integration@checkout.com

    For support, you can contact us at support@checkout.com

    #### Step 1: Checkout Page Load

    - Customer fills out billing and shipping information

    - Flow payment method is selected

    - Flow Web Component is initialized and mounted

    _Checkout.com is authorised and regulated as a Payment institution by the UK Financial Conduct Authority._

    #### Step 2: Order Creation (Before Payment)

    - **Why Early?** Orders are created via AJAX before payment processing begins

    - This ensures the order exists in the database for webhook matching

    - Order status: `Pending payment`

    - Payment session ID is stored with the order

    #### Step 3: Payment Session Creation

    - Payment session is created with Checkout.com API

    - Session includes order details, customer information, and amount

    - Payment session ID is returned and stored

    #### Step 4: Flow Component Validation

    - **Client-Side Validation**: Flow component validates card details in real-time

    - Card number, expiry, CVV are validated before submission

    - Invalid cards are rejected before payment attempt

    #### Step 5: Payment Processing

    - Customer submits payment through Flow component

    - Payment is processed securely through Checkout.com

    - For 3D Secure: Customer is redirected for authentication

    - Payment result is returned

    #### Step 6: Webhook Processing

    - Checkout.com sends webhook with payment status

    - Webhook is matched to order using:

      1. Order ID from metadata (primary)

      2. Payment Session ID + Payment ID (secondary)

      3. Payment ID alone (fallback)

    - If order not found immediately, webhook is queued for later processing

    #### Step 7: Order Status Update

    - Order status is automatically updated based on payment result:

      - ✅ **Payment Approved** → Order status: `Processing`

      - ✅ **Payment Captured** → Order status: `Processing` (if not already)

      - ❌ **Payment Declined** → Order status: `Failed`

      - ⏸️ **Payment Cancelled** → Order status: `Cancelled`

    ### Key Features Explained

    #### 🔒 Early Order Creation

    **What it does:** Creates the WooCommerce order before payment processing begins.

    **Why it's important:**

    - Ensures webhooks can always find the order

    - Prevents webhook matching failures

    - Allows order tracking throughout the payment process

    **How it works:**

    - Order is created via AJAX when customer clicks "Place Order"

    - Order is saved with `Pending payment` status

    - Payment session ID is stored for webhook matching

    #### ✅ Dual Validation System

    **Client-Side Validation:**

    - Flow component validates card details in real-time

    - Prevents invalid cards from being submitted

    - Provides instant feedback to customers

    **Server-Side Validation:**

    - Comprehensive validation of all checkout fields

    - Validates billing/shipping addresses

    - Ensures data integrity before order creation

    - Blocks order creation if validation fails

    #### 🚫 Duplicate Prevention

    **Problem:** Multiple clicks or slow networks can cause duplicate orders.

    **Solution:**

    - Client-side lock prevents multiple simultaneous requests

    - Server-side check prevents duplicate orders with same payment session ID

    - If duplicate detected, existing order is returned instead of creating new one

    #### 📬 Webhook Queue System

    **Problem:** Webhooks might arrive before order is fully saved to database.

    **Solution:**

    - Webhook queue temporarily stores webhooks if order not found

    - Queue is processed when order becomes available

    - Ensures no webhooks are lost

    - Automatic retry mechanism

    #### 🔐 3D Secure (3DS) Support

    **How it works:**

    1. Payment requires 3DS authentication

    2. Customer is redirected to bank's 3DS page

    3. Customer completes authentication

    4. Customer is redirected back to store

    5. Payment status is confirmed via webhook

    6. Order status is updated accordingly

    **Features:**

    - Automatic 3DS detection

    - Seamless redirect flow

    - Webhook handling after 3DS return

    - Prevents duplicate status updates

    #### 💳 Saved Cards

    **How it works:**

    1. Customer opts to save card during checkout

    2. Card is tokenized securely by Checkout.com

    3. Token is stored in customer's account

    4. Saved cards appear on future checkouts

    5. Customer can select saved card for quick checkout

    **Security:**

    - Cards are never stored on your server

    - Only secure tokens are stored

    - PCI compliance handled by Checkout.com

    - Cards can be deleted by customer

    ### Payment Flow Diagram

    ```

    Customer Checkout

        ↓

    Fill Billing/Shipping Info

        ↓

    Select Flow Payment Method

        ↓

    Click "Place Order"

        ↓

    [VALIDATION] Client-Side + Server-Side

        ↓

    [ORDER CREATED] Status: Pending payment

        ↓

    Create Payment Session with Checkout.com

        ↓

    [FLOW COMPONENT] Card Details Entered

        ↓

    [VALIDATION] Flow Component Validates Card

        ↓

    Submit Payment

        ↓

    [3DS?] If Required → Redirect → Authenticate → Return

        ↓

    Payment Processed

        ↓

    [WEBHOOK] Payment Status Received

        ↓

    Match Webhook to Order

        ↓

    Update Order Status

        ↓

    [COMPLETE] Order Status: Processing/Failed

    ```

    ### Technical Architecture

    #### Frontend (JavaScript)

    - **payment-session.js**: Handles order creation, payment session, Flow component integration

    - **flow-container.js**: Manages Flow component container and initialization

    - **flow-customization.js**: Customizes Flow component appearance and behavior

    #### Backend (PHP)

    - **class-wc-gateway-checkout-com-flow.php**: Main gateway class, handles payment processing

    - **Webhook Handler**: Processes incoming webhooks and updates orders

    - **Webhook Queue**: Manages webhook queuing system

    #### Database

    - Order meta stores: Payment Session ID, Payment ID, Webhook IDs

    - Webhook queue table: Temporary storage for unmatched webhooks

    ## Webhook Configuration

    Configure the following webhook URL in your Checkout.com Hub:

    ```

    https://your-site.com/?wc-api=wc_checkoutcom_webhook

    ```

    ### Webhook Events Supported

    - `payment_approved`

    - `payment_captured`

    - `payment_declined`

    - `payment_cancelled`

    - `payment_voided`

    - `payment_refunded`

    ## Development

    ### Building the Plugin

    Use the build script to create the plugin zip:

    ```bash

    ./bin/build.sh

    ```

    This will create `checkout-com-unified-payments-api.zip` with the correct WordPress plugin structure.

    ### File Structure

    ```

    checkout-com-unified-payments-api/

    ├── woocommerce-gateway-checkout-com.php  # Main plugin file

    ├── flow-integration/                      # Flow integration

    │   ├── class-wc-gateway-checkout-com-flow.php

    │   └── assets/

    │       ├── js/

    │       │   ├── payment-session.js

    │       │   ├── flow-container.js

    │       │   └── flow-customization.js

    │       └── css/

    │           └── flow.css

    ├── includes/                              # Core functionality

    │   ├── api/

    │   ├── settings/

    │   ├── admin/

    │   └── ...

    ├── assets/                                # Frontend assets

    ├── lib/                                   # Libraries

    └── vendor/                                # Composer dependencies

    ```

    ## Requirements

    - WordPress 5.0+

    - WooCommerce 3.0+

    - PHP 7.3+

    - SSL Certificate (required for production)

    ## Support

    For support and integration help:

    - **Integration Support**: integration@checkout.com

    - **General Support**: support@checkout.com

    - **Sales**: sales@checkout.com

    ## License

    MIT License

    ## Changelog

    ### Version 5.0.0

    - Initial Flow integration release

    - Complete Flow Web Components integration

    - Saved cards functionality

    - 3D Secure support

    - Webhook queue system

    - Enhanced order management

    - Comprehensive validation and error handling

    ## Documentation

    For detailed documentation, visit: [Checkout.com Documentation](https://docs.checkout.com)

    ---

    **Checkout.com** is authorised and regulated as a Payment institution by the UK Financial Conduct Authority.
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Release/v5.0.0 #397

Uh oh!

Diff view

Diff view

Uh oh!

There are no files selected for viewing

Uh oh!

Uh oh!
