Get Payment Result

HTTP Request

GET /v5/bybitpay/pay_result

Request Parameters

Parameter	Required	Type	Comments
merchantId	true	string	Onboarding merchant UID
clientId	false	string	Merchant client ID
paymentType	true	string	Payment type
merchantTradeNo	false	string	"paymentType"=E_COMMERCE: it is merchant order number; "paymentType"=E_COMMERCE_REFUND: it is merchant refund order number required if "payId" is not provided
payId	false	string	"paymentType"=E_COMMERCE: it is Bybit pay ID; "paymentType"=E_COMMERCE_REFUND: it is Bybit refund ID required if "merchantTradeNo" is not provided

Response Parameters

Parameter	Type	Comments
order	<PayOrderType>	Bybit PayOrder Detail
customer	<CustomerType>	Customer info

Request Example

Query Pay Order by merchantTradeNo

GET /v5/bybitpay/pay_result?merchantId=305142568&paymentType=E_COMMERCE&merchantTradeNo=af8c2d1-5b3e-4a9f-b6c7-8d2e1f3a4b5c HTTP/1.1
Host: api2.bybit.com
X-BAPI-SIGN: XXXXX
X-BAPI-API-KEY: xxxxxxxxxxxxxxxxxx
X-BAPI-TIMESTAMP: 1736233200000
X-BAPI-RECV-WINDOW: 5000
Content-Type: application/json

Query Pay Order by payId (Recommended)

GET /v5/bybitpay/pay_result?merchantId=305142568&paymentType=E_COMMERCE&payId=01JY2KM5QNPXR8S4HTJZT9BC12 HTTP/1.1
Host: api2.bybit.com
X-BAPI-SIGN: XXXXX
X-BAPI-API-KEY: xxxxxxxxxxxxxxxxxx
X-BAPI-TIMESTAMP: 1736233200000
X-BAPI-RECV-WINDOW: 5000
Content-Type: application/json

Query Refund Order

GET /v5/bybitpay/pay_result?merchantId=305142568&paymentType=E_COMMERCE_REFUND&merchantTradeNo=RF-2026-0001 HTTP/1.1
Host: api2.bybit.com
X-BAPI-SIGN: XXXXX
X-BAPI-API-KEY: xxxxxxxxxxxxxxxxxx
X-BAPI-TIMESTAMP: 1736233200000
X-BAPI-RECV-WINDOW: 5000
Content-Type: application/json

Response Example

Pay Order Response (Payment Success)

{
    "retCode": 100000,
    "retMsg": "success",
    "result": {
        "order": {
            "merchantId": "305142568",
            "clientId": "client_001",
            "paymentType": "E_COMMERCE",
            "merchantTradeNo": "af8c2d1-5b3e-4a9f-b6c7-8d2e1f3a4b5c",
            "payId": "01JY2KM5QNPXR8S4HTJZT9BC12",
            "status": "PAY_SUCCESS",
            "amount": "100",
            "currency": "USDT",
            "currencyType": "crypto",
            "createTime": 1736233200,
            "paymentTime": 1736233260,
            "finishTime": 1736233260,
            "refundOrders": [],
            "remark": "Order for digital goods"
        },
        "customer": {
            "uid": "104326789",
            "externalUserId": "user123@merchant.com",
            "userName": "John Doe",
            "registerTime": 1704067200,
            "kycCountry": "USA",
            "onChainInfo": {
                "chainType": "TRC20",
                "chainAddress": "TXxx...xxxx"
            },
            "remarks": "VIP customer"
        }
    }
}

Pay Order Response (Timeout)

{
    "retCode": 100000,
    "retMsg": "success",
    "result": {
        "order": {
            "merchantId": "305142568",
            "clientId": "client_001",
            "paymentType": "E_COMMERCE",
            "merchantTradeNo": "bf9d3e2-6c4f-5b0e-c8d9-9e3f2a4b6d7e",
            "payId": "01JY2KM5QNPXR8S4HTJZT9BC13",
            "status": "TIMEOUT",
            "amount": "50",
            "currency": "USDT",
            "currencyType": "crypto",
            "createTime": 1736230000,
            "paymentTime": 0,
            "finishTime": 1736233600,
            "refundOrders": []
        },
        "customer": {
            "uid": "104326790",
            "externalUserId": "user456@merchant.com",
            "userName": "Jane Smith",
            "registerTime": 1709251200,
            "kycCountry": "GBR",
            "onChainInfo": {
                "chainType": "TRC20",
                "chainAddress": "TYyy...yyyy"
            }
        }
    }
}

Order with Refund Response

{
    "retCode": 100000,
    "retMsg": "success",
    "result": {
        "order": {
            "merchantId": "305142568",
            "clientId": "client_001",
            "paymentType": "E_COMMERCE",
            "merchantTradeNo": "af8c2d1-5b3e-4a9f-b6c7-8d2e1f3a4b5c",
            "payId": "01JY2KM5QNPXR8S4HTJZT9BC12",
            "status": "PAY_SUCCESS",
            "amount": "100",
            "currency": "USDT",
            "currencyType": "crypto",
            "createTime": 1736233200,
            "paymentTime": 1736233260,
            "finishTime": 1736233260,
            "refundOrders": [
                {
                    "refundId": "RF01JY2KM5QNPXR8S4HTJZT9BC14",
                    "refundType": "MERCHNT_SELF_REFUND",
                    "merchantTradeNo": "af8c2d1-5b3e-4a9f-b6c7-8d2e1f3a4b5c",
                    "merchantRefundNo": "RF-2026-0001",
                    "payId": "01JY2KM5QNPXR8S4HTJZT9BC12",
                    "refundStatus": "REFUND_SUCCESS",
                    "refundCurrency": "USDT",
                    "amount": "50",
                    "createTime": 1736234000
                }
            ],
            "remark": "Partial refund processed"
        },
        "customer": {
            "uid": "104326789",
            "externalUserId": "user123@merchant.com",
            "userName": "John Doe",
            "registerTime": 1704067200,
            "kycCountry": "USA"
        }
    }
}

Auth

Auth reuses the Payment Result endpoint. The query parameters remain unchanged: use paymentType = E_COMMERCE and provide either payId or merchantTradeNo. Using payId is recommended. The response adds the following fields:

Field Name	Type	Required	Description
result.order.authStatus	string	Yes	Current authorization status.
result.order.authExpireAt	string	No	Authorization expiry time as a UTC Unix timestamp in milliseconds. Returned after authorization succeeds.
result.customer	Customer Type	No	Authorized customer fields. Returned only when authStatus is SUCCESS and the authorization has not expired.

Authorization status:

authStatus	Order status	Description
PENDING	INIT	Waiting for the user to agree to or reject the authorization request.
SUCCESS	PAY_SUCCESS	The user agreed and the authorization is still valid. Authorized customer fields may be returned.
REJECTED	ERROR	The user rejected the authorization request.
OVERTIME	TIMEOUT	The user did not complete authorization before orderExpireTime.
EXPIRED	PAY_SUCCESS	The user previously agreed, but the authorization validity period has ended. The original order remains successful and customer fields are no longer returned.

authStatus is the authoritative authorization status. The existing order status continues to represent the payment-order result. The actual customer fields are determined by the merchant's current authorization package:

Authorization Field	Response Field	Description
uid	customer.uid	Bybit user UID.
legalIdNumber	customer.legalIdNumber	Legal identity document number.
idType	customer.idType	Legal identity document type.
fullName	customer.firstName, customer.lastName	Customer's first and last name.
birthdate	customer.dateOfBirth	Date of birth.
kyc1Country	customer.kyc1Country	KYC Level 1 country or region code.
email	customer.email	Email address.
phoneNumber	customer.phone	Phone number, including the country calling code when available.

legalIdNumber and idType are returned as a pair from one complete identity-document source.

Request demo

{{base_url}}/v5/bybitpay/pay_result?merchantId=305142568&paymentType=E_COMMERCE&payId=01M45AUTHEXAMPLE00000000001

Response demo

{
  "retCode": 100000,
  "retMsg": "success",
  "result": {
    "order": {
      "merchantId": "305142568",
      "clientId": "",
      "paymentType": "E_COMMERCE",
      "merchantTradeNo": "auth-20261005-000001",
      "payId": "01M45AUTHEXAMPLE00000000001",
      "status": "PAY_SUCCESS",
      "amount": "0",
      "currency": "USDT",
      "currencyType": "crypto",
      "createTime": 1791178200,
      "paymentTime": 1791178300,
      "finishTime": 0,
      "refundOrders": [],
      "authStatus": "SUCCESS",
      "authExpireAt": "1791264700000"
    },
    "customer": {
      "uid": "100000001",
      "legalIdNumber": "P1234567",
      "idType": "PASSPORT",
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1990-01-01",
      "kyc1Country": "SGP",
      "email": "john.doe@example.com",
      "phone": "+65 81234567"
    }
  }
}