Skip to content

Commit afb91ce

Browse files
belenweiclaude
belenwei
and
claude
committed
Update scan-payment docs to v5.20 from Lark source
Sync with Lark document (https://uponly.larksuite.com/wiki/StZZwcTsniQD2OkIZ0vu59dHsxd): Major changes: - Add comprehensive version history table to introduction - Add API Version header documentation (default v5.00) - Update Payment Notify to include publicKey header - Mark Settlement API as temporarily unsupported - Replace ASCII flowcharts with Mermaid diagrams for better rendering Data model consistency: - Verified refundAmount uses camelCase naming (consistent) - Verified PaymentType enum includes QR_PAY types - Verified error codes include 50000, 400004, 500105 Documentation improvements: - Enhanced readability with Mermaid flowcharts - Added clear notice for Settlement API availability - Improved authentication guide with Version header examples Co-Authored-By: Claude (global.anthropic.claude-sonnet-4-5-20250929-v1:0) <[email protected]>
1 parent 297068b commit afb91ce

File tree

5 files changed

+125
-5
lines changed

5 files changed

+125
-5
lines changed

‎docs/scan-payment/flow.mdx‎

Lines changed: 71 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,78 @@ title: Flowchart
33
sidebar_label: Flowchart
44
---
55

6-
![flowchar1](/img/flowchart1.png)
6+
## E-Commerce Payment Flow
77

8+
```mermaid
9+
graph TD
10+
Merchant[E-commerce] -->|Create pay order| BybitPay[Bybit Pay]
11+
User[User] -->|Create order| Merchant
12+
BybitPay -->|Pay notify and settlement| Merchant
13+
User -->|Pay| BybitPay
14+
```
815

9-
![flowchar2](/img/flowchart2.png)
16+
## Users' Guide After Creating Payment Order
17+
18+
```mermaid
19+
graph TD
20+
CreateOrder([Create Payment Order])
21+
GetResponse(Get Response)
22+
ClickPay(User click 'Pay' button)
23+
CheckTerminal{User's terminal type}
24+
ShowQR(Show the QR code to user)
25+
OpenLink(Open the 'result.checkoutLink')
26+
27+
CreateOrder --> GetResponse
28+
GetResponse --> ClickPay
29+
ClickPay --> CheckTerminal
30+
CheckTerminal -->|WEB, OTHERS| ShowQR
31+
CheckTerminal -->|APP, WAP, MINIAPP| OpenLink
32+
```
1033

1134
## Payout Flowchart
12-
![flowchar3](/img/payout_flowchart.png)
35+
36+
```mermaid
37+
graph TD
38+
Payer[Payer]
39+
BybitPay[Bybit Pay]
40+
Payee[Payee]
41+
42+
Payer -->|1. Confirm the contract, agreement, or other whitelist requirements| Payee
43+
Payer -->|2. Call 'payout' API| BybitPay
44+
BybitPay -->|3. Create Payment Order| BybitPay
45+
BybitPay -->|4. Risk check| BybitPay
46+
BybitPay -->|5. Debit balance| Payer
47+
BybitPay -->|6. Credit Balance| Payee
48+
BybitPay -->|7. Response the result| Payee
49+
```
50+
51+
## Order Status State Machine
52+
53+
```mermaid
54+
graph TD
55+
CREATE[CREATE] -->|1. Order create success| INIT[INIT]
56+
INIT -->|2. User's payment order is under 'PAY_PROCESS'| PAY_PROCESS[PAY_PROCESS]
57+
58+
PAY_PROCESS -->|2.1 User's payment order failed| INIT
59+
PAY_PROCESS -->|2.2 After 1 hour no success payment| TIMEOUT[TIMEOUT]
60+
PAY_PROCESS -->|2.3 Merchant call the cancel API| CANCEL[CANCEL]
61+
PAY_PROCESS -->|2.4 User's payment order is under 'PAY_SUCCESS'| PAY_SUCCESS[PAY_SUCCESS]
62+
PAY_PROCESS --> PAY_FAILED[PAY_FAILED]
63+
64+
PAY_SUCCESS -->|4. Partial refund success| PARTIAL_REFUND[PARTIAL_REFUND]
65+
PARTIAL_REFUND -->|5. The whole order was refunded| REFUND[REFUND]
66+
67+
REFUND -->|1. Refund order create success| REFUND_PROCESS[REFUND_PROCESS]
68+
REFUND_PROCESS -->|1.1 Merchant call the cancel API| REFUND_CANCEL[REFUND_CANCEL]
69+
REFUND_PROCESS -->|1.2 Refund failed| REFUND_FAILED[REFUND_FAILED]
70+
REFUND_PROCESS -->|2. Order proceed successfully| REFUND_SUCCESS[REFUND_SUCCESS]
71+
REFUND_SUCCESS --> PARTIAL_REFUND
72+
73+
PayoutInit[INIT - Payout] -->|Create order| PAY_PROCESS_Payout[PAY_PROCESS]
74+
PAY_PROCESS_Payout --> PAY_FAILED_Payout[FAILED]
75+
PAY_PROCESS_Payout --> PAY_SUCCESS_Payout[PAY_SUCCESS]
76+
```
77+
78+
:::info
79+
For detailed status descriptions, see [Order Status](order-status).
80+
:::

‎docs/scan-payment/guide.mdx‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,30 @@ REST API Base Endpoint:
1414
`https://api.bybit.com`<br/>
1515
`https://api.bytick.com`
1616

17+
### API Version
18+
19+
All Bybit Pay API requests should include a `Version` header to specify the API version. The current default version is **v5.00**.
20+
21+
```http
22+
Version: 5.00
23+
```
24+
25+
**Example Request:**
26+
```shell
27+
curl --request POST \
28+
--url https://api.bybit.com/v5/bybitpay/create_pay \
29+
--header 'Version: 5.00' \
30+
--header 'Content-Type: application/json' \
31+
--header 'X-BAPI-API-KEY: YOUR_API_KEY' \
32+
--header 'X-BAPI-TIMESTAMP: 1736233200000' \
33+
--header 'X-BAPI-SIGN: YOUR_SIGNATURE' \
34+
--data '{ ... }'
35+
```
36+
37+
:::info
38+
If the `Version` header is not provided, the API will default to v5.00.
39+
:::
40+
1741
### Select Your API Key Type
1842
**System-generated API Keys**: The API key generated by the Bybit system operates with HMAC encryption. You will be
1943
provided with a pair of public and private keys. Please treat this pair of keys as passwords and keep them safe.

‎docs/scan-payment/introduction.mdx‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,29 @@ sidebar_label: Introduction
44
sidebar_position: 0
55
---
66

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

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

‎docs/scan-payment/payment-notify.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ URL: provide the callback url in the [Create Payment](create-payment) request pa
1616
|:-----|----- |
1717
|Content-Type |application/json|
1818
|timestamp |Current timestamp|
19+
|publicKey |Merchant's RSA public key (optional, used for webhook signature verification)|
1920
|signature |Generated by [Signature Algorithm](#signature-algorithm)|
2021

2122
### Callback Request Parameters

‎docs/scan-payment/settlement.mdx‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,12 @@ sidebar_label: Settlement
55
### HTTP Request
66
POST `/v5/bybitpay/settlement_record`
77

8-
:::caution Note
9-
This API is not yet supported. Please contact Bybit Pay team for settlement report inquiries.
8+
:::warning Feature Currently Unavailable
9+
The Settlement Report API is temporarily not supported.
10+
11+
If you need access to settlement data, please contact us:
12+
- Email: [[email protected]](mailto:[email protected])
13+
- Business inquiries: [Partner with us](https://forms.gle/Kou91v4MUT61C8o97)
1014
:::
1115

1216
### Request Parameters

0 commit comments

Comments
 (0)