The BotSubscription API

This REST API provides endpoints for managing projects, users, subscriptions, payments, and related resources. All endpoints require authentication unless explicitly specified otherwise.

Quick reference

Authentication

Include your authentication token in the Authorization header:

Authorization: Bearer YOUR_TOKEN

Language Selection

Specify the language for translated messages by sending an Accept-Language header:

Accept-Language: bg

If the header is omitted, English (en) is used.

Common Response Format

All API responses follow this format:

{
  "ok": true,
  "request_id": "uuid",
  "method": "HTTP_METHOD",
  "path": "/api/path",
  "code": 200,
  "message": "Success message",
  "data": {} // or [] for list responses
}

Error Responses

Error responses follow this format:

{
  "ok": false,
  "request_id": "uuid",
  "method": "HTTP_METHOD",
  "path": "/api/path",
  "code": 400,
  "error": {
    "error_code": "ERROR_CODE",
    "message": "Error description"
  }
}

Error Codes

Pagination

List endpoints support pagination using the following query parameters:

Live Updates (Socket.IO)

For real-time push events — payment request status changes, target lifecycle, and saved payment methods — connect a Socket.IO client to the live updates gateway at /v2/live-updates. Sessions are scoped per project and authenticated through a JWT handshake.

To get started, see the Live Updates Overview, or jump straight to Connecting to the Gateway for the handshake and quick-start examples.

Outbound Webhooks (Real-Time Events)

For server-to-server integrations, BotSubscription supports outbound webhooks. You can register HTTPS POST endpoints per project to receive real-time notifications for payment completion and other platform events.

To get started, see our comprehensive Webhooks Overview or explore active events like payment-request.completed.

Health Check

• GET /ping
• No authentication required
• Returns: { "ok": true }