Agreement Deduction API

HTTP Request

POST /v5/pay/agreement/deduction

Execute automatic deduction from user's account using a signed agreement. This is the core API for agreement payment.

Request Parameters

Parameter	Type	Required	Description
merchantId	string	Yes	Merchant ID
userId	string	Yes	Platform user ID
agreementType	string	Yes	Sign type: `CYCLE` / `NON_CYCLE` / `SINGLE`
agreementNo	string	Yes	Platform agreement number
outTradeNo	string	Yes	Merchant order number (unique)
sceneCode	string	Yes	Scene code - Supports 17 scenarios including TAXI, PARKING, SUBSCRIPTION, FOOD, ENTERTAINMENT, EDUCATION, etc.
amount	object	Yes	Deduction amount
amount.total	string	Yes	Amount (minimum unit)
amount.currency	string	Yes	Currency code
amount.currencyType	string	Yes	`FIAT` or `CRYPTO`
amount.chain	string	No	Chain network (required in dynamic chain settlement mode, e.g., BSC, TRX, ARBI, LTC, SOL, ETH, TON, APTOS)
amount.chainAddress	string	No	Chain address (required in dynamic chain settlement mode)
orderInfo	object	Yes	Order information
orderInfo.orderTitle	string	Yes	Order title (displayed to user)
orderInfo.orderDesc	string	No	Order description
orderInfo.goodsName	string	No	Goods name
orderInfo.goodsId	string	No	Goods ID
orderInfo.goodsCategory	string	Yes	Goods category (4-digit code, see Appendix.MCC Industry Categories)
sceneInfo	object	No	Scene information
sceneInfo.deviceId	string	No	Device ID
sceneInfo.deviceIp	string	No	Device IP
sceneInfo.location	object	No	Location information
sceneInfo.location.latitude	string	No	Latitude
sceneInfo.location.longitude	string	No	Longitude
sceneInfo.location.address	string	No	Detailed address
notifyUrl	string	Yes	Deduction result webhook URL
riskInfo	object	No	Risk control information
riskInfo.userIp	string	No	User IP address
riskInfo.deviceFingerprint	string	No	Device fingerprint
riskInfo.userAgent	string	No	User agent string

Response Parameters

Parameter	Type	Description
retCode	int	Response code
retMsg	string	Response message
result	object	Response data
result.orderNo	string	Platform order number
result.tradeNo	string	Platform trade number
result.outTradeNo	string	Merchant order number
result.status	string	Transaction status: `PROCESSING` / `SUCCESS` / `FAILED` / `TIMEOUT`
result.amount	object	Requested amount
result.cryptoPayment	object	Actual crypto payment info (for fiat orders)
result.cryptoPayment.currency	string	Cryptocurrency (e.g., USDT)
result.cryptoPayment.amount	string	Cryptocurrency amount
result.cryptoPayment.chain	string	Chain network (e.g., BSC, TRX, ARBI, LTC, SOL, ETH, TON, APTOS)
result.cryptoPayment.exchangeRate	string	Exchange rate
result.cryptoPayment.rateTime	string	Rate lock time
result.payTime	string	Payment time (on success)
result.failureReason	string	Failure reason (on failure)

Request Examples

Cryptocurrency Order

POST /v5/pay/agreement/deduction HTTP/1.1
Host: api.bybit.com
Content-Type: application/json
X-Request-Id: 550e8400-e29b-41d4-a716-446655440000
X-Timestamp: 1736233200000
X-Signature: {signature}
Authorization: Bearer {access_token}

{
  "merchantId": "M123456789",
  "userId": "U_123456789",
  "agreementType": "CYCLE",
  "agreementNo": "AGR202601070001",
  "outTradeNo": "ORDER20260107001",
  "sceneCode": "SUBSCRIPTION",
  "amount": {
    "total": "2350",
    "currency": "USDT",
    "currencyType": "CRYPTO",
    "chain": "TRC20"
  },
  "orderInfo": {
    "orderTitle": "Monthly subscription - January 2026",
    "orderDesc": "Premium membership",
    "goodsName": "Premium Plan",
    "goodsId": "PREMIUM_001",
    "goodsCategory": "7372"
  },
  "notifyUrl": "https://merchant.com/notify/pay"
}

Fiat Currency Order

POST /v5/pay/agreement/deduction HTTP/1.1
Host: api.bybit.com
Content-Type: application/json
X-Request-Id: 550e8400-e29b-41d4-a716-446655440000
X-Timestamp: 1736233200000
X-Signature: {signature}
Authorization: Bearer {access_token}

{
  "merchantId": "M123456789",
  "userId": "U_123456789",
  "agreementType": "CYCLE",
  "agreementNo": "AGR202601070001",
  "outTradeNo": "ORDER20260107002",
  "sceneCode": "TAXI",
  "amount": {
    "total": "10000",
    "currency": "USD",
    "currencyType": "FIAT"
  },
  "orderInfo": {
    "orderTitle": "Ride fare",
    "orderDesc": "Trip from A to B",
    "goodsCategory": "4121"
  },
  "sceneInfo": {
    "deviceId": "DEVICE_001",
    "deviceIp": "192.168.1.1",
    "location": {
      "latitude": "39.9042",
      "longitude": "116.4074",
      "address": "Beijing, China"
    }
  },
  "riskInfo": {
    "userIp": "203.0.113.45",
    "deviceFingerprint": "fp_abc123xyz"
  },
  "notifyUrl": "https://merchant.com/notify/pay"
}

Response Examples

Crypto Order Success

{
  "retCode": 20000,
  "retMsg": "Success",
  "result": {
    "orderNo": "ORD202601070001",
    "tradeNo": "PAY202601070001",
    "outTradeNo": "ORDER20260107001",
    "status": "SUCCESS",
    "amount": {
      "total": "2350",
      "currency": "USDT",
      "currencyType": "CRYPTO",
      "chain": "TRC20"
    },
    "payTime": "2026-01-07T10:30:00Z"
  }
}

Fiat Order Success (with Crypto Payment)

{
  "retCode": 20000,
  "retMsg": "Success",
  "result": {
    "orderNo": "ORD202601070002",
    "tradeNo": "PAY202601070002",
    "outTradeNo": "ORDER20260107002",
    "status": "SUCCESS",
    "amount": {
      "total": "10000",
      "currency": "USD",
      "currencyType": "FIAT"
    },
    "cryptoPayment": {
      "currency": "USDT",
      "amount": "10005.50",
      "chain": "TRC20",
      "exchangeRate": "1.00055",
      "rateTime": "2026-01-07T10:29:55Z"
    },
    "payTime": "2026-01-07T10:30:00Z"
  }
}

Processing Status

{
  "retCode": 20000,
  "retMsg": "Success",
  "result": {
    "orderNo": "ORD202601070003",
    "tradeNo": "PAY202601070003",
    "outTradeNo": "ORDER20260107003",
    "status": "PROCESSING",
    "amount": {
      "total": "5000",
      "currency": "USDT",
      "currencyType": "CRYPTO",
      "chain": "TRC20"
    }
  }
}

Deduction Failed

{
  "retCode": 20000,
  "retMsg": "Success",
  "result": {
    "orderNo": "ORD202601070004",
    "tradeNo": "PAY202601070004",
    "outTradeNo": "ORDER20260107004",
    "status": "FAILED",
    "amount": {
      "total": "5000",
      "currency": "USDT",
      "currencyType": "CRYPTO",
      "chain": "TRC20"
    },
    "failureReason": "BALANCE_NOT_ENOUGH"
  }
}

Verification Steps

Platform performs the following checks before executing deduction:

Agreement Validity: Agreement must be in SIGNED status
Single Limit Check: Amount does not exceed single transaction limit
Period Limit Check: Cumulative amount does not exceed period limit
Balance Check: User account has sufficient balance
Risk Check: Transaction passes risk control rules

Notes

Idempotency: Same outTradeNo returns result of first request
Async Processing: PROCESSING status requires waiting for webhook or query
Timeout Handling: Set 30-second timeout, query if timeout occurs
Fiat Orders: User pays with cryptocurrency; cryptoPayment shows actual payment details

HTTP Request​

Request Parameters​

Response Parameters​

Request Examples​

Cryptocurrency Order​

Fiat Currency Order​

Response Examples​

Crypto Order Success​

Fiat Order Success (with Crypto Payment)​

Processing Status​

Deduction Failed​

Verification Steps​

Notes​