Guide
Business Scenarios
Bybit Pay provides two main payment integration methods for merchants:
| Scenario | Description | Use Case |
|---|---|---|
| QR Payment | QR code based payment where users scan to pay | E-commerce checkout, retail POS, one-time payments |
| Recurring Payments | Pre-authorized automatic deduction payment | Subscriptions, ride-hailing, recurring payments, utility bills |
QR Payment Flow
User scans merchant's QR code and completes payment through Bybit App.
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Merchant │ │ Bybit │ │ Bybit App │ │ User │
│ Server │ │ Platform │ │ │ │ │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │ │
│ 1. Create Payment │ │ │
│ ─────────────────→ │ │ │
│ │ │ │
│ 2. Return QR Code │ │ │
│ ←───────────────── │ │ │
│ │ │ │
│ Display QR │ │ 3. Scan QR │
│ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│─ ─ ─ ─ ─ ─ ─ ─ ─ →│← ─ ─ ─ ─ ─ ─ ─ ─ │
│ │ │ │
│ │ │ 4. Confirm Payment │
│ │ │ ←─────────────────→│
│ │ │ │
│ │ 5. Deduct │ │
│ │ ←──────────────────│ │
│ │ │ │
│ 6. Webhook Notify │ │ │
│ ←───────────────── │ │ │
│ │ │ │
▼ ▼ ▼ ▼
Key Features:
- One-time payment authorization
- Real-time payment result notification
- Support for crypto and fiat currencies
- Refund capability
Auth Flow
Merchant creates a zero-amount Auth order. The user scans the QR code and decides whether to authorize the requested customer fields in Bybit App. Auth does not initiate a payment or asset transfer.
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Merchant │ │ Bybit │ │ Bybit App │ │ User │
│ Server │ │ Platform │ │ │ │ │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │ │
│ 1. Create Auth │ │ │
│ Order (amount 0) │ │ │
│ ─────────────────→ │ │ │
│ │ │ │
│ 2. Return QR Code │ │ │
│ ←───────────────── │ │ │
│ │ │ │
│ Display QR │ │ 3. Scan QR │
│ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│─ ─ ─ ─ ─ ─ ─ ─ ─ ─→│ │
│ │ │← ─ ─ ─ ─ ─ ─ ─ ─ ─ │
│ │ │ │
│ │ │ 4. Review Auth │
│ │ │ ←─────────────────→│
│ │ │ │
│ │ │ 5. Agree / Reject │
│ │ │ ←─────────────────→│
│ │ │ │
│ 6. Auth Webhook │ │ │
│ ←───────────────── │ │ │
│ │ │ │
│ 7. Query Auth │ │ │
│ ─────────────────→ │ │ │
│ │ │ │
│ 8. Auth Result │ │ │
│ ←───────────────── │ │ │
│ │ │ │
▼ ▼ ▼ ▼
Key Features:
- Zero-amount authorization without payment or asset transfer
- User authorization through Bybit App
- Authorization result notification by Webhook
- Merchant query support for Auth status and authorized customer fields
Recurring Payments Flow
User pre-authorizes merchant for automatic deductions without manual confirmation each time.
Sign Flow (One-time Setup)
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Merchant │ │ Bybit │ │ Bybit App │ │ User │
│ Server │ │ Platform │ │ │ │ │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │ │
│ 1. Sign Request │ │ │
│ ─────────────────→ │ │ │
│ │ │ │
│ 2. Return Sign URL │ │ │
│ ←───────────────── │ │ │
│ │ │ │
│ Display QR │ │ 3. Scan QR │
│ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│─ ─ ─ ─ ─ ─ ─ ─ ─ →│← ─ ─ ─ ─ ─ ─ ─ ─ │
│ │ │ │
│ │ │ 4. Identity Verify │
│ │ │ ←─────────────────→│
│ │ │ │
│ │ │ 5. Confirm Sign │
│ │ │ ←─────────────────→│
│ │ │ │
│ 6. Sign Webhook │ │ │
│ (agreement_no) │ │ │
│ ←───────────────── │ │ │
│ │ │ │
▼ ▼ ▼ ▼
Deduction Flow (Automatic Payment)
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Merchant │ │ Bybit │ │ User │
│ Server │ │ Platform │ │ (Passive) │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
│ 1. Deduction │ │
│ (agreement_no) │ │
│ ─────────────────→ │ │
│ │ │
│ │ 2. Verify: │
│ │ - Agreement valid │
│ │ - Limit check │
│ │ - Risk check │
│ │ - Balance check │
│ │ │
│ │ 3. Auto Deduct │
│ │ ──────────────────→│
│ │ │
│ 4. Result + Webhook│ │
│ ←───────────────── │ │
│ │ │
│ │ 5. Notification │
│ │ ──────────────────→│
│ │ │
▼ ▼ ▼
Key Features:
- Pre-authorized automatic payments
- No user confirmation required per transaction
- Single and period limit controls
- Support for subscriptions, ride-hailing, utilities
- Agreement lifecycle management (sign, suspend, resume, unsign)
Base URL
| Environment | Base URL |
|---|---|
| Testnet (Sandbox) | https://api-testnet.bybit.com |
| Mainnet (Production) | https://api.bybit.com |
Common Response Structure
{
"retCode": 100000,
"retMsg": "success",
"result": {
// Response data
}
}
| Field | Type | Description |
|---|---|---|
| retCode | number | Return code. 100000 indicates success |
| retMsg | string | Return message |
| result | object | Business data |
Getting Started
Choose the integration method based on your business needs:
- For one-time payments: Start with QR Payment Integration
- For recurring/automatic payments: Start with Recurring Payments Integration