Token & API documentation

Start here

Getting started

Integrate Paysecure with a merchant token. Sandbox first, then live — the same endpoints, different keys.

Create a token

1. Log in and open Tokens in the sidebar.
2. Complete your profile if the dashboard asks for it.
3. Generate a Sandbox token for testing, or Live after KYC.
4. Copy the token immediately — it is shown once. Store it as an environment variable.

Test the connection

Use the test action on the Tokens page, or send an authenticated request to the base URL with your Bearer token. When that succeeds, you are ready for checkout, payouts, or webhooks.

SDK & Plugins

Integrate Paysecure seamlessly with your application using our official SDKs and plugins. These tools are designed to make integration easier and faster.

API Libraries

We provide official libraries for Node.js, Python, and PHP. Install one of them, then run the command below in your terminal.

Click "Copy" next to the command, paste in your terminal, and press Enter. Click "View Docs" to see full documentation.

const { Payhiive } = require('payhiive-node');

// Initialize the client with your token
const client = new Payhiive({ apiKey: 'your_token_here' });

// Create a payment intent (recommended)
const payment = await client.payments.create({
    amount: 50000,  // Amount in UGX
    description: 'Order #12345',
    callbackUrl: 'https://yoursite.com/webhooks/payhiive'
});

// Redirect customer to the checkout URL
console.log(payment.checkout_url);

const link = await client.paymentLinks.create({
    amount: 100000,
    currency: 'UGX',
    description: 'Membership Fee'
});
console.log(link.data.payment_link);

const session = await client.checkout.create({
    amount: 75000,
    currency: 'UGX',
    successUrl: 'https://site.com/success',
    cancelUrl: 'https://site.com/cancel'
});

from payhiive import Payhiive

# Initialize the client with your token
client = Payhiive(api_key="your_token_here")

# Create a payment intent (recommended)
payment = client.payments.create(
    amount=50000,  # Amount in UGX
    description="Order #12345",
    callback_url="https://yoursite.com/webhooks/payhiive"
)

# Redirect customer to the checkout URL
print(payment["checkout_url"])

link = client.payment_links.create(
    amount=100000,
    currency="UGX",
    description="Membership Fee"
)
print(link["data"]["payment_link"])

session = client.checkout.create(
    amount=75000,
    currency="UGX",
    success_url="https://site.com/success",
    cancel_url="https://site.com/cancel"
)

<?php
use Payhiive\Payhiive;

// Initialize the client with your token
$client = new Payhiive('your_token_here');

// Create a payment intent (recommended)
$payment = $client->payments->create(
    50000,  // Amount in UGX
    'Order #12345',
    'https://yoursite.com/webhooks/payhiive'
);

// Redirect customer to the checkout URL
header('Location: ' . $payment['checkout_url']);

$link = $client->paymentLinks->create([
    'amount' => 100000,
    'currency' => 'UGX',
    'description' => 'Membership Fee'
]);
echo $link['data']['payment_link'];

$session = $client->checkout->create([
    'amount' => 75000,
    'currency' => 'UGX',
    'success_url' => 'https://site.com/success',
    'cancel_url' => 'https://site.com/cancel'
]);

Available Plugins

Installation Guides

Security

Authentication

Every request needs your merchant token. Create it under Dashboard → Tokens. Tokens start with sk_ — that is the only credential the API expects.

Required headers

Example request

Pass the token on every call. Amounts are in major units (USD dollars, not cents).

Pricing

Fees & pricing

Platform fees sit on top of the amount you collect. You receive the exact USD you requested; the customer pays that amount plus the fee.

API example — collect $100.00

Payment link example — collect $100.00

Payout example — send $100.00

Payout fees are deducted from the withdrawal, so the recipient gets the net amount.

This install

Base URL

All API paths on this page are relative to the domain you are viewing. Point APP_URL in .env (or App URL in Admin → Settings) at the same host so checkout links and emails match.

API Endpoints

Payments

Create a Direct Charge (No Checkout Page)

Charge a mobile money number directly — no redirect, no checkout page. You collect the phone number and provider on your own form.

POST /api/v1/payments/direct is kept as a backward-compatible alias — new integrations should use /charges.

Request Body

Example Request

Example Response (Success)

Example Response (Error)

Transaction Status Values

Get Payment Status

Retrieve the current status and details of a specific payment transaction. This endpoint works for any transaction regardless of how it was created — direct charge (/charges) or hosted checkout (/payments).

Response Example

Getting Transaction Reference

The transaction reference is a unique identifier (UUID format) that is returned in the response when you create a payment or retrieve payment status. This reference can be used for tracking, reconciliation, and webhook verification.

To get the transaction reference:

1. From Payment Response: When you create a payment using POST /payments, the reference is included in the response.
2. From Status Check: When you retrieve payment status using GET /payments/{transaction_id}, the reference field is included in the response data.
3. From Dashboard: You can also view the transaction reference in your merchant dashboard at https://payset.okao.site/customer/dashboard/recent-transactions.

Step-by-Step: Integrating Transaction Reference in Your System

This guide will walk you through integrating transaction reference tracking into your application system.

Step 1: Set Up Your Token

1. Log in to your merchant dashboard at https://payset.okao.site/customer/login
2. Navigate to Dashboard → Tokens
3. Generate a new token (Dashboard → Tokens)
4. Store your token and public identifier securely in your application's environment variables (e.g. in .env):
   PAYHIIVE_TOKEN=sk_your_token API_BASE_URL=https://payset.okao.site/api/v1

Step 2: Create a Payment Request

When creating a payment, make a POST request to the payments endpoint:

The response will include a transaction_id:

Step 3: Retrieve the Transaction Reference

After creating a payment, use the transaction_id to retrieve the full transaction details, including the reference:

The response will include the reference field:

Step 4: Store the Reference in Your Database

Save both the transaction_id and reference in your database for future reference and reconciliation:

Step 5: Check Payment Status Using Reference

You can verify payment status by checking the transaction using either the transaction_id or by querying your database using the stored reference:

Step 6: Complete Code Example (PHP)

Step 7: Complete Code Example (Node.js/JavaScript)

Step 8: Verify Reference in Dashboard

You can also verify the transaction reference by viewing it in your merchant dashboard:

1. Log in to your dashboard at https://payset.okao.site/customer/login
2. Navigate to Dashboard → Recent Transactions
3. Find your transaction and check the Reference column
4. The reference will be displayed in UUID format (e.g., b6a677d8-8a3d-4d2d-9de5-d439510d7c62)

List Payments

Retrieve a list of all your payments. Supports pagination and filtering.

Payouts

Payouts let you send money from your Paysecure balance directly to a recipient's mobile money account — from your own website, app, or backend system. All you need is your secret token from Dashboard → Tokens.

Sandbox vs Live

Create a Payout

Sends money from your Paysecure balance to a recipient's mobile money number. Supports two payload formats — flat fields or a nested recipient object.

Request Headers

Request Body

Example — Simple (flat fields)

Example — With recipient object & custom payout_id

Success Response — Sandbox (201 Created)

In sandbox mode the payout completes instantly. No real money is moved and no SMS is sent.

Success Response — Live (201 Created)

In live mode the payout is submitted to the payment provider. Status will be processing. Poll GET /api/v1/payouts/{payout_id} until status becomes completed or failed.

Response Fields

Payout Status Lifecycle

Get Payout Status

Returns the current status of a payout. For pending or processing payouts the API automatically refreshes the status from the payment provider before responding.

Example

Response

List Payouts

Returns a paginated list of your payouts, newest first.

Query Parameters

Example

Response

Error Responses

Insufficient Balance Error Example

Amount Below Minimum Error Example

Code Examples

cURL

JavaScript (fetch)

PHP (cURL)

Python (requests)

Refunds

Create Refund

Create a refund for a payment.

Request Body

Checkout Pages (Using Your Token)

Paysecure provides hosted checkout pages that you can redirect your customers to for secure payment processing. Authenticate with your token (Dashboard → Tokens) when creating payment intents. This is the easiest way to accept payments without handling sensitive payment data yourself.

Creating a Payment Intent

To create a payment intent, make a POST request to the payments endpoint with the payment details.

Create Payment Intent

Create a new payment intent and get a secure checkout URL to redirect your customer to.

Request Body

Example Request

Example Response

Redirecting to Checkout

After creating a payment intent, redirect your customer to the checkout_url provided in the response.

JavaScript Example

PHP Example

Checking Payment Status

After redirecting your customer to the checkout page, you can check the payment status using the status endpoint.

Get Payment Status

Check the status of a payment intent using the reference returned when creating the payment.

Example Request

Example Response

Payment Intent Statuses

Checkout Page Features

• Secure Payment Processing: All payment data is handled securely by Paysecure with SSL encryption
• Mobile Money Payments: Supports MTN Mobile Money and Airtel Money
• Mobile Optimized: Fully responsive design optimized for mobile devices
• Real-time Status Updates: Automatic status polling to track payment progress
• Expiration Management: Payment intents expire after 24 hours for security
• Email Notifications: Merchants receive email notifications when payments are completed
• Webhook Support: Instant payment notifications via webhooks

Hosted checkout

Payment intent checkout

Redirect customers to a Paysecure checkout page. Amount, currency, and recipient stay on the server — the frontend only ever sees an unguessable reference.

const API_BASE_URL = 'https://payset.okao.site/api/v1';
const TOKEN = 'sk_your_token';

async function redirectToPayhiiveCheckout(amount, description) {
  const response = await fetch(`${API_BASE_URL}/payments`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: amount,              // e.g. 100.00 USD
      currency: 'USD',
      description: description,
      callback_url: 'https://yoursite.com/webhooks/payment'
    })
  });

  const data = await response.json();
  if (!data.checkout_url) throw new Error(data.message || 'Failed to create payment');
  window.location.href = data.checkout_url;
}

document.getElementById('pay-button').addEventListener('click', () => {
  redirectToPayhiiveCheckout(100.00, 'Payment for Order #12345');
});

<?php
$API_BASE_URL = 'https://payset.okao.site/api/v1';
$TOKEN = 'sk_your_token';

function redirectToPayhiiveCheckout($amount, $description) {
    global $API_BASE_URL, $TOKEN;

    $ch = curl_init($API_BASE_URL . '/payments');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $TOKEN,
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'amount' => $amount,           // e.g. 100.00 USD
            'currency' => 'USD',
            'description' => $description,
            'callback_url' => 'https://yoursite.com/webhooks/payment',
        ]),
    ]);

    $data = json_decode(curl_exec($ch), true);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode === 201 && isset($data['checkout_url'])) {
        header('Location: ' . $data['checkout_url']);
        exit;
    }

    throw new RuntimeException($data['message'] ?? 'Payment failed');
}

if (isset($_POST['pay_now'])) {
    redirectToPayhiiveCheckout(100.00, 'Payment for Order #12345');
}

import requests
from flask import redirect

API_BASE_URL = 'https://payset.okao.site/api/v1'
TOKEN = 'sk_your_token'

def redirect_to_payhiive_checkout(amount, description):
    response = requests.post(
        f'{API_BASE_URL}/payments',
        headers={
            'Authorization': f'Bearer {TOKEN}',
            'Content-Type': 'application/json',
        },
        json={
            'amount': amount,              # e.g. 100.00 USD
            'currency': 'USD',
            'description': description,
            'callback_url': 'https://yoursite.com/webhooks/payment',
        },
    )
    result = response.json()
    if response.status_code == 201 and 'checkout_url' in result:
        return redirect(result['checkout_url'])
    return {'error': result.get('message', 'Payment failed')}

@app.route('/pay', methods=['POST'])
def pay():
    return redirect_to_payhiive_checkout(100.00, 'Payment for Order #12345')

Step by step

Same flow, broken into the four API moments.

Creating a Payment Intent

To create a payment intent, make a POST request to the payments endpoint. This will create a payment intent and return a checkout URL.

Create Payment Intent

Create a new payment intent and get a secure checkout URL to redirect your customer to.

Request Body

Example Request

Example Response

How to Redirect Customers to Checkout

After creating a payment intent, you'll receive a checkout_url in the response. Redirect your customer to this URL to complete the payment.

What Customers Will See

When customers visit the checkout URL, they will see:

• PayHive Branding: Professional, secure checkout page
• Payment Amount: Displayed prominently (read-only, from database)
• Merchant Name: Your business name
• Payment Description: Description you provided when creating the payment intent
• Mobile Money Options: MTN Mobile Money and Airtel Money buttons
• Secure Form: Fields for customer name, email, and phone number

Complete Integration Examples

JavaScript/React Example (Frontend)

PHP Example (Backend - Recommended)

Python Example (Flask/Django)

Checkout Endpoint URL Format

The checkout URL that you receive from the API follows this format:

Example Checkout URLs

Here are real examples of checkout URLs you'll receive:

How to Use the Checkout URL

When you receive the checkout_url from the response, simply redirect your customer to that URL:

Checkout URL Breakdown

Checkout flow

1. Pay now — the customer clicks Pay on your site or app.
2. Create the intent — your backend posts amount and description to POST /api/v1/payments.
3. Checkout URL — the API returns checkout_url, e.g. https://payset.okao.site/checkout/PHV_72UJVK2EN8.
4. Redirect — send the customer to that URL. Do not build it yourself.
5. Hosted page — they see amount, currency, and card, bank, or wallet options.
6. Pay — they confirm with their bank or wallet. You never handle card data.
7. Webhook — if you set callback_url, we POST the status to your server.
8. Done — the customer lands on your success page after completion.

Payment Intent Statuses

Webhook Notifications

If you provided a callback_url when creating the payment intent, you will receive a POST request to that URL when the payment status changes.

Webhook Payload

Webhook Status Values

• paid - Payment successfully completed
• failed - Payment failed

Verifying Webhook Requests

Always verify that the webhook request is legitimate by:

1. Checking the payment reference exists in your system
2. Verifying the amount matches your records
3. Updating your order/payment status only after verification

Checking Payment Status

After redirecting your customer to the checkout page, you can check the payment status in several ways:

Method 1: Status Endpoint (Recommended for Real-time Updates)

Poll the status endpoint to check if payment has been completed. The system automatically checks the payment provider directly if the webhook hasn't arrived yet.

Example Request

Example Response

JavaScript Polling Example

Method 2: Webhook Notifications (Recommended for Server-side)

If you provided a callback_url, you'll receive a POST request when the payment status changes. This is the most reliable method for server-side applications.

How Payment Status Detection Works

The system uses multiple methods to ensure reliable payment status detection:

1. Webhook Processing: When the payment provider sends a webhook, the system updates the payment intent and transaction status immediately
2. Direct Payment Provider API Check: If payment is still pending, the status endpoint queries the payment provider's API directly (same method as payment links)
3. Automatic Status Sync: When checking status, the system automatically updates the payment intent if the payment provider shows it's completed
4. Real-time Updates: The checkout page polls the status endpoint every 1-3 seconds and redirects to success when payment is detected

Security Best Practices

• Never trust frontend data: All payment amounts, currency, and recipient information are stored server-side and fetched from the database
• Verify payment status: Always verify payment completion on your server before fulfilling orders
• Use HTTPS: Always use HTTPS for callback URLs
• Handle expiration: Payment intents expire after 24 hours (configurable). Handle expired payments gracefully
• Rate limiting: Checkout routes are rate-limited to prevent abuse

Testing

You can test the checkout page by visiting:

This will create a test payment intent and redirect you to the checkout page.

Troubleshooting

If you encounter issues with the checkout page, here are common problems and solutions:

"Checkout Endpoint Not Found" Error

If you receive the error message "PayHive checkout endpoint not found. Please contact support to verify your API configuration." when creating a payment intent:

• API Endpoint Issue: Verify you're using the correct endpoint: POST /api/v1/payments
• API Authentication: Ensure your Authorization: Bearer header is correct and your token is active
• Route Configuration: This error typically occurs when the checkout URL cannot be generated. Check that the route checkout.payment-intent.show exists
• Base URL: Verify your application's APP_URL is correctly configured in your .env file

Checkout Page Shows "Service Temporarily Unavailable"

If customers see the error message "PayHive payment service is temporarily unavailable. Please try again in a few moments or contact support.", this usually indicates:

• Payment Provider Integration Not Configured: Ensure payment provider API tokens are configured in the admin settings (either live or sandbox tokens)
• Database Connection Issues: Check that the database is accessible and the payment_intents table exists
• Service Error: Check the Laravel logs at storage/logs/laravel.log for detailed error messages

Payment Intent Not Found (404 Error)

If you get a 404 error when accessing the checkout URL:

• Verify the payment intent reference is correct (format: PHV_72UJVK2EN8 or similar PHV_ format)
• Check that the payment intent exists in the database
• Ensure the payment intent hasn't been deleted

Payment Intent Expired

If customers see an "expired" message:

• Payment intents expire after 24 hours by default (configurable)
• Create a new payment intent for the customer
• Handle expiration gracefully in your application by checking the expires_at field

No Payment Providers Available

If the checkout page loads but shows no mobile money options:

• Check that payment provider integration is configured and active
• Verify that MTN and/or Airtel providers are enabled in the payment provider integration settings
• Check the integration's enabled_providers field contains MTN_MOMO_UGA and/or AIRTEL_OAPI_UGA

Payment Processing Fails

If payment submission fails:

• Check that the phone number is in the correct format (Uganda: 9-10 digits, e.g., 0771234567)
• Verify the selected mobile money network matches the phone number (MTN vs Airtel)
• Check payment provider API logs for provider-specific errors
• Ensure the customer's mobile money account is active and can receive USSD prompts

Webhook Not Received

If you're not receiving webhook notifications:

• Verify your callback_url is publicly accessible (not localhost)
• Check that your webhook endpoint accepts POST requests
• Verify your server can receive requests from PayHive's servers
• Check server logs for incoming webhook requests
• Ensure your webhook endpoint returns a 200 status code

Webhooks (Using Your Token)

Webhooks let you receive real-time notifications about payment and account events. When you create a payment or payment intent with your token, you can pass a callback_url; we will POST to that URL when the payment status changes.

Setting Up Webhooks

1. Go to your dashboard and navigate to API Management → Webhooks
2. Click Create Webhook
3. Enter your webhook URL (must be HTTPS)
4. Select the events you want to listen to
5. Save your webhook secret (you'll need it to verify requests)

Webhook Events

Testing Webhooks Locally

Your payment still completes normally even when the webhook can't be delivered — it's only the notification to your app that fails silently. If you're testing locally, use one of these instead:

• Tunnel your local server (recommended): use a tool like ngrok to expose your local dev server on a public URL, then use that URL as your callback_url.
  ngrok http 3000 # use the https://xxxx.ngrok-free.app URL it prints as your callback_url
• Poll instead of waiting for the webhook: call GET /api/v1/payments/{transaction_id} directly to check whether it succeeded, instead of relying only on the callback.

Error Handling

All errors follow a consistent format:

Error Codes

Common Issues & Troubleshooting

Issue: "AUTH_FAILED" Error

Possible causes:

• Missing or incorrect token in headers
• Token is inactive or revoked
• Using sandbox keys in production or vice versa

Solution: Verify your token is correct and active in Dashboard → Tokens.

Issue: "PROVIDER_NOT_ENABLED" Error

Possible causes:

• The provider (MTN_MOMO_UGA or AIRTEL_OAPI_UGA) is not enabled for your account
• Typo in provider name

Solution: Use the correct provider name: MTN_MOMO_UGA or AIRTEL_OAPI_UGA. Contact support if the provider needs to be enabled.

Issue: Payment Stays in "pending" Status

Possible causes:

• Customer hasn't approved the payment on their phone
• Customer's phone is off or out of network coverage
• Insufficient mobile money balance

Solution: Wait for the customer to approve. Check payment status periodically. Payments typically complete within a few minutes.

Issue: Phone Number Format

Format: Phone numbers must be in international format without the + sign:

• Correct: 256700000000 (Uganda MTN)
• Incorrect: +256700000000 or 0700000000

Rate Limiting

API requests are rate-limited to ensure fair usage:

• Sandbox: 100 requests per minute
• Live: 1000 requests per minute

Rate limit information is included in response headers:

Direct Payments (Without Checkout Page)

You can use the same token (from Dashboard → Tokens at https://payset.okao.site/customer/tokens) to collect payments without redirecting customers to the hosted checkout page. This is useful when you want to keep users on your own website or app and collect the phone number and network yourself.

Two ways to accept payments with your token:

• Hosted checkout: POST /api/v1/payments with amount, description, callback_url → get checkout_url and redirect the customer to our secure page. PAYHIIVE handles phone number entry and network selection.
• Direct charge (no checkout): POST /api/v1/charges with amount, currency, phone_number, provider → we send the mobile money prompt directly to the customer's phone; they never leave your site. You own the entire UI.

Tokens generated from the customer dashboard work for both flows. Use the same Authorization: Bearer header.

Create a Direct Charge

Charge a mobile money number directly. You collect the customer's phone number and network (MTN or Airtel) on your own form; PAYHIIVE sends the mobile money prompt to their phone. No redirect. No checkout page.

POST /api/v1/payments/direct is kept as a backward-compatible alias — new integrations should use /charges.

Request Body

Example Request

Example Response (Success)

Status lifecycle: pending → completed or failed. The customer receives a mobile money USSD/push prompt on their phone to approve or decline. Status is updated via webhook or when you poll GET /api/v1/charges/{transaction_id}.

Sample Code (Copy & Paste)

React (JavaScript)

Python

PHP (Laravel)

The customer will receive a mobile money prompt on their phone. Track status via webhook or poll GET /api/v1/charges/{transaction_id}.

Integration Examples

Here are complete integration examples for different platforms and languages:

PHP (Laravel/Plain PHP)

React (JavaScript/TypeScript)

Python (Flask/Django)

Need help?

Questions about this API can go to the operator of this installation:

• Email: support@payset.okao.site
• Website: https://payset.okao.site
• Dashboard: Merchant login