InvoX Integration API Documentation

This guide covers all the endpoints, request formats, sample code snippets, and expected responses for integrating the Invoice Payment API in Node.js, PHP, and Python.

Prerequisites

A registered account on InvoX.
Your API Key from Account Settings -> API & Webhooks.
A Callback URL configured in your account settings.
Node.js v14+, PHP 7.4+, or Python 3.7+ runtime.

Authentication

Every request must include the API key in the HTTP headers:

api_key: YOUR_API_KEY  # example fANMINeogiMAf92b4l35EXAMPLEKnMAGEopnetb

Additionally, JSON requests must set:

Content-Type: application/json

Endpoints Overview

Action	Method	Path
Generate Payment Link	POST	https://invox.weperch.live/api/payment/{invoice_code}
Verify Transaction	GET	https://invox.weperch.live/payment/callback?reference=&invoice=&api=true

Generate Payment Link

Use this endpoint to generate a redirect URL where the user can complete payment.

Sample Request (Node.js)

async function generatePaymentLink(invoice_code) {
  const response = await fetch(
    `https://invox.weperch.live/api/payment/${invoice_code}`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'api_key': process.env.PAY_API_KEY
      },
      body: JSON.stringify({ invoice_code })
    }
  );
  return response.json();
}

Sample Request (PHP)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "{$endpoint}/api/payment/{$invoice_code}");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Content-Type: application/json',
  "api_key: {$api_key}"
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['invoice_code' => $invoice_code]));
$response = curl_exec($ch);

Sample Request (Python)

response = requests.post(
  f'https://invox.weperch.live/api/payment/{invoice_code}',
  headers={'Content-Type': 'application/json', 'api_key': api_key},
  json={'invoice_code': invoice_code}
)
print(response.json())

Redirect Users

After receiving a success response, redirect the user to the provided URL:

if (data.success) {
  window.location.href = data.url;
}

Verify Transaction (Callback Handler)

Node.js

async function verifyTransaction(ref, invoiceCode) {
  const res = await fetch(
    `https://invox.weperch.live/payment/callback?reference=${ref}&invoice=${invoiceCode}&api=true`,
    {
      method: 'GET',
      headers: { 'api_key': process.env.PAY_API_KEY }
    }
  );
  return res.json();
}

PHP

$ch = curl_init("https://invox.weperch.live/payment/callback?reference={$ref}&invoice={$invoice_code}&api=true");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["api_key: {$api_key}"]);
$response = curl_exec($ch);

Python

response = requests.get(
  'https://invox.weperch.live/payment/callback',
  headers={'api_key': api_key},
  params={'reference': reference, 'invoice': invoice_code, 'api': 'true'}
)
print(response.json())

Error Codes & Messages

Message	Scenario
Missing transaction reference	reference or trxref query param is empty
Transaction not successful	Paystack verify returned non-success status
Invoice is already paid	Invoice marked paid in your system
Invalid API Key provided	Header api_key missing or not found

Best Practices

Always serve these endpoints over HTTPS.
Keep your `api_key` and Paystack secret key secure.
Validate all incoming parameters.
Implement retry logic for network failures.

Support

For further assistance, contact our support team through your dashboard or email company@weperch.live.

InvoX API Docs