Developer API
Integrate your app to collect payments via Monietude
Base URL
https://monietude.com
Authentication
Use your Merchant API Key on every request:
Authorization: Bearer YOUR_MERCHANT_API_KEY
You can also use:
X-API-KEY: YOUR_MERCHANT_API_KEY
Create your Merchant API Key from your dashboard: Gateway → API Keys.
Integrated Checkout Experience
Our checkout process is designed to maximize conversion with a seamless multi-step interface. When your customer visits the checkout_url, they will experience:
  • Dynamic Selection: Choose between Card, Bank Transfer, or PalmPay.
  • 30-Minute Window: Bank transfers are held for 30 minutes with a live countdown timer for immediate confirmation.
  • Real-time Updates: The page automatically confirms payment the moment it's received—no refresh required.
Create Payment
POST https://monietude.com/api/gateway/payments/initiate
Body fields:
amount (number, min 100)
currency (string, default NGN)
method (card | transfer | ussd)
customer_email (email)
customer_phone (string, optional)
customer_name (string, optional)
return_url (url)
merchant_webhook_url (url, optional override)
reference (string, optional)
Amount sent in the request is in major units (e.g. NGN). Amount stored/returned is in minor units (kobo).
The payment method selects the checkout flow. Provider routing is handled internally via PalmPay.
If merchant_webhook_url is omitted, the saved default webhook URL from your dashboard is used.
Example (cURL)
curl -X POST "https://monietude.com/api/gateway/payments/initiate" \
  -H "Authorization: Bearer YOUR_MERCHANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000,
    "currency": "NGN",
    "method": "card",
    "customer_email": "customer@example.com",
    "customer_phone": "08000000000",
    "customer_name": "John Doe",
    "return_url": "https://yourapp.com/paid",
    "merchant_webhook_url": "https://yourapp.com/webhook/payment-gateway-ng"
  }'
Response contains provider.checkout_url. Redirect your customer to that URL to complete payment.
Response (example)
{
  "status": "success",
  "message": "Payment initialized",
  "data": {
    "reference": "gtw_xxxxxxxxxxxxxxxxxxxxxxxx",
    "amount": 200000,
    "currency": "NGN",
    "method": "card",
    "status": "unpaid",
    "provider": {
      "name": "palmpay",
      "reference": "gtw_xxxxxxxxxxxxxxxxxxxxxxxx",
      "transaction_id": null,
      "checkout_url": "https://monietude.com/checkout/gtw_xxxxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}
Verify Transaction
GET https://monietude.com/api/gateway/payments/verify/{reference}
Refresh Payment Status
POST https://monietude.com/api/gateway/payments/{reference}/refresh
Refreshes the live transaction status directly with PalmPay.
Create Virtual Account
Generate a dedicated virtual account for your customers to pay into. Each customer is identified by their phone number.
Note: The account name will be automatically prefixed with the company abbreviation (e.g., "M Monietude") to ensure brand recognition at the bank.
PalmPay Virtual Account: Generates a dedicated PalmPay Virtual Account.
POST https://monietude.com/api/gateway/virtual-accounts
Body fields:
name (string, required - customer name)
phone (string, required - customer phone)
email (string, optional - customer email)
provider (string, optional - palmpay)
Example (cURL - PalmPay)
curl -X POST "https://monietude.com/api/gateway/virtual-accounts" \
  -H "Authorization: Bearer YOUR_MERCHANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "phone": "08012345678",
    "email": "john@example.com",
    "provider": "palmpay"
  }'
Sample Response (200 OK)
{
  "status": "success",
  "message": "Virtual account created successfully",
  "data": {
    "account_number": "6649335104",
    "bank_name": "PalmPay",
    "bank_code": "100033",
    "account_name": "M John Doe",
    "provider": "palmpay",
    "phone": "08012345678"
  }
}
Get Virtual Account Details
GET https://monietude.com/api/gateway/virtual-accounts/show?phone=08012345678&provider=palmpay
Query parameters:
  • phone (string, optional) - Customer's phone number.
  • provider (string, optional) - Provider parameter (palmpay).
List All Virtual Accounts
GET https://monietude.com/api/gateway/virtual-accounts?provider=palmpay
Returns a paginated list of all virtual accounts created under your merchant account.
Webhooks
Save your default webhook URL from the Webhook Events page. You can still override it per payment request with merchant_webhook_url.
Webhook delivery is best-effort. You can view and repush webhook deliveries from the Webhook Events page.
Event types currently sent: payment.success and virtual_account.funding.success.
Payment Webhook Payload
{
  "event": "payment.success",
  "type": "payment",
  "reference": "gtw_xxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "success",
  "paid_at": "2026-05-01T12:34:56.000000Z",
  "amount": 200000,
  "currency": "NGN",
  "method": "card",
  "provider": "palmpay",
  "provider_reference": "gtw_xxxxxxxxxxxxxxxxxxxxxxxx",
  "provider_transaction_id": "1234567890"
}
Virtual Account Funding Payload
{
  "event": "virtual_account.funding.success",
  "type": "virtual_account_funding",
  "reference": "fund_xxxxxxxxxxxxx",
  "status": "success",
  "amount": 500000,
  "currency": "NGN",
  "funded_at": "2026-06-26T12:34:56.000000Z",
  "provider": "palmpay",
  "provider_reference": "fund_xxxxxxxxxxxxx",
  "virtual_account": {
    "account_number": "1234567890",
    "account_name": "ABC John Doe",
    "bank_name": "PalmPay",
    "bank_code": "100033",
    "customer_phone": "08012345678",
    "customer_email": "john@example.com",
    "merchant_ref": "08012345678",
    "account_reference": "08012345678"
  },
  "source": {
    "account_name": "John Doe",
    "account_number": null,
    "bank_name": null
  }
}
Webhooks are not currently signed. Recommended: treat webhooks as notifications and confirm final status by calling GET /api/gateway/payments/{reference}.
Common Errors
401 Missing API key / Invalid API key
422 Validation error (missing fields, invalid method, min amount)
400 Provider error (PalmPay not configured or request failed)
PalmPay sign error / Whitelist Error Usually means the PalmPay app ID, merchant private key, uploaded public key, target environment, or Whitelist IP Address do not match.