Billing & FiscalAuth: API Key Only (Public checkout) or Bearer JWT (Folio settlement)

Payments & Tax Engine API

Initialize secure hosted checkout sessions (Stripe, Paystack), record manual bank transfer proofs, and fetch live tax & service fee calculations.

POSThttps://api.thegrandeur.vip/api/v1/payments/guest-initialize

Header Parameters

X-API-Keystringrequired

Your hotel live public API key.

Example: hak_live_8f3a1290...

Request Body Schema (JSON)

amountnumberrequired

Payment amount in property base currency.

Example: 280.00

emailstringrequired

Guest email for receipt delivery and gateway customer record.

Example: [email protected]

providerstring ('stripe' | 'paystack')optional

Target payment processor configured in hotel settings. Defaults to active provider.

Example: stripe

callback_urlstring (URL)required

Frontend redirect URL after user completes or cancels payment.

Example: https://your-site.com/booking/confirmation

booking_idUUIDoptional

Associated booking to automatically credit upon gateway webhook receipt.

Example: bk_9812a

Automatic Folio Reconciliation

When the guest completes payment on Stripe or Paystack, the provider dispatches an asynchronous webhook to the platform. The booking status flips to confirmed, payment is credited to the stay folio, and a confirmation receipt email is automatically dispatched.

# 1) Initialize Guest Checkout
curl -s -X POST "https://api.thegrandeur.vip/api/v1/payments/guest-initialize" \
  -H "X-API-Key: hak_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 280.00,
    "email": "[email protected]",
    "provider": "stripe",
    "callback_url": "https://your-site.com/booking/confirmation",
    "booking_id": "bk_9812a"
  }'

# 2) Fetch Public Hotel Tax Rates (VAT, City Tax, Tourism Levy)
curl -s "https://api.thegrandeur.vip/api/v1/settings/tax/public" \
  -H "X-API-Key: hak_live_YOUR_KEY"

Response Preview

{
  "success_status": true,
  "message": "Checkout session created",
  "data": {
    "payment_id": "pay_sess_883a",
    "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
    "client_secret": "pi_3Mtwx_secret_...",
    "amount": 280,
    "currency": "USD",
    "status": "pending"
  }
}

Hotel Services & Add-ons

Tenant Config & CMS