Bytepay Merchant API

Authentication

Bytepay API uses API keys to authenticate requests. You can obtain your credentials from your merchant dashboard.

Required Credentials

Request Signing Examples

$timestamp = (string) time();
$method = 'POST';
$path = '/api/v1/initiate-payout';
$body = json_encode($payload, JSON_UNESCAPED_SLASHES);
$signature = hash_hmac('sha256', "{$timestamp}.{$method}.{$path}.{$body}", $apiSecret);

Quick Start

Use this flow for a production-safe integration. Credentials identify the merchant, while currency and gateway availability are controlled from the merchant dashboard.

Merchant Setup & API Config

The merchant API is no longer a single-currency, fixed-gateway flow. A merchant can now support multiple currency rails, keep separate sandbox and production credentials, and choose eligible gateways from the API Config page without regenerating API keys.

Runtime Decision Order

1. 01
   Authenticate the environment

   X-Environment decides which merchant key, API key, and API secret are used.

2. 02
   Check merchant availability

   Rejected or disabled merchants are blocked. Production also requires approved merchant status.

3. 03
   Validate requested currency

   currency_code must match a merchant-supported rail such as USD, EUR, or BDT.

4. 04
   Confirm receiver wallet

   The merchant owner needs an active wallet for that same currency.

5. 05
   Resolve configured gateways

   Merchant API Config selections restrict checkout to the chosen eligible gateways. If none are selected, the safe fallback is all active automatic gateways for that currency.

6. 06
   Apply optional API filter

   allow_payment_methods can narrow the available gateway list, but it cannot expose an unconfigured or wrong-currency gateway.

Real Cases & Results

API Commission (Pay-in)

Each merchant has an API commission percentage set by the platform administrator. You choose who pays that fee from Merchant → API → API Commission. Payout fees are separate and come from the withdrawal method configuration.

initiate-payment Response Fields

Example (Merchant Pays, 5% fee, ₦1,000 payment)

{
  "payment_url": "https://bytepay.online/payment/checkout?...",
  "info": {
    "ref_trx": "ORDER_1001",
    "amount": 1000,
    "base_amount": 1000,
    "currency_code": "NGN",
    "environment": "production",
    "api_fee_bearer": "merchant",
    "api_fee_percent": 5,
    "api_commission_fee": 50,
    "commission_fee": 50,
    "commission_bearer": "merchant",
    "customer_pays": 1000,
    "merchant_receives": 1000
  }
}

verify-payment & IPN commission object

On successful payments, verify-payment and payment IPN payloads include a commission object:

"commission": {
  "base_amount": 1000,
  "commission_fee": 50,
  "commission_bearer": "merchant",
  "customer_paid": 1000,
  "merchant_received": 1000,
  "commission_trx_id": "TXN..."
}

Currency & Gateway Rules

Merchant API checkout is controlled by three layers: merchant-supported currency, active receiver wallet, and configured payment gateways. This keeps checkout options accurate after API credentials are generated.

How allow_payment_methods Works Now

Korapay Integration (Pay-In & Pay-Out)

Bytepay uses Korapay as the primary NGN payout provider for merchant API settlements, merchant withdrawals, and wallet bank transfers. Pay-in is available via Korapay hosted checkout and optional virtual account deposits.

Admin configuration

Configure Korapay under Admin → Integration Center → Korapay:

Platform webhook URL (Korapay dashboard)

Register this URL in your Korapay merchant dashboard. Korapay sends charge.success for deposits and transfer.success / transfer.failed for payouts.

Korapay Pay-In (Merchant collections)

Pay-In API flow

1. 01
   POST /api/v1/initiate-payment

   Include currency_code NGN and optional allow_payment_methods containing Korapay.

2. 02
   Redirect customer

   Open payment_url from the response.

3. 03
   Webhook + verify

   Receive payment IPN on your ipn_url. Poll GET /api/v1/verify-payment/{trx_id} if needed.

Korapay Pay-Out (Merchant settlements)

Payouts debit the merchant owner wallet immediately. Korapay disbursement runs asynchronously when status is processing; final status arrives via Korapay webhook and merchant IPN.

Required beneficiary fields (inline)

Example — Korapay NGN payout

{
  "payout_amount": 5000,
  "currency_code": "NGN",
  "ref_trx": "SETTLE_20260608_001",
  "ipn_url": "https://merchant.example/webhooks/bytepay-payout",
  "withdraw_method_id": 18,
  "description": "Vendor settlement",
  "beneficiary": {
    "bank_code": "044",
    "account_number": "0123456789"
  }
}

Payout status lifecycle

Merchant API error codes (payouts)

Korapay API endpoints used by Bytepay

Reconciliation & retries

• Pending Korapay payouts are finalized by webhooks (transfer.success / transfer.failed).
• Platform cron: php artisan korapay:reconcile-pending-payouts reconciles stuck pending transactions.
• Use GET /api/v1/verify-payout/{trx_id} to poll payout status from your integration.

Merchant onboarding checklist

1. 01
   Complete KYC

   Merchant owner must pass platform KYC and have Withdraw Money enabled.

2. 02
   Fund NGN wallet

   Collect pay-in via initiate-payment or manual funding.

3. 03
   GET payout-methods

   Note korapay_ngn_transfer withdraw_method_id for NGN.

4. 04
   POST initiate-payout

   Send bank_code + account_number; platform resolves account name.

5. 05
   Handle IPN

   Listen for event payout on your ipn_url; verify X-Signature.

PocketFi Integration (Pay-In & Pay-Out)

Bytepay supports PocketFi as a secondary NGN payment gateway alongside Korapay. Use PocketFi for hosted checkout collections, dynamic virtual accounts, and bank transfer payouts without affecting existing Korapay or StroWallet integrations.

Admin configuration

Configure PocketFi under Admin → Integration Center → Payment Gateways → PocketFi:

Platform webhook URL (PocketFi dashboard)

Register this URL under PocketFi Dashboard → Settings → Webhooks. PocketFi signs payloads with HMAC-SHA512 in the HTTP_POCKETFI_SIGNATURE header.

PocketFi Pay-In

PocketFi Pay-Out

Use withdraw_method_id from GET /api/v1/payout-methods where method_code is pocketfi_ngn_transfer.

Environment variables

POCKETFI_WEBHOOK_SECRET=
POCKETFI_LOG_CHANNEL=pocketfi
POCKETFI_VA_BANK=kuda
POCKETFI_SANDBOX_BVN=
POCKETFI_SANDBOX_NIN=

Reconciliation

Schedule pending payout reconciliation: php artisan pocketfi:reconcile-pending-payouts

XudoPay Integration (Pay-In & Pay-Out)

Bytepay supports XudoPay as an additional NGN payment gateway alongside Korapay, PocketFi, and StroWallet. Use XudoPay payment links for collections and the withdrawals API for bank transfer payouts without modifying existing gateway integrations.

Admin configuration

Platform webhook URL

Register this URL in XudoPay → Settings → API Settings → Webhooks. Verify the X-XudoPay-Signature header using HMAC-SHA256 over the raw JSON body.

XudoPay Pay-In

Underlying XudoPay API

POST https://xudopay.com/api/v1/payment-links
Authorization: Bearer xudo_sk_live_...

{
  "amount": 5000,
  "currency": "NGN",
  "title": "Wallet deposit",
  "reference": "TXN123456",
  "callback_url": "https://bytepay.online/status/callback?gateway=xudopay&trx=TXN123456"
}

XudoPay Pay-Out

Use withdraw_method_id from GET /api/v1/payout-methods where method_code is xudopay_ngn_transfer. Minimum payout_amount is ₦500. The XudoPay provider wallet must have sufficient balance to cover the transfer and withdrawal fee.

POST https://xudopay.com/api/v1/withdrawals
Authorization: Bearer xudo_sk_live_...

{
  "currency": "NGN",
  "amount": 5000,
  "bank_code": "057",
  "account_number": "0123456789",
  "account_name": "John Doe"
}

Transaction verification

GET https://xudopay.com/api/v1/transactions?reference=TXN123456
Authorization: Bearer xudo_sk_live_...

Environment variables

XUDOPAY_WEBHOOK_SECRET=
XUDOPAY_LOG_CHANNEL=xudopay
XUDOPAY_BASE_URL_LIVE=https://xudopay.com/api/v1
XUDOPAY_BASE_URL_SANDBOX=https://xudopay.com/api/v1

Reconciliation

php artisan xudopay:reconcile-pending-deposits

php artisan xudopay:reconcile-pending-payouts

Request Headers

Request Parameters

Gateway Availability Response Fields

Commission Response Fields

Code Examples

• cURL
• PHP
• Node.js

curl -X POST "https://bytepay.online/api/v1/initiate-payment" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Environment: sandbox" \
  -H "X-Merchant-Key: test_merchant_key" \
  -H "X-API-Key: test_api_key" \
  -H "X-Timestamp: 1778650000" \
  -H "X-Signature: sha256=generated_hmac_signature" \
  -d '{
    "payment_amount": 250.00,
    "currency_code": "USD",
    "ref_trx": "ORDER_12345",
    "description": "Premium Subscription",
    "success_redirect": "https://merchant.example/payments/success",
    "cancel_redirect": "https://merchant.example/payments/cancel",
    "ipn_url": "https://merchant.example/webhooks/bytepay",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "allow_payment_methods": ["stripe", "paypal"]
  }'

<?php

use Illuminate\Support\Facades\Http;

$payload = [
    'payment_amount' => 250.00,
    'currency_code' => 'USD',
    'ref_trx' => 'ORDER_12345',
    'description' => 'Premium Subscription',
    'success_redirect' => route('payments.success'),
    'cancel_redirect' => route('payments.cancel'),
    'ipn_url' => route('webhooks.bytepay'),
    'customer_name' => 'John Doe',
    'customer_email' => 'john@example.com',
    'allow_payment_methods' => ['stripe', 'paypal'],
];

$body = json_encode($payload, JSON_THROW_ON_ERROR);
$timestamp = (string) time();
$path = '/api/v1/initiate-payment';
$signature = hash_hmac(
    'sha256',
    $timestamp.'.POST.'.$path.'.'.$body,
    config('services.bytepay.api_secret')
);

$response = Http::withHeaders([
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'X-Environment' => 'sandbox',
    'X-Merchant-Key' => config('services.bytepay.merchant_key'),
    'X-API-Key' => config('services.bytepay.api_key'),
    'X-Timestamp' => $timestamp,
    'X-Signature' => 'sha256='.$signature,
])->withBody($body, 'application/json')
    ->post('https://bytepay.online/api/v1/initiate-payment')
    ->throw()
    ->json();

return redirect()->away($response['payment_url']);

const crypto = require('crypto');

const payload = {
  payment_amount: 250.00,
  currency_code: 'USD',
  ref_trx: 'ORDER_12345',
  description: 'Premium Subscription',
  success_redirect: 'https://merchant.example/payments/success',
  cancel_redirect: 'https://merchant.example/payments/cancel',
  ipn_url: 'https://merchant.example/webhooks/bytepay',
  customer_name: 'John Doe',
  customer_email: 'john@example.com',
  allow_payment_methods: ['stripe', 'paypal']
};

const body = JSON.stringify(payload);
const timestamp = Math.floor(Date.now() / 1000).toString();
const path = '/api/v1/initiate-payment';
const signature = crypto
  .createHmac('sha256', process.env.DIGIKASH_API_SECRET)
  .update(`${timestamp}.POST.${path}.${body}`)
  .digest('hex');

const response = await fetch('https://bytepay.online/api/v1/initiate-payment', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'X-Environment': 'sandbox',
    'X-Merchant-Key': process.env.DIGIKASH_MERCHANT_KEY,
    'X-API-Key': process.env.DIGIKASH_API_KEY,
    'X-Timestamp': timestamp,
    'X-Signature': `sha256=${signature}`
  },
  body
});

const data = await response.json();

if (!response.ok) {
  throw new Error(data.error || 'Payment initiation failed');
}

window.location.href = data.payment_url;

Success Response

{
  "payment_url": "https://Bytepay.test/payment/checkout?token=encrypted&signature=signed",
  "info": {
    "ref_trx": "ORDER_12345",
    "description": "Premium Subscription",
    "ipn_url": "https://merchant.example/webhooks/bytepay",
    "cancel_redirect": "https://merchant.example/payments/cancel",
    "success_redirect": "https://merchant.example/payments/success",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "merchant_id": 1,
    "merchant_name": "Demo Store",
    "amount": 250,
    "currency_code": "USD",
    "environment": "sandbox",
    "is_sandbox": true,
    "allow_payment_methods": ["stripe", "paypal"],
    "merchant_payment_methods_restricted": true,
    "merchant_payment_method_ids": [7],
    "merchant_payment_method_codes": ["stripe-usd"],
    "base_amount": 250,
    "api_fee_bearer": "customer",
    "api_fee_percent": 5,
    "api_commission_fee": 12.5,
    "commission_fee": 12.5,
    "commission_bearer": "customer",
    "customer_pays": 262.5,
    "merchant_receives": 250
  }
}

Common Error Responses

Request Headers

Path Parameter

cURL Example

curl -X GET "https://bytepay.online/api/v1/verify-payment/TXNQ5V8K2L9N3XM1" \
  -H "Accept: application/json" \
  -H "X-Environment: sandbox" \
  -H "X-Merchant-Key: test_merchant_key" \
  -H "X-API-Key: test_api_key" \
  -H "X-Timestamp: 1778650000" \
  -H "X-Signature: sha256=generated_hmac_signature"

Success Response

{
  "status": "success",
  "trx_id": "TXNQ5V8K2L9N3XM1",
  "amount": 237.5,
  "fee": 12.5,
  "currency": "USD",
  "net_amount": 237.5,
  "commission": {
    "base_amount": 250,
    "commission_fee": 12.5,
    "commission_bearer": "customer",
    "customer_paid": 262.5,
    "merchant_received": 250,
    "commission_trx_id": null
  },
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "description": "Premium Subscription",
  "created_at": "2026-05-13T10:30:00.000000Z",
  "updated_at": "2026-05-13T10:35:45.000000Z"
}

Payment Status Values

cURL Example

curl -X GET "https://bytepay.online/api/v1/site-info" \
  -H "Accept: application/json" \
  -H "X-Environment: sandbox" \
  -H "X-Merchant-Key: test_merchant_key" \
  -H "X-API-Key: test_api_key" \
  -H "X-Timestamp: 1778650000" \
  -H "X-Signature: sha256=generated_hmac_signature"

Success Response

{
  "site_name": "Bytepay",
  "site_logo": "https://bytepay.online/storage/images/2026/06/05/20260605_090923_chatgpt_image_jun_5_2026_04_03_22_am_nueh.png",
  "site_url": "https://bytepay.online",
  "gateway_name": "Bytepay Payment Gateway",
  "gateway_description": "Secure payment powered by Bytepay",
  "features": {
    "ssl_secured": "SSL Secured",
    "instant_processing": "Instant",
    "global_support": "Global",
    "mobile_ready": "Mobile Ready"
  },
  "environments": {
    "production": "Production Mode - Live payment processing is active",
    "sandbox": "Test Mode - This is a test transaction. No real money will be charged"
  },
  "api_version": "1.0",
  "status": "active"
}

Merchant Payout Guide

Use the payout API to send funds from your merchant owner wallet to a beneficiary bank account. Payouts debit your Bytepay wallet immediately; automatic gateways (Korapay, PocketFi, XudoPay) settle asynchronously and notify you via IPN or verify-payout.

End-to-end payout flow

1. 01
   Fund your wallet

   Collect pay-in via initiate-payment or receive manual credits. Your wallet must cover payout_amount plus the withdrawal method fee (payable_amount).

2. 02
   GET /api/v1/payout-methods?currency=NGN

   List active auto and manual withdrawal methods. Note the id, min_withdraw, max_withdraw, and fields for your chosen rail.

3. 03
   Prepare beneficiary

   Either save an account in Dashboard → Withdraw → Saved accounts (withdraw_account_id), or send inline beneficiary fields from the payout-methods response.

4. 04
   POST /api/v1/initiate-payout

   Sign the request with your API Secret. Wallet is debited immediately. Automatic payouts return status pending while the gateway processes.

5. 05
   Poll or listen

   Receive payout IPN on your ipn_url (event: payout), or poll GET /api/v1/verify-payout/{trx_id}.

6. 06
   Handle failures

   If the gateway rejects a transfer after wallet debit, Bytepay refunds payable_amount automatically. Check error_code and the error message.

NGN automatic payout methods

When Korapay, PocketFi, and XudoPay are configured, payout-methods returns them in this priority order. Only gateways with valid admin credentials appear in the API list.

Wallet, fees, and response amounts

Beneficiary field aliases

Inline beneficiary objects accept canonical field names from payout-methods, plus these aliases:

Prerequisites checklist

• Merchant approved for production (sandbox works with test credentials while pending).
• Merchant owner has Withdraw Money feature enabled.
• KYC and phone verification completed when required by platform rules.
• Active wallet for the payout currency_code.
• Wallet balance ≥ payable_amount (payout_amount + fee).
• Payout amount within method min_withdraw and max_withdraw from payout-methods.
• Platform withdrawal schedule allows payouts today.
• Valid bank_code for the selected gateway (Korapay codes for Korapay, etc.).

Request Headers

Request Parameters

Beneficiary options

Example — Saved account

{
  "payout_amount": 5000,
  "currency_code": "NGN",
  "ref_trx": "PAYOUT_20260607_001",
  "ipn_url": "https://merchant.example/webhooks/bytepay-payout",
  "withdraw_method_id": 18,
  "withdraw_account_id": 7,
  "description": "Vendor settlement"
}

withdraw_method_id is an example — always use the id from GET payout-methods for korapay_ngn_transfer.

Example — Korapay NGN (inline beneficiary, recommended)

{
  "payout_amount": 5000,
  "currency_code": "NGN",
  "ref_trx": "PAYOUT_98765",
  "ipn_url": "https://merchant.example/webhooks/payout",
  "withdraw_method_id": 18,
  "description": "Vendor settlement",
  "beneficiary": {
    "bank_code": "044",
    "account_number": "0123456789"
  }
}

Example — PocketFi NGN (inline beneficiary)

{
  "payout_amount": 2000,
  "currency_code": "NGN",
  "ref_trx": "PAYOUT_PF_001",
  "ipn_url": "https://merchant.example/webhooks/payout",
  "withdraw_method_id": 15,
  "description": "Affiliate commission",
  "beneficiary": {
    "bank_code": "100004",
    "account_number": "8033106710"
  }
}

Example — XudoPay NGN (inline beneficiary, min ₦500)

{
  "payout_amount": 500,
  "currency_code": "NGN",
  "ref_trx": "PAYOUT_XD_001",
  "ipn_url": "https://merchant.example/webhooks/payout",
  "withdraw_method_id": 17,
  "description": "Supplier payment",
  "beneficiary": {
    "bank_code": "100004",
    "account_number": "8033106710"
  }
}

Request signing (PHP)

$payload = [
    'payout_amount' => 5000,
    'currency_code' => 'NGN',
    'ref_trx' => 'PAYOUT_' . time(),
    'ipn_url' => 'https://merchant.example/webhooks/payout',
    'withdraw_method_id' => 18, // from GET payout-methods
    'beneficiary' => [
        'bank_code' => '044',
        'account_number' => '0123456789',
    ],
];

$body = json_encode($payload, JSON_UNESCAPED_SLASHES);
$timestamp = (string) time();
$path = '/api/v1/initiate-payout';
$signature = hash_hmac('sha256', "{$timestamp}.POST.{$path}.{$body}", $apiSecret);

$response = Http::withHeaders([
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'X-Environment' => 'production',
    'X-Merchant-Key' => $merchantKey,
    'X-API-Key' => $apiKey,
    'X-Timestamp' => $timestamp,
    'X-Signature' => $signature,
])->withBody($body, 'application/json')
  ->post('https://bytepay.online/api/v1/initiate-payout');

cURL Example

curl -X POST "https://bytepay.online/api/v1/initiate-payout" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Environment: production" \
  -H "X-Merchant-Key: {merchant_key}" \
  -H "X-API-Key: {api_key}" \
  -H "X-Timestamp: {unix_timestamp}" \
  -H "X-Signature: {hmac_sha256_hex}" \
  -d '{
    "payout_amount": 5000,
    "currency_code": "NGN",
    "ref_trx": "PAYOUT_001",
    "ipn_url": "https://merchant.example/webhooks/payout",
    "withdraw_method_id": 18,
    "beneficiary": {
      "bank_code": "044",
      "account_number": "0123456789"
    }
  }'

Success Response

{
  "trx_id": "TXNL8VXLVMTJS50",
  "status": "pending",
  "info": {
    "merchant_id": 10,
    "merchant_name": "Essential-NG",
    "ref_trx": "PAYOUT_001",
    "ipn_url": "https://merchant.example/webhooks/payout",
    "environment": "production",
    "is_sandbox": false,
    "api_merchant_payout": true,
    "withdraw_method_id": 18,
    "withdraw_method": "Korapay Bank Transfer (NGN)",
    "trx_id": "TXNL8VXLVMTJS50",
    "payout_amount": 5000,
    "currency_code": "NGN",
    "fee": 75,
    "net_amount": 5000,
    "payable_amount": 5075,
    "status": "pending",
    "processing_type": "auto"
  }
}

Payout status lifecycle

Payout Error Codes (422 responses)

Example error response

{
  "error": "Payout failed: Korapay has not enabled live payouts for this merchant account yet. Enable Disburse/Payout in Korapay, whitelist server IP, or contact Korapay support. The deducted amount has been refunded.",
  "error_code": "payout_failed"
}

Request Headers

Same signed headers as other merchant API GET endpoints. Sign timestamp.GET./api/v1/verify-payout/{trxId}. with an empty raw body.

Path Parameter

cURL Example

curl -X GET "https://bytepay.online/api/v1/verify-payout/TXNL8VXLVMTJS50" \
  -H "Accept: application/json" \
  -H "X-Environment: production" \
  -H "X-Merchant-Key: {merchant_key}" \
  -H "X-API-Key: {api_key}" \
  -H "X-Timestamp: {unix_timestamp}" \
  -H "X-Signature: {hmac_sha256_hex}"

Success Response (completed)

{
  "status": "success",
  "event": "payout",
  "trx_id": "TXNL8VXLVMTJS50",
  "ref_trx": "PAYOUT_001",
  "amount": 5000,
  "fee": 75,
  "currency": "NGN",
  "net_amount": 5000,
  "description": "Withdraw via Korapay Bank Transfer (NGN)",
  "created_at": "2026-06-07T16:26:22.000000Z",
  "updated_at": "2026-06-07T16:26:26.000000Z"
}

Pending response

{
  "status": "pending",
  "event": "payout",
  "trx_id": "TXNL8VXLVMTJS50",
  "ref_trx": "PAYOUT_001",
  "message": "Payout is still pending."
}

Failed response

{
  "status": "failed",
  "event": "payout",
  "trx_id": "TXNL8VXLVMTJS50",
  "ref_trx": "PAYOUT_001",
  "message": "Payout failed or was canceled."
}

Status Values

Query Parameters

Response fields

Success Response (NGN example)

{
  "currency_code": "NGN",
  "methods": [
    {
      "id": 18,
      "name": "Korapay Bank Transfer (NGN)",
      "method_code": "korapay_ngn_transfer",
      "type": "auto",
      "currency": "NGN",
      "min_withdraw": 100,
      "max_withdraw": 5000000,
      "fields": [
        {
          "name": "bank_code",
          "type": "select",
          "validation": "required",
          "label": "Bank"
        },
        {
          "name": "account_number",
          "type": "text",
          "validation": "required",
          "label": "Account Number"
        },
        {
          "name": "account_name",
          "type": "text",
          "validation": "nullable",
          "label": "Account Holder Name",
          "api_auto_resolved": true
        }
      ]
    },
    {
      "id": 15,
      "name": "PocketFi Bank Transfer (NGN)",
      "method_code": "pocketfi_ngn_transfer",
      "type": "auto",
      "currency": "NGN",
      "min_withdraw": 100,
      "max_withdraw": 5000000,
      "fields": [
        {
          "name": "bank_code",
          "type": "select",
          "validation": "required",
          "label": "Bank"
        },
        {
          "name": "account_number",
          "type": "text",
          "validation": "required",
          "label": "Account Number"
        },
        {
          "name": "account_name",
          "type": "text",
          "validation": "nullable",
          "label": "Account Holder Name",
          "api_auto_resolved": true
        }
      ]
    },
    {
      "id": 17,
      "name": "XudoPay Bank Transfer (NGN)",
      "method_code": "xudopay_ngn_transfer",
      "type": "auto",
      "currency": "NGN",
      "min_withdraw": 500,
      "max_withdraw": 5000000,
      "fields": [
        {
          "name": "bank_code",
          "type": "select",
          "validation": "required",
          "label": "Bank"
        },
        {
          "name": "account_number",
          "type": "text",
          "validation": "required",
          "label": "Account Number"
        },
        {
          "name": "account_name",
          "type": "text",
          "validation": "nullable",
          "label": "Account Holder Name",
          "api_auto_resolved": true
        }
      ]
    },
    {
      "id": 14,
      "name": "Bank Transfer",
      "method_code": "Bytepay",
      "type": "manual",
      "currency": "NGN",
      "min_withdraw": 500,
      "max_withdraw": 1000000,
      "fields": [
        {
          "name": "Bank Name",
          "type": "text",
          "validation": "required"
        },
        {
          "name": "Account Number",
          "type": "text",
          "validation": "required"
        }
      ]
    }
  ]
}

Method ids (18, 15, 17, 14) are examples from a typical installation. Always use live values from your payout-methods response. Only gateways with configured credentials are listed.

Webhooks (IPN)

Bytepay sends real-time notifications to your specified IPN URL when payment status changes. This ensures you're immediately notified of payment completions, failures, and other status updates. Webhooks work identically in both sandbox and production environments.

Webhook Headers

Webhook Payload

All webhook payloads include environment information to help you differentiate between sandbox and production transactions:

Payment IPN

{
  "event": "payment",
  "data": {
    "ref_trx": "ORDER_1234",
    "trx_id": "TXNQ5V8K2L9N3XM1",
    "description": "Order #1234",
    "ipn_url": "https://merchant.com/webhooks/payment",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "merchant_name": "Demo Store",
    "amount": 1000,
    "base_amount": 1000,
    "currency_code": "NGN",
    "environment": "production",
    "is_sandbox": false,
    "commission": {
      "base_amount": 1000,
      "commission_fee": 50,
      "commission_bearer": "merchant",
      "customer_paid": 1000,
      "merchant_received": 1000
    }
  },
  "message": "Payment Completed",
  "status": "completed",
  "timestamp": 1705747245
}

Payout IPN

{
  "event": "payout",
  "data": {
    "ref_trx": "PAYOUT_001",
    "trx_id": "TXNL8VXLVMTJS50",
    "ipn_url": "https://merchant.com/webhooks/payout",
    "environment": "production",
    "is_sandbox": false,
    "api_merchant_payout": true,
    "payout_amount": 5000,
    "currency_code": "NGN",
    "withdraw_method_id": 18,
    "withdraw_method": "Korapay Bank Transfer (NGN)"
  },
  "message": "Payout Completed",
  "status": "completed",
  "timestamp": 1705747300
}

Signature Verification

Always verify webhook signatures to ensure authenticity and prevent unauthorized requests. Use your API secret (environment-specific) to verify signatures:

<?php
// Laravel Webhook Handler
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use App\Enums\EnvironmentMode;

class BytepayWebhookController extends Controller
{
    public function handle(Request $request)
    {
        // Get webhook headers
        $environment = $request->header('X-Environment', 'production');
        $signature = $request->header('X-Signature');
        
        // Get appropriate secret based on environment
        $secret = $this->getSecretForEnvironment($environment);
        
        // Verify signature
        if (!$this->verifySignature($request->getContent(), $signature, $secret)) {
            Log::warning('Bytepay webhook signature verification failed', [
                'environment' => $environment
            ]);
            
            return response()->json(['error' => 'Invalid signature'], 401);
        }
        
        $payload = $request->json()->all();
        
        // Handle based on environment
        if ($environment === EnvironmentMode::SANDBOX->value) {
            return $this->handleSandboxWebhook($payload);
        } else {
            return $this->handleProductionWebhook($payload);
        }
    }
    
    private function getSecretForEnvironment(string $environment): string
    {
        // Return test secret for sandbox, live secret for production
        return $environment === 'sandbox' 
            ? config('bytepay.test_api_secret')
            : config('bytepay.api_secret');
    }
    
    private function verifySignature(string $payload, string $signature, string $secret): bool
    {
        $expectedSignature = hash_hmac('sha256', $payload, $secret);
        $providedSignature = str_starts_with($signature, 'sha256=') ? substr($signature, 7) : $signature;

        return hash_equals($expectedSignature, $providedSignature);
    }
    
    private function handleSandboxWebhook(array $payload): JsonResponse
    {
        Log::info('Processing sandbox webhook', $payload);
        
        // Your sandbox-specific logic here
        // Don't fulfill orders, don't send emails to real customers, etc.
        
        return response()->json(['status' => 'sandbox_processed']);
    }
    
    private function handleProductionWebhook(array $payload): JsonResponse
    {
        Log::info('Processing production webhook', $payload);
        
        // Your production logic here
        // Fulfill orders, send confirmation emails, etc.
        
        return response()->json(['status' => 'processed']);
    }
}

const crypto = require('crypto');
const express = require('express');

const EnvironmentMode = {
    SANDBOX: 'sandbox',
    PRODUCTION: 'production'
};

// Webhook handler
app.post('/api/webhooks/bytepay', async (req, res) => {
    const environment = req.headers['x-environment'] || 'production';
    const signature = req.headers['x-signature'];
    
    # Get appropriate secret based on environment
    const secret = getSecretForEnvironment(environment);
    
    # Verify signature
    if (!verifySignature(JSON.stringify(req.body), signature, secret)) {
        console.warn('Bytepay webhook signature verification failed', {
            environment: environment
        });
        
        return res.status(401).json({ error: 'Invalid signature' });
    }
    
    const payload = req.body;
    
    try {
        # Handle based on environment
        if (environment === EnvironmentMode.SANDBOX) {
            await handleSandboxWebhook(payload);
        } else {
            await handleProductionWebhook(payload);
        }
        
        res.json({ status: 'processed' });
    } catch (error) {
        console.error('Webhook processing error:', error);
        res.status(500).json({ error: 'Processing failed' });
    }
});

function getSecretForEnvironment(environment) {
    # Return test secret for sandbox, live secret for production
    return environment === 'sandbox' 
        ? process.env.BYTEPAY_TEST_API_SECRET
        : process.env.BYTEPAY_API_SECRET;
}

function verifySignature(payload, signature, secret) {
    if (!signature) {
        return false;
    }
    
    const expectedSignature = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    const providedSignature = signature.startsWith('sha256=') ? signature.slice(7) : signature;
    
    return crypto.timingSafeEqual(
        Buffer.from(expectedSignature),
        Buffer.from(providedSignature)
    );
}

async function handleSandboxWebhook(payload) {
    console.log('Processing sandbox webhook:', payload);
    
    # Your sandbox-specific logic here
    # Don't fulfill orders, don't send emails to real customers, etc.
}

async function handleProductionWebhook(payload) {
    console.log('Processing production webhook:', payload);
    
    # Your production logic here
    # Fulfill orders, send confirmation emails, etc.
}

import hmac
import hashlib
import json
import logging
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_http_methods

logger = logging.getLogger(__name__)

ENVIRONMENT_MODE = {
    'SANDBOX': 'sandbox',
    'PRODUCTION': 'production'
}

@csrf_exempt
@require_http_methods(["POST"])
def bytepay_webhook(request):
    environment = request.headers.get('X-Environment', 'production')
    signature = request.headers.get('X-Signature', '')
    
    # Get appropriate secret based on environment
    secret = get_secret_for_environment(environment)
    
    # Verify signature
    if not verify_signature(request.body, signature, secret):
        logger.warning('Bytepay webhook signature verification failed', extra={
            'environment': environment
        })
        
        return JsonResponse({'error': 'Invalid signature'}, status=401)
    
    try:
        payload = json.loads(request.body)
        
        # Handle based on environment
        if environment == ENVIRONMENT_MODE['SANDBOX']:
            handle_sandbox_webhook(payload)
        else:
            handle_production_webhook(payload)
        
        return JsonResponse({'status': 'processed'})
    
    except Exception as e:
        logger.error(f'Webhook processing error:{str(e)}')
        return JsonResponse({'error': 'Processing failed'}, status=500)

def get_secret_for_environment(environment):
    from django.conf import settings
    
    # Return test secret for sandbox, live secret for production
    return (settings.BYTEPAY_TEST_API_SECRET 
            if environment == 'sandbox' 
            else settings.BYTEPAY_API_SECRET)

def verify_signature(payload, signature, secret):
    if not signature:
        return False
    
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    provided_signature = signature[7:] if signature.startswith('sha256=') else signature
    
    return hmac.compare_digest(expected_signature, provided_signature)

def handle_sandbox_webhook(payload):
    logger.info('Processing sandbox webhook', extra=payload)
    
    # Your sandbox-specific logic here
    # Don't fulfill orders, don't send emails to real customers, etc.

def handle_production_webhook(payload):
    logger.info('Processing production webhook', extra=payload)
    
    # Your production logic here
    # Fulfill orders, send confirmation emails, etc.

Environment-Specific Best Practices

Integration Examples

Production-oriented integration examples for popular platforms and frameworks. Keep gateway selection in Merchant API Config, then sign each API request from your server.

Payout integration snippet

// 1. List methods: GET /api/v1/payout-methods?currency=NGN
//    Pick id where method_code = 'korapay_ngn_transfer' (primary NGN rail)
$methods = $bytepay->getPayoutMethods('NGN');
$korapay = collect($methods['methods'])->firstWhere('method_code', 'korapay_ngn_transfer');

// 2. Initiate payout (inline beneficiary or saved withdraw_account_id)
$payload = [
    'payout_amount' => 5000,
    'currency_code' => 'NGN',
    'ref_trx' => 'PAYOUT_' . time(),
    'ipn_url' => route('webhooks.payout'),
    'withdraw_method_id' => $korapay['id'],
    'beneficiary' => [
        'bank_code' => '044',
        'account_number' => '0123456789',
    ],
];
// Sign POST /api/v1/initiate-payout with sandbox or production api_secret
$result = $bytepay->initiatePayout($payload); // trx_id, status: pending

// 3. Verify: GET /api/v1/verify-payout/{trx_id} or handle payout IPN (event: payout)

<?php
// Laravel Integration Service
namespace App\Services;

use Illuminate\Support\Facades\Http;
use Exception;

class BytepayService
{
    private string $baseUrl;
    private string $merchantKey;
    private string $apiKey;
    private string $environment;

    public function __construct()
    {
        $this->baseUrl = config('bytepay.base_url');
        $this->merchantKey = config('bytepay.merchant_key');
        $this->apiKey = config('bytepay.api_key');
        $this->environment = config('bytepay.environment'); // 'sandbox' or 'production'
    }

    public function initiatePayment(array $paymentData): array
    {
        try {
            $response = Http::withHeaders([
                'Content-Type' => 'application/json',
                'X-Environment' => $this->environment,
                'X-Merchant-Key' => $this->merchantKey,
                'X-API-Key' => $this->apiKey,
            ])->post("{$this->baseUrl}/api/v1/initiate-payment", $paymentData);

            if ($response->successful()) {
                return $response->json();
            }

            throw new Exception('Bytepay API Error: Payment initiation failed');
        } catch (Exception $e) {
            throw new Exception('Bytepay API Error: ' . $e->getMessage());
        }
    }

    public function verifyPayment(string $transactionId): array
    {
        try {
            $response = Http::withHeaders([
                'Accept' => 'application/json',
                'X-Environment' => $this->environment,
                'X-Merchant-Key' => $this->merchantKey,
                'X-API-Key' => $this->apiKey,
            ])->get("{$this->baseUrl}/api/v1/verify-payment/{$transactionId}");

            if ($response->successful()) {
                return $response->json();
            }

            throw new Exception('Bytepay API Error: Payment verification failed');
        } catch (Exception $e) {
            throw new Exception('Bytepay API Error: ' . $e->getMessage());
        }
    }
}

// Configuration (config/bytepay.php)
return [
    'base_url' => env('BYTEPAY_BASE_URL', 'https://bytepay.online'),
    'environment' => env('BYTEPAY_ENVIRONMENT', 'sandbox'), // sandbox or production
    'merchant_key' => env('BYTEPAY_MERCHANT_KEY'), // Use appropriate prefix
    'api_key' => env('BYTEPAY_API_KEY'), // Use appropriate prefix
];

// Usage in Controller
class PaymentController extends Controller
{
    public function initiatePayment(Request $request, BytepayService $bytepay)
    {
        $paymentData = [
            'payment_amount' => $request->amount,
            'currency_code' => 'USD',
            'ref_trx' => 'ORDER_' . time(),
            'description' => $request->description,
            'success_redirect' => route('payment.success'),
            'cancel_redirect' => route('payment.cancelled'),
            'ipn_url' => route('webhooks.bytepay'),
            'allow_payment_methods' => ['stripe', 'paypal'],
        ];

        try {
            $result = $bytepay->initiatePayment($paymentData);
            return redirect($result['payment_url']);
        } catch (Exception $e) {
            return back()->withErrors(['error' => $e->getMessage()]);
        }
    }
}

// Node.js Integration Service
const axios = require('axios');

class BytepayService {
    constructor() {
        this.baseUrl = process.env.BYTEPAY_BASE_URL || 'https://bytepay.online';
        this.environment = process.env.BYTEPAY_ENVIRONMENT || 'sandbox'; // sandbox or production
        this.merchantKey = process.env.BYTEPAY_MERCHANT_KEY; // Use appropriate prefix
        this.apiKey = process.env.BYTEPAY_API_KEY; // Use appropriate prefix
    }

    async initiatePayment(paymentData) {
        try {
            const response = await axios.post(`${this.baseUrl}/api/v1/initiate-payment`, paymentData, {
                headers: {
                    'Content-Type': 'application/json',
                    'X-Environment': this.environment,
                    'X-Merchant-Key': this.merchantKey,
                    'X-API-Key': this.apiKey
                }
            });

            return response.data;
        } catch (error) {
            throw new Error(`Bytepay API Error: ${error.message}`);
        }
    }

    async verifyPayment(transactionId) {
        try {
            const response = await axios.get(`${this.baseUrl}/api/v1/verify-payment/${transactionId}`, {
                headers: {
                    'Accept': 'application/json',
                    'X-Environment': this.environment,
                    'X-Merchant-Key': this.merchantKey,
                    'X-API-Key': this.apiKey
                }
            });

            return response.data;
        } catch (error) {
            throw new Error(`Bytepay API Error: ${error.message}`);
        }
    }
}

// Express.js Route Example
const express = require('express');
const app = express();
const bytepay = new BytepayService();

app.post('/initiate-payment', async (req, res) => {
    const paymentData = {
        payment_amount: req.body.amount,
        currency_code: 'USD',
        ref_trx: `ORDER_${Date.now()}`,
        description: req.body.description,
        success_redirect: `${req.protocol}://${req.get('host')}/payment/success`,
        cancel_redirect: `${req.protocol}://${req.get('host')}/payment/cancelled`,
        ipn_url: `${req.protocol}://${req.get('host')}/webhooks/bytepay`,
        allow_payment_methods: ['stripe', 'paypal'],
    };

    try {
        const result = await bytepay.initiatePayment(paymentData);
        res.redirect(result.payment_url);
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

module.exports = BytepayService;

# Python/Django Integration Service
import os
import requests
from django.conf import settings

class BytepayService:
    def __init__(self):
        self.base_url = getattr(settings, 'BYTEPAY_BASE_URL', 'https://bytepay.online')
        self.environment = getattr(settings, 'BYTEPAY_ENVIRONMENT', 'sandbox')  # sandbox or production
        self.merchant_key = getattr(settings, 'BYTEPAY_MERCHANT_KEY')  # Use appropriate prefix
        self.api_key = getattr(settings, 'BYTEPAY_API_KEY')  # Use appropriate prefix

    def initiate_payment(self, payment_data):
        try:
            headers = {
                'Content-Type': 'application/json',
                'X-Environment': self.environment,
                'X-Merchant-Key': self.merchant_key,
                'X-API-Key': self.api_key
            }

            response = requests.post(
                f"{self.base_url}/api/v1/initiate-payment",
                headers=headers,
                json=payment_data,
                timeout=30
            )

            response.raise_for_status()
            return response.json()

        except requests.RequestException as e:
            raise Exception(f'Bytepay API Error: {str(e)}')

    def verify_payment(self, transaction_id):
        try:
            headers = {
                'Accept': 'application/json',
                'X-Environment': self.environment,
                'X-Merchant-Key': self.merchant_key,
                'X-API-Key': self.api_key
            }

            response = requests.get(
                f"{self.base_url}/api/v1/verify-payment/{transaction_id}",
                headers=headers,
                timeout=30
            )

            response.raise_for_status()
            return response.json()

        except requests.RequestException as e:
            raise Exception(f'Bytepay API Error: {str(e)}')

# Django Settings Configuration
BYTEPAY_BASE_URL = 'https://bytepay.online'
BYTEPAY_ENVIRONMENT = 'sandbox'  # Change to 'production' for live
BYTEPAY_MERCHANT_KEY = os.environ.get('BYTEPAY_MERCHANT_KEY')  # Use appropriate prefix
BYTEPAY_API_KEY = os.environ.get('BYTEPAY_API_KEY')  # Use appropriate prefix

# Django View Example
from django.shortcuts import redirect
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
import json

bytepay = BytepayService()

@csrf_exempt
def initiate_payment(request):
    if request.method == 'POST':
        data = json.loads(request.body)
        
        payment_data = {
            'payment_amount': data['amount'],
            'currency_code': 'USD',
            'ref_trx': f'ORDER_{int(time.time())}',
            'description': data['description'],
            'success_redirect': request.build_absolute_uri('/payment/success/'),
            'cancel_redirect': request.build_absolute_uri('/payment/cancelled/'),
            'ipn_url': request.build_absolute_uri('/webhooks/bytepay/'),
            'allow_payment_methods': ['stripe', 'paypal'],
        }

        try:
            result = bytepay.initiate_payment(payment_data)
            return redirect(result['payment_url'])
        except Exception as e:
            return JsonResponse({'error': str(e)}, status=500)

# Environment Variables Setup
export BYTEPAY_ENVIRONMENT="sandbox"  # or "production"
export BYTEPAY_MERCHANT_KEY="test_merchant_your_key"  # or "merchant_your_key" for production
export BYTEPAY_API_KEY="test_your_api_key"  # or "your_api_key" for production

# Initiate Payment
curl -X POST "https://bytepay.online/api/v1/initiate-payment" \
  -H "Content-Type: application/json" \
  -H "X-Environment: $BYTEPAY_ENVIRONMENT" \
  -H "X-Merchant-Key: $BYTEPAY_MERCHANT_KEY" \
  -H "X-API-Key: $BYTEPAY_API_KEY" \
  -d '{
    "payment_amount": 250.00,
    "currency_code": "USD",
    "ref_trx": "ORDER_12345",
    "description": "Premium Subscription",
    "success_redirect": "https://yoursite.com/payment/success",
    "cancel_redirect": "https://yoursite.com/payment/cancelled",
    "ipn_url": "https://yoursite.com/api/webhooks/bytepay",
    "allow_payment_methods": ["stripe", "paypal"]
  }'

# Verify Payment
curl -X GET "https://bytepay.online/api/v1/verify-payment/TXNQ5V8K2L9N3XM1" \
  -H "Accept: application/json" \
  -H "X-Environment: $BYTEPAY_ENVIRONMENT" \
  -H "X-Merchant-Key: $BYTEPAY_MERCHANT_KEY" \
  -H "X-API-Key: $BYTEPAY_API_KEY"

# Environment-specific credential examples:
# Sandbox: test_merchant_xxxxx, test_api_key_xxxxx
# Production: merchant_xxxxx, api_key_xxxxx

WooCommerce Integration

Advanced Bytepay payment gateway with modern WooCommerce Blocks support, dynamic branding, and enterprise-grade security features.

X-Environment: sandbox|production
X-Merchant-Key: your_merchant_id
X-API-Key: your_api_key
Content-Type: application/json

Sandbox & Go Live Checklist

Use this checklist before moving from test payments to live checkout. The same API routes work in both modes; only the environment header and credential set change.

Interactive API Testing

Test Bytepay API endpoints directly from this documentation. Use the demo credentials below for sandbox testing.

Error Codes

Bytepay API uses conventional HTTP response codes to indicate the success or failure of API requests.

HTTP Status Codes

API Error Codes

Error Response Format

{
  "error": "Insufficient wallet balance.",
  "error_code": "insufficient_balance"
}