Payxit Developer Documentation

Use Payxit to manage Nigerian payment gateways through a single API.

1) Overview

Payxit lets merchants manage multiple Nigerian payment gateways with a single API. Merchants generate Payxit API keys in the dashboard, then use those keys to create payment sessions for their customers. Customers are redirected to a Payxit-hosted public payment page and then routed to the selected gateway’s checkout flow (Flutterwave, Paystack, Opay, PalmPay, KongaPay, Moniepoint).

2) Base URLs

  • Local development: https://api.payxit.online/api
  • Public pay page: https://payxit.online/pay/{token}

3) Authentication (Public Developer Access)

Payxit payment processing endpoints require a Payxit API public key in the request header.

  • Header: x-payxit-key
  • Alternate: x-api-key
POST /api/public/payments HTTP/1.1
Host: localhost:4010
Content-Type: application/json
x-payxit-key: pk_live_xxxxxxxxxxxxxxxxx

4) Payment Processing Flow

  1. Merchant creates a payment session using Payxit’s public API.
  2. Payxit returns a token and a public payment page redirect URL.
  3. Merchant redirects the customer to the Payxit payment page.
  4. Customer clicks “Proceed with Payment” to open gateway checkout.
  5. Gateway confirms payment via webhook callbacks.
  6. Payxit records the transaction and updates status.

5) Public Developer Endpoints

5.1 Health Check Public

GET /api/health

{ "status": "ok" }

5.2 List Supported Gateways Public

GET /api/public/gateways

{ "gateways": [] }

5.3 Pricing Public

GET /api/public/pricing

{ "pricing": [] }

5.4 Create Payment Session Auth

POST /api/public/payments

Headers: x-payxit-key

{
  "name": "Ada Nwosu",
  "email": "ada@example.com",
  "phone": "+2348012345678",
  "amount": 25000,
  "currency": "NGN"
}
{
  "token": "ab12cd34ef56...",
  "redirectUrl": "https://payxit.online/pay/ab12cd34ef56...",
  "session": {
    "id": "uuid",
    "status": "created",
    "amount": 25000,
    "currency": "NGN",
    "customerName": "Ada Nwosu",
    "customerEmail": "ada@example.com",
    "customerPhone": "+2348012345678",
    "gateway": "flutterwave"
  }
}

5.5 Get Payment Session Public

GET /api/public/payments/:token

{
  "session": {
    "id": "uuid",
    "status": "created",
    "amount": 25000,
    "currency": "NGN",
    "customerName": "Ada Nwosu",
    "customerEmail": "ada@example.com",
    "customerPhone": "+2348012345678",
    "gateway": "flutterwave",
    "checkoutUrl": null
  }
}

5.6 Initiate Payment Session Public

POST /api/public/payments/:token/initiate

This is invoked by the Payxit payment page when a customer proceeds to the gateway checkout. 

{
  "session": {
    "id": "uuid",
    "status": "initiated",
    "gateway": "flutterwave",
    "checkoutUrl": "https://gateway.example/checkout/xyz"
  }
}

5.7 Webhooks Gateway

POST /api/webhooks/:gateway

Raw body is required. Payxit validates signatures and updates transactions based on gateway payloads.

6) Error Responses

{ "message": "Description of the error." }
  • 400 — invalid or missing fields
  • 401 — invalid API key
  • 404 — payment session not found
  • 409 — payment already initiated
  • 502 — gateway checkout URL not returned

7) Example Integration

curl -X POST "http://localhost:4010/api/public/payments" \
  -H "Content-Type: application/json" \
  -H "x-payxit-key: pk_live_xxxxxxxxxxxxx" \
  -d '{
    "name": "Ada Nwosu",
    "email": "ada@example.com",
    "phone": "+2348012345678",
    "amount": 25000,
    "currency": "NGN"
  }'

Redirect the customer to the returned redirectUrl, which will look like: 

https://payxit.online/pay/{token}

8) Security Notes

  • Keep Payxit API keys secret.
  • Use HTTPS in production.
  • Rotate keys if exposed.
  • Use gateway-specific webhook signatures.

9) Environment Notes

  • Payxit supports Live and Sandbox environments.
  • Keys and webhook URLs are managed per environment.
  • Use the corresponding public key for each environment.