Mono¶

Mono's payment driver focuses on DirectPay collections and Direct Debit mandates. It also exposes Mono-specific endpoints for customers, payout queries, split accounts, Disburse, and Owo. Some of those product endpoints are not represented by the package's shared optional contracts.

Setup¶

MONO_SECRET_KEY=your_payments_app_secret_key
MONO_PUBLIC_KEY=your_public_key
MONO_DISBURSE_SECRET_KEY=your_disburse_app_secret_key
MONO_OWO_SECRET_KEY=your_owo_app_secret_key
MONO_BASE_URL=https://api.withmono.com
MONO_CALLBACK_URL=https://example.com/payment/callback
MONO_WEBHOOK_SECRET=your_mono_webhook_secret

The primary API authenticates with Mono's mono-sec-key header. Separate Disburse and Owo secrets are optional, and each falls back to the main secret if not set; use separate app credentials where Mono requires them.

DirectPay checkout¶

use Alphabalex\PaymentMadeEasy\Facades\Payment;

$driver = Payment::driver('mono');
$checkout = $driver->initializePayment([
    'email'        => 'customer@example.com',
    'name'         => 'Jane Doe',
    'amount'       => 5000.00,
    'method'       => 'account', // account, transfer, or whatsapp
    'reference'    => 'ORDER_123',
    'callback_url' => 'https://example.com/payment/callback',
    'meta'         => ['order_id' => '123'],
]);

// Redirect to data.mono_url; verify the reference server-side.
$payment = $driver->verifyPayment('ORDER_123');

The driver converts major currency units to kobo for amount-bearing DirectPay requests. Use a unique reference and verify with Mono before fulfilling an order.

Direct Debit mandates¶

Mono implements the shared subscription, charge-authorization, and balance interfaces. Customer onboarding/mandate setup requires Mono-specific methods and additional KYC fields; the customer interface is not implemented. Create a Mono customer, initialize a hosted mandate, and then handle authorization/mandate callbacks before issuing debit instructions. Fixed mandates require a schedule; variable mandates use a total amount cap. Mono supports e-mandate and sweep flows, subject to account enablement.

The API reference documents the full Direct Debit lifecycle (createCustomer, initializeMandate, createSubscription, chargeAuthorization, mandate balance checks, pause/resume/cancel), along with fees and partial-sweep constraints.

Mono-specific products¶

Payout queries and split accounts: read payouts/transactions, list banks, create/list split subaccounts.
Mono Disburse: requires an enabled Disburse app and credential; the shared DisbursementDriverInterface is not implemented. Use its separate create/trigger/list operations only when your account is entitled.
Owo / WhatsApp: requires an Owo-enabled app and key; fund-request amounts follow Owo's API units (kobo), unlike the shared major-unit payment interface.

These methods are documented with request fields in Mono's API reference section.

Webhooks¶

Configure Mono's webhook secret and register POST /webhooks/payment-gateways/mono. Keep signature verification enabled and deduplicate deliveries by provider event ID. Subscribe to the Mono product events your application uses. See webhook configuration.