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

# WordPress

> Install and configure the Novac payment plugin to accept payments on your WordPress site.

## Overview

The Novac WordPress plugin enables you to accept payments on your WordPress site using Novac's secure payment gateway. It includes a full admin interface for managing transactions and API settings, flexible frontend options for embedding payment forms, and a robust backend integration that handles webhooks, transaction recording, and REST API communication automatically.

### Prerequisites

<Accordion title="See details" defaultOpen={true}>
  Before you begin, ensure that you have the following:

  * A Novac Business Account with API keys from your [Novac Dashboard](https://www.app.novacpayment.com/login)
  * A WordPress site with admin access
  * Ability to install plugins via the WordPress admin panel or FTP
</Accordion>

### Installation

<Steps>
  <Step title="Step 1 - Upload the Plugin">
    Upload the plugin folder to your WordPress plugins directory:
    /wp-content/plugins/
  </Step>

  <Step title="Step 2 - Activate the Plugin">
    In your WordPress admin panel, go to **Plugins** and activate the Novac Payments plugin.
  </Step>

  <Step title="Step 3 - Open Plugin Settings">
    Navigate to **Novac Payments** in the WordPress admin menu to begin configuration.
  </Step>
</Steps>

***

## Configuration

### API Keys

Your API keys authenticate all communication between your WordPress site and Novac's backend. You'll need both a public and secret key from your dashboard.

1. Get your API keys from the [Novac Dashboard](https://www.app.novacpayment.com/login).
2. Go to **Novac Payments → Settings** in your WordPress admin.
3. Enter your **Public Key** and **Secret Key**.
4. Select your **Mode**, choose **Test** for development or **Live** for production.
5. Copy the generated **Webhook URL** and add it to your Novac dashboard.

### Webhook Setup

The webhook URL allows Novac to send real-time payment notifications to your WordPress site, so transaction statuses are updated automatically after each payment. Configure the following URL in your Novac dashboard:
[https://yoursite.com/?novac-webhook=1](https://yoursite.com/?novac-webhook=1)

Replace `yoursite.com` with your actual WordPress site domain.

***

## Usage

### Using the Shortcode

The `[novac_payment_form]` shortcode lets you embed a payment form on any page, post, or widget area. There are three ways to use it depending on your needs.

1. **Basic form**: lets the customer enter their own amount: \[novac\_payment\_form]

2. **Fixed amount form**: pre-sets the amount and describes what the payment is for

```
[
    novac_payment_form amount="1000" 
    currency="NGN" 
    description="Product 
    Purchase" 
    button_text="Pay Now"
]
 
```

3. **Fully customized form**: applies custom brand colors to the form container, button, and text

```
 [ 
    novac_payment_form amount="1000" 
    currency="NGN" description="Product Purchase" 
    button_text="Pay Now" 
    text_color="#F4F4F5" 
    container_color="#111827" 
    button_color="#EAB308" 
    button_text_color="#111827"
]
```

#### Shortcode Parameters

| Parameter           | Description                                                           | Default   |
| ------------------- | --------------------------------------------------------------------- | --------- |
| `amount`            | Fixed payment amount. Leave empty to let the customer enter their own | —         |
| `currency`          | Currency code                                                         | `NGN`     |
| `description`       | Payment description shown on the form                                 | `Payment` |
| `button_text`       | Label on the payment button                                           | `Pay Now` |
| `text_color`        | Color of form text                                                    | `#111111` |
| `container_color`   | Background color of the form container                                | —         |
| `button_color`      | Background color of the payment button                                | —         |
| `button_text_color` | Color of the text on the payment button                               | —         |

***

### Using the Gutenberg Block

If you use the WordPress block editor, you can add the payment form as a block instead of a shortcode.

1. In the block editor, click the **(+)** button to add a new block.
2. Search for **Novac Payment Form**.
3. Add the block to your page.
4. Use the **block inspector panel** on the right to configure:
   * Fixed amount (optional)
   * Currency
   * Payment description
   * Button text

***

### Managing Transactions

All payments processed through the plugin are recorded automatically and accessible from the WordPress admin.

1. Go to **Novac Payments → Transactions**.
2. Each transaction entry shows:
   * Transaction reference
   * Customer information
   * Amount and currency
   * Payment status
   * Date and time
3. Use the **search bar** to look up transactions by email, name, or reference.
4. Use the **status filter** to narrow results by Successful, Pending, or Failed.
5. Navigate large transaction lists using **pagination**.

***

## Payment Flow

Understanding the full payment lifecycle helps with debugging and verifying your integration.

```mermaid theme={null}
sequenceDiagram
    actor Customer
    participant Form as Payment Form
    participant WP as WordPress
    participant Novac as Novac API
    participant Webhook as Webhook Handler

    Customer->>Form: Fills out payment form
    Form->>WP: Submits via AJAX (no page reload)
    WP->>Novac: Initiates checkout session
    Novac-->>WP: Returns checkout session URL
    WP-->>Customer: Redirects to Novac payment page
    Customer->>Novac: Completes payment
    Novac->>Webhook: Sends webhook notification
    Webhook->>WP: Verifies & updates transaction status
    WP-->>Customer: Redirects back with payment result
```

***

## API Reference

### Settings Endpoints

Use these REST API endpoints to read or update your plugin settings programmatically.

| Method | Endpoint                     | Description                      |
| ------ | ---------------------------- | -------------------------------- |
| `GET`  | `/wp-json/novac/v1/settings` | Retrieve current plugin settings |
| `POST` | `/wp-json/novac/v1/settings` | Update plugin settings           |

### Transaction Endpoints

| Method | Endpoint                              | Description                                                  |
| ------ | ------------------------------------- | ------------------------------------------------------------ |
| `GET`  | `/wp-json/novac/v1/transactions`      | List all transactions with pagination, search, and filtering |
| `GET`  | `/wp-json/novac/v1/transactions/{id}` | Retrieve a single transaction by ID                          |

***

## Advanced Usage

### Database

The plugin automatically creates a `wp_novac_transactions` table in your WordPress database when activated. This table stores the following for each transaction:

* Transaction reference
* Customer information (email, name)
* Amount and currency
* Payment status and method
* Metadata and timestamps

### Roles & Permissions

The plugin introduces custom capabilities for fine-grained access control, and creates two dedicated roles so you can grant team members access without giving them full admin rights.

**Custom capabilities:**

| Capability                  | Description                                         |
| --------------------------- | --------------------------------------------------- |
| `novac_manage_settings`     | Configure API keys and plugin settings              |
| `novac_view_transactions`   | View the transactions list                          |
| `novac_refund_transactions` | Process refunds *(reserved for future use)*         |
| `novac_export_transactions` | Export transaction data *(reserved for future use)* |

**Custom roles:**

| Role                      | Access                             |
| ------------------------- | ---------------------------------- |
| **Novac Payment Manager** | Full access to all plugin features |
| **Novac Finance Analyst** | View and export transactions only  |

Administrators automatically receive all capabilities.

***

## Development

### Building Assets

The plugin's admin interface and Gutenberg block are built from source using Node.js and Composer. Run the following commands from the plugin root to compile all assets:

```bash theme={null}
composer install
npm install
npm run build
```

This produces compiled output in two locations:

* Admin React app → `includes/admin/build/`
* Gutenberg block → `includes/blocks/build/`

### File Structure

<Tree>
  <Tree.Folder name="novac" defaultOpen>
    <Tree.Folder name="includes" defaultOpen>
      <Tree.Folder name="admin">
        <Tree.Folder name="src" />

        <Tree.Folder name="build" />
      </Tree.Folder>

      <Tree.Folder name="api" />

      <Tree.Folder name="blocks">
        <Tree.Folder name="src" />

        <Tree.Folder name="build" />
      </Tree.Folder>

      <Tree.Folder name="database" />

      <Tree.Folder name="frontend" />

      <Tree.Folder name="users" />

      <Tree.Folder name="webhooks" />
    </Tree.Folder>

    <Tree.Folder name="frontend">
      <Tree.Folder name="css" />

      <Tree.Folder name="js" />
    </Tree.Folder>

    <Tree.File name="novac.php" />
  </Tree.Folder>
</Tree>