QR Payment Introduction

Version History

Version	Date	Changes
1.0	2025-02-10	Initial release
5.0	2025-02-17	Modified the state machine Added "Pay Id" to Payment Notify Added "Authentication" description to Payment Notify Added "MccCodes" explanation for goods details
5.0	2025-03-03	Changed `clientId` to optional when initiating refund or querying order status Moved field `goods` into `PayOrder` structure Moved field `customer` from `PayOrder` structure Renamed `orderAmount` to `amount` for all `PayOrder` types Changed request body type from JSON array to JSON object when creating a refund order Added `merchantRefundNo` when creating a refund order Added error codes: `50000` (Bybit internal error), `400004` (Order not found), `500105` (Order not paid) Changed `regionTime` to `registerTime` in Customer type Added Type RefundOrder, removed refund fields from PayOrder Removed all Customer and Good data from response structure Added Signature Algorithm description Changed notify request body Changed timestamp from millisecond to second precision
5.0	2025-03-31	Added Payment Status Mock API Added Payout API
5.0	2025-04-16	Added Settlement Report API
5.0	2025-05-09	Added payout status
5.0	2025-05-13	Refactored payment status mock path from `/v5/bybitpay/pay-status/mock` to `/v5/bybitpay/paystatus/mock`
5.0	2025-05-21	Added webhook support for merchant public key
5.0	2025-05-27	Refactored payment type from `BYBIT_PAY_MERCHANT_PAYOUT` to `MERCHANT_PAYOUT`
5.0	2025-05-28	Added customer uid in `/v5/bybitpay/pay_result` API and Payment Notify
5.0	2025-06-01	Added crypto scale (8 decimal places for crypto currencies)
5.0	2025-06-30	Updated signature algorithm
5.01	2025-07-04	Added Payment FxConvert API Support fiat or crypto to create order with different settlement currency
5.01	2025-07-04	Made payout mccCode required
5.01	2025-09-03	Added additional error codes
5.01	2025-09-09	Added `remarks` field in `/v5/bybitpay/create_pay` and `/v5/bybitpay/pay_result` APIs

Overview

QR Payment is a one-time payment method where users scan a merchant-generated QR code to complete payment through the Bybit App.

Applicable Scenarios:

E-commerce checkout
Retail POS systems
One-time service payments
Event ticket purchases

Payment Flow

┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Merchant   │     │    Bybit     │     │   Bybit App  │     │     User     │
│    Server    │     │   Platform   │     │              │     │              │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                    │                    │                    │
       │ 1. Create Payment  │                    │                    │
       │ ─────────────────→ │                    │                    │
       │                    │                    │                    │
       │ 2. Return QR Code  │                    │                    │
       │    & Pay URL       │                    │                    │
       │ ←───────────────── │                    │                    │
       │                    │                    │                    │
       │   Display QR Code  │                    │                    │
       │   to User          │                    │    3. Scan QR      │
       │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│─ ─ ─ ─ ─ ─ ─ ─ ─ →│← ─ ─ ─ ─ ─ ─ ─ ─  │
       │                    │                    │                    │
       │                    │                    │ 4. Confirm Payment │
       │                    │                    │    & Enter PIN     │
       │                    │                    │ ←─────────────────→│
       │                    │                    │                    │
       │                    │    5. Process      │                    │
       │                    │    Payment         │                    │
       │                    │ ←──────────────────│                    │
       │                    │                    │                    │
       │ 6. Webhook Notify  │                    │  7. Show Result    │
       │    Payment Result  │                    │ ──────────────────→│
       │ ←───────────────── │                    │                    │
       │                    │                    │                    │
       ▼                    ▼                    ▼                    ▼

API List

API Name	Method	Endpoint	Description
Create Payment	POST	`/v5/bybitpay/create_pay`	Create payment order, get QR code
Get Payment Result	GET	`/v5/bybitpay/pay_result`	Query payment status
Payment Notify	POST	Webhook URL	Receive payment result callback
Payment FxConvert	POST	`/v5/bybitpay/fx/convert`	Get exchange rate quotation
Payment Status Mock	POST	`/v5/bybitpay/paystatus/mock`	Mock payment status (sandbox only)

Order Status Flow

┌──────────┐     ┌───────────────┐     ┌───────────────┐
│   INIT   │────→│  PAY_SUCCESS  │────→│ REFUND_SUCCESS│
│  (Created)│     │   (Paid)      │     │  (Refunded)   │
└────┬─────┘     └───────────────┘     └───────────────┘
     │
     │ Timeout/Failed
     ▼
┌───────────────┐
│ TIMEOUT/FAILED│
│               │
└───────────────┘

Status	Description
`INIT`	Order created, waiting for payment
`PAY_SUCCESS`	Payment completed successfully
`PAY_FAILED`	Payment failed
`TIMEOUT`	Order expired (not paid in time)
`REFUND_SUCCESS`	Refund completed
`REFUND_FAILED`	Refund failed

Quick Start

Step 1: Create Payment

POST /v5/bybitpay/create_pay

{
    "merchantId": "305142568",
    "clientId": "client_001",
    "paymentType": "E_COMMERCE",
    "merchantTradeNo": "ORDER-2026-0001",
    "orderAmount": "100",
    "currency": "USDT",
    "webhookUrl": "https://merchant.com/webhook",
    "expireTime": 1800
}

Step 2: Display QR Code

Display the returned qrCodeUrl or payUrl to the user.

Step 3: Handle Webhook

Receive payment result notification at your webhook URL:

{
    "paymentType": "E_COMMERCE",
    "merchantId": "305142568",
    "merchantTradeNo": "ORDER-2026-0001",
    "payId": "01JY2KM5QNPXR8S4HTJZT9BC12",
    "status": "PAY_SUCCESS",
    "amount": "100",
    "currency": "USDT"
}

Refund - Process refunds for completed payments
Payout - Send payouts to Bybit users
Settlement - Query settlement records

Version History​

Overview​

Payment Flow​

API List​

Order Status Flow​

Quick Start​

Step 1: Create Payment​

Step 2: Display QR Code​

Step 3: Handle Webhook​

Related APIs​