MyRoPay API

Create an account. Returns access + refresh token immediately — no separate login step needed.

Copy{
  "first_name":   "Dami",
  "last_name":    "Ehimare",
  "email":        "dami@example.com",
  "phone":        "+2348100000001",
  "password":     "StrongPass1!",
  "account_type": "personal",  // "personal" | "business"
  "country_code": "NG",        // ISO 3166-1 alpha-2
  "referral_code":"DAMI1234"  // optional
}

{
  "success": true,
  "token":         "eyJhbGci...",     // 15-min access token
  "refresh_token": "a3f2b9...",      // 30-day refresh token
  "user": {
    "id": 42, "uuid": "4c758d...",
    "first_name": "Dami", "last_name": "Ehimare",
    "myrotag": "damiehimare",
    "email": "dami@example.com",
    "currency": "NGN", "currency_symbol": "₦",
    "country_code": "NG", "country": "Nigeria",
    "kyc_status": "pending", "kyc_level": 0,
    "pin_set": false, "email_verified": false,
    "account_type": "personal",
    "referral_code": "DAMI7A2C"
  }
}

Authenticate with email + password. Include totp_code if 2FA is enabled on the account.

Copy{ "email": "dami@example.com", "password": "StrongPass1!", "totp_code": "123456" }

Exchange a refresh token for a new access + refresh pair. Tokens rotate on every use — store the new refresh token immediately.

Copy{ "refresh_token": "b7d3e1..." }

Returns the authenticated user's full profile: balance, KYC status, pin_set, referral code, and unread notification count.

Change your @myrotag. Maximum 3 changes per year. Body: { "myrotag": "newhandle" }

Verify email address using the 6-digit OTP sent at registration. Body: { "otp": "123456" }

Trigger a password reset email. Always returns 200 to prevent user enumeration. Body: { "email": "..." }

Complete the reset. Body: { "token": "...", "password": "NewPass1!" }

Generate a TOTP secret and QR code URI. Returns secret and qr_url. The user scans it in an authenticator app then confirms via confirm-2fa.

Activate 2FA by verifying the first TOTP code. Returns 10 single-use recovery codes — store immediately. Body: { "code": "123456" }

Disable 2FA by confirming with a current TOTP code. Body: { "code": "123456" }

Primary wallet balance plus locked funds (in active escrows) and monthly flow totals.

{
  "success":     true,
  "balance":     "42910.24",
  "locked":      "1200.00",   // held in active escrows
  "currency":    "NGN",  "symbol": "₦",
  "monthly_in":  "55000.00",
  "monthly_out": "12090.00"
}

Send money to any user. The recipient field accepts @myrotag, email, or phone. Requires PIN or active biometric session. KYC Level 0 limit: $200 per transfer.

Copy{
  "recipient": "@alexvance",  // @tag | email | phone
  "amount":    1500,
  "pin":       "1234",        // or "biometric_session": "..."
  "note":      "Thanks for dinner"
}

{
  "success":        true,
  "message":        "Transfer of ₦1,500 to @alexvance successful!",
  "transaction_id": "4c758d30-60a6-...",
  "new_balance":    "41395.86",
  "receipt": {
    "amount": "1500.00", "fee": "0.10",
    "from": { "name": "Dami E.", "tag": "@damiehimare" },
    "to":   { "name": "Alex V.", "tag": "@alexvance" },
    "status": "completed", "timestamp": "2025-04-23T14:20:00Z"
  }
}

Find a user by @myrotag, email, or phone. Returns id, first_name, last_name, myrotag, avatar, currency.

Request payment from another user. They receive an in-app notification with a one-tap pay button. Body: { "target_email": "...", "amount": 500, "note": "..." }

Pay a received payment request. Body: { "request_id": 14, "pin": "1234" }

Paginated transaction history with full-text search and type filters.

Smart gateway init. Returns different payloads depending on the selected gateway. Optionally pass method to force a specific gateway.

Copy{
  "amount":   5000,
  "currency": "NGN",
  "method":   "auto"  // "auto"|"paystack"|"flutterwave"|"checkout"
}

// Nigeria → Paystack  (access_code only, no public key exposed)
{ "gateway":"paystack", "access_code":"0peioxfhpn", "reference":"MRP_PS_3F2A1B8C" }

// Africa → Flutterwave  (hosted payment link, no key)
{ "gateway":"flutterwave", "payment_link":"https://checkout.flutterwave.com/...", "tx_ref":"MRP_FLW_7C4E2A" }

// Global → MyRoPay Checkout session
{ "gateway":"checkout", "checkout_url":"https://app.myropay.com/pay?session=cs_live_...", "session_id":"cs_live_4f2b..." }

Call after PaystackPop onSuccess fires. Body: { "reference": "MRP_PS_..." }. Returns new_balance.

Call after Flutterwave redirect. Body: { "tx_ref": "...", "transaction_id": "..." }.

Server-to-server event from Paystack. Validated using X-Paystack-Signature HMAC-SHA512. Register at: myropay.com/app/api/deposit.php?action=paystack-webhook

Server-to-server event from Flutterwave. Validated using VERIF-HASH header. Register at: myropay.com/app/api/deposit.php?action=flutterwave-webhook

Supported banks for a given country code. NG uses Paystack's list; other countries use Flutterwave.

Verify an account number before adding it. Params: account_number, bank_code. Returns the account holder name (Nigeria only, powered by Paystack).

Save a bank account for future withdrawals. Account numbers are AES-256-CBC encrypted at rest. Body: { "bank_name", "bank_code", "account_number", "account_name" }

Start a withdrawal. KYC must be verified. Fee: max($1.00, 1%). Funds are debited from the wallet immediately.

Copy{
  "method":  "bank",   // "bank" | "paypal" | "mobile_money"
  "amount":  10000,
  "pin":     "1234",
  "details": { "bank_id": 3 }  // from /payout.php?action=my-banks
}

{
  "success":        true,
  "message":        "Withdrawal initiated. Processing within 24h.",
  "transaction_id": "7f3b9d...",
  "new_balance":    "32810.00"
}

Paginated list. Query params: page, limit, type, q (search), from, to.

Single transaction with full sender and receiver names, @tags, avatars, and fee breakdown.

Export up to 5,000 transactions as JSON. Date range params: from, to. Returns a file attachment.

Create and fund an escrow in one step. Amount + 1.5% fee debited immediately and locked.

Copy{
  "beneficiary": "@alexvance",  // @tag or email
  "amount":      50000,
  "title":       "Website redesign",
  "description": "5 pages, 2 revisions, delivered in 2 weeks",
  "due_date":    "2025-05-15",
  "pin":         "1234"
}

Release locked funds to the beneficiary. Only the initiator can call this. Body: { "uuid": "...", "pin": "1234" }

Raise a dispute. Either party can call this. Funds are frozen until resolved by MyRoPay admin. Body: { "uuid": "...", "reason": "...", "evidence": "https://..." }

Submit your response to an open dispute. Body: { "dispute_uuid": "...", "response": "...", "evidence": "..." }

All escrows where you are initiator or beneficiary. Returns status, counterparty details, amounts, and any open dispute IDs.

Copy{
  "title":        "Design Bundle v2",
  "description":  "Includes logo, brand guide, and social kit",
  "amount":       29999,       // 0 = open amount (payer sets it)
  "is_fixed":     true,
  "usage_limit":  50,          // 0 = unlimited
  "expires_days": 30           // 0 = never expires
}

Returns link (full URL), uuid, and times_used.

All your payment links with times_used, active flag, expiry date, and full payer URLs.

Enable or disable a link. Body: { "id": 7 }. Returns the new active boolean.

Permanently delete a payment link. Body: { "id": 7 }

Returns supported categories: AIRTIME, DATA_BUNDLE, POWERBI (electricity), DSTV, GOTV, STARTIMES, WATERBI, NETPLUSINC. Each category includes its valid billers.

Validate a customer number before payment (e.g. electricity meter, SmartCard number). Body: { "item_code": "...", "biller_code": "...", "customer": "12345678" }

Copy{
  "type":     "AIRTIME",
  "customer": "08012345678",
  "amount":   1000,
  "pin":      "1234"
}

Copy{
  "name":               "New MacBook",
  "target_amount":       450000,
  "target_date":         "2025-12-01",
  "auto_save":           true,
  "auto_save_amount":    15000,
  "auto_save_frequency": "monthly"  // "daily"|"weekly"|"monthly"
}

Manually top up a goal from your wallet. Body: { "id": 3, "amount": 5000, "pin": "1234" }. Returns new_amount and progress percentage.

Withdraw funds from a goal back to your wallet. Body: { "id": 3, "amount": 5000, "pin": "1234" }

Create a new virtual card. Returns masked details only. Full number available via reveal. Body: { "pin": "1234" }

Decrypt and return full card number, CVV, and expiry. Requires PIN. Body: { "id": 1, "pin": "1234" }

Toggle card freeze/unfreeze. Body: { "id": 1 }. Returns new status.

Returns current tier, document submission status per tier, and per-tier daily limits.

Submit a KYC document. Multipart form-data (not JSON). Max 5 MB per file. Accepted: JPEG, PNG, PDF.

CopyPOST /kyc.php?action=upload
Content-Type: multipart/form-data

doc_type: "govt_id"   # govt_id|selfie|proof_of_address|passport|drivers_license
tier:     1
document: <binary>

Nigerian BVN verification. BVN is hashed (SHA-256) immediately on receipt — never stored in plain text. Body: { "bvn": "12345678901" }

Copy{
  "client_name":  "Acme Corp",
  "client_email": "billing@acme.com",
  "currency":     "NGN",
  "due_date":     "2025-05-30",
  "tax_rate":     7.5,
  "items": [
    { "description": "Logo design", "quantity": 1, "unit_price": 80000 },
    { "description": "Brand guide",  "quantity": 1, "unit_price": 45000 }
  ]
}

Returns uuid, invoice_number (e.g. INV-A3F2B901), subtotal, tax total, and grand total.

Email the invoice PDF to the client. Changes status from draft → sent. Body: { "uuid": "..." }

All invoices with status. Query param status: draft · sent · paid · overdue.

Copy{
  "name": "April 2025 Payroll",
  "recipients": [
    { "myrotag": "@alice", "amount": 250000, "note": "April salary" },
    { "myrotag": "@bob",   "amount": 180000, "note": "April salary" }
  ]
}

Wallet must cover the total. Returns batch_id, total_amount, and per-recipient status.

Payroll batches with totals, recipient count, and completion status.

Copy{
  "name":   "Production endpoint",
  "url":    "https://yoursite.com/hooks/myropay",
  "events": ["payment.success", "escrow.released", "payout.completed"]
}

Returns a secret for HMAC verification — shown once, store it immediately.

Send a test ping to your endpoint. Body: { "id": 5 }. Returns the HTTP status code your server responded with.

KPI summary for last N days (7 · 30 · 90). Returns revenue, spending, net, transaction counts, payment link stats, invoice totals, and payroll disbursements.

Daily inflow/outflow series. Returns array of { "date": "2025-04-01", "inflow": 55000, "outflow": 12000 }

Top 10 users by total amount sent to your account in the last 90 days.

Breakdown of transaction volume by type (deposit, transfer, escrow, bill, withdrawal) for charting.

Verify a session after payment. Always verify server-side before fulfilling an order. Check status === "completed" and confirm amount matches your expected value.

Create a merchant app and get pk_live_ / sk_live_ keys. Limited to 5 apps per account.

Copy{
  "app_name":      "My Store",
  "app_url":       "https://mystore.com",
  "support_email": "support@mystore.com",
  "mode":          "live"   // "live"|"test"
}

Returns public_key and user_ref. Pass these to the Mono Connect widget on your frontend.

Exchange the Mono auth code returned by the Connect widget. Stores the linked account and returns account details. Body: { "code": "mono_auth_code_..." }

Bank statement for a linked account. Returns last 90 days of transactions.

Remove a linked bank account. Body: { "account_id": "..." }

Paginated notifications with unread count. Query param: page.

Returns { "count": 4 } — fast endpoint for polling badge counts.

Mark all notifications as read. No body required.

Update display name and phone. Body: { "first_name", "last_name", "phone" }

Body: { "current_password", "new_password" }. Triggers a security alert email and invalidates all other sessions.

Set or change the 4-digit transaction PIN. Body: { "pin": "1234", "confirm_pin": "1234" }

Toggle a preference flag. Body: { "key": "push_notifications", "value": 1 }. Valid keys: push_notifications · email_notifications · login_alerts · weekly_digest_enabled · roundup_enabled.

List all active login sessions with device, browser, IP, and last active time.

Log out all other sessions except the current one. No body required. Good for "logout everywhere" on suspicious activity.

Check if a key exists. Returns has_key, key_masked (e.g. mrp_4a7b****c6b7), and key_prefix. Full key is never re-exposed.

Generate or regenerate a key. Requires PIN. The full key is returned once only — copy it immediately.

{ "success": true, "api_key": "mrp_4a7b2c9e1f3d0e8a5c6b..." }

Immediately invalidate the current key. All requests using it will return 401. Body: { "pin": "1234" }

Copy{
  "subject":   "Deposit not reflecting",
  "message":   "I paid ₦5000 via Paystack at 2:14pm but...",
  "category":  "payment",  // payment|account|kyc|technical|other
  "priority":  "high"       // low|normal|high|urgent
}

All your tickets with status (open, in_progress, resolved, closed) and unread reply count.

Add a reply to an open ticket. Body: { "ticket_id": 12, "message": "..." }