MyroPay API v3.8

Complete payments infrastructure for Africa and beyond - send money, collect payments, hold funds in escrow, run payroll, and build full checkout experiences through a unified REST API.

Authentication

There are two credentials in MyroPay. Only one of them is for building a third-party integration - the other is for a person managing their own account.

Copy# User session - logged-in individual only
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

Copy# Merchant App secret key - this is what a third-party integration sends
X-API-Key: sk_live_...

Each Merchant App key can optionally be restricted to a list of scopes at creation (or left unscoped for full access to everything below). Unscoped is the default so a first integration isn't blocked by a permission it forgot to request.

Errors & Rate Limiting

// All errors follow this shape
{ "success": false, "message": "Insufficient balance.", "retry_after": 42 }

Idempotency. Financial endpoints accept X-Idempotency-Key header. Send a UUID - repeat calls within 24h return the original response.

Rate limits. Login: 10/5 min · Register: 5/5 min · OTP resend: 3/5 min · General: 300/min.

Checkout SDK

One script tag. Four integration modes. No gateway keys ever touch your frontend.

Copy<script src="https://checkout.myropay.com/myropay.js"></script>

CopyMyroPay.checkout({
  publicKey:       'pk_live_...',
  amount:          5000,
  currency:        'NGN',
  orderRef:        'ORD-001',
  description:     'Premium plan',
  customer:        { email: 'buyer@email.com', name: 'John Doe' },
  escrow:          true,
  escrowCondition: 'Software delivered and tested',
  onSuccess:  (data) => console.log('Paid:', data),
  onClose:    ()     => console.log('Closed'),
  onError:    (msg)  => console.error(msg),
});

Copyconst session = await MyroPay.createSession({
  secretKey: 'sk_live_...',
  amount: 15000, currency: 'NGN',
  orderRef: 'ORD-002',
  successUrl: 'https://yoursite.com/thanks',
  cancelUrl:  'https://yoursite.com/cart',
});
res.redirect(session.checkout_url);

Copyconst { destroy } = await MyroPay.inline({
  container: '#checkout-box',
  publicKey: 'pk_live_...',
  amount: 2500, currency: 'NGN',
});

CopyMyroPay.createButton({
  container: '#pay-here',
  label: 'Pay with MyroPay',
  publicKey: 'pk_live_...',
  amount: 5000, currency: 'NGN',
});

Copyconst result = await MyroPay.verify(sessionId, 'sk_live_...');
if (result.status === 'completed' && result.amount === expectedAmount) {
  // fulfil order
}

Server SDKs

Official libraries for creating and verifying charges from your own backend - thin wrappers around the same hosted-checkout session API the JS Checkout SDK uses. Every method below maps 1:1 onto POST /api/sessions.php?action=create and GET /api/sessions.php?session_id=... on checkout.myropay.com.

Copy// npm install myropay-node

Copyconst myropay = require('myropay-node')('YOUR_SECRET_KEY');

const charge = await myropay.charges.create({
  email: "customer@email.com",
  amount: 500000,
  currency: "NGN", // optional - defaults to NGN; USD/GBP/EUR/GHS/KES/ZAR/CAD also accepted
});

res.redirect(charge.checkoutUrl);

Copy# pip install myropay

Copyimport myropay
myropay.api_key = 'YOUR_SECRET_KEY'

charge = myropay.Charge.create(
    email="customer@email.com",
    amount=500000
)

print(charge.checkout_url)

Copy// composer require myropay/myropay-php

Copyrequire_once('vendor/autoload.php');
\Myropay\Myropay::setApiKey('YOUR_SECRET_KEY');

$charge = \Myropay\Charge::create([
    'email' => 'customer@email.com',
    'amount' => 500000
]);

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

Copy# gem install myropay

Copyrequire 'myropay'
Myropay.api_key = 'YOUR_SECRET_KEY'

charge = Myropay::Charge.create(
    email: 'customer@email.com',
    amount: 500000
)

Copy<!-- Maven: pom.xml -->
<dependency>
  <groupId>com.myropay</groupId>
  <artifactId>myropay-java</artifactId>
  <version>1.0.0</version>
</dependency>

// Gradle
implementation 'com.myropay:myropay-java:1.0.0'

Copyimport com.myropay.Myropay;
import com.myropay.model.Charge;
import java.util.HashMap;
import java.util.Map;

Myropay.apiKey = "YOUR_SECRET_KEY";

Map<String, Object> params = new HashMap<>();
params.put("email", "customer@email.com");
params.put("amount", 500000);

Charge charge = Charge.create(params);

E-commerce Plugins

Drop-in payment gateway extensions for the platforms merchants already run on. Each one redirects to hosted checkout, then confirms the order two independent ways - a fast return-redirect for UX, and a webhook as the authoritative source of truth - so a closed browser tab can never strand an order as unpaid.

Mobile SDKs

Thin hosted-checkout wrappers for iOS and Android - no card data, secret keys, or payment logic lives on-device. Your own backend creates the session server-side (same X-API-Key call the server SDKs make); the mobile SDK just presents the resulting checkout_url in a native in-app browser and reports when it redirects back into your app.

CopyMyroPayCheckout.shared.present(
    checkoutURL: checkoutURL,
    callbackURLScheme: "myshop-checkout",
    presentationContext: self
) { result in /* verify session_id against your backend */ }

CopyMyroPayCheckout.redirectListener = MyroPayRedirectListener { uri ->
    // verify uri.myroPaySessionId() against your backend
}
MyroPayCheckout.present(context, checkoutUrl)

Subscriptions & Auto-billing

Recurring billing on top of Checkout Sessions. Create a plan (price + interval), subscribe a customer to it, and every billing cycle MyroPay generates an invoice and collects it according to the subscription's billing mode. All endpoints live on checkout.myropay.com/api/subscriptions.php (sandbox.myropay.com for test keys) and take a Merchant App secret key.

1. You create a plan once (price, currency, interval, optional trial). Plans are immutable on price so nobody is ever re-priced behind their back.
2. You subscribe a customer (subscribe). You get the subscription and, unless a trial applies, the first invoice with a checkout_url.
3. The customer sets it up once. invoice: pays the link each cycle. wallet_auto: pays the first invoice from their MyroPay wallet with their PIN - that single PIN entry authorises capped automatic payments. card_token: pays the first card checkout, which saves the card.
4. MyroPay bills every cycle automatically (a job runs hourly): a wallet is debited, a saved card is charged, or a new checkout link is issued. No PIN, no login, no action from you.
5. The customer stays in control. They see every subscription in the MyroPay app, get a receipt for each charge, are warned before a charge their balance can't cover, and can switch auto-pay off or cancel in one tap.
6. Failures are handled for you. A declined charge is retried on a fixed schedule and you are told about every attempt by webhook; only after the last attempt does the subscription cancel.
7. The money lands in your wallet and you take it out with Payouts.

CopyPOST /api/subscriptions.php?action=create-plan
{
  "name": "Pro Monthly",
  "amount": 15000,
  "currency": "NGN",
  "interval": "monthly",
  "trial_days": 7
}

CopyPOST /api/subscriptions.php?action=subscribe
{
  "plan_id": "plan_live_...",
  "customer": { "email": "customer@email.com", "name": "Ada Obi" },
  "billing_mode": "invoice",
  "success_url": "https://yourshop.com/thanks",
  "cancel_url": "https://yourshop.com/pricing"
}

reason values: insufficient_funds, exceeds_mandate, wallet_unavailable, fx_unavailable, card_unavailable, card_declined: ..., declined, expired_unpaid, error. Wallet owners are notified in-app on every failed attempt.

CopyPOST /api/subscriptions.php?action=subscribe
{
  "plan_id": "plan_live_...",
  "customer": { "email": "customer@email.com" },
  "billing_mode": "wallet_auto",
  "success_url": "https://yourshop.com/thanks"
}

1. The response has authorization_required: true and an invoice.checkout_url for a wallet-only checkout. Send the customer there.
2. They sign in to MyroPay and pay with their PIN. The account that pays becomes the debit source and you receive subscription.wallet_authorized and subscription_invoice.paid. You never choose whose wallet is debited - a wallet_user_id in the request is ignored.
3. Every later cycle is debited automatically with no PIN or login. The authorisation is a mandate capped at the plan price you were shown (mandate_amount): MyroPay refuses any invoice above it or in another currency, and a plan's price can never be edited, so a charge can never exceed what the customer agreed to. The customer sees the subscription in their MyroPay app under Subscriptions, gets a receipt for every charge, is reminded 7, 3 and 1 day(s) before it is due if their balance is still short, and can turn auto-pay off or cancel at any time.
4. Until authorisation completes, wallet_authorized on the subscription is false and nothing is debited. Trials work too: the authorisation checkout is issued at trial end.

CopyPOST /api/subscriptions.php?action=subscribe
{
  "plan_id": "plan_live_...",
  "customer": { "email": "customer@email.com", "name": "Ada Obi" },
  "billing_mode": "card_token",
  "consent": { "accepted": true },
  "success_url": "https://yourshop.com/thanks"
}

1. The response contains an invoice with a checkout_url. Send the customer there - it is card-only, because only a card can be saved.
2. When they pay you receive payment.success, subscription_card.attached (with card_brand and card_last4) and subscription_invoice.paid.
3. Every following cycle is charged server-side on the retry policy above. Cancelling immediately revokes the saved card; at_period_end: true stops the next charge.

Everything below is built into the MyroPay app (Subscriptions) - you don't build or host any of it.

Turning auto-pay off and cancelling need only a signed-in session, not the PIN, because they can only stop spending - starting or raising a payment always requires the PIN. A customer can never be charged more than the plan price they authorised, and you can never choose whose wallet is debited.

Each paid invoice credits your MyroPay wallet (converted to your wallet currency when the plan currency differs). Withdraw it with Payouts.

Subscriptions made with a sk_test_ key (sub_test_...) run the full lifecycle and fire every webhook but never move real money: silent charges succeed instantly without touching a wallet or card.

Auth Endpoints

Wallet & Transfers

Deposits

Payouts

A payout (withdrawal) moves money out of a MyroPay wallet to a bank account, a PayPal account or a mobile-money wallet. The wallet is debited immediately (amount + fee), the money is sent through the payment gateway, and the withdrawal then settles asynchronously: it either completes, or fails and the full amount is refunded automatically. Integrations use https://business.myropay.com/api/payout.php with a Merchant App secret key; the MyroPay apps call the same actions with a signed-in session.

1. Save the destination once with add-bank (up to 5 per account; numbers are encrypted at rest and only the last 4 digits are ever returned). Bank withdrawals can only go to a saved account - free-text account numbers are rejected.
2. Call initiate. MyroPay checks authorisation, KYC, the daily limit and the balance, then in one atomic step debits amount + fee, creates the withdrawal as pending and records the wallet transaction. Two parallel requests can never spend the same balance.
3. The payout is dispatched to the gateway for the chosen method (see Methods) and the withdrawal becomes processing.
4. It settles. The gateway confirms in the background and MyroPay marks the withdrawal completed and sends payout.completed - or marks it failed, returns amount + fee to the wallet and sends payout.failed. You never have to poll, but history always shows the current status.

CopyPOST https://business.myropay.com/api/payout.php?action=initiate
X-API-Key: sk_live_...
X-Idempotency-Key: wd-2026-10-28-0001

{ "method": "bank", "amount": 50000, "details": { "bank_id": 12 } }

// PayPal:        { "method": "paypal", "amount": 100, "details": { "paypal_email": "me@example.com" } }
// Mobile money:  { "method": "mobile_money", "amount": 20000, "details": { "phone": "+2348012345678", "network": "MTN" } }

// 200
{ "success": true, "message": "Withdrawal initiated. Processing within 24h.",
  "transaction_id": "6f1c0c52-...", "new_balance": 149500.0 }

transaction_id is the withdrawal's uuid in history. Re-sending the same X-Idempotency-Key (for example after a dropped connection) returns the original result instead of creating a second withdrawal - always send one.

wire accounts can be saved, but international wire withdrawals are not available yet - initiate with method: "wire" returns 400 before any money is reserved.

Delivered in the standard signed envelope ({ "event", "data", "timestamp" }, see Webhooks). Each fires once, when the withdrawal really settles - not when it is queued.

transaction_id is the withdrawal's uuid - the same id initiate returned as transaction_id and history lists as uuid - so match on it directly. Webhooks are delivered at least once: treat a repeated transaction_id + event as a duplicate.

Every paid subscription invoice - whether collected from a customer's wallet, a saved card or a checkout link - is credited to your MyroPay wallet (converted to your wallet currency if the plan currency differs) and appears as a transaction referencing the invoice id. Payouts are how you take that balance out; there is nothing subscription-specific to configure. Refunds of failed payouts and subscription credits are independent: a failed withdrawal only ever returns money to the wallet it left.

Transactions

Notifications

Escrow

Lock funds until delivery conditions are met. Either party can raise a dispute. MyroPay resolves within 48 hours. Fee: 1.5%.

KYC Verification

Invoices Business accounts

Payroll

Analytics

Checkout API

A session can be created in any of NGN/USD/GBP/EUR/GHS/KES/ZAR/CAD. You are always paid the full face value of what the session was created for - the conversion (when one happens) only affects what the buyer's card or wallet was actually charged, never what you receive or what GET /sessions.php reports.

Testing & Sandbox

A checkout session created with an sk_test_/pk_test_ key (a merchant app with mode: "test" - see API Keys) never touches a real balance. Wallet pay, card charge, and escrow fund/release/dispute/auto-release all behave exactly as they do in live mode - same statuses, same webhooks, same guest escrow portal - the only difference is that users.balance and users.locked_balance are never written to. Every test-mode session and escrow is stamped with is_test: true in its API response, and the checkout page / escrow portal both show a persistent test-mode banner so it's never ambiguous which one you're looking at.

Two ways this works, and it's automatic - nothing in your integration code changes between them:

The built-in simulator only works with pay-card (full card-detail entry - required for escrow anyway). pay-card-init's inline widget is Flutterwave's own hosted iframe, so it always requires real Flutterwave test keys, in test mode or live.

pay-wallet works in test mode too, with a real logged-in account and a real PIN - the debit/credit is just never actually applied to either party's balance. Useful for exercising the full checkout-to-webhook flow without needing test card numbers.

Fully functional, including the buyer-facing portal (sandbox.myropay.com/escrow.html): fund, view, release, dispute, and auto-release all work identically to live mode. A disputed test escrow behaves exactly like a real one - release is blocked until resolved - good for testing your own dispute-handling logic before it matters.

This is platform-level configuration (shared/config/config.php), set by whoever operates this MyroPay deployment - not something an individual merchant integration configures. From your Flutterwave dashboard: Settings → API → the "Test" tab (every Flutterwave account has both live and test key pairs). Set FLW_SECRET_KEY_TEST and FLW_ENCRYPTION_KEY_TEST (optionally FLW_PUBLIC_KEY_TEST) alongside the existing live-mode FLW_* variables. The simulator is a fallback for when these aren't set, not the recommended long-term setup for testing card payments seriously.

API Keys

A Merchant App is one pk_live_.../sk_live_... key pair. Create it once and it authenticates deposits, escrow, payouts, wallet, transactions, invoices, subscriptions, and checkout - this is the single integration surface for a third-party platform.

Webhook Management

Manage the webhook(s) attached to a specific app. See Webhook Events for the event catalogue and signature verification.

Settings

Webhook Events

Every webhook secret starts with whsec_ and belongs to exactly one app - you get it once, in the same response as that app's pk_/sk_ pair (see API Keys). Store it as MYROPAY_WEBHOOK_SECRET next to MYROPAY_SECRET_KEY - see Environment Variables below for the full naming reference.

Copy// PHP - always verify before processing
$rawBody = file_get_contents('php://input');
$sig     = $_SERVER['HTTP_X_MYROPAY_SIGNATURE'] ?? '';
// $_ENV['MYROPAY_WEBHOOK_SECRET'] - the whsec_... value returned when
// you created this app (or its webhook) under API Keys. Not the sk_/pk_
// key itself - a distinct secret, one per webhook endpoint.
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $_ENV['MYROPAY_WEBHOOK_SECRET']);
if (!hash_equals($expected, $sig)) {
    http_response_code(401); exit;
}
http_response_code(200); // ack fast, process async
$event = json_decode($rawBody, true);

Every delivery is an HTTP POST with a JSON body wrapped in the same three-key envelope - it is not a flat object. Parse event first, then read the event's fields from data.

Each request also carries Content-Type: application/json, User-Agent: MyroPay-Webhook/1.0 and X-MyroPay-Signature: sha256=<hex> (HMAC-SHA256 of the raw body, keyed with your whsec_ secret - compute it over the raw bytes, before any JSON parsing).

Copy{
  "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
}

Copy{
  "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": 1790586990
}

Same envelope. data is not the payment.success shape - it describes the invoice, and the fields below are the same on all three events. status is created, paid or failed. When an invoice is paid through a checkout (invoice mode, or the first card_token cycle) you also receive payment.success for that session, with subscription_id and subscription_invoice_id set; silent renewals (wallet_auto, later card_token cycles) send only the subscription_invoice event.

Copy{
  "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
}

Copy{
  "event": "subscription_invoice.payment_failed",
  "data": {
    "invoice_id": "inv_live_4d1e...",
    "subscription_id": "sub_live_7b3a...",
    "plan_id": "plan_live_2c9f...",
    "status": "failed",
    "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": null,
    "attempt": 1,
    "max_attempts": 4,
    "will_retry": true,
    "next_retry_at": "2026-10-29 10:00:09",
    "subscription_status": "past_due",
    "reason": "insufficient_funds"
  },
  "timestamp": 1793178009
}

Environment Variables

The exact variable names to use when wiring MyroPay into a codebase or briefing an AI coding agent. Copy this table verbatim - it's the single source of truth this whole site should agree with.

Changelog