Token & API Documentation

Getting Started

Welcome to the PAYHIIVE API documentation. This guide will help you integrate PAYHIIVE payment gateway into your applications.

Prerequisites

• An active PAYHIIVE account
• A token from your dashboard (Dashboard → Tokens)
• Basic knowledge of REST APIs and HTTP requests

Step 1: Get Your Token

1. Log in to your PAYHIIVE dashboard
2. Go to Tokens (in the sidebar)
3. Complete your profile (required to generate a token)
4. Click "Generate Live Token" or use Sandbox for testing
5. Choose your environment:
   • Sandbox: For testing (no real money)
   • Live: For production (requires KYC approval)
6. Copy your token (it is shown once; store it securely)

Step 2: Test Your Connection

Before integrating, test your token using the test feature on the Tokens page or by making a test API call.

SDK & Plugins

Integrate PAYHIIVE 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

Authentication (Using Your Token)

All API requests require your token. Get it from Dashboard → Tokens. Your token starts with sk_ — it is the only key you need.

Headers

Example Request

Use your token in the Authorization header when making any API call:

Fees & Pricing

PAYHIIVE charges platform fees on transactions. Fees are added on top of the amount you want to collect, so you receive the exact amount you requested.

API Transaction Fees

For transactions made through the API:

Payment Link Transaction Fees

For transactions made through payment links:

API Fee Calculation Example (Fees On Top)

If you want to collect 10,000 UGX via API:

Payment Link Fee Calculation Example (Fees On Top)

If you want to collect 10,000 UGX via Payment Link:

Payout/Withdrawal Fees

For withdrawals/payouts made through the API:

Payout Fee Calculation Example

If you withdraw 10,000 UGX:

Base URL

The base URL for all API requests:

API Endpoints

Payments

Create Payment

Create a new payment transaction.

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.

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://payhiive.com/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://payhiive.com/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://payhiive.com/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://payhiive.com/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 PAYHIIVE 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 PAYHIIVE 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)

PAYHIIVE 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 PAYHIIVE 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

Payment Intent Checkout (Hosted Checkout)

PAYHIIVE provides a secure hosted checkout page for payment intents. This is the recommended way to accept payments as it ensures merchants never control payment amounts, currency, or recipient information on the frontend. All payment data is stored server-side and fetched from the database using a secure, unguessable reference.

// Step 1: Replace with your token from Dashboard → Tokens
const API_BASE_URL = 'https://payhiive.com/api/v1';
const TOKEN = 'sk_your_token';  // Your token from Dashboard → Tokens

// Step 2: Function to create payment and redirect to checkout
async function redirectToPayHiveCheckout(amount, description) {
  try {
    // Create payment intent via API
    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., 50000.00 for 50,000 UGX
        description: description,  // e.g., "Order #12345"
        callback_url: 'https://yoursite.com/webhooks/payment'  // Optional: for webhooks
      })
    });

    const data = await response.json();

    // Step 3: Redirect customer to checkout page
    if (data.checkout_url) {
      window.location.href = data.checkout_url;  // ← This redirects to PayHive checkout
      return { success: true, reference: data.reference };
    } else {
      throw new Error(data.message || 'Failed to create payment');
    }
  } catch (error) {
    console.error('Payment error:', error);
    alert('Payment failed: ' + error.message);
    return { success: false, error: error.message };
  }
}

// Step 4: Use it in your "Pay Now" button
document.getElementById('pay-button').addEventListener('click', async () => {
  await redirectToPayHiveCheckout(50000.00, 'Payment for Order #12345');
  // Customer will be automatically redirected to checkout page
});

// Notes:
// - Replace API_BASE_URL with your PayHive instance URL
// - Get your token from: Dashboard → Tokens
// - The checkout_url from the response is the redirect destination
// - Amount is in smallest currency unit (50000.00 = 50,000 UGX)
// - Always call this from your backend in production (keep token secure)

<?php
// Step 1: Replace with your token from Dashboard → Tokens
$API_BASE_URL = 'https://payhiive.com/api/v1';
$TOKEN = 'sk_your_token';  // Your token from Dashboard → Tokens

// Step 2: Function to create payment and redirect to checkout
function redirectToPayHiveCheckout($amount, $description) {
    global $API_BASE_URL, $TOKEN;
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $API_BASE_URL . '/payments');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $TOKEN,
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
        'amount' => $amount,           // e.g., 50000.00 for 50,000 UGX
        'description' => $description, // e.g., "Order #12345"
        'callback_url' => 'https://yoursite.com/webhooks/payment'  // Optional
    ]));
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    $data = json_decode($response, true);
    
    // Step 3: Redirect customer to checkout page
    if ($httpCode === 201 && isset($data['checkout_url'])) {
        header('Location: ' . $data['checkout_url']);  // ← This redirects to PayHive checkout
        exit;
    } else {
        die('Payment failed: ' . ($data['message'] ?? 'Unknown error'));
    }
}

// Step 4: Use it when customer clicks "Pay Now"
if (isset($_POST['pay_now'])) {
    redirectToPayHiveCheckout(50000.00, 'Payment for Order #12345');
    // Customer will be automatically redirected to checkout page
}

// Notes:
// - Replace $API_BASE_URL with your PayHive instance URL
// - Get your token from: Dashboard → Tokens
// - The checkout_url from the response is the redirect destination
// - Amount is in smallest currency unit (50000.00 = 50,000 UGX)
// - Always keep token on server, never expose in frontend

import requests
from flask import redirect  # or: from django.shortcuts import redirect

# Step 1: Replace with your token from Dashboard → Tokens
API_BASE_URL = 'https://payhiive.com/api/v1'
TOKEN = 'sk_your_token'  # Your token from Dashboard → Tokens

# Step 2: Function to create payment and redirect to checkout
def redirect_to_payhive_checkout(amount, description):
    url = f'{API_BASE_URL}/payments'
    headers = {
        'Authorization': f'Bearer {TOKEN}',
        'Content-Type': 'application/json'
    }
    data = {
        'amount': amount,           # e.g., 50000.00 for 50,000 UGX
        'description': description,  # e.g., "Order #12345"
        'callback_url': 'https://yoursite.com/webhooks/payment'  # Optional
    }
    
    response = requests.post(url, json=data, headers=headers)
    result = response.json()
    
    # Step 3: Redirect customer to checkout page
    if response.status_code == 201 and 'checkout_url' in result:
        return redirect(result['checkout_url'])  # ← This redirects to PayHive checkout
    else:
        return {'error': result.get('message', 'Payment failed')}

# Step 4: Use it in your route/view
@app.route('/pay', methods=['POST'])  # Flask example
def pay():
    return redirect_to_payhive_checkout(50000.00, 'Payment for Order #12345')
    # Customer will be automatically redirected to checkout page

# Notes:
# - Replace API_BASE_URL with your PayHive instance URL
# - Get your token from: Dashboard → Tokens
# - The checkout_url from the response is the redirect destination
# - Amount is in smallest currency unit (50000.00 = 50,000 UGX)
# - Keep your token on server, never expose in frontend
# - Install requests: pip install requests

Quick Start Guide: Step-by-Step Instructions

Follow these simple steps to integrate the hosted checkout page into your application:

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

Complete Flow Diagram

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_PO6JMNWHCD 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

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://payhiive.com/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?

If you have any questions or need assistance with the API, please contact our support team:

• Email: support@payhiive.com
• Website: https://payhiive.com
• Dashboard: Login to Dashboard