1
Create a MafrexPay workspace
Use the full hotel workspace or standalone merchant workspace. Configure departments, products, reservations, and settlement first.
MafrexPay Developer API
Add MafrexPay to an existing website or booking system.
MafrexPay can act as the payment orchestration layer for hospitality businesses that already have a public website, booking engine, POS process, or custom reservation system.
Integration status
Payment-order creation, dashboard API-key generation, Paystack checkout initialization, redirect verification, server-to-server status lookup, and MafrexPay transaction records are available for pilot integrations. Signed outbound webhook delivery is the next hardening step.
2
Generate an API key
Open MafrexPay in the dashboard, create an External integrations key, copy it once, and store it only on the external system server.
3
Create payment orders
The external website sends booking or order details to MafrexPay and receives a secure Paystack checkout URL.
4
Redirect and verify
The guest pays on Paystack. MafrexPay verifies the payment, records the transaction, redirects back, and exposes status through a server-to-server lookup.
When To Use This
Keep your website. Let MafrexPay handle the payment layer.
This is useful when a business already has its own website or booking software but wants MafrexPay for payment collection, reconciliation, department reporting, and settlement routing.
Existing hotel websites can keep their current booking flow.
Clubs, restaurants, resorts, and event venues can accept QR or website payments.
MafrexPay records payment orders, attempts, provider events, and transaction history.
Hotel and merchant settlement configuration still controls Paystack subaccount routing.
API keys are hashed at rest and can be revoked from the dashboard.
API keys
API keys are generated from the authenticated MafrexPay dashboard and are shown once. Store the key in the external server environment, never in browser JavaScript.
Dashboard locations
- Hotel workspace: `/hotel/mafrexpay` then External integrations.
- Standalone merchant: `/merchant/mafrexpay` then External integrations.
Authorization: Bearer mfx_pay_your_key
or
x-api-key: mfx_pay_your_keyAllowed origins
Server-to-server requests usually do not include an `Origin` header, so MafrexPay allows them when the API key is valid. If an `Origin` header is present, it must match the allowed origins. When allowed origins are configured, `success_url` and `cancel_url` must also use one of those origins.
Create a payment order
The external system sends the guest, amount, business context, and return URLs to MafrexPay. MafrexPay creates a payment order and returns a Paystack checkout URL.
Request
POST https://www.mafrexai.com/api/v1/mafrexpay/payment-orders
Content-Type: application/json
Authorization: Bearer mfx_pay_your_key
{
"reference": "EXT-BOOKING-1001",
"amount_minor": 16500000,
"currency": "NGN",
"customer": {
"name": "Guest Name",
"email": "guest@example.com",
"phone": "+2348012345678"
},
"context": {
"type": "room_booking",
"booking_id": "EXT-BOOKING-1001",
"department": "Rooms",
"check_in_date": "2026-08-10",
"check_out_date": "2026-08-12",
"guests": 2,
"mafrexai_room_id": "optional-hotel-room-uuid"
},
"success_url": "https://yourbusiness.com/payment-success",
"cancel_url": "https://yourbusiness.com/payment-failed"
}Response
{
"payment_order_id": "uuid",
"order_reference": "MPO-ABC123",
"external_reference": "EXT-BOOKING-1001",
"status": "processing",
"amount_minor": 16500000,
"amount": 165000,
"currency": "NGN",
"provider": "paystack",
"provider_reference": "MPO-ABC123",
"checkout_url": "https://checkout.paystack.com/...",
"reused": false
}Amount format
`amount_minor` uses the smallest currency unit. For NGN, `16500000` means NGN 165,000.00.
Idempotency
`reference` is treated as the external reference and must be unique per MafrexPay workspace. Retrying the same reference with the same amount and currency returns the existing order with `reused: true`. Retrying the same reference with a different amount or currency returns `409 Conflict`.
Hotel booking dashboard sync
For hotel API clients, paid `room_booking` orders are mirrored into the MafrexAI hotel bookings dashboard when `check_in_date` and `check_out_date` are included in `context`. Add `mafrexai_room_id` when the external site should lock a specific MafrexAI room. Without a room id, MafrexAI still records the paid booking for manual room assignment.
Verification, redirect, and status lookup
After the guest pays, Paystack returns to MafrexPay. MafrexPay verifies the provider reference, updates records, and redirects the guest back to the external site. The external site must still confirm payment from its server by calling the status endpoint.
GET /api/v1/mafrexpay/payment-orders/verify?reference=MPO-ABC123
On success:
https://yourbusiness.com/payment-success?payment=success&payment_order=MPO-ABC123&reference=MPO-ABC123
On failure:
https://yourbusiness.com/payment-failed?payment=failed&payment_order=MPO-ABC123&reference=MPO-ABC123
Never mark an order paid from these redirect query parameters.
GET https://www.mafrexai.com/api/v1/mafrexpay/payment-orders/MPO-ABC123
Authorization: Bearer mfx_pay_your_key
{
"payment_order_id": "uuid",
"order_reference": "MPO-ABC123",
"external_reference": "EXT-BOOKING-1001",
"status": "paid",
"amount_minor": 16500000,
"currency": "NGN",
"provider": "paystack",
"provider_reference": "MPO-ABC123",
"paid_at": "2026-07-23T17:30:00Z",
"mafrexai_booking_sync": {
"status": "synced",
"booking_id": "uuid",
"booking_reference": "EXT-BOOKING-1001",
"confirmation_code": "A1B2C3D4"
}
}Error contract
MafrexPay API errors use stable machine-readable codes. Store and log the `request_id` when asking MafrexAI support to inspect an integration issue.
{
"error": {
"code": "EXTERNAL_REFERENCE_CONFLICT",
"message": "This external reference already belongs to a different payment order.",
"request_id": "req_..."
}
}
Common codes:
MISSING_API_KEY
INVALID_API_KEY
CUSTOMER_EMAIL_REQUIRED
INVALID_AMOUNT
UNSUPPORTED_CURRENCY
ORIGIN_NOT_ALLOWED
RETURN_URL_NOT_ALLOWED
EXTERNAL_REFERENCE_CONFLICT
PAYMENT_ORDER_NOT_FOUND
INTERNAL_ERRORWebhooks
MafrexPay stores webhook delivery queue records when a payment order is verified and the API client has a webhook URL. Signed outbound delivery with retries is the next hardening phase.
Future event payload shape:
{
"event": "payment_order.paid",
"payment_order": {
"order_reference": "MPO-ABC123",
"external_reference": "EXT-BOOKING-1001",
"status": "paid",
"amount_minor": 16500000,
"currency": "NGN"
}
}Security rules
Keep MafrexPay API keys on the server only.
Use a unique external reference for each booking or order.
Do not mark an external order as paid from redirect query parameters.
Confirm payment by calling the payment-order status endpoint or by verifying a signed MafrexPay webhook.
Restrict allowed origins for browser-facing integrations and permitted return URLs.
Configure success_url and cancel_url only on permitted return domains.
Revoke old keys immediately if a system is replaced or compromised.
Ready to connect an external site?
Create a MafrexPay workspace, generate a server-side API key, and create your first low-value test payment order before going live.