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]

5. Click Install Now

6. After installation completes, click Activate Plugin

Method 2: Upload via FTP

1. Extract the plugin ZIP file [download here]

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

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:

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):

{
  "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:

// 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

• Payment Callback Documentation

• Sub-account Management

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.