Sync recurring-payments docs with v2.3 changes

belenwei · claude · belenwei · commit 297068bfebfa · 2026-01-16T21:35:57.000+08:00
- Add NON_CYCLE agreement type to all API documentation - Add failureCode field to webhook notifications - Remove Sign Confirmation API (sign-confirm.mdx) - Update API list and sidebar references - Update error code descriptions This change keeps recurring-payments docs in sync with the main agreement-payment-api-lark-en.md document (commit 047da11). Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/docs/recurring-payments/deduction.mdx b/docs/recurring-payments/deduction.mdx
@@ -18,7 +18,7 @@ Execute automatic deduction from user's account using a signed agreement. This i
 |:----------|:-----|:---------|:------------|
 | merchant_id | string | **Yes** | Merchant ID |
 | user_id | string | **Yes** | Platform user ID |
-| agreement_type | string | **Yes** | Sign type: `CYCLE` / `SINGLE` |
+| agreement_type | string | **Yes** | Sign type: `CYCLE` / `NON_CYCLE` / `SINGLE` |
 | agreement_no | string | **Yes** | Platform agreement number |
 | out_trade_no | string | **Yes** | Merchant order number (unique) |
 | scene_code | string | **Yes** | [Scene code](appendix#scene-codes) |
diff --git a/docs/recurring-payments/error-codes.mdx b/docs/recurring-payments/error-codes.mdx
@@ -46,7 +46,7 @@ Error codes are returned through the `retCode` field in the response body. The `
 | 139001010 | USER_ID_MISMATCH | User ID mismatch | Check if user ID matches sign time |
 | 139001011 | AGREEMENT_USER_MISMATCH | Agreement user mismatch | Check user-agreement binding |
 | 139001012 | SIGN_URL_EXPIRED | Sign URL has expired | Re-initiate sign request for new link |
-| 139001013 | AGREEMENT_TYPE_MISMATCH | Agreement type mismatch | Check if agreement type (CYCLE/SINGLE) is correct |
+| 139001013 | AGREEMENT_TYPE_MISMATCH | Agreement type mismatch | Check if agreement type (CYCLE/NON_CYCLE/SINGLE) is correct |
 
 ---
 
diff --git a/docs/recurring-payments/introduction.mdx b/docs/recurring-payments/introduction.mdx
@@ -165,7 +165,6 @@ User receives refund notification (Push/SMS)
 | API Name | Method | Endpoint | Description |
 |:---------|:-------|:---------|:------------|
 | [Sign Request](sign-request) | POST | `/v5/bybitpay/agreement/sign` | Create sign request, get QR code |
-| [Sign Confirm](sign-confirm) | POST | `/v5/bybitpay/agreement/confirm` | Confirm sign status (optional) |
 | [Unsign](unsign) | POST | `/v5/bybitpay/agreement/unsign` | Terminate agreement |
 | [Deduction](deduction) | POST | `/v5/bybitpay/agreement/pay` | Execute automatic deduction |
 | [Refund](refund) | POST | `/v5/bybitpay/agreement/refund` | Refund deduction transaction |
diff --git a/docs/recurring-payments/list-agreements.mdx b/docs/recurring-payments/list-agreements.mdx
@@ -18,7 +18,7 @@ Query agreement list under merchant with pagination and filtering support.
 |:----------|:-----|:---------|:------------|
 | merchant_id | string | **Yes** | Merchant ID |
 | user_id | string | No | Platform user ID (filter by user) |
-| agreement_type | string | No | Sign type: `CYCLE` / `SINGLE` (query all if not provided) |
+| agreement_type | string | No | Sign type: `CYCLE` / `NON_CYCLE` / `SINGLE` (query all if not provided) |
 | status | string | No | Status filter: `INIT` / `PENDING` / `SIGNED` / `SUSPENDED` / `UNSIGNED` / `EXPIRED` / `FAILED` |
 | scene_code | string | No | Scene code filter |
 | start_time | string | No | Sign start time (ISO8601) |
diff --git a/docs/recurring-payments/list-transactions.mdx b/docs/recurring-payments/list-transactions.mdx
@@ -18,7 +18,7 @@ Query deduction transaction or refund record list under an agreement with pagina
 |:----------|:-----|:---------|:------------|
 | merchant_id | string | **Yes** | Merchant ID |
 | user_id | string | **Yes** | Platform user ID |
-| agreement_type | string | **Yes** | Sign type: `CYCLE` / `SINGLE` |
+| agreement_type | string | **Yes** | Sign type: `CYCLE` / `NON_CYCLE` / `SINGLE` |
 | agreement_no | string | **Yes** | Platform agreement number |
 | record_type | string | No | Record type: `PAY` (default) / `REFUND` |
 | status | string | No | Status filter: `SUCCESS` / `FAILED` / `PROCESSING` |
diff --git a/docs/recurring-payments/pay-with-sign.mdx b/docs/recurring-payments/pay-with-sign.mdx
@@ -31,7 +31,7 @@ This API supports merchants to complete both agreement signing and deduction pay
 |:----------|:-----|:---------|:------------|
 | merchant_id | string | **Yes** | Merchant ID |
 | user_id | string | **Yes** | Platform user ID |
-| agreement_type | string | **Yes** | Sign type: `CYCLE` / `SINGLE` |
+| agreement_type | string | **Yes** | Sign type: `CYCLE` / `NON_CYCLE` / `SINGLE` |
 | sign_params | object | No | Sign parameters (required for first sign + payment) |
 | sign_params.merchant_user_id | string | Conditional | Merchant-side user ID (required when passing sign_params) |
 | sign_params.scene_code | string | Conditional | [Scene code](appendix#scene-codes) (required when passing sign_params) |
diff --git a/docs/recurring-payments/query-agreement.mdx b/docs/recurring-payments/query-agreement.mdx
@@ -18,7 +18,7 @@ Query single agreement status and details.
 |:----------|:-----|:---------|:------------|
 | merchant_id | string | **Yes** | Merchant ID |
 | user_id | string | **Yes** | Platform user ID |
-| agreement_type | string | **Yes** | Sign type: `CYCLE` / `SINGLE` |
+| agreement_type | string | **Yes** | Sign type: `CYCLE` / `NON_CYCLE` / `SINGLE` |
 | agreement_no | string | Either | Platform agreement number |
 | external_agreement_no | string | Either | Merchant agreement number |
 
diff --git a/docs/recurring-payments/query-transaction.mdx b/docs/recurring-payments/query-transaction.mdx
@@ -18,7 +18,7 @@ Query single deduction transaction or refund record details.
 |:----------|:-----|:---------|:------------|
 | merchant_id | string | **Yes** | Merchant ID |
 | user_id | string | **Yes** | Platform user ID |
-| agreement_type | string | **Yes** | Sign type: `CYCLE` / `SINGLE` |
+| agreement_type | string | **Yes** | Sign type: `CYCLE` / `NON_CYCLE` / `SINGLE` |
 | record_type | string | No | Record type: `PAY` (default) / `REFUND` |
 | trade_no | string | Conditional | Platform trade number (for `record_type=PAY`) |
 | out_trade_no | string | Conditional | Merchant order number (for `record_type=PAY`) |
diff --git a/docs/recurring-payments/refund.mdx b/docs/recurring-payments/refund.mdx
@@ -18,7 +18,7 @@ Initiate refund for a successful deduction transaction. Supports full and partia
 |:----------|:-----|:---------|:------------|
 | merchant_id | string | **Yes** | Merchant ID |
 | user_id | string | **Yes** | Platform user ID |
-| agreement_type | string | **Yes** | Sign type: `CYCLE` / `SINGLE` |
+| agreement_type | string | **Yes** | Sign type: `CYCLE` / `NON_CYCLE` / `SINGLE` |
 | trade_no | string | Either | Platform trade number |
 | out_trade_no | string | Either | Merchant order number |
 | out_refund_no | string | **Yes** | Merchant refund number (unique) |
diff --git a/docs/recurring-payments/sign-confirm.mdx b/docs/recurring-payments/sign-confirm.mdx
diff --git a/docs/recurring-payments/sign-request.mdx b/docs/recurring-payments/sign-request.mdx
@@ -18,7 +18,7 @@ Create a sign request to initiate the agreement signing process. Returns a QR co
 |:----------|:-----|:---------|:------------|
 | merchant_id | string | **Yes** | Merchant ID |
 | user_id | string | **Yes** | Platform user ID |
-| agreement_type | string | **Yes** | Sign type: `CYCLE` (periodic) / `SINGLE` (one-time) |
+| agreement_type | string | **Yes** | Sign type: `CYCLE` (periodic) / `NON_CYCLE` (non-periodic) / `SINGLE` (one-time) |
 | merchant_user_id | string | **Yes** | Merchant-side user ID (for mapping) |
 | scene_code | string | **Yes** | [Scene code](appendix#scene-codes): TAXI, PARKING, SUBSCRIPTION, etc. |
 | product_code | string | No | Product code (assigned by platform) |
diff --git a/docs/recurring-payments/unsign.mdx b/docs/recurring-payments/unsign.mdx
@@ -18,7 +18,7 @@ Terminate an active agreement. After unsign, no further deductions can be made.
 |:----------|:-----|:---------|:------------|
 | merchant_id | string | **Yes** | Merchant ID |
 | user_id | string | **Yes** | Platform user ID |
-| agreement_type | string | **Yes** | Sign type: `CYCLE` / `SINGLE` |
+| agreement_type | string | **Yes** | Sign type: `CYCLE` / `NON_CYCLE` / `SINGLE` |
 | agreement_no | string | Either | Platform agreement number |
 | external_agreement_no | string | Either | Merchant agreement number |
 | unsign_type | string | No | Unsign type: `USER` / `MERCHANT` / `SYSTEM` |
diff --git a/docs/recurring-payments/webhooks/agreement.mdx b/docs/recurring-payments/webhooks/agreement.mdx
@@ -18,14 +18,15 @@ Notifies merchant when user completes or fails the sign process.
 |:----------|:-----|:------------|
 | agreementNo | string | Platform agreement number |
 | externalAgreementNo | string | Merchant agreement number |
-| agreementType | string | Sign type: `CYCLE` / `SINGLE` |
+| agreementType | string | Sign type: `CYCLE` / `NON_CYCLE` / `SINGLE` |
 | eventType | string | Event type: `SIGNED` / `FAILED` |
 | status | string | Sign status: `SIGNED` / `FAILED` |
 | userId | string | Platform user ID |
 | merchantUserId | string | Merchant-side user ID |
 | sceneCode | string | Scene code |
 | signTime | string | Sign time (on success) |
-| failureReason | string | Failure reason (on failure) |
+| failureCode | string | Failure error code (on failure, 9-digit string) |
+| failureReason | string | Failure reason description (on failure) |
 
 ### Example (Success)
 
@@ -66,7 +67,8 @@ Notifies merchant when user completes or fails the sign process.
     "userId": "U_123456789",
     "merchantUserId": "merchant_user_123",
     "sceneCode": "SUBSCRIPTION",
-    "failureReason": "USER_AUTH_TIMEOUT"
+    "failureCode": "139001001",
+    "failureReason": "User authentication timeout (downstream code=300100002, msg=User auth timeout)"
   },
 }
 ```
@@ -189,7 +191,7 @@ Notifies merchant when sign link/QR code expires.
 |:----------|:-----|:------------|
 | agreementNo | string | Platform agreement number |
 | externalAgreementNo | string | Merchant agreement number |
-| agreementType | string | Sign type: `CYCLE` / `SINGLE` |
+| agreementType | string | Sign type: `CYCLE` / `NON_CYCLE` / `SINGLE` |
 | eventType | string | Event type: `TIMEOUT` |
 | status | string | Agreement status: `TIMEOUT` |
 | userId | string | Platform user ID |
diff --git a/docs/recurring-payments/webhooks/transaction.mdx b/docs/recurring-payments/webhooks/transaction.mdx
@@ -28,7 +28,8 @@ Notifies merchant when a deduction is completed or fails.
 | amount.currency | string | Currency code |
 | amount.currency_type | string | Currency type |
 | payTime | string | Payment time (on success) |
-| failureReason | string | Failure reason (on failure) |
+| failureCode | string | Failure error code (on failure, 9-digit string) |
+| failureReason | string | Failure reason description (on failure) |
 
 ### Example (Success)
 
@@ -77,7 +78,8 @@ Notifies merchant when a deduction is completed or fails.
       "currency": "USDT",
       "currency_type": "CRYPTO"
     },
-    "failureReason": "BALANCE_NOT_ENOUGH"
+    "failureCode": "139002003",
+    "failureReason": "Insufficient balance (downstream code=120100006, msg=Balance insufficient)"
   },
 }
 ```
@@ -103,7 +105,8 @@ Notifies merchant when a refund is completed or fails.
 | status | string | Refund status: `SUCCESS` / `FAILED` |
 | refund_amount | object | Refund amount object |
 | refundTime | string | Refund time (on success) |
-| failureReason | string | Failure reason (on failure) |
+| failureCode | string | Failure error code (on failure, 9-digit string) |
+| failureReason | string | Failure reason description (on failure) |
 
 ### Example (Success)
 
@@ -156,7 +159,8 @@ Notifies merchant when a refund is completed or fails.
       "currency": "USDT",
       "currency_type": "CRYPTO"
     },
-    "failureReason": "BALANCE_NOT_ENOUGH"
+    "failureCode": "139002003",
+    "failureReason": "Insufficient balance (downstream code=120100006, msg=Balance insufficient)"
   },
 }
 ```
diff --git a/sidebars.js b/sidebars.js
@@ -100,7 +100,6 @@ const sidebars = {
               label: 'Agreement',
               items: [
                 'recurring-payments/sign-request',
-                'recurring-payments/sign-confirm',
                 'recurring-payments/unsign',
                 'recurring-payments/query-agreement',
                 'recurring-payments/list-agreements',
