Introduction

OpenPay provides a simple, developer-friendly API to accept payments from customers across Nigeria. Our payment gateway aggregator routes transactions through multiple payment providers to ensure the highest success rate.

This documentation will help you integrate OpenPay into your application quickly and securely.

Base URL: https://openpay.com.ng/api/v1

Authentication

All API requests require authentication using your secret key. Include your secret key in the Authorization header of every request:

Authorization: Bearer sk_test_your_secret_key_here

You can find your API keys in your merchant dashboard.

Important: Never expose your secret key in client-side code or public repositories.

POST Initialize Payment

Create a new payment transaction and get a payment URL for your customer.

Endpoint

POST /api/v1/payment/initialize

Request Parameters

Parameter Type Required Description
amount integer Yes Amount in kobo (e.g., 50000 for ₦500)
email string Yes Customer's email address
reference string No Unique transaction reference (auto-generated if not provided)
callback_url string No URL to redirect after payment

Example Request

PHP
Node.js
Python
<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://openpay.com.ng/api/v1/payment/initialize",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_test_your_secret_key",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "amount" => 50000,
        "email" => "[email protected]",
        "callback_url" => "https://yoursite.com/payment/callback"
    ])
]);

$response = curl_exec($curl);
$result = json_decode($response);

echo $result->data->payment_url;
?>
const axios = require('axios');

const response = await axios.post(
    'https://openpay.com.ng/api/v1/payment/initialize',
    {
        amount: 50000,
        email: '[email protected]',
        callback_url: 'https://yoursite.com/payment/callback'
    },
    {
        headers: {
            'Authorization': 'Bearer sk_test_your_secret_key',
            'Content-Type': 'application/json'
        }
    }
);

console.log(response.data.data.payment_url);
import requests
import json

url = "https://openpay.com.ng/api/v1/payment/initialize"
headers = {
    "Authorization": "Bearer sk_test_your_secret_key",
    "Content-Type": "application/json"
}
data = {
    "amount": 50000,
    "email": "[email protected]",
    "callback_url": "https://yoursite.com/payment/callback"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

print(result['data']['payment_url'])

Example Response

{
    "status": "success",
    "message": "Payment initialized successfully",
    "data": {
        "reference": "OPAY_1234_20240120_001234",
        "payment_url": "https://openpay.com.ng/checkout/OPAY_1234_20240120_001234",
        "amount": 50000,
        "email": "[email protected]"
    }
}

GET Verify Transaction

Verify the status of a transaction using its reference.

Endpoint

GET /api/v1/payment/verify/{reference}

Example Request

curl -X GET https://openpay.com.ng/api/v1/payment/verify/OPAY_1234_20240120_001234 \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example Response

{
    "status": "success",
    "message": "Transaction verified",
    "data": {
        "reference": "OPAY_1234_20240120_001234",
        "amount": 50000,
        "status": "success",
        "gateway": "paystack",
        "customer_email": "[email protected]",
        "paid_at": "2024-01-20T14:30:00Z"
    }
}

Webhooks

OpenPay sends webhook notifications to your server when payment events occur. Configure your webhook URL in your merchant dashboard.

Webhook Payload

{
    "event": "payment.success",
    "data": {
        "reference": "OPAY_1234_20240120_001234",
        "amount": 50000,
        "status": "success",
        "gateway": "paystack",
        "customer_email": "[email protected]",
        "paid_at": "2024-01-20T14:30:00Z"
    }
}

Verifying Webhook Signatures

All webhooks include an X-OpenPay-Signature header. Verify this signature to ensure the webhook came from OpenPay:

<?php

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_OPENPAY_SIGNATURE'];

$computed_signature = hash_hmac('sha512', $payload, $your_webhook_secret);

if ($signature === $computed_signature) {
    // Process webhook
    $event = json_decode($payload);
    // Handle event...
} else {
    http_response_code(400);
    exit();
}
?>

Error Handling

OpenPay uses standard HTTP status codes to indicate success or failure:

Status Code Meaning
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid API key
404 Not Found - Resource doesn't exist
500 Server Error - Something went wrong

SDKs & Libraries

We provide official SDKs to make integration easier:

PHP SDK

View on GitHub →

Node.js SDK

View on GitHub →

Python SDK

View on GitHub →