MyroPay API Reference

# Checkout API (SDK-facing — auth via checkout key)
https://checkout.myropay.com/api/

# Business API (auth via JWT or business key)
https://business.myropay.com/api/

# Personal App API (auth via JWT)
https://app.myropay.com/api/

X-Checkout-Key: ck_sec_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOjEsImFjdG9yX3R5cGUiOiJidXNpbmVzcyJ9.xxx

{
  "success": true,
  "message": "Session created",
  "data": { /* response payload */ }
}

{
  "success": false,
  "message": "amount must be greater than 0",
  "error_code": "VALIDATION_ERROR",
  "status_code": 422
}

GET /api/invoices.php?action=list&page=2&per_page=20

{
  "success": true,
  "data": {
    "data":         [ /* array of items */ ],
    "total":        143,
    "page":         2,
    "per_page":     20,
    "total_pages":  8,
    "has_next":     true,
    "has_prev":     true
  }
}

{
  "amount":          5000,
  "currency_code":   "NGN",
  "idempotency_key": "order_9876_attempt_1"
}

const crypto = require('crypto');

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig      = req.headers['x-myropay-signature'] || '';
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.MYROPAY_WEBHOOK_SECRET).update(req.body).digest('hex');
  const ok = sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  if (!ok) return res.status(401).send('Unauthorized');

  const { event, data } = JSON.parse(req.body);
  if (event === 'payment.success') fulfillOrder(data.session_id, data.order_ref);
  res.json({ received: true });
});

$payload  = file_get_contents('php://input');
$sig      = $_SERVER['HTTP_X_MYROPAY_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $payload, $_ENV['MYROPAY_WEBHOOK_SECRET']);

if (!hash_equals($expected, $sig)) {
  http_response_code(401); exit;
}
$event = json_decode($payload, true);
if ($event['event'] === 'payment.success') {
  fulfillOrder($event['data']['session_id'], $event['data']['order_ref']);
}
http_response_code(200);

import hmac, hashlib, os

@app.route('/webhook', methods=['POST'])
def webhook():
    payload  = request.get_data()
    sig      = request.headers.get('X-MyroPay-Signature', '')
    expected = 'sha256=' + hmac.new(os.environ['MYROPAY_WEBHOOK_SECRET'].encode(), payload, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sig):
        return 'Unauthorized', 401
    event = request.get_json()
    if event['event'] == 'payment.success':
        fulfill_order(event['data']['session_id'], event['data']['order_ref'])
    return '', 200

import MyroPay from 'myropay-js';
const client = new MyroPay('ck_sec_live_xxxx');

const session = await client.checkout.create({
  amount:         500000,   // ₦5,000.00 in kobo
  currency_code:  'NGN',
  description:    'Order #1234',
  customer_email: 'customer@example.com',
  success_url:    'https://mystore.com/success',
  cancel_url:     'https://mystore.com/cancel',
  metadata:       { order_id: 'ORD-9876' },
  idempotency_key: 'order-9876-attempt-1',
});

// Redirect customer to payment page
window.location.href = session.checkout_url;

use MyroPay\Client;
$client = new Client('ck_sec_live_xxxx');

$session = $client->checkout->create([
  'amount'          => 500000,
  'currency_code'   => 'NGN',
  'description'     => 'Order #1234',
  'customer_email'  => 'customer@example.com',
  'success_url'     => 'https://mystore.com/success',
  'cancel_url'      => 'https://mystore.com/cancel',
  'metadata'        => ['order_id' => 'ORD-9876'],
  'idempotency_key' => 'order-9876-attempt-1',
]);

header('Location: ' . $session['checkout_url']);

import myropay
client = myropay.Client("ck_sec_live_xxxx")

session = client.checkout.create(
    amount=500000,
    currency_code="NGN",
    description="Order #1234",
    customer_email="customer@example.com",
    success_url="https://mystore.com/success",
    cancel_url="https://mystore.com/cancel",
    metadata={"order_id": "ORD-9876"},
    idempotency_key="order-9876-attempt-1",
)
return redirect(session["checkout_url"])

curl -X POST https://checkout.myropay.com/api/session.php?action=create \
  -H "X-Checkout-Key: ck_sec_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "currency_code": "NGN",
    "description": "Order #1234",
    "customer_email": "customer@example.com",
    "success_url": "https://mystore.com/success",
    "cancel_url": "https://mystore.com/cancel",
    "metadata": { "order_id": "ORD-9876" },
    "idempotency_key": "order-9876-attempt-1"
  }'

{ "token": "a1b2c3d4..." }

{ "id": 42 }

{
  "event": "payment.success",
  "data": {
    "session_id": "cs_live_9f2c4e7a1b3d5f60718293a4b5c6d7e8f9a0b1c2",
    "order_ref": "ORD-9876",
    "status": "success",
    "amount": 15000.0,
    "currency": "NGN",
    "gateway": "flutterwave",
    "customer_email": "customer@example.com",
    "escrow": false,
    "is_test": false,
    "metadata": { "cart_id": "c_123" },
    "paid_at": "2026-09-28T10:15:32+01:00"
  },
  "timestamp": 1790586932
}

{
  "event": "payment.failed",
  "data": {
    "session_id": "cs_live_9f2c4e7a1b3d5f60718293a4b5c6d7e8f9a0b1c2",
    "order_ref": "ORD-9876",
    "status": "failed",
    "amount": 15000.0,
    "currency": "NGN",
    "gateway": "flutterwave",
    "customer_email": "customer@example.com",
    "escrow": false,
    "is_test": false,
    "metadata": { "cart_id": "c_123" },
    "gateway_status": "failed"
  },
  "timestamp": 1790586932
}

{
  "event": "subscription_invoice.paid",
  "data": {
    "invoice_id": "inv_live_4d1e...",
    "subscription_id": "sub_live_7b3a...",
    "plan_id": "plan_live_2c9f...",
    "status": "paid",
    "amount": 15000.0,
    "currency": "NGN",
    "billing_mode": "card_token",
    "customer_email": "customer@example.com",
    "checkout_session_id": null,
    "due_at": "2026-10-28 10:00:04",
    "paid_at": "2026-10-28 10:00:06"
  },
  "timestamp": 1793178006
}

{
  "event": "transfer.received",
  "data": { "amount": 10000.0, "currency": "NGN", "sent_amount": 10000.0, "sent_currency": "NGN", "from": "@adaobi" },
  "timestamp": 1790586932
}

{
  "event": "payout.completed",
  "data": { "transaction_id": "6f1c0c52-9b1e-4c1a-8e0d-2a5f6c0b7a11", "amount": 50000.0, "fee": 500.0, "currency": "NGN", "method": "bank", "status": "completed" },
  "timestamp": 1790586932
}

{
  "event": "payout.failed",
  "data": { "transaction_id": "6f1c0c52-9b1e-4c1a-8e0d-2a5f6c0b7a11", "amount": 50000.0, "fee": 500.0, "currency": "NGN", "method": "bank", "status": "failed", "reason": "Account closed" },
  "timestamp": 1790586932
}

{
  "event": "subscription.wallet_authorized",
  "data": { "subscription_id": "sub_live_7b3a...", "authorized_at": "2026-10-28T10:00:06+00:00" },
  "timestamp": 1793178006
}

{
  "event": "subscription.autopay_stopped",
  "data": { "subscription_id": "sub_live_7b3a...", "billing_mode": "invoice" },
  "timestamp": 1793178006
}

{
  "event": "subscription.cancel_scheduled",
  "data": { "subscription_id": "sub_live_7b3a...", "cancelled_by": "customer", "ends_at": "2026-11-28 10:00:04" },
  "timestamp": 1793178006
}

{
  "event": "subscription.cancelled",
  "data": { "subscription_id": "sub_live_7b3a...", "reason": "payment_failed" },
  "timestamp": 1793178006
}

{
  "event": "subscription.resumed",
  "data": { "subscription_id": "sub_live_7b3a..." },
  "timestamp": 1793178006
}

{
  "event": "payroll.completed",
  "data": { "batch_id": "0b8f0a1e-...", "total": 1200000.0, "count": 24 },
  "timestamp": 1790586932
}