Skip to main content

Query Card List

Query the authenticated user's virtual and physical cards. By default, only non-final cards and cards being processed are returned.

tip

Only cards belonging to the authenticated user are returned.

The request body can be omitted or set to {}. Pagination parameters are not accepted.

HTTP Request​

POST/v5/card/list

Request Parameters​

ParameterRequiredTypeComments
includeFinalCardsfalsebooleanWhether to include cancelled and invalid cards. true: include final cards. Omitted, false, or null: use the default filtering

Response Parameters​

ParameterTypeComments
retCodeintegerBusiness return code. 0: success; non-zero: failure
retMsgstringReturn message
resultobjectQuery result. null on failure
> pageNointegerCurrent page number. Fixed at 1
> pageSizeintegerNumber of cards returned
> totalPageintegerTotal number of pages. Fixed at 1
> totalCountintegerTotal number of matching cards
> dataarrayCard list. Empty array when no cards match
>> cardIdstringCard ID
>> cardProductCodeintegerCard product code. Identifies the product together with productId
>> productIdintegerCard product ID
>> cardHolderNamestringCardholder name printed on the card
>> cardTypeintegerCard type. 1: Virtual card, 2: Physical card
>> maskedCardNumberstringMasked card number
>> pan6stringCard number prefix, usually the first 6 digits
>> pan4stringCard number suffix, usually the last 4 digits
>> cardExpireDatestringCard expiry date, in MM/yy format
>> cardCurrencystringCard currency code
>> statusintegerCard status. 0: Undefined, 1: Inactive, 2: Active, 3: Frozen, 4: Banned, 5: Cancelled, 6: Invalid, 7: Created
>> subStatusintegerCard sub-status code. Examples: 200: Active, 300: Regular freeze, 501: Cancelled by user, 601: Expired
>> countryAlpha3stringCountry Alpha-3 code, e.g. AUS
>> cardActivateTimeintegerCard activation time (Unix ms timestamp)
>> createTimeintegerCard creation time (Unix ms timestamp)
>> allowOnlineTransactionbooleanWhether online transactions are allowed
>> allowAtmWithdrawalbooleanWhether ATM withdrawals are allowed
>> supportedCurrencyListarrayList of supported currency codes. Entries can be null
>> shippingInfoobjectPhysical card shipping information. null for virtual cards
>>> delvProviderstringDelivery provider
>>> trackingNostringTracking number
>>> shipmentTimeintegerShipment time (Unix ms timestamp)
>>> shippingStatusstringShipping status
>>> shippingStatusDetailstringDetailed shipping status
>>> trackingUrlstringTracking URL
>>> allowToChangeAddressbooleanWhether the shipping address can be changed
>>> deliverReminderCodestringDelivery reminder code
>> isGooglePayAvailablebooleanWhether the product supports Google Pay. false when the configuration is missing
>> isApplePayAvailablebooleanWhether the product supports Apple Pay. false when the configuration is missing
retExtInfoobjectExtended information. Defaults to {}
timeintegerResponse time (Unix ms timestamp)

Card detail fields can be null, except isGooglePayAvailable and isApplePayAvailable, which are always returned as booleans. Shipping fields can be null; shipping addresses are not returned. Some physical cards without shipping records still return an object with empty fields.

Error Codes​

retCoderetMsgComments
913100000SYSTEM ERRORRequest binding failure or system error

Global error responses may omit retExtInfo and time.


Request Example​

POST /v5/card/list HTTP/1.1
Host: api-testnet.bybit.com
X-BAPI-SIGN: XXXXX
X-BAPI-API-KEY: xxxxxxxxxxxxxxxxxx
X-BAPI-TIMESTAMP: 1672211918471
X-BAPI-RECV-WINDOW: 5000
Content-Type: application/json

{
"includeFinalCards": true
}

Response Example​

{
"retCode": 0,
"retMsg": "OK",
"result": {
"pageNo": 1,
"pageSize": 1,
"totalPage": 1,
"totalCount": 1,
"data": [
{
"cardId": "180585395564494848",
"cardProductCode": 1,
"productId": 4,
"cardHolderName": "TEST HOLDER",
"cardType": 1,
"maskedCardNumber": "539900******5497",
"pan6": "539900",
"pan4": "5497",
"cardExpireDate": "12/29",
"cardCurrency": "USD",
"status": 2,
"subStatus": 200,
"countryAlpha3": "AUS",
"cardActivateTime": 1672211918471,
"createTime": 1672211918471,
"allowOnlineTransaction": true,
"allowAtmWithdrawal": true,
"supportedCurrencyList": ["USD"],
"shippingInfo": null,
"isGooglePayAvailable": false,
"isApplePayAvailable": false
}
]
},
"retExtInfo": {},
"time": 1672211918471
}