External Website Integration

Connect an existing hotel website without migrating everything at once.

MafrexAI can receive property data, process payments, mirror confirmed room bookings, and send callbacks back to the existing system. This guide explains the practical build path for partner developers.

View implementation path Property Sync API

Recommended use case

Use this when a hotel already has a public website or booking system but wants MafrexPay checkout, MafrexAI dashboard visibility, reception QR room sales, department payments, and safer reconciliation.

1. Connect

Open Hotel Dashboard -> External Website -> Setup, then create or rotate the paired Property Sync and MafrexPay credentials.

2. Import inventory

Push categories and rooms, or use the dashboard import wizard for JSON/CSV onboarding.

3. Sync bookings

Send existing active bookings so MafrexAI availability is accurate before reception QR bookings go live.

4. Add payments

Create MafrexPay payment orders from the external booking flow and verify status server-to-server.

5. Close the loop

Receive MafrexAI booking.confirmed callbacks so bookings created from reception QR or MafrexAI pages appear in the external system.

Credential model

The payment key and sync key are intentionally separate. The external website backend should store both as private environment variables.

MAFREXAI_PROPERTY_SYNC_KEY=mfx_sync_your_key
MAFREXPAY_API_KEY=mfx_pay_your_key

Do not expose these as NEXT_PUBLIC_ variables.
Do not send them from browser JavaScript.
Do not reuse the payment key for room or booking sync.

Server flow

All integration calls should originate from the external website server. MafrexAI should never receive trusted operational writes directly from guest browsers.

Guest browser
  -> External website server
    -> MafrexAI Property Sync API
    -> MafrexPay payment order API
      -> Paystack checkout
    <- MafrexPay status lookup
  <- External website confirmation page

Payment order

Create a payment order when the guest is ready to pay. For hotel room bookings, include stay dates and the MafrexAI room ID when available.

POST https://www.mafrexai.com/api/v1/mafrexpay/payment-orders
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",
    "check_in_date": "2026-08-15",
    "check_out_date": "2026-08-17",
    "guests": 2,
    "mafrexai_room_id": "optional-room-uuid"
  },
  "success_url": "https://customer-site.com/payment-success",
  "cancel_url": "https://customer-site.com/payment-failed"
}

Callback receiver

Configure a callback URL when the external system needs to know about bookings confirmed from MafrexAI pages or the reception QR room flow.

POST /your-server/mafrexai/booking-confirmed

Required checks:
1. Read the raw request body.
2. Verify X-MafrexAI-Signature using the callback secret.
3. Store X-MafrexAI-Delivery and ignore duplicate deliveries.
4. Upsert the booking using booking.booking_reference.
5. Return 2xx only after the booking is recorded.

Go-live checklist

Use this checklist before allowing real guests to pay from the external website or reception QR flow.

Generate a Property Sync key for rooms, bookings, check-ins, and availability.

Generate a MafrexPay key for external payment orders.

Store both keys only on the external website server.

Push room categories, rooms, and active bookings into MafrexAI.

Use MafrexPay payment orders for guest checkout.

Implement the MafrexAI booking callback receiver for confirmed bookings created inside MafrexAI.

Use the dashboard sync activity and callback delivery logs during testing.

Read the detailed API contracts.

Property Sync covers room and booking data. MafrexPay covers checkout, payment verification, and external payment-order status.

Property Sync MafrexPay API