Pay Now

This flow applies when a guest selects Paystack as their payment method during booking. The guest pays in full online before the reservation is confirmed.

payMethodId: 4

Diagram Overview

Overview

1. Load Reference Data   →  Countries, States, Room Types, Payment Methods
2. Check Availability    →  Confirm rooms are available for chosen dates
3. Initialize Payment    →  Get Paystack authorization URL
4. Guest Pays            →  Redirect guest to Paystack checkout
5. Verify Payment        →  Confirm transaction succeeded on callback
6. Create Reservation    →  Submit booking with payment reference
7. Confirm Booking       →  Retrieve and display booking details

Step 1 — Load Reference Data

Fetch the data needed to populate your booking form dropdowns. These can be loaded in parallel.

1a. Get Countries

Returns a list of countries. Use id as countryId in the reservation payload.

1b. Get States (after country is selected)

Returns states for the selected country. Use id as stateId in the reservation payload.

1c. Get Room Types

Returns all configured room types with names, rates, and images — useful for building a room catalogue page.

1d. Get Active Payment Methods

Response:

{
    "items": [
        { "id": 1, "name": "Book On Hold" },
        { "id": 4, "name": "Paystack" }
    ]
}

💾 Store the payment method id values — you'll need payMethodId in Step 6.

1e. Get Hotel Rules (optional but recommended)

Returns check-in/out times, min/max stay length, and advance booking windows. Display these constraints in your UI to prevent invalid bookings.

Step 2 — Check Availability

Once the guest has selected dates and guest count, confirm rooms are available and retrieve current rates.

Request:

Response:

{
    "errorCode": 0,
    "errorMessage": "Successfully retrieved available rooms.",
    "types": [
        {
            "roomTypeId": 4,
            "roomType": "Economy",
            "rate": 35000,
            "available": 2,
            "currencySymbol": "₦"
        }
    ]
}

💾 Store roomTypeId and rate for each room the guest selects — both are required in Step 6.

⚠️ Only display rooms where available > 0.

Step 3 — Initialize the Payment

Initialize a Paystack transaction to generate a checkout URL for the guest.

💡 Amount must be in kobo (NGN × 100). For example, ₦35,000 = 3500000 kobo.

Request:

Response:

{
    "status": true,
    "message": "Authorization URL created",
    "data": {
        "authorization_Url": "https://checkout.paystack.com/kfx4ota680ptmpd",
        "access_Code": "kfx4ota680ptmpd",
        "reference": "sti58qbn3w"
    },
    "errorCode": 0,
    "errorMessage": "Access code retrieved successfully."
}

💾 Store data.reference — you will need it in Steps 5 and 6.

Step 4 — Redirect Guest to Paystack Checkout

Redirect the guest to data.authorization_Url. Paystack handles the full payment UI including card entry, bank authentication, and receipt.

Redirect → https://checkout.paystack.com/kfx4ota680ptmpd

After payment is completed or abandoned, Paystack redirects the guest back to your configured callback URL.

⚙️ Set your callback URL in your Paystack Dashboard under:
Settings → API Keys & Webhooks → Callback URL

⚠️ Do not create the reservation yet. Always verify payment first in Step 5.

Step 5 — Verify the Payment

On the callback, use the reference from Step 3 to verify the transaction status.

Request:

Response — Success:

{
    "status": true,
    "message": "Verification successful",
    "data": {
        "status": "success",
        "reference": "sti58qbn3w",
        "amount": 3500000,
        "channel": "card",
        "currency": "NGN"
    },
    "errorCode": 0,
    "errorMessage": "Transaction verified successfully."
}

Response — Abandoned / Failed:

{
    "status": true,
    "message": "Verification successful",
    "data": {
        "status": "abandoned",
        "reference": "sti58qbn3w",
        "amount": 3500000
    },
    "errorCode": -314,
    "errorMessage": "Transaction abandoned!"
}

`data.status`	`errorCode`	Action
`"success"`	`0`	✅ Proceed to Step 6
`"abandoned"`	`-314`	❌ Prompt guest to retry payment
`"failed"`	non-zero	❌ Prompt guest to retry or choose a different method

🚫 Do not proceed to Step 6 if errorCode is not 0.

Step 6 — Create the Reservation

Once payment is verified, submit the full reservation payload with the Paystack reference included.

Request:

📌 payment.amount is in naira, not kobo. e.g. 35000.00 not 3500000.

Response — Success:

{
    "bookingRef": "F8AUA6",
    "errorCode": 0,
    "errorMessage": "Reservations made successfully"
}

💾 Store the bookingRef — the guest will need it to retrieve or cancel the reservation.

Step 7 — Confirm the Booking

Retrieve and display the full booking summary to the guest.

Request:

Response:

{
    "guest": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com"
    },
    "reservations": [
        {
            "roomType": "Economy",
            "bookingRef": "F8AUA6",
            "checkInDate": "2025-09-15",
            "checkOutDate": "2025-09-16",
            "quantity": 1,
            "rate": 35000
        }
    ],
    "errorCode": 0,
    "errorMessage": "Reservation details retrieved successfully."
}

Display the booking reference prominently. The guest will need it to look up or cancel their reservation.

Payment Object Reference

Field	Value	Description
`payTypeId`	`1`	Pre-paid
`payMethodId`	`4`	Paystack
`reference`	from Step 3	Paystack transaction reference
`transaction`	from Step 3	Same as reference
`amount`	in naira	Total amount charged

Diagram Overview#

Overview#

Step 1 — Load Reference Data#

1a. Get Countries#

1b. Get States (after country is selected)#

1c. Get Room Types#

1d. Get Active Payment Methods#

1e. Get Hotel Rules (optional but recommended)#

Step 2 — Check Availability#

Step 3 — Initialize the Payment#

Step 4 — Redirect Guest to Paystack Checkout#

Step 5 — Verify the Payment#

Step 6 — Create the Reservation#

Step 7 — Confirm the Booking#

Payment Object Reference#

Diagram Overview

Overview

Step 1 — Load Reference Data

1a. Get Countries

1b. Get States (after country is selected)

1c. Get Room Types

1d. Get Active Payment Methods

1e. Get Hotel Rules (optional but recommended)

Step 2 — Check Availability

Step 3 — Initialize the Payment

Step 4 — Redirect Guest to Paystack Checkout

Step 5 — Verify the Payment

Step 6 — Create the Reservation

Step 7 — Confirm the Booking

Payment Object Reference