> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Card
> Retrieve full details for a single card by ID. GET /cards/{id}. Requires cards:read scope.
## Overview
Returns the full details of a single card including live balance, full PAN, CVV, masked card number, expiry, and capability flags. Provider-internal fields are never returned.
## Path Parameters
| Parameter | Type | Description |
| --------- | ------ | --------------------------- |
| `id` | string | The card ID (prefix `crd_`) |
## Example
```bash cURL theme={null}
curl https://api.fyatu.com/api/v3.20/cards/crd_01HXYZ5555ABCDEF1111 \
-H "Authorization: Bearer $FYATU_API_KEY"
```
```javascript Node.js theme={null}
const resp = await fetch(
'https://api.fyatu.com/api/v3.20/cards/crd_01HXYZ5555ABCDEF1111',
{ headers: { 'Authorization': `Bearer ${process.env.FYATU_API_KEY}` } }
);
const body = await resp.json();
const card = body.data;
console.log('Status:', card.status);
console.log('Balance:', card.balance, card.currency);
console.log('CVV:', card.cvv);
console.log('Expiry:', card.expirationDate);
```
```python Python theme={null}
import os, requests
resp = requests.get(
'https://api.fyatu.com/api/v3.20/cards/crd_01HXYZ5555ABCDEF1111',
headers={'Authorization': f'Bearer {os.environ["FYATU_API_KEY"]}'}
)
card = resp.json()['data']
print(card['status'], card['balance'], card['cvv'])
```
## Success Response (200)
```json theme={null}
{
"success": true,
"status": 200,
"message": "Card retrieved",
"data": {
"id": "crd_01HXYZ5555ABCDEF1111",
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"productId": "prd_01HXYZ1111ABCDEF0001",
"status": "ACTIVE",
"cardType": "VIRTUAL",
"cardBrand": "VISA",
"maskedPan": "445123******4123",
"last4": "4123",
"pan": "4451230000004123",
"expirationDate": "06/2030",
"balance": 100.00,
"heldAmount": 53.88,
"pendingAuthorizations": [
{
"merchantName": "LOTUS'S 5121 CHALONG",
"mcc": "5411",
"amount": 43.30,
"currency": "USD",
"authorizedAt": "2026-07-08 14:32:10"
},
{
"merchantName": "NIRANAPA BOUTIQUE RESO",
"mcc": "7011",
"amount": 9.52,
"currency": "USD",
"authorizedAt": "2026-07-08 09:15:44"
}
],
"needsReissue": false,
"currency": "USD",
"cvv": "123",
"features": {
"has3DS": true,
"hasApplePay": false,
"hasGooglePay": false,
"hasJIT": false,
"hasSpendControl": true,
"hasMccControl": false,
"isReloadable": true,
"isOneTimeUse": false
},
"spendingLimit": 1000.00,
"spendingPeriod": "DAILY",
"billingAddress": {
"address": "1234 Main St",
"city": "New York",
"state": "NY",
"zipCode": "10001",
"country": "US"
},
"createdAt": "2026-05-26T10:00:00Z",
"updatedAt": "2026-05-26T10:00:00Z"
},
"meta": {
"requestId": "req_01HXY123456ABCDEF",
"platform": "Fyatu CaaS",
"timestamp": "2026-05-26T10:00:00Z"
}
}
```
## Response Fields
| Field | Type | Description |
| -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Card identifier (prefix `crd_`) |
| `cardholderId` | string | The cardholder this card belongs to |
| `productId` | string | The product the card was issued under |
| `status` | string | `CREATING` (provisioning), `ACTIVE`, `FROZEN`, or `TERMINATED` |
| `cardType` | string | `VIRTUAL` or `PHYSICAL` |
| `cardBrand` | string | `VISA` or `MASTERCARD` |
| `maskedPan` | string | BIN-masked PAN — first 6 digits + 6 stars + last 4 (e.g. `445123******4123`) |
| `last4` | string | Last 4 digits of the PAN |
| `pan` | string | Full unmasked card number — only present when the card is provisioned at the provider |
| `expirationDate` | string | Card expiry in `MM/YYYY` format (e.g. `06/2030`) |
| `balance` | number | Available (spendable) card balance in USD fetched from the card provider, net of any pending authorization holds |
| `heldAmount` | number | Total value of pending authorization holds (liens) currently on the card. Reserved but not yet settled — `balance` already excludes it |
| `pendingAuthorizations` | array | Individual pending authorization holds making up `heldAmount` (see below). Omitted when there are no active holds |
| `pendingAuthorizations[].merchantName` | string | Merchant that placed the hold |
| `pendingAuthorizations[].mcc` | string | Merchant category code |
| `pendingAuthorizations[].amount` | number | Held amount in USD |
| `pendingAuthorizations[].currency` | string | Currency of the hold (always `USD`) |
| `pendingAuthorizations[].authorizedAt` | string | When the authorization was placed — UTC `YYYY-MM-DD HH:MM:SS` |
| `needsReissue` | boolean | `true` when the provider flags the card for reissue (expired/compromised) and a replacement should be requested |
| `currency` | string | Card currency (always `USD`) |
| `cvv` | string | Card verification value |
| `features` | object | Card capability flags inherited from the product |
| `features.has3DS` | boolean | 3D Secure enabled |
| `features.hasApplePay` | boolean | Apple Pay tokenisation supported |
| `features.hasGooglePay` | boolean | Google Pay tokenisation supported |
| `features.hasJIT` | boolean | Just-In-Time funding enabled |
| `features.hasSpendControl` | boolean | Spend limit control active |
| `features.hasMccControl` | boolean | MCC (merchant category) control active |
| `features.isReloadable` | boolean | Card can be topped up via `POST /cards/{id}/fund` |
| `features.isOneTimeUse` | boolean | Card terminates automatically after its first settled transaction |
| `spendingLimit` | number | Spend cap per `spendingPeriod` in USD |
| `spendingPeriod` | string | Period over which the spend cap applies — `DAILY`, `WEEKLY`, `MONTHLY`, etc. |
| `billingAddress` | object | Billing address registered with the card provider |
| `billingAddress.address` | string | Street address |
| `billingAddress.city` | string | City |
| `billingAddress.state` | string | State or region |
| `billingAddress.zipCode` | string | Postal code |
| `billingAddress.country` | string | Two-letter ISO 3166-1 country code |
| `createdAt` | string | ISO 8601 creation timestamp |
| `updatedAt` | string | ISO 8601 last-update timestamp |
## Conditional Fields
| Field | Present when |
| ----------------------- | ------------------------------------------------------------------ |
| `balance` | Card has been provisioned at the provider |
| `heldAmount` | Card has been provisioned at the provider (0 when no active holds) |
| `pendingAuthorizations` | Card has one or more active authorization holds |
| `needsReissue` | Card has been provisioned at the provider |
| `cvv` | Card has been provisioned at the provider |
| `pan` | Card has been provisioned at the provider |
| `frozenAt` | `status` is `FROZEN` |
| `terminatedAt` | `status` is `TERMINATED` |
## Error Codes
| Code | HTTP | Cause |
| -------------------- | ---- | -------------------------------------------------------------- |
| `CARD_NOT_FOUND` | 404 | Card does not exist or belongs to another business/environment |
| `INSUFFICIENT_SCOPE` | 403 | Key lacks `cards:read` scope |
| `INTERNAL_ERROR` | 500 | Server error |
## OpenAPI
````yaml v3.20/openapi.json GET /cards/{id}
openapi: 3.1.0
info:
title: FYATU CaaS API v3.20
description: >-
FYATU Cards-as-a-Service API — API key authentication, Cardholder
lifecycle, Card issuance, Transactions, Webhooks, and Programs.
version: 3.20.0
contact:
name: FYATU Support
url: https://fyatu.com
email: support@fyatu.com
servers:
- url: https://api.fyatu.com/api/v3.20
description: >-
FYATU CaaS API — the environment (LIVE or SANDBOX) is determined by the
API key, not the URL
security:
- BearerAuth: []
tags:
- name: Meta
description: Liveness, account info, and supported event types
- name: Account
description: Account-level balance and funding status
- name: Programs
description: Read card program configuration
- name: Cardholders
description: Create and manage cardholder profiles
- name: Cards
description: Issue, fund, freeze, and terminate virtual cards
- name: Transactions
description: Read-only card transaction history
- name: Webhooks
description: Manage webhook endpoints for real-time event delivery
- name: Products
description: Read card product configurations
paths:
/cards/{id}:
parameters:
- name: id
in: path
required: true
schema:
type: string
example: crd_01HXYZ5555ABCDEF1111
get:
tags:
- Cards
summary: Get a card
description: >-
Retrieve full details for a single card including live balance, CVV,
features, and billing address.
operationId: getCard
responses:
'200':
description: Card retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/CardResponse'
example:
success: true
status: 200
message: Card retrieved
data:
id: crd_01HXYZ5555ABCDEF1111
cardholderId: chl_01HXYZ1234ABCDEF5678
productId: prd_01HXYZ1111ABCDEF0001
status: ACTIVE
cardType: VIRTUAL
cardBrand: VISA
maskedPan: 445123******4123
last4: '4123'
expirationDate: 06/2030
balance: 100
heldAmount: 53.88
pendingAuthorizations:
- merchantName: LOTUS'S 5121 CHALONG
mcc: '5411'
amount: 43.3
currency: USD
authorizedAt: '2026-07-08 14:32:10'
- merchantName: NIRANAPA BOUTIQUE RESO
mcc: '7011'
amount: 9.52
currency: USD
authorizedAt: '2026-07-08 09:15:44'
needsReissue: false
currency: USD
cvv: '123'
features:
has3DS: true
hasApplePay: false
hasGooglePay: false
hasJIT: false
hasSpendControl: true
hasMccControl: false
isReloadable: true
isOneTimeUse: false
spendingLimit: 1000
spendingPeriod: DAILY
billingAddress:
address: 1234 Main St
city: New York
state: NY
zipCode: '10001'
country: US
createdAt: '2026-05-26T10:00:00Z'
updatedAt: '2026-05-26T10:00:00Z'
meta:
requestId: req_01HXY123456ABCDEF
platform: Fyatu CaaS
timestamp: '2026-05-26T10:00:00Z'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimitExceeded'
'500':
$ref: '#/components/responses/InternalError'
components:
schemas:
CardResponse:
type: object
properties:
success:
type: boolean
example: true
status:
type: integer
example: 200
message:
type: string
example: Card retrieved
data:
$ref: '#/components/schemas/CardDetail'
meta:
$ref: '#/components/schemas/Meta'
example:
success: true
status: 200
message: Card retrieved
data:
id: crd_01HXYZ5555ABCDEF1111
cardholderId: chl_01HXYZ1234ABCDEF5678
productId: prd_01HXYZ1111ABCDEF0001
status: ACTIVE
cardType: VIRTUAL
cardBrand: VISA
maskedPan: 445123******4123
last4: '4123'
expirationDate: 06/2030
balance: 100
heldAmount: 53.88
pendingAuthorizations:
- merchantName: LOTUS'S 5121 CHALONG
mcc: '5411'
amount: 43.3
currency: USD
authorizedAt: '2026-07-08 14:32:10'
- merchantName: NIRANAPA BOUTIQUE RESO
mcc: '7011'
amount: 9.52
currency: USD
authorizedAt: '2026-07-08 09:15:44'
needsReissue: false
currency: USD
cvv: '123'
features:
has3DS: true
hasApplePay: false
hasGooglePay: false
hasJIT: false
hasSpendControl: true
hasMccControl: false
isReloadable: true
isOneTimeUse: false
spendingLimit: 1000
spendingPeriod: DAILY
billingAddress:
address: 1234 Main St
city: New York
state: NY
zipCode: '10001'
country: US
createdAt: '2026-05-26T10:00:00Z'
updatedAt: '2026-05-26T10:00:00Z'
meta:
requestId: req_01HXY123456ABCDEF
platform: Fyatu CaaS
timestamp: '2026-05-26T10:00:00Z'
CardDetail:
type: object
description: >-
Full card object returned by GET /cards/{id}. Includes live balance,
full PAN, CVV, features, and billing address.
properties:
id:
type: string
example: crd_01HXYZ5555ABCDEF1111
cardholderId:
type: string
example: chl_01HXYZ1234ABCDEF5678
productId:
type: string
nullable: true
example: prd_01HXYZ1111ABCDEF0001
status:
type: string
enum:
- CREATING
- ACTIVE
- FROZEN
- TERMINATED
example: ACTIVE
cardType:
type: string
enum:
- VIRTUAL
- PHYSICAL
example: VIRTUAL
cardBrand:
type: string
enum:
- VISA
- MASTERCARD
example: VISA
maskedPan:
type: string
nullable: true
description: Populated after provisioning completes
example: 445123******4123
last4:
type: string
nullable: true
description: Populated after provisioning completes
example: '4123'
pan:
type: string
nullable: true
description: >-
Full unmasked card number — only present when the card is
provisioned at the provider
example: '4451230000004123'
expirationDate:
type: string
nullable: true
description: Card expiry in MM/YYYY format
example: 06/2030
balance:
type: number
format: float
nullable: true
description: >-
Available (spendable) card balance in USD fetched from the card
provider, net of any pending authorization holds
example: 100
heldAmount:
type: number
format: float
nullable: true
description: >-
Total value of pending authorization holds (liens) currently placed
on the card. Funds are reserved but not yet settled. Available
balance already excludes this amount.
example: 53.88
pendingAuthorizations:
type: array
nullable: true
description: >-
Individual pending authorization holds making up heldAmount. Each
entry is a merchant authorization awaiting settlement or reversal.
items:
type: object
properties:
merchantName:
type: string
nullable: true
description: Merchant that placed the hold
example: LOTUS'S 5121 CHALONG
mcc:
type: string
nullable: true
description: Merchant category code
example: '5411'
amount:
type: number
format: float
description: Held amount in USD
example: 43.3
currency:
type: string
description: Currency of the hold
example: USD
authorizedAt:
type: string
description: When the authorization was placed (UTC, YYYY-MM-DD HH:MM:SS)
example: '2026-07-08 14:32:10'
needsReissue:
type: boolean
nullable: true
description: >-
True when the provider flags the card for reissue (e.g. expired or
compromised) and a replacement should be requested
example: false
currency:
type: string
example: USD
cvv:
type: string
nullable: true
description: Card verification value
example: '123'
features:
type: object
nullable: true
properties:
has3DS:
type: boolean
example: true
hasApplePay:
type: boolean
example: false
hasGooglePay:
type: boolean
example: false
hasJIT:
type: boolean
example: false
hasSpendControl:
type: boolean
example: true
hasMccControl:
type: boolean
example: false
isReloadable:
type: boolean
example: true
isOneTimeUse:
type: boolean
example: false
spendingLimit:
type: number
format: float
nullable: true
example: 1000
spendingPeriod:
type: string
nullable: true
example: DAILY
billingAddress:
type: object
nullable: true
properties:
address:
type: string
example: 1234 Main St
city:
type: string
example: New York
state:
type: string
example: NY
zipCode:
type: string
example: '10001'
country:
type: string
example: US
createdAt:
type: string
format: date-time
example: '2026-05-26T10:00:00Z'
updatedAt:
type: string
format: date-time
example: '2026-05-26T10:00:00Z'
frozenAt:
type: string
format: date-time
nullable: true
description: Present when status is FROZEN
example: null
terminatedAt:
type: string
format: date-time
nullable: true
description: Present when status is TERMINATED
example: null
Meta:
type: object
properties:
requestId:
type: string
example: req_a1b2c3d4e5f6a7b8c9d0e1f2
platform:
type: string
example: Fyatu CaaS
timestamp:
type: string
format: date-time
example: '2026-05-22T15:00:00Z'
Error:
type: object
properties:
success:
type: boolean
example: false
status:
type: integer
example: 422
message:
type: string
example: Human readable message
error:
$ref: '#/components/schemas/ErrorBody'
meta:
$ref: '#/components/schemas/Meta'
ErrorBody:
type: object
properties:
code:
type: string
example: VALIDATION_ERROR
detail:
type: string
example: dateOfBirth must be in YYYY-MM-DD format
responses:
Unauthorized:
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missing:
summary: API key missing
value:
success: false
status: 401
message: API key is required
error:
code: AUTH_TOKEN_MISSING
detail: API key is required
meta:
requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
platform: Fyatu CaaS
timestamp: '2026-05-22T15:00:00Z'
invalid:
summary: API key invalid
value:
success: false
status: 401
message: Invalid API key
error:
code: AUTH_TOKEN_INVALID
detail: Invalid API key
meta:
requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
platform: Fyatu CaaS
timestamp: '2026-05-22T15:00:00Z'
Forbidden:
description: Scope denied or business suspended
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
success: false
status: 403
message: Scope denied
error:
code: INSUFFICIENT_SCOPE
detail: This endpoint requires the cards:write scope
meta:
requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
platform: Fyatu CaaS
timestamp: '2026-05-22T15:00:00Z'
NotFound:
description: Resource not found or does not belong to your business
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimitExceeded:
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
success: false
status: 429
message: Rate limit exceeded
error:
code: RATE_LIMIT_EXCEEDED
detail: Too many requests
meta:
requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
platform: Fyatu CaaS
timestamp: '2026-05-22T15:00:00Z'
InternalError:
description: Unexpected server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
success: false
status: 500
message: Internal error
error:
code: INTERNAL_ERROR
detail: An unexpected error occurred
meta:
requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
platform: Fyatu CaaS
timestamp: '2026-05-22T15:00:00Z'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
API key from the FYATU CaaS portal. Pass as `Authorization: Bearer
`.
````