Maya Payments

Base path: /api/v1/maya

POST /api/v1/maya/bookings/:id/checkout-session — Create Booking Checkout Session

Auth: Protected (Authorization: Bearer <accessToken>)
Used by: customer-booki-web-app · Role: customer
organizationId: From JWT token
Description: Create a Maya checkout session for a specific booking. Returns a redirect URL to Maya payment page.

Request

POST /api/v1/maya/bookings/507f1f77bcf86cd799439041/checkout-session

No request body required.

Response (201 Created)

{
  "checkoutId": "chk_live_abc123...",
  "url": "https://payments.maya.ph/checkout/..."
}

cURL Example

curl -X POST "http://localhost:4001/api/v1/maya/bookings/507f1f77bcf86cd799439041/checkout-session" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGc..."

POST /api/v1/maya/bookings/:id/verify-session — Verify Booking Payment Session

Auth: Protected (Authorization: Bearer <accessToken>)
Used by: customer-booki-web-app · Role: customer
organizationId: From JWT token
Description: Verify that a Maya checkout session was completed successfully for a booking.

Request

POST /api/v1/maya/bookings/507f1f77bcf86cd799439041/verify-session

Body:

{
  "checkoutId": "chk_live_abc123..."
}

Fields:

• checkoutId (string, required): The checkout ID returned from the checkout session

Response (200 OK)

{
  "message": "Payment verified successfully.",
  "booking_id": "507f1f77bcf86cd799439041"
}

cURL Example

curl -X POST "http://localhost:4001/api/v1/maya/bookings/507f1f77bcf86cd799439041/verify-session" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGc..." \
  -d '{"checkoutId": "chk_live_abc123..."}'

POST /api/v1/maya/webhook — Maya Webhook Receiver

Auth: Public (webhook signature required)
Used by: Maya payment gateway (server-to-server)
Description: Receives webhook events from Maya payment gateway (payment completed, failed, etc.).

Note: This endpoint is called by Maya's servers, not by the frontend. Verify the webhook signature in production.

Request

POST /api/v1/maya/webhook
Headers: X-Maya-Signature: <hmac_signature>

{
  "event": "payment.completed",
  "data": {
    "checkoutId": "chk_live_abc123...",
    "referenceNumber": "REF-2026-0001",
    "status": "PAYMENT_SUCCESS"
  }
}

cURL Example

curl -X POST https://api.booki.app/api/v1/maya/webhook \
  -H "Content-Type: application/json" \
  -H "X-Maya-Signature: <signature>" \
  -d '{"event":"payment.completed","data":{...}}'

POST /api/v1/maya/create-subscription-checkout — Create Subscription Checkout

Auth: Public (no authentication required)
Used by: cms-booki-web-app · Role: owner (during onboarding)
Description: Create a Maya checkout session for an organization subscription plan.

Request

{
  "email": "owner@example.com",
  "pricePerBranch": 999,
  "branchCount": 1,
  "trialDays": 90,
  "interval": "monthly"
}

Fields:

• email (string, required): Owner email address
• pricePerBranch (number, required): Price per branch (min 0)
• branchCount (number, required): Number of branches (min 1)
• trialDays (number, optional, default: 90): Trial period in days
• interval (string, optional, default: monthly): Billing interval
• metadata (object, optional): Additional metadata
• registrationData (any, optional): Data to carry through the registration flow

cURL Example

curl -X POST "http://localhost:4001/api/v1/maya/create-subscription-checkout" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@example.com",
    "pricePerBranch": 999,
    "branchCount": 1
  }'

POST /api/v1/maya/verify-session — Verify Subscription Session

Auth: Public (no authentication required)
Used by: cms-booki-web-app · Role: owner (during onboarding)
Description: Verify that a subscription checkout was completed successfully.

Request

{
  "checkoutId": "chk_live_abc123..."
}

Fields:

• checkoutId (string, required): The checkout ID returned from the subscription checkout

cURL Example

curl -X POST "http://localhost:4001/api/v1/maya/verify-session" \
  -H "Content-Type: application/json" \
  -d '{"checkoutId": "chk_live_abc123..."}'

Notes

• Webhook verification details are implementation-specific; check booki-api/src/controllers/maya-payment.controller.ts for verification logic.
• Subscription checkout/verification endpoints are used during the owner onboarding flow in cms-booki-web-app.
• All Maya API keys are encrypted at rest; never returned in API responses.