Card types

The card-type catalog lists the card products your account can see: name, network, fees, load limits, what the product requires from you, and whether you can apply right now. Always read the catalog before issuing a card. Do not hardcode product IDs, fees or limits; they can change.

List card types

GET/api/v2/card-typesBearer agent-vc

bash

curl https://agentcard.fluxapay.xyz/api/v2/card-types \
  -H "Authorization: Bearer $AGENT_VC"

CLI:

bash

fluxa-wallet card types

Response 200:

json

{
  "cardTypes": [
    {
      "cardTypeId": "ct_63243cc4f38836aef2c62ca4",
      "name": "FluxA Visa Prepaid Card",
      "description": "A USD-denominated Visa prepaid card. …",
      "imageUrl": "https://…/card.png",
      "badge": null,
      "sortOrder": 0,
      "network": "Visa",
      "region": null,
      "bins": [{ "binId": "bin_9c1e0b7f4d2a6e38c5b1a0f2", "bin": "123456" }],
      "features": {
        "applePay": "unknown",
        "googlePay": "unknown",
        "chatGPT": "unknown",
        "claude": "unknown",
        "cashback": { "status": "unknown" },
        "highlights": []
      },
      "fees": {
        "issuance": { "status": "charged", "amountUsd": "1.00" },
        "fx": { "status": "charged", "basisPoints": 300 },
        "annual": { "status": "free" },
        "monthly": { "status": "unknown" }
      },
      "promotions": {},
      "limits": { "minInitialLoadUsd": "5.00", "maxInitialLoadUsd": null },
      "availability": { "canApply": true, "reason": null },
      "requirements": { "cardholder": true, "kyc": true, "vipWhitelist": false },
      "version": 1
    }
  ]
}

The values above are illustrative.

Fields

Field	Type	Description
`cardTypeId`	string	Opaque product ID. Pass it to `POST /cards/initiate`.
`name`, `description`	string	Customer-facing product name and description.
`imageUrl`, `badge`	string \| null	Optional display assets.
`sortOrder`	number	Suggested display order (ascending). The list is already sorted.
`network`	string \| null	Card network, e.g. `Visa` or `Mastercard`.
`region`	string \| null	Region the product is intended for, when set.
`bins`	array	`{ binId, bin }` pairs. `binId` is opaque; `bin` is the leading digits of card numbers for this product (may be `null`).
`features`	object	Capability flags (`applePay`, `googlePay`, `chatGPT`, `claude`) and `cashback`, plus free-text `highlights`. A value of `"unknown"` means not confirmed; do not present it as supported.
`fees`	object	Fee schedule; see below.
`promotions`	object	Promotional information for display. It does not change what is charged.
`limits.minInitialLoadUsd` / `maxInitialLoadUsd`	string \| null	Initial-load range for this product. `null` means no product-specific bound (account limits still apply).
`availability.canApply`	boolean	Whether your account can apply for this product now.
`availability.reason`	string \| null	Why not, when `canApply` is `false`. See below.
`requirements`	object	What the product needs from you before issuance. See below.
`version`	number	Product version.

Fees

fees contains entries for issuance, usdTransaction, fx, annual, monthly, transaction, refund, crossBorder and smallTransaction. Each entry has a status:

`status`	Meaning
`free`	No fee.
`charged`	A fee applies: a flat `amountUsd`, a percentage in `basisPoints` (`300` = 3%), or both.
`not_applicable`	The fee does not apply to this product.
`unknown`	Not published. Do not show it as zero.

fees.issuance.amountUsd is exactly the issuance fee you will be charged. Recharge and withdrawal fees are returned as feeUsd by the recharge and withdraw endpoints before you pay or confirm.

Requirements

Field	When `true`
`cardholder`	The account needs a cardholder profile before issuance.
`kyc`	The account owner must complete identity verification.
`vipWhitelist`	The product needs separate approval. The user applies in FluxA Wallet (Agent Cards page); there is no API to apply.

When cardholder and kyc are both false, do not ask the user for personal details or identity verification.

Availability reasons

`reason`	Meaning	What to do
`card_type_unavailable`	The product is not open for applications right now.	Choose another product or try later.
`vip_whitelist_required`	The product needs approval the account does not have yet.	Ask the user to apply in FluxA Wallet, then retry.
`card_access_unavailable`	Eligibility could not be checked right now.	Retry later. This is not a rejection.

Selecting a product when issuing

POST /cards/initiate takes exactly one selector:

Selector	Example	Notes
`cardTypeId`	`"ct_63243cc4f38836aef2c62ca4"`	Recommended.
`binId`	`"bin_9c1e0b7f4d2a6e38c5b1a0f2"`	A `binId` from the catalog.
`bin`	`"123456"`	6–10 digits. Must match exactly one product, otherwise `409 card_type_ambiguous`.

There is no default product. See Errors for selector errors.

Card types ​

List card types ​

Fields ​

Fees ​

Requirements ​

Availability reasons ​

Selecting a product when issuing ​