Organizations - Payments & Integrations

Base path: /api/v1/organizations/payments and /api/v1/integrations

Used by: owner-booki-web-app · Role: owner, branch-manager
organizationId: From authenticated user's JWT token (no tenant header needed)

Organizations can integrate payment gateways (Maya, Cash) for booking payments and subscriptions.

POST /api/v1/organizations/payments/maya/connect — Connect Maya Payment

Auth: Protected (Authorization: Bearer <accessToken>)
Used by: owner-booki-web-app · Role: owner
Description: Connect Maya payment gateway for the organization. No request body required — organizationId is resolved from the JWT token.

Aliases (same behavior):

• POST /api/v1/organizations/payments/maya
• POST /api/v1/integrations/maya/connect

Response (200 OK)

{
  "status": "ok"
}

Error Responses

409 Conflict — Already connected:

{
  "statusCode": 409,
  "message": "Maya payment gateway is already connected for this organization."
}

cURL Example

curl -X POST http://localhost:4001/api/v1/organizations/payments/maya/connect \
  -H "Authorization: Bearer eyJhbGc..."

POST /api/v1/organizations/payments/maya/disconnect — Disconnect Maya Payment

Auth: Protected (Authorization: Bearer <accessToken>)
Used by: owner-booki-web-app · Role: owner
Description: Disconnect Maya payment gateway from the organization.

Aliases (same behavior):

• POST /api/v1/organizations/payments/maya/disconnect (via /:type/disconnect)
• POST /api/v1/integrations/maya/disconnect

Response (200 OK)

{
  "status": "ok"
}

cURL Example

curl -X POST http://localhost:4001/api/v1/organizations/payments/maya/disconnect \
  -H "Authorization: Bearer eyJhbGc..."

GET /api/v1/organizations/payments — List Organization Payments

Auth: Protected (Authorization: Bearer <accessToken>)
Used by: owner-booki-web-app · Role: owner, branch-manager
Description: Get the connected payment method status for the authenticated user's organization.

Response (200 OK)

{
  "mayaConnected": true,
  "cashConnected": false
}

cURL Example

curl -X GET http://localhost:4001/api/v1/organizations/payments \
  -H "Authorization: Bearer eyJhbGc..."

GET /api/v1/organizations/payments/available-methods — Get Available Payment Methods

Auth: Public
Used by: cms-booki-web-app, customer-booki-web-app · Role: guest / customer
organizationId: Resolved via tenant middleware (X-Tenant header or subdomain)
Description: Get payment methods available for a specific organization (for checkout display).

Response (200 OK)

{
  "availablePaymentMethods": ["maya", "cash"],
  "mayaEnabled": true,
  "cashEnabled": true
}

cURL Example

curl -X GET "http://localhost:4001/api/v1/organizations/payments/available-methods" \
  -H "X-Tenant: <organization-slug>"

POST /api/v1/organizations/payments/:type — Connect Cash Payment

Auth: Protected (Authorization: Bearer <accessToken>)
Used by: owner-booki-web-app · Role: owner
Description: Connect the cash payment method. For maya, use the dedicated /maya/connect endpoint above.

Response (200 OK)

{
  "mayaConnected": false,
  "cashConnected": true
}

cURL Example

curl -X POST "http://localhost:4001/api/v1/organizations/payments/cash" \
  -H "Authorization: Bearer eyJhbGc..."

POST /api/v1/organizations/payments/:type/disconnect — Disconnect Cash Payment

Auth: Protected (Authorization: Bearer <accessToken>)
Used by: owner-booki-web-app · Role: owner
Description: Disconnect the cash payment method. For maya, use the dedicated /maya/disconnect endpoint above.

Response (200 OK)

{
  "mayaConnected": false,
  "cashConnected": false
}

cURL Example

curl -X POST "http://localhost:4001/api/v1/organizations/payments/cash/disconnect" \
  -H "Authorization: Bearer eyJhbGc..."

PUT /api/v1/organizations/payments — Update Payment Settings

Auth: Protected (Authorization: Bearer <accessToken>)
Used by: owner-booki-web-app · Role: owner
Description: Update organization payment configuration. organizationId is resolved from the JWT token — do not include it in the request body.

Request

{
  "mayaConnected": true,
  "cashConnected": false
}

All fields optional; at least one required:

• mayaConnected (boolean): Enable or disable Maya payment
• cashConnected (boolean): Enable or disable cash payment

Response (200 OK)

{
  "mayaConnected": true,
  "cashConnected": false
}

cURL Example

curl -X PUT http://localhost:4001/api/v1/organizations/payments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGc..." \
  -d '{
    "mayaConnected": true
  }'

Supported Payment Methods

Notes

• Credentials are encrypted before storage; never returned in API responses.
• Available methods are determined by organization's connected integrations.
• "cash" is always available as a fallback payment option.