FinAPI Documentation

Step 1: Configure Your Gateways

Before initiating any payments, you must first add your preferred payment providers. Our engine routes your transactions through these gateways to ensure maximum uptime.

1. Go to the My Gateways page.
2. Click Add Gateway, select a provider (like Payhero, Hashback, etc.), and enter your API credentials.
3. Once added, navigate to the Platforms page.
4. Create or edit your platform and select the gateways you want to enable for that specific platform.

Pro Tip: Select multiple gateways for a single platform to enable automatic failover. If one gateway goes down, FinAPI instantly routes the payment through the next available gateway!

Authentication & Security

FinAPI uses API keys to authenticate requests. You can view and manage your API keys in the API Keys dashboard.

How to authenticate:

• Method 1: Pass it in the Authorization header as a Bearer token. (Recommended)
• Method 2: Include it directly in your JSON payload using the api_key property.

// Example Request Headers
{
  "Content-Type": "application/json",
  "Authorization": "Bearer sk_test_your_api_key_here"
}

Initiate STK Push

Trigger an M-Pesa STK Push prompt on the customer's phone to collect payment. The engine automatically handles routing across your configured fallback providers to ensure maximum uptime.

Request Payload (JSON)

Example Request

fetch('https://www.stkpush.surveymax.online/api/stk-push/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer sk_test_your_api_key_here'
    },
    body: JSON.stringify({
        phone_number: '254712345678',
        amount: 100,
        reference: 'ORDER_102394'
    })
})
.then(response => response.json())
.then(data => console.log(data));

Example Response (200 OK)

{
  "success": true,
  "message": "Payment request initiated successfully",
  "transaction_id": "ws_CO_09112023150000",
  "checkout_request_id": "ws_CO_09112023150000",
  "provider_used": "hashback"
}

Verify Payment Status

Check the final status of a previously initiated STK push. You use the exact same transaction ID returned from the initialization step.

Example Request

fetch('https://www.stkpush.surveymax.online/api/verify-payment/ws_CO_09112023150000/', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer sk_test_your_api_key_here'
    }
})
.then(response => response.json())
.then(data => console.log(data));

Example Response (200 OK)

{
  "success": true,
  "message": "Payment verification successful",
  "error_code": null,
  "reference": "ws_CO_09112023150000",
  "status": "Success",
  "provider_used": "hashback"
}

No-Code Payment Widget

If you want to accept payments quickly without building your own checkout UI, you can embed our powerful Payment Widget directly into your website. It handles STK pushes, loading states, error handling, and even the manual payment fallback automatically!

1. Add the Widget Script

Include this script tag in your HTML, preferably just before the closing </body> tag:

<script src="https://www.stkpush.surveymax.online/static/js/finapi-widget.min.js"></script>

2. Add the Payment Button

Place this HTML element wherever you want the payment button to appear. The script will automatically convert it into an interactive payment button.

<div class="finapi-widget" 
     data-api-key="sk_test_your_api_key_here" 
     data-amount="100" 
     data-color="#2563eb"
     data-provider="hashback">
</div>

3. Handle Payment Events

The widget dispatches custom events to the parent container when a payment succeeds or fails. You can listen to these events in your Javascript to unlock content, update your database, or redirect the user.

const widget = document.querySelector('.finapi-widget');

// Listen for successful payments
widget.addEventListener('finapi:payment_success', function(event) {
    const { reference, message, data } = event.detail;
    console.log('Success!', reference, data);
    // e.g. Redirect to a success page or unlock content
});

// Listen for failed payments
widget.addEventListener('finapi:payment_failed', function(event) {
    const { reference, message, data } = event.detail;
    console.log('Failed:', message);
});