> For the complete documentation index, see [llms.txt](https://pivot-payment.gitbook.io/pivot-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pivot-payment.gitbook.io/pivot-docs/for-developers/third-party-integrations/pivot-payment-gateway-for-woocommerce.md).

# Pivot Payment Gateway for WooCommerce

Official plugin to integrate Pivot payment methods into WooCommerce. This plugin allows merchants to accept payments via Pivot using hosted Payment UI redirection.

### 📋 Table of Contents

* System Requirements
* Installation
* Configuration
* How to Use
* Advanced Settings
* Testing
* Troubleshooting
* FAQ
* Support

### 🔧 System Requirements

Before installing the plugin, make sure your system meets the following requirements:

* **WordPress**: Version 6.0 or higher
* **WooCommerce**: Version 7.0 or higher (tested up to version 9.0)
* **PHP**: Version 7.4 or higher
* **Pivot Account**: Valid Merchant ID and Merchant Secret from Pivot
* **SSL Certificate**: Required for transaction security (HTTPS)

### 📦 Installation

#### Method 1: Upload via WordPress Admin

1. Log in to the WordPress Admin Dashboard
2. Navigate to **Plugins → Add New**
3. Click **Upload Plugin**
4. Select the plugin ZIP file `pivot-payment-gateway.zip`  [\[download here\]](https://drive.google.com/file/d/1NpldVahiHKxkJZmG2Z3y4Cwc7Tf-KxIo/view?usp=drive_link)
5. Click **Install Now**
6. After installation completes, click **Activate Plugin**

#### Method 2: Upload via FTP

1. Extract the plugin ZIP file [\[download here\]](https://drive.google.com/file/d/1NpldVahiHKxkJZmG2Z3y4Cwc7Tf-KxIo/view?usp=drive_link)
2. Upload the `pivot-payment-gateway` folder to the `/wp-content/plugins/` directory
3. Log in to the WordPress Admin Dashboard
4. Navigate to **Plugins**
5. Activate the **Pivot Payment Gateway for WooCommerce** plugin

### ⚙️ Configuration

#### Step 1: Enable the Payment Gateway

1. Log in to the WordPress Admin Dashboard
2. Navigate to **WooCommerce → Settings → Payments**
3. Find **Pivot** in the list of payment methods
4. Click **Manage** or **Set up**
5. Check the **Enable Pivot Payment** checkbox
6. Click **Save changes**

#### Step 2: Basic Configuration

**1. Title & Description**

* **Title**: Payment method name displayed at checkout (default: "Pivot Payment")
* **Description**: Description shown to customers on the checkout page

**2. Test Mode**

* **Enable Test Mode**: Enable for testing in the sandbox environment
  * Check to use the Sandbox API
  * Uncheck to use the Live API (production)

**3. API Configuration**

**Sandbox API Base URL** (for testing): `https://sandbox-api.pivot-payments.com`

**Live API Base URL** (for production): `https://api.pivot-payments.com`

**4. Credentials**

**Merchant ID**:

* Obtain from your Pivot dashboard
* Used to generate access tokens
* Format: Alphanumeric string

**Merchant Secret**:

* Obtain from your Pivot dashboard
* Used together with the Merchant ID for authentication
* **IMPORTANT**: Do not share this credential with anyone

**Callback API Key (X-API-Key)**:

* Dedicated Callback API Key for verifying webhooks from Pivot
* Obtain from your Pivot dashboard
* Used to validate callback requests
* Callback URL: `https://your-site.com/pivot/payment-callback`

**5. Sub-account (Optional)**

**Sub-account ID**:

* Sub-account UUID if you use the sub-account management feature
* Leave empty if not using sub-accounts
* [Learn more about Sub-accounts](https://pivot-payment.gitbook.io/pivot-docs/api-references/api-lists/account-and-balance/sub-account-management/activity-on-behalf-of-sub-account)

**6. Payment Session Expiry**

**Payment Session Expiry (Minutes)**:

* Time in minutes before the payment session expires
* Customers must complete payment within this time
* Range: 1 minute up to 5 days (43200 minutes)
* Default: 15 minutes
* Recommended: 15–30 minutes for normal transactions

**7. Refresh Payment Status Settings**

**Enable Refresh in Admin**:

* Enable to show a refresh payment status button on the admin order details page
* Default: Enabled
* Useful if order status is not automatically updated via callback

#### Step 3: Save Configuration

1. Fill in all required fields
2. Click **Save changes**
3. Ensure no error messages appear

### 🚀 How to Use

#### For Customers

1. Customer adds products to the cart
2. Proceeds to checkout
3. Selects **Pivot Payment** as the payment method
4. Clicks **Place order**
5. Customer is redirected to the Pivot payment page
6. Customer completes payment on the Pivot page
7. After payment is completed, customer is redirected back to the "Thank You" page on your website

#### For Merchants

1. After the customer completes payment, the order status will automatically change to:
   * **Processing** or **Completed** (if payment is successful)
   * **Failed** (if payment fails or is cancelled)
2. Merchant can view order details in **WooCommerce → Orders**
3. The Pivot Payment ID is stored in order meta for reference

### 🔐 Advanced Settings

#### Callback URL Configuration

The plugin automatically uses the following URL as the callback endpoint: `https://your-site.com/pivot/payment-callback`

**IMPORTANT**: Make sure this URL is registered in your Pivot dashboard:

1. Log in to the Pivot Dashboard
2. Navigate to Settings → Webhooks/Callbacks
3. Add or update the callback URL with the URL above
4. Ensure the Callback API Key used matches the one configured in the plugin settings

#### Permalink Settings

The plugin uses WordPress rewrite rules for the callback endpoint. If the callback does not work:

1. Navigate to **Settings → Permalinks**
2. Click **Save Changes** (without changing anything) to refresh rewrite rules
3. Test the callback endpoint again

#### Order Status Handling

The plugin automatically updates order status based on events from Pivot:

* **PAYMENT.PAID** → Order status: Processing/Completed
* **CHARGE.SUCCESS** → Order status: Processing/Completed
* **PAYMENT.CANCELLED** → Order status: Failed
* **PAYMENT.PROCESSING** → Order status: Pending (not changed)

### 🧪 Testing

#### Test Mode

1. Enable **Test Mode** in plugin settings
2. Use Sandbox credentials from Pivot
3. Create a test order with a small amount
4. Test various scenarios:
   * Successful payment
   * Failed payment
   * Cancelled payment
   * Timeout/expired

#### Test Callback Endpoint

You can test the callback endpoint using the following request:

**Request:**

```bash
curl -X POST https://your-site.com/pivot/payment-callback \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-callback-api-key" \
  -d '{
    "event": "PAYMENT.TEST",
    "data": {
      "test": "OK"
    }
  }'
```

**Expected Response:**

```
{
  "success": true,
  "message": "Test callback received successfully",
  "test": "OK"
}
```

#### Payment Status Verification

The plugin automatically verifies payment status on the "Thank You" page:

1. If the order is not yet paid, the plugin will call the Pivot API to check status
2. Order status will be updated based on the API response
3. Logs can be viewed at **WooCommerce → Status → Logs → pivot-payment-gateway**

#### Manual Refresh Payment Status

The plugin provides a feature to manually refresh payment status if the order status is not automatically updated:

**For Admin**

1. Navigate to **WooCommerce → Orders**
2. Open the order you want to refresh
3. On the order details page, a button **🔄 Refresh Payment Status (Pivot)** will appear
4. Click the button to refresh status from the Pivot API
5. Order status will automatically update if there are changes

**Note**: This feature can be enabled or disabled via plugin settings:

* **WooCommerce → Settings → Payments → Pivot → Enable Refresh in Admin**

**For Customers (Public Endpoint)**

Customers can refresh payment status via a public endpoint:

**URL Format:**

```
https://your-site.com/pivot/payment-refresh-status/<order_id>
```

**Example:**

```
https://your-site.com/pivot/payment-refresh-status/9011
```

**Response (JSON):**

```json
{
  "success": true,
  "message": "Payment status updated successfully. Order is now marked as paid.",
  "status": "PAID",
  "status_updated": true,
  "old_status": "pending",
  "new_status": "processing"
}
```

**Rate Limiting:**

* Endpoint is protected with rate limiting (30 seconds per order)
* If accessed too frequently, it will return HTTP 429 with the message "Please wait X seconds before refreshing payment status again"

**Security:**

* If the customer is logged in, the endpoint verifies that the order belongs to the logged-in customer
* Rate limiting prevents abuse and reduces load on Pivot servers

**Frontend Usage:**

You can integrate this endpoint on the customer order page using JavaScript:

```javascript
// Example: Refresh payment status via AJAX
fetch('https://your-site.com/pivot/payment-refresh-status/9011')
  .then(response => response.json())
  .then(data => {
    if (data.success) {
      console.log('Status updated:', data.message);
      // Reload page or update UI
      location.reload();
    } else {
      console.error('Error:', data.message);
    }
  });
```

### 🔍 Troubleshooting

#### Issue: Payment gateway does not appear at checkout

**Solution:**

1. Ensure the plugin is activated
2. Ensure the payment gateway is enabled in **WooCommerce → Settings → Payments**
3. Ensure Merchant ID and Merchant Secret are filled in
4. Check whether the order currency is supported by Pivot
5. Clear cache if using a caching plugin

#### Issue: Error "Missing Pivot API credentials"

**Solution:**

1. Ensure Merchant ID is filled in
2. Ensure Merchant Secret is filled in
3. Ensure there are no leading or trailing spaces in credentials
4. Try disabling and re-enabling the payment gateway

#### Issue: Customer is not redirected to the Pivot payment page

**Solution:**

1. Check logs at **WooCommerce → Status → Logs → pivot-payment-gateway**
2. Ensure the API Base URL is correct (sandbox for test mode, live for production)
3. Ensure Merchant ID and Secret are valid
4. Test API connection using the test callback endpoint

#### Issue: Order status does not change after payment

**Solution:**

1. Check whether the callback URL is registered in the Pivot Dashboard
2. Ensure the Callback API Key is correct
3. Check logs at **WooCommerce → Status → Logs → pivot-payment-gateway**
4. Ensure permalink settings have been refreshed
5. Try manually accessing the "Thank You" page to trigger verification

#### Issue: Callback is not received

**Solution:**

1. Ensure the server can receive POST requests from the internet
2. Check firewall settings
3. Ensure the Callback URL is accessible via browser: `https://your-site.com/pivot/payment-callback`
4. Test using the test callback endpoint
5. Check logs to see whether requests are received

#### Issue: Error "Invalid or missing X-API-Key"

**Solution:**

1. Ensure the Callback API Key is filled in plugin settings
2. Ensure the Callback API Key used in the Pivot Dashboard matches the plugin settings
3. Check logs for detailed error information

### ❓ FAQ

#### Q: Does this plugin support multiple currencies?

A: Yes, the plugin supports all currencies supported by Pivot. Ensure your order currency is supported by Pivot.

#### Q: Do I need to manually configure the callback URL?

A: No, the plugin automatically uses the URL `https://your-site.com/pivot/payment-callback`. You only need to register this URL in the Pivot Dashboard.

#### Q: How do I know if a payment is successful?

A: Order status will automatically change to "Processing" or "Completed" if payment is successful. You can also see the Payment ID in the order details.

#### Q: Is this plugin secure?

A: Yes, the plugin uses:

* HTTPS for all communications
* X-API-Key validation for callbacks
* Secure credential storage
* Order key validation for the thank you page

#### Q: Can I use sub-accounts?

A: Yes, the plugin supports sub-accounts. Fill in the Sub-account ID in plugin settings if you use Pivot’s sub-account management feature.

#### Q: How do I view transaction logs?

A: Logs can be viewed at **WooCommerce → Status → Logs**. Select the source "pivot-payment-gateway" to view plugin logs.

#### Q: How do I manually refresh payment status if the order is not updated?

A:

* **For Admin**: Use the "🔄 Refresh Payment Status (Pivot)" button on the order details page
* **For Customers**: Use the `/pivot/payment-refresh-status/<order_id>` endpoint or integrate it into the customer order page
* Ensure the refresh feature is enabled in plugin settings

#### Q: Is the refresh payment status endpoint secure?

A: Yes, the endpoint is protected with:

* Rate limiting (30 seconds per order) to prevent abuse
* User verification if the customer is logged in
* Logging for activity monitoring

#### Q: Is this plugin compatible with WooCommerce Blocks (Checkout Block)?

A: Yes, this plugin supports WooCommerce Checkout Blocks and Cart Blocks.

#### Q: What if I want to use a custom callback URL?

A: Currently, the plugin uses a fixed callback URL. For a custom URL, you would need to modify the plugin or contact support.

#### Q: Does this plugin support refunds?

A: This plugin focuses on payment processing. For refunds, use standard WooCommerce refund features or contact Pivot support for refund APIs.

#### Q: How do I switch from test mode to production?

A:

1. Open plugin settings
2. Uncheck "Enable Test Mode"
3. Ensure the Live API Base URL is correct
4. Ensure you are using Live credentials (Merchant ID & Secret)
5. Update the Callback URL in the Pivot Dashboard if different
6. Save changes

### 📞 Support

#### Pivot Documentation

* [Pivot API Documentation](https://pivot-payment.gitbook.io/pivot-docs/)
* [Payment Callback Documentation](https://pivot-payment.gitbook.io/pivot-docs/api-references/api-lists/payments/payment-callback)
* [Sub-account Management](https://pivot-payment.gitbook.io/pivot-docs/api-references/api-lists/account-and-balance/sub-account-management/activity-on-behalf-of-sub-account)

#### Logging & Debugging

For debugging, check logs at:

* **WooCommerce → Status → Logs → pivot-payment-gateway**

Logs include:

* Payment session creation
* API calls
* Callback processing
* Error messages
* Status updates

#### Support Contact

If you encounter issues that cannot be resolved:

1. Check WooCommerce logs for error details
2. Document steps to reproduce the issue
3. Screenshot error messages if any
4. Contact Pivot support with the information above

### 📝 Changelog

#### Version 1.0.0

* Initial release
* Payment session creation
* Payment callback handling
* Thank you page verification
* Sub-account support
* WooCommerce Blocks compatibility
* Comprehensive logging
* Test callback endpoint
* Manual refresh payment status (admin)
* Public refresh payment status endpoint (customer)
* Rate limiting for public endpoint
* Configurable payment session expiry
* Enable/disable refresh feature settings

### 🔒 Security Best Practices

1. **Do not share credentials**: Merchant ID, Merchant Secret, and Callback API Key are confidential
2. **Use HTTPS**: Ensure the website uses an SSL certificate
3. **Regular updates**: Update the plugin regularly for security patches
4. **Monitor logs**: Regularly check logs for suspicious activity
5. **Use test mode for development**: Always use test mode during development/testing

### 📄 License

This plugin is developed for integration with the Pivot Payment Gateway. Ensure you have a valid license to use Pivot services.