Get User Card Overview
GET/openapi/v2/cards/overviewReturns all existing cards for one user in the current tenant. Shared cards are nested as fund account → card account limits → product → card. Individual-balance cards carry their own details, balance result, and associated account limit result. Only held products are included. There is no pagination or status filter; existing locked or cancelled cards still count.
Follow V2 Signing and Authentication and Common Responses. The current credentials determine the tenant; callers cannot select a tenant or provider account. Existing List User Cards, Get Card Balance, and Get Card Account Limits contracts remain unchanged.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
memberId | string | Conditional | Platform member ID, maximum 64 characters. Supply exactly one of memberId and email. |
email | string | Conditional | User email in the current tenant, maximum 128 characters. Supply exactly one of memberId and email. |
Pagination and status-filter parameters are not provided.
GET /openapi/v2/cards/overview?memberId=DEMO-MB-101
GET /openapi/v2/cards/overview?email=user@example.comResponse data
| Field | Type | Description |
|---|---|---|
memberId | string | Platform member ID. |
totalCardCount | integer | Total number of shared and individual cards, counting each card once. |
sharedAccounts | array | Shared fund accounts containing a balance and nested card accounts, products, and cards. |
individualCards | array | Individual-balance cards, each directly carrying balanceQuery and limitsQuery. |
An existing user with no cards receives totalCardCount=0 and two empty arrays. A missing user produces a business error.
sharedAccounts: Shared Fund Accounts
| Field | Type | Description |
|---|---|---|
sharedAccountId | string | Stable platform shared fund account identifier, not a provider account ID. Treat it as opaque. |
balanceQuery | object | Shared fund balance query result. |
cardAccounts | array | Associated card accounts, each containing its own limits and products. |
Each shared fund balance appears once. Different tenants, users, and service providers have separate fund associations. One fund account may be associated with multiple card accounts and products.
cardAccounts: Associated Card Accounts
Located at sharedAccounts[].cardAccounts[], not at the top level.
| Field | Type | Description |
|---|---|---|
fpCardAccountId | string/null | Platform card account identifier; explicitly null if not identified. |
limitsQuery | object | This card account's limit query result. |
products | array | Held products and cards belonging to this card account. |
Unknown accounts retain separate groups per card; they are not merged because their identifiers are all null. Limits belong to the account. The overview does not expose the cardId used as query evidence. Shared fund and card account identifiers are not interchangeable.
products: Products Within a Card Account
Located at sharedAccounts[].cardAccounts[].products[].
| Field | Type | Description |
|---|---|---|
cardTypeId | string | Platform card product ID. |
displayName | string/null | Product display name. |
cardImageUrl | string/null | Product card image URL. |
cardCount | integer | Number of cards for this account and product, equal to cards.length. |
cards | array | All cards for this account and product. |
Cards from one product may belong to different card accounts, so the product can appear under different accounts. A card does not appear in multiple groups.
Card Details
Shared cards are located at sharedAccounts[].cardAccounts[].products[].cards[].
| Field | Type | Description |
|---|---|---|
cardId | string | Platform card ID used by existing details, locking, and other APIs. |
cardTypeId | string | Platform card product ID. |
cardName | string | Card display name. |
cardImageUrl | string/null | Card image URL. |
status | string/null | Platform card status; see Get Card Details. |
network | string/null | Card network, for example VISA. |
cardType | string/null | Card type, for example VIRTUAL. |
last4 | string/null | Last four digits only, never a full card number. |
Shared card details do not repeat the account references, balance, or limits; read their parent accounts.
individualCards: Individual-Balance Cards
Includes all card detail fields above, plus:
| Field | Type | Description |
|---|---|---|
balanceMode | string | Always INDIVIDUAL. |
fpCardAccountId | string/null | Associated platform card account identifier; null if not identified. |
balanceQuery | object | This card's balance query result. |
limitsQuery | object | Associated card account limit query result, including an explicit unsupported status. |
balanceQuery: Fund Balance Result
| Field | Type | Description |
|---|---|---|
status | string | SUCCESS or FAILED. |
balance | object/null | Single-currency balance on success; explicitly null on failure. |
balance.currency | string | Balance currency selected using the card product currency; no conversion. |
balance.available | string | Available balance. |
balance.ledger | string | Ledger balance. |
errorCode | string/null | null on success; otherwise an error code listed below. |
queriedAt | string | Query completion or failure time in ISO 8601 format. |
limitsQuery: Account Limit Result
Shared card accounts and individual-balance cards use the same result structure.
| Field | Type | Description |
|---|---|---|
status | string | SUCCESS, FAILED, or UNSUPPORTED. |
accountLimits | object/null | Limits defined below on success; null on failure or when unsupported. |
errorCode | string/null | null on success; otherwise an error code listed below. |
queriedAt | string/null | Query completion or failure time; null for UNSUPPORTED. |
| accountLimits field | Type | Description |
|---|---|---|
currency | string | Limit currency. |
accountType | string | asset-link, fixed-limit, program-limit, or prepaid. |
totalLimit | string/null | Total account limit; may be null for prepaid. |
usedLimit | string/null | Current net usage, not cumulative spending or a frozen amount; may be null for prepaid. |
availableLimit | string | Provider-returned available account limit; do not calculate it as total minus usage. |
Amounts have the same meaning as Get Card Account Limits, but the overview limit object does not repeat that standalone endpoint's cardId or fpCardAccountId.
All amounts are non-scientific decimal strings. Real zero "0" is valid; trailing zeros are not guaranteed. Unknown values must not be treated as zero. Fund balances and limits cannot be added or substituted. Do not derive frozen funds from a balance difference. Query times may differ, so this response is not an atomic snapshot.
Partial Failures and Error Codes
A failed balance or limit query retains the account, products, and cards. Failed amounts are never replaced with zero.
| errorCode | Result | Description |
|---|---|---|
BALANCE_QUERY_FAILED | balanceQuery | Balance query failed, or currency, data, or ownership could not be confirmed. |
BALANCE_ACCOUNT_MISSING | balanceQuery | The shared fund account ownership is missing. |
SHARED_ACCOUNT_CURRENCY_CONFLICT | balanceQuery | Products under the shared account have conflicting currencies, preventing a single-currency balance. |
ACCOUNT_LIMITS_QUERY_FAILED | limitsQuery | Limit query failed or account ownership could not be confirmed. |
CARD_ACCOUNT_MISSING | limitsQuery | Limits are supported, but the platform card account has not been identified. |
ACCOUNT_LIMITS_UNSUPPORTED | limitsQuery | Card account limits are unsupported; status is UNSUPPORTED. |
Invalid user identifiers or a missing user fail the overall request using the common error response.
Response Example
All values below are examples: one fund account links to two card accounts, with the same product held under each account, plus an individual card whose balance query failed.
{
"code": 200,
"msg": "操作成功",
"data": {
"memberId": "DEMO-MB-101",
"totalCardCount": 3,
"sharedAccounts": [
{
"sharedAccountId": "DEMO-SA-001",
"balanceQuery": {
"status": "SUCCESS",
"balance": {
"currency": "USD",
"available": "100",
"ledger": "120"
},
"errorCode": null,
"queriedAt": "2026-11-13T16:00:00+08:00"
},
"cardAccounts": [
{
"fpCardAccountId": "DEMO-CA-001",
"limitsQuery": {
"status": "SUCCESS",
"accountLimits": {
"currency": "USD",
"accountType": "asset-link",
"totalLimit": "100",
"usedLimit": "20",
"availableLimit": "80"
},
"errorCode": null,
"queriedAt": "2026-11-13T16:00:00+08:00"
},
"products": [
{
"cardTypeId": "DEMO-SHARED-VIRTUAL",
"displayName": "Shared virtual card",
"cardImageUrl": null,
"cardCount": 1,
"cards": [
{
"cardId": "DEMO-CARD-001",
"cardTypeId": "DEMO-SHARED-VIRTUAL",
"cardName": "Shared virtual card",
"cardImageUrl": null,
"status": "active",
"network": "VISA",
"cardType": "VIRTUAL",
"last4": "1001"
}
]
}
]
},
{
"fpCardAccountId": "DEMO-CA-002",
"limitsQuery": {
"status": "SUCCESS",
"accountLimits": {
"currency": "USD",
"accountType": "prepaid",
"totalLimit": null,
"usedLimit": null,
"availableLimit": "50"
},
"errorCode": null,
"queriedAt": "2026-11-13T16:00:00+08:00"
},
"products": [
{
"cardTypeId": "DEMO-SHARED-VIRTUAL",
"displayName": "Shared virtual card",
"cardImageUrl": null,
"cardCount": 1,
"cards": [
{
"cardId": "DEMO-CARD-002",
"cardTypeId": "DEMO-SHARED-VIRTUAL",
"cardName": "Shared virtual card",
"cardImageUrl": null,
"status": "active",
"network": "VISA",
"cardType": "VIRTUAL",
"last4": "1002"
}
]
}
]
}
]
}
],
"individualCards": [
{
"cardId": "DEMO-CARD-003",
"cardTypeId": "DEMO-INDIVIDUAL",
"cardName": "Individual balance card",
"cardImageUrl": null,
"status": "locked",
"network": "MASTERCARD",
"cardType": "VIRTUAL",
"last4": "2001",
"balanceMode": "INDIVIDUAL",
"fpCardAccountId": "DEMO-CA-003",
"balanceQuery": {
"status": "FAILED",
"balance": null,
"errorCode": "BALANCE_QUERY_FAILED",
"queriedAt": "2026-11-13T16:00:00+08:00"
},
"limitsQuery": {
"status": "UNSUPPORTED",
"accountLimits": null,
"errorCode": "ACCOUNT_LIMITS_UNSUPPORTED",
"queriedAt": null
}
}
]
}
}Structure Update and Display Rules
This overview revision replaces the former top-level sharedCardGroups and cardAccounts with the nested hierarchy. Integrations using the trial overview must update their paths. Existing card list, details, balance, and standalone limit APIs retain their contracts.
- Display shared cards by fund account, card account, and product without joining top-level collections.
- Show or count each shared balance once, not once per product, card account, or card.
- Product card counts are local to their card account; the user total counts all shared plus individual cards.
- Individual card limits still belong to the associated account; do not multiply limits by the number of cards sharing one
fpCardAccountId. - Show failure and unsupported states explicitly, never as a zero amount.
- Do not sum amounts across currencies. This endpoint does not modify cards or funds.
