> ## Documentation Index
> Fetch the complete documentation index at: https://docs.khaime.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Flow

> How payments are processed in the WooCommerce plugin.

# WooCommerce Payment Flow

## Checkout Compatibility

KhaimePay works with both WooCommerce checkout types:

* **Classic checkout** — The traditional shortcode-based checkout (`[woocommerce_checkout]`)
* **Block-based checkout** — The modern Gutenberg block checkout (default since WooCommerce 8.3+)

No additional configuration is needed — the plugin registers with both automatically.

## Checkout Process

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant W as WooCommerce
    participant K as Khaime API
    participant G as Gateway

    C->>W: Place Order
    W->>K: POST /payments/charge
    K-->>W: charge_id + gateway info

    alt Stripe
        W->>C: Render Payment Element
        C->>G: Enter card details
        G->>C: Redirect to return_url
    else Paystack
        W->>C: Redirect to payment_url
        C->>G: Complete payment
        G->>C: Redirect to callback_url
    end

    C->>W: Return to thank-you page
    W->>K: Verify payment
    K-->>W: Payment confirmed
    W->>C: Order complete
    K->>W: Webhook confirmation
```

## Step by Step

### 1. Customer Places Order

Customer fills in billing details and clicks "Place Order" with KhaimePay selected.

### 2. Charge Created

The plugin sends a charge request to Khaime with:

* **Amount**: The exact order total the customer sees at checkout (in their currency, minor units)
* **Currency**: Customer's active currency
* **Baseline amount**: The equivalent amount in your store's pricing currency
* **Customer info**: Email and name from the WooCommerce order
* **Metadata**: WooCommerce order ID, line items, and site URL
* **Callback URL**: Where to redirect after payment

<Note>
  The charge amount is taken directly from the WooCommerce order total, which includes all product prices, addon surcharges, shipping, fees, and taxes — already converted to the customer's currency. This ensures the charge matches exactly what the customer saw.
</Note>

### 3. Gateway Routing

Khaime returns the charge details including which gateway will process it:

* **Stripe**: Plugin renders a Stripe Payment Element on the order-pay page where the customer enters card details
* **Paystack**: Plugin redirects the customer to Paystack's hosted payment page

### 4. Payment Completion

* **Stripe**: Customer completes payment in the embedded form. Stripe redirects to the return URL.
* **Paystack**: Customer pays on Paystack's page. Paystack redirects to the callback URL.

### 5. Verification

On return, the plugin verifies the payment:

* **Paystack**: Verifies the transaction reference with the Khaime API. If the API is unavailable, the order is set to on-hold pending webhook confirmation.
* **Stripe**: Checks the payment status from URL parameters.

### 6. Webhook Confirmation

Khaime sends a `payment.succeeded` webhook to your store. The plugin:

* Verifies the HMAC signature
* Checks for duplicate events
* Marks the WooCommerce order as paid
* Stores the transaction ID and payment details

## Refunds

The plugin supports WooCommerce's built-in refund flow. When you initiate a refund from the order admin page:

1. The plugin sends a refund request to the Khaime API
2. On success, the refund ID is stored on the order
3. An order note is added with the refund details

Khaime also sends a `refund.completed` webhook when the refund is processed, adding a confirmation note to the order.

## Order Metadata

After payment, the plugin stores these fields on the WooCommerce order for reference:

| Field                  | Description                                                 |
| ---------------------- | ----------------------------------------------------------- |
| Charge ID              | Unique Khaime charge identifier                             |
| Payment Gateway        | Which gateway processed the payment (e.g. Stripe, Paystack) |
| Transaction ID         | Khaime transaction ID                                       |
| Environment            | Whether the payment was sandbox or live                     |
| Customer Paid Amount   | The amount the customer actually paid                       |
| Customer Paid Currency | The currency the customer paid in                           |

Gateway-specific fields (Stripe client secret, Paystack reference, etc.) are also stored for payment verification.