Skip to content

Get User Card Overview ​

GET /openapi/v2/cards/overview

Returns 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 ​

FieldTypeRequiredDescription
memberIdstringConditionalPlatform member ID, maximum 64 characters. Supply exactly one of memberId and email.
emailstringConditionalUser email in the current tenant, maximum 128 characters. Supply exactly one of memberId and email.

Pagination and status-filter parameters are not provided.

http
GET /openapi/v2/cards/overview?memberId=DEMO-MB-101
GET /openapi/v2/cards/overview?email=user@example.com

Response data ​

FieldTypeDescription
memberIdstringPlatform member ID.
totalCardCountintegerTotal number of shared and individual cards, counting each card once.
sharedAccountsarrayShared fund accounts containing a balance and nested card accounts, products, and cards.
individualCardsarrayIndividual-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 ​

FieldTypeDescription
sharedAccountIdstringStable platform shared fund account identifier, not a provider account ID. Treat it as opaque.
balanceQueryobjectShared fund balance query result.
cardAccountsarrayAssociated 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.

FieldTypeDescription
fpCardAccountIdstring/nullPlatform card account identifier; explicitly null if not identified.
limitsQueryobjectThis card account's limit query result.
productsarrayHeld 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[].

FieldTypeDescription
cardTypeIdstringPlatform card product ID.
displayNamestring/nullProduct display name.
cardImageUrlstring/nullProduct card image URL.
cardCountintegerNumber of cards for this account and product, equal to cards.length.
cardsarrayAll 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[].

FieldTypeDescription
cardIdstringPlatform card ID used by existing details, locking, and other APIs.
cardTypeIdstringPlatform card product ID.
cardNamestringCard display name.
cardImageUrlstring/nullCard image URL.
statusstring/nullPlatform card status; see Get Card Details.
networkstring/nullCard network, for example VISA.
cardTypestring/nullCard type, for example VIRTUAL.
last4string/nullLast 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:

FieldTypeDescription
balanceModestringAlways INDIVIDUAL.
fpCardAccountIdstring/nullAssociated platform card account identifier; null if not identified.
balanceQueryobjectThis card's balance query result.
limitsQueryobjectAssociated card account limit query result, including an explicit unsupported status.

balanceQuery: Fund Balance Result ​

FieldTypeDescription
statusstringSUCCESS or FAILED.
balanceobject/nullSingle-currency balance on success; explicitly null on failure.
balance.currencystringBalance currency selected using the card product currency; no conversion.
balance.availablestringAvailable balance.
balance.ledgerstringLedger balance.
errorCodestring/nullnull on success; otherwise an error code listed below.
queriedAtstringQuery completion or failure time in ISO 8601 format.

limitsQuery: Account Limit Result ​

Shared card accounts and individual-balance cards use the same result structure.

FieldTypeDescription
statusstringSUCCESS, FAILED, or UNSUPPORTED.
accountLimitsobject/nullLimits defined below on success; null on failure or when unsupported.
errorCodestring/nullnull on success; otherwise an error code listed below.
queriedAtstring/nullQuery completion or failure time; null for UNSUPPORTED.
accountLimits fieldTypeDescription
currencystringLimit currency.
accountTypestringasset-link, fixed-limit, program-limit, or prepaid.
totalLimitstring/nullTotal account limit; may be null for prepaid.
usedLimitstring/nullCurrent net usage, not cumulative spending or a frozen amount; may be null for prepaid.
availableLimitstringProvider-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.

errorCodeResultDescription
BALANCE_QUERY_FAILEDbalanceQueryBalance query failed, or currency, data, or ownership could not be confirmed.
BALANCE_ACCOUNT_MISSINGbalanceQueryThe shared fund account ownership is missing.
SHARED_ACCOUNT_CURRENCY_CONFLICTbalanceQueryProducts under the shared account have conflicting currencies, preventing a single-currency balance.
ACCOUNT_LIMITS_QUERY_FAILEDlimitsQueryLimit query failed or account ownership could not be confirmed.
CARD_ACCOUNT_MISSINGlimitsQueryLimits are supported, but the platform card account has not been identified.
ACCOUNT_LIMITS_UNSUPPORTEDlimitsQueryCard 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.

json
{
  "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.