> For the complete documentation index, see [llms.txt](https://docs.skypaybd.top/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skypaybd.top/readme.md).

# Overview

Welcome to the official developer documentation suite for **SkyPay**, a high-performance payment gateway and hardware telemetry infrastructure designed for digital commerce, software-as-a-service (SaaS) platforms, bots, and mobile applications across Bangladesh and global cryptocurrency rails.

{% hint style="info" %}
**Production API Base URLs**:

* **Hosted & Core Gateway (v1)**: `https://core.skypaybd.top/api`
* **Headless, Telemetry & SMS API (v2)**: `https://core.skypaybd.top/api/v2`

All requests must be transmitted securely over HTTPS with TLS 1.3 encryption.
{% endhint %}

***

## 1. Platform Overview & Architecture

SkyPay bridges the gap between conventional Mobile Financial Services (MFS), centralized digital payment systems, and decentralized web3 blockchain infrastructure. By utilizing an automated, event-driven Android hardware relay and direct RPC nodes, SkyPay eliminates third-party aggregator processing cuts and provides real-time transaction reconciliation.

### Supported Channels & Payment Rails

* **Mobile Financial Services (MFS)**: bKash (Personal, Agent, Merchant Payment), Nagad (Personal, Agent), Rocket (Personal), Upay.
* **National Interoperable QR**: Bangla QR (TallyPay, Mutual Trust Bank, City Bank, and inter-bank push data).
* **Decentralized Cryptocurrency**: BEP20 (USDT on BNB Smart Chain) with automatic RPC smart contract token transfer confirmation.
* **Exchange Micro-Payments**: Binance Pay (USDT) server-to-server merchant verification.
* **SMS Gateway Integration**: Real-time programmatic outbound SMS dispatching via dedicated Android relay hardware.

### Architectural Models: Hosted (v1) vs. Headless (v2)

SkyPay provides two distinct integration architectures to support diverse technical requirements:

| Architecture Feature         | Hosted Gateway (v1.0)                             | Headless API (v2.0)                                                |
| ---------------------------- | ------------------------------------------------- | ------------------------------------------------------------------ |
| **Primary Integration Flow** | Web checkout redirection                          | Native in-app, Telegram bot, or custom UI                          |
| **User Experience**          | SkyPay hosted payment page                        | 100% white-label custom screens                                    |
| **Creation Endpoint**        | `POST /api/payment/create`                        | `POST /api/v2/payment/create`                                      |
| **Verification Endpoint**    | `POST /api/payment/verify`                        | `POST /api/v2/payment/verify`                                      |
| **Response Payload**         | Returns pre-built checkout `payment_url`          | Returns session `id`, active numbers, rates, and QR codes          |
| **Webhook Support**          | Automated HTTP POST callback to `webhook_url`     | Background IPN on confirmed transaction commitment                 |
| **Best Suited For**          | E-commerce websites, WooCommerce, WHMCS, PHP apps | Mobile apps (Flutter, React Native), Telegram bots, gaming portals |

***

## 2. Navigational Directory

To quickly navigate through the SkyPay documentation suite, refer to the directory below:

| Documentation Section          | File Reference                                                   | Primary Focus & Topics Covered                                                        |
| ------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **Overview & Getting Started** | [README.md](/readme.md)                                          | Platform architecture, integration prerequisites, and quickstart guide                |
| **Authentication & Headers**   | [authentication.md](/integration-and-api/authentication.md)      | API keys, Bearer token authorization, header hierarchies, and security best practices |
| **Create Payment**             | [create-payment.md](/integration-and-api/create-payment.md)      | Hosted v1 and Headless v2 session generation, parameters, and payloads                |
| **Verify Payment**             | [verify-payment.md](/integration-and-api/verify-payment.md)      | Transaction verification across MFS, Bangla QR, BEP20 USDT, and Binance Pay           |
| **Webhooks (IPN)**             | [webhooks.md](/integration-and-api/webhooks.md)                  | Asynchronous notifications, HMAC-SHA256 signature verification, and idempotency       |
| **Device Health & Telemetry**  | [devices-telemetry.md](/system-and-devices/devices-telemetry.md) | Hardware relay state machine, ping queues, and uptime calculations                    |
| **Error Code Reference**       | [error-codes.md](/system-and-devices/error-codes.md)             | Comprehensive HTTP status codes, error string constants, and troubleshooting          |
| **Changelog & Versioning**     | [changelog.md](/system-and-devices/changelog.md)                 | API release history, version deprecation schedule, and migration guides               |
| **Deployment & Sync Guide**    | [DEPLOYMENT.md](/deployment-and-setup/deployment.md)             | GitHub synchronization, GitBook space linking, and custom domain DNS setup            |

***

## 3. Global Integration Prerequisites

Before dispatching transactions against the SkyPay Core API in production, verify that your backend infrastructure adheres to the following mandatory standards:

### 1. Transport Security & Content Negotiation

* **Strict HTTPS**: Insecure HTTP requests are automatically rejected with an HTTP 403 or redirected. TLS 1.2 minimum is enforced (TLS 1.3 strongly recommended).
* **HTTP Headers**: All POST requests must include:

  ```http
  Content-Type: application/json
  Accept: application/json
  ```

### 2. Callback & Webhook Accessibility

* **Public Routing**: Webhook callback URLs (`webhook_url`) must be publicly reachable from the internet. Local addresses (`localhost`, `127.0.0.1`, private RFC 1918 subnets) will fail delivery.
* **Valid SSL Certificates**: Webhook listeners must present a valid SSL/TLS certificate issued by a recognized Certificate Authority (CA). Self-signed certificates are rejected.
* **Acknowledgement**: Webhook listeners must return an HTTP 200 OK within 5,000 milliseconds to prevent retry triggers.

### 3. Cellular Telecom Latency Window (5–20 Seconds)

{% hint style="warning" %}
**Telecom SMS Delay Buffer**: Mobile Financial Services transactions (bKash, Nagad, Rocket) rely on cellular SMS generation and cellular broadcast towers. There is an inherent propagation delay of **5 to 20 seconds** from the customer's USSD/App transfer to receipt on the merchant relay phone.

When implementing client-side polling or user verification prompts, enforce a minimum 10 to 15-second grace period before marking a transaction as failed.
{% endhint %}

### 4. Merchant Android Relay Maintenance

* **Continuous Power**: Merchant relay devices running `SkyPay.apk` must remain plugged into dedicated AC power adapters 24/7.
* **Battery Optimization**: The Android OS Battery Optimization / Doze Mode must be explicitly set to **Unrestricted** for the SkyPay application to prevent background thread suspension.
* **Network Redundancy**: Dual-channel connectivity (Wi-Fi with automatic cellular mobile data failover) is recommended to avoid transient telemetry drops.

***

## 4. Official SDKs, Plugins & Tools

SkyPay maintains pre-built integration modules and developer assets for standard web applications:

| Package / Module             | Description                                                                | Format / Distribution |
| ---------------------------- | -------------------------------------------------------------------------- | --------------------- |
| **WooCommerce Gateway**      | Plug-and-play payment gateway plugin for WordPress & WooCommerce stores    | `.zip` Plugin Archive |
| **WHMCS Billing Module**     | Automated invoice settlement module for web hosting platforms (v7.x, v8.x) | `.zip` Module Archive |
| **SMM Panel Auto-Deposit**   | Automated balance top-up integration for SmartPanel and clone scripts      | `.zip` Script Addon   |
| **Sketchware SWB Project**   | Complete native Android mobile app source project for mobile developers    | `.swb` Project File   |
| **SkyPay Merchant Sync APK** | Android background SMS relay and hardware telemetry bridge                 | `.apk` Package        |
| **Postman API Collection**   | Pre-configured environment variables, request schemas, and tests           | `.json` Collection    |

***

## 5. Next Steps

To begin integrating SkyPay into your application, proceed to the Authentication guide:

* Continue to [Authentication & Security](/integration-and-api/authentication.md)