Build the Future of Payments with Servinux

Architecture & Auth

The Servinux API is built on RESTful principles, returning structured JSON responses to every request. To ensure maximum reliability and ease of use, all merchant actions are routed through our Unified Gateway.

Securing Your Requests

Authentication is handled via your Secret Key. Every server-side request must include this key as a Bearer Token in the Authorization header. This ensures only your authorized systems can move funds or access sensitive data.

Authorization: Bearer fn_live_xxxxxxxxxxxxxxxxxxxxxxxx

Developer Alert: Your Secret Key is the master key to your merchant account. Never expose it in client-side JavaScript or public repositories.

Initialize Checkout (Unified POST)

To begin a payment session, send a POST request to the central gateway using the checkout action. We handle the heavy lifting of processing Card, Bank Transfer, and USSD, returning a secure URL for your customer.

POST /v1/index.php

Standard Request Payload (JSON)

{
    "action": "checkout",
    "amount": 2500.00,
    "customer_email": "[email protected]",
    "customer_name": "John Doe"
}

Verify Payment Status

Payment integrity is paramount. After your customer is redirected back to your site, you must perform a server-side check to confirm the fund's movement before fulfilling any order.

POST /v1/index.php

Verification Payload

{
    "action": "verify_payment_status",
    "reference": "FP_CH_XXXXX"
}

Smart Webhooks

Webhooks provide the fastest way to confirm payments asynchronously. When a payment is successful, Servinux dispatches a signed notification to your server. You must verify the X-Servinux-Signature using your Webhook Secret to prevent spoofing.

HTTP Status Codes

We use descriptive HTTP codes alongside JSON error objects to help you debug quickly:

• 200 Success: Your request was successful and processed.
• 401 Unauthorized: Missing or invalid Secret Key.
• 404 Not Supported: The requested action is invalid.
• 500 Server Error: An internal issue occurred. Reach out to support.