Query Transaction API

HTTP Request

GET /v5/bybitpay/agreement/pay/query

Query single deduction transaction or refund record details.

---

Request Parameters

Parameter	Type	Required	Description
merchant_id	string	Yes	Merchant ID
user_id	string	Yes	Platform user ID
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)
refund_no	string	Conditional	Platform refund number (for record_type=REFUND)
out_refund_no	string	Conditional	Merchant refund number (for record_type=REFUND)

信息

• For record_type=PAY: Either trade_no or out_trade_no required
• For record_type=REFUND: Either refund_no or out_refund_no required

---

Response Parameters (Deduction Transaction)

Parameter	Type	Description
retCode	int	Response code
retMsg	string	Response message
result	object	Transaction details
result.trade_no	string	Platform trade number
result.out_trade_no	string	Merchant order number
result.status	string	Transaction status
result.amount	object	Requested amount
result.crypto_payment	object	Actual crypto payment (for fiat orders)
result.pay_time	string	Payment time
result.refund_amount	object	Refunded amount

Response Parameters (Refund Record)

Parameter	Type	Description
retCode	int	Response code
retMsg	string	Response message
result	object	Refund details
result.refund_no	string	Platform refund number
result.out_refund_no	string	Merchant refund number
result.trade_no	string	Original trade number
result.status	string	Refund status: PROCESSING / SUCCESS / FAILED
result.refund_amount	object	Refund amount
result.refund_time	string	Refund success time
result.failure_reason	string	Failure reason

---

Request Examples

Query Deduction Transaction

GET /v5/bybitpay/agreement/pay/query?merchant_id=M123456789&user_id=U_123456789&agreement_type=CYCLE&record_type=PAY&trade_no=PAY202601070001 HTTP/1.1
Host: api2.bybit.com
X-BAPI-API-KEY: xxxxxxxxxxxxxxxxxx
X-BAPI-TIMESTAMP: 1736233200000
X-BAPI-SIGN: {signature}
X-BAPI-RECV-WINDOW: 5000

Query Refund Record

GET /v5/bybitpay/agreement/pay/query?merchant_id=M123456789&user_id=U_123456789&agreement_type=CYCLE&record_type=REFUND&refund_no=RF202601070001 HTTP/1.1
Host: api2.bybit.com
X-BAPI-API-KEY: xxxxxxxxxxxxxxxxxx
X-BAPI-TIMESTAMP: 1736233200000
X-BAPI-SIGN: {signature}
X-BAPI-RECV-WINDOW: 5000

---

Response Examples

Deduction Transaction (with Fiat to Crypto Conversion)

{
  "retCode": 20000,
  "retMsg": "Success",
  "result": {
    "trade_no": "PAY202601070002",
    "out_trade_no": "ORDER20260107002",
    "status": "SUCCESS",
    "amount": {
      "total": "10000",
      "currency": "USD",
      "currency_type": "FIAT"
    },
    "crypto_payment": {
      "currency": "USDT",
      "amount": "10005.50",
      "chain": "TRC20",
      "exchange_rate": "1.00055",
      "rate_time": "2026-01-07T10:29:55Z"
    },
    "pay_time": "2026-01-07T10:30:00Z",
    "refund_amount": {
      "total": "0",
      "currency": "USD",
      "currency_type": "FIAT"
    }
  }
}

Refund Record

{
  "retCode": 20000,
  "retMsg": "Success",
  "result": {
    "refund_no": "RF202601070001",
    "out_refund_no": "REFUND20260107001",
    "trade_no": "PAY202601070001",
    "status": "SUCCESS",
    "refund_amount": {
      "total": "2350",
      "currency": "USDT",
      "currency_type": "CRYPTO",
      "chain": "TRC20"
    },
    "refund_time": "2026-01-07T11:30:00Z"
  }
}

---

Notes

• Use this API to confirm transaction status after timeout
• refund_amount in transaction response shows total refunded amount
• For PROCESSING status, wait for webhook or poll periodically