PAYMENT & BILLING APIDual-Auth · API Keys & JWT

Client Website Payment Integration

Collect payments and fund your Verixa NGX balance directly from your own website or application. You can initiate checkouts, trigger in-page Paystack popup modals with zero redirects, or display dedicated bank transfer accounts on your own domain.

01. ZERO REDIRECT

In-Page Modal

Use the returned accessCode with Paystack Inline to open a secure payment popup on your site.

02. HOSTED CHECKOUT

Direct Redirect

Redirect payers to checkoutUrl and receive them back at your custom callbackUrl.

03. DIRECT TRANSFER

Dedicated Account

Display your organization's Titan Trust Bank virtual account for instant credit via direct bank transfer.

POST/v1/billing/checkout

Call this endpoint from your backend server using your Verixa Live API key (Authorization: Bearer vrx_live_...).

cURL: Initialize Payment Checkout

curl -X POST https://api.verixa.io/v1/billing/checkout \
  -H "Authorization: Bearer vrx_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "customerEmail": "finance@yourcompany.com",
    "callbackUrl": "https://yourcompany.com/billing/callback",
    "metadata": {
      "orderId": "ORD-8821",
      "purpose": "wallet_funding"
    }
  }'

Response (200 OK)

{
  "status": "success",
  "data": {
    "reference": "vrx_tx_8a92bfae",
    "checkoutUrl": "https://checkout.paystack.com/0peioxfhpn",
    "accessCode": "0peioxfhpn",
    "amount": 25000,
    "currency": "NGN",
    "customerEmail": "finance@yourcompany.com",
    "callbackUrl": "https://yourcompany.com/billing/callback",
    "dedicatedVirtualAccount": {
      "bankName": "Titan Trust Bank",
      "accountNumber": "9940182741",
      "accountName": "Verixa ID / Settlement",
      "status": "active"
    }
  }
}

Frontend Implementation Options

Option A: Seamless In-Page Popup (Zero Redirect)

Load Paystack Inline JS on your website. Once your backend returns the accessCode, trigger the popup modal directly:

Frontend JavaScript (Embedded Modal)

<!-- Include Paystack Inline Script -->
<script src="https://js.paystack.co/v1/inline.js"></script>
<script>
async function handlePayFromMyWebsite() {
  // 1. Call your own backend API which calls Verixa /v1/billing/checkout
  const res = await fetch('/api/create-payment', {
    method: 'POST',
    body: JSON.stringify({ amount: 25000 })
  });
  const { data } = await res.json();
  // 2. Open Paystack popup directly on your website using accessCode
  const popup = PaystackPop.setup({
    access_code: data.accessCode,
    onClose: function() {
      console.log('Customer dismissed payment popup');
    },
    callback: function(response) {
      console.log('Payment successful! Reference:', response.reference);
      // Verify payment status with your backend
      window.location.reload();
    }
  });
  popup.openIframe();
}
</script>

Option B: Standard Hosted Redirect

Simply direct your user to the hosted checkout page:

Redirect Flow

// Redirect payer to checkoutUrl
window.location.href = data.checkoutUrl;

GET/v1/billing/payments/:reference

Verify real-time completion status of any payment reference. If the payment was completed on Paystack, calling this endpoint automatically verifies and credits your Live balance immediately.

cURL: Query Payment Reference

curl -X GET https://api.verixa.io/v1/billing/payments/vrx_tx_8a92bfae \
  -H "Authorization: Bearer vrx_live_YOUR_API_KEY"

Response (200 OK)

{
  "status": "success",
  "data": {
    "reference": "vrx_tx_8a92bfae",
    "paymentStatus": "COMPLETED",
    "amount": 25000,
    "currency": "NGN",
    "description": "Paystack Verified Checkout",
    "paidAt": "2026-10-06T08:14:22.000Z"
  }
}

Real-time Webhook Notification

Whenever a payment is settled via card checkout or direct DVA bank transfer, Verixa dispatches a signed payment.completed event to your configured webhook URL.

Webhook Payload (payment.completed)

{
  "event": "payment.completed",
  "timestamp": "2026-10-06T08:14:23.102Z",
  "data": {
    "reference": "vrx_tx_8a92bfae",
    "amount": 25000,
    "currency": "NGN",
    "balance": 175000
  }
}