Query Transaction API

HTTP Request

GET /v5/pay/agreement/transaction/query

Query a single deduction transaction or refund record by its transaction or refund number. The current implementation determines the returned detail type from the matched order record.

---

Request Parameters

Parameter	Type	Required	Description
merchantId	string	Yes	Merchant ID
userId	string	No	Platform user ID; accepted by the interface but not used by the current query lookup
agreementType	string	Yes	Sign type: CYCLE / NON_CYCLE / SINGLE; accepted but not used by the current query lookup
recordType	string	No	Record type: PAY / REFUND; accepted but not used by the current query lookup, and no default is applied
tradeNo	string	Conditional	Platform trade number; provide at least one transaction/refund number
outTradeNo	string	Conditional	Merchant order number; provide at least one transaction/refund number
refundNo	string	Conditional	Platform refund number; provide at least one transaction/refund number
outRefundNo	string	Conditional	Merchant refund number; provide at least one transaction/refund number

信息

At least one of tradeNo, outTradeNo, refundNo, or outRefundNo must be provided.

---

Response Parameters (Deduction Transaction)

Parameter	Type	Description
retCode	int	Response code
retMsg	string	Response message
result	object	Response data
result.tradeDetail	object	Transaction details; populated when the matched order is a deduction transaction
result.tradeDetail.tradeNo	string	Platform trade number
result.tradeDetail.outTradeNo	string	Merchant order number
result.tradeDetail.status	string	Transaction status: PROCESSING / SUCCESS / FAILED / TIMEOUT
result.tradeDetail.amount	object	Merchant requested amount
result.tradeDetail.amount.total	string	Amount (minimum unit)
result.tradeDetail.amount.currency	string	Currency code
result.tradeDetail.amount.currencyType	string	Currency type: FIAT / CRYPTO
result.tradeDetail.amount.chain	string	Chain network
result.tradeDetail.cryptoPayment	object	Defined by the response schema but not populated by the current query implementation
result.tradeDetail.payTime	string	Payment time
result.tradeDetail.refundAmount	object	Defined by the response schema but not populated by the current query implementation
result.tradeDetail.orderInfo	object	Order information
result.tradeDetail.orderInfo.orderTitle	string	Order title
result.tradeDetail.orderInfo.orderDesc	string	Order description
result.tradeDetail.orderInfo.goodsName	string	Goods name
result.tradeDetail.orderInfo.goodsId	string	Goods ID
result.tradeDetail.orderInfo.goodsCategory	string	Goods category
result.tradeDetail.customerInfo	object	Customer KYC information; returned only for successful orders when enabled for the merchant
result.tradeDetail.customerInfo.firstName	string	Customer first name
result.tradeDetail.customerInfo.lastName	string	Customer last name
result.tradeDetail.customerInfo.dateOfBirth	string	Customer date of birth
result.tradeDetail.customerInfo.kyc1Country	string	KYC level 1 country
result.tradeDetail.customerInfo.kyc2Country	string	KYC level 2 country

Response Parameters (Refund Record)

Parameter	Type	Description
retCode	int	Response code
retMsg	string	Response message
result	object	Response data
result.refundDetail	object	Refund details; populated when the matched order is a refund
result.refundDetail.refundNo	string	Platform refund number
result.refundDetail.outRefundNo	string	Merchant refund number
result.refundDetail.tradeNo	string	Original trade number
result.refundDetail.status	string	Refund status: PROCESSING / SUCCESS / FAILED / TIMEOUT
result.refundDetail.refundAmount	object	Refund amount
result.refundDetail.refundAmount.total	string	Refund amount (minimum unit)
result.refundDetail.refundAmount.currency	string	Currency code
result.refundDetail.refundAmount.currencyType	string	Currency type: FIAT / CRYPTO
result.refundDetail.refundTime	string	Refund success time
result.refundDetail.failureReason	string	Failure reason
result.refundDetail.customerInfo	object	Customer KYC information; returned only for successful orders when enabled for the merchant
result.refundDetail.customerInfo.firstName	string	Customer first name
result.refundDetail.customerInfo.lastName	string	Customer last name
result.refundDetail.customerInfo.dateOfBirth	string	Customer date of birth
result.refundDetail.customerInfo.kyc1Country	string	KYC level 1 country
result.refundDetail.customerInfo.kyc2Country	string	KYC level 2 country

---

Request Examples

Query Deduction Transaction

GET /v5/pay/agreement/transaction/query?merchantId=M123456789&userId=U_123456789&agreementType=CYCLE&recordType=PAY&tradeNo=PAY202601070001 HTTP/1.1
Host: api.bybit.com
X-Request-Id: 550e8400-e29b-41d4-a716-446655440000
X-Timestamp: 1736233200000
X-Signature: {signature}
Authorization: Bearer {access_token}

Query Refund Record

GET /v5/pay/agreement/transaction/query?merchantId=M123456789&userId=U_123456789&agreementType=CYCLE&recordType=REFUND&refundNo=RF202601070001 HTTP/1.1
Host: api.bybit.com
X-Request-Id: 550e8400-e29b-41d4-a716-446655440000
X-Timestamp: 1736233200000
X-Signature: {signature}
Authorization: Bearer {access_token}

---

Response Examples

Deduction Transaction

{
  "retCode": 20000,
  "retMsg": "Success",
  "result": {
    "tradeDetail": {
      "tradeNo": "PAY202601070002",
      "outTradeNo": "ORDER20260107002",
      "status": "SUCCESS",
      "amount": {
        "total": "10000",
        "currency": "USD",
        "currencyType": "FIAT",
        "chain": ""
      },
      "payTime": "2026-01-07T10:30:00Z",
      "orderInfo": {
        "orderTitle": "Ride fare",
        "orderDesc": "January 7 trip fare",
        "goodsName": "Express service",
        "goodsId": "TAXI_SERVICE_001",
        "goodsCategory": "4121"
      }
    }
  }
}

Refund Record

{
  "retCode": 20000,
  "retMsg": "Success",
  "result": {
    "refundDetail": {
      "refundNo": "RF202601070001",
      "outRefundNo": "REFUND20260107001",
      "tradeNo": "PAY202601070001",
      "status": "SUCCESS",
      "refundAmount": {
        "total": "2350",
        "currency": "USDT",
        "currencyType": "CRYPTO"
      },
      "refundTime": "2026-01-07T11:30:00Z",
      "failureReason": ""
    }
  }
}

---

Notes

• Use this API to confirm transaction or refund status after timeout
• The detail type is determined by the matched order and returned in either tradeDetail or refundDetail
• For PROCESSING status, wait for the webhook or poll periodically