> ## 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 Details
> Get full card details — masked number, expiry, brand, balance, status, and spending limits. GET /cards/{cardId}.
## Overview
Retrieve full card details including the card number, CVV, and expiration date. This endpoint returns sensitive PCI data that should be handled securely.
**Security Notice**: This endpoint returns full card details (card number, CVV). Never expose this data in client-side code, logs, or analytics.
## Path Parameters
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| `cardId` | string | The unique card identifier |
## Example Usage
```php PHP theme={null}
[
'method' => 'GET',
'header' => 'Authorization: Bearer ' . $accessToken
]
])
);
$result = json_decode($response, true);
$card = $result['data'];
echo "Card Number: " . $card['cardNumber'] . "\n";
echo "CVV: " . $card['cvv'] . "\n";
echo "Expiry: " . $card['expiryMonth'] . '/' . $card['expiryYear'] . "\n";
echo "Balance: $" . $card['balance']['available'] . "\n";
```
```javascript Node.js theme={null}
const cardId = 'crd_8f3a2b1c4d5e6f7890abcdef12345678';
const response = await fetch(`https://api.fyatu.com/api/v3/cards/${cardId}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${accessToken}`
}
});
const result = await response.json();
const card = result.data;
console.log('Card Number:', card.cardNumber);
console.log('CVV:', card.cvv);
console.log('Expiry:', `${card.expiryMonth}/${card.expiryYear}`);
console.log('Balance: $' + card.balance.available);
```
## Response Fields
| Field | Type | Description |
| -------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | string | Unique card identifier |
| `cardholderId` | string | The cardholder this card belongs to |
| `name` | string | Name printed on the card |
| `last4` | string | Last 4 digits of the card number |
| `maskedNumber` | string | Masked card number (e.g. `****4829`) |
| `cardNumber` | string | Full 16-digit card number (PCI sensitive) |
| `cvv` | string | 3-digit security code (PCI sensitive) |
| `expiryMonth` | string | Card expiration month (MM format) |
| `expiryYear` | string | Card expiration year (YYYY format) |
| `expiration` | string | Short expiration date (MM/YY format, e.g. `09/28`) |
| `brand` | string | Card brand: `MASTERCARD` or `VISA` |
| `status` | string | Card status: `ACTIVE`, `FROZEN`, `SUSPENDED`, `TERMINATED` |
| `suspendedReason` | string\|null | Reason for suspension, or `null` |
| `isReloadable` | boolean | Whether the card can be funded |
| `balance.available` | number | Available (spendable) balance in USD, net of any pending authorization holds |
| `balance.holding` | number | Total value of pending authorization holds (liens) currently on the card. Reserved but not yet settled — `balance.available` already excludes it |
| `pendingAuthorizations` | array | Individual pending authorization holds making up `balance.holding` (see below). Empty when there are no active holds |
| `pendingAuthorizations[].merchantName` | string\|null | Merchant that placed the hold |
| `pendingAuthorizations[].mcc` | string\|null | Merchant category code |
| `pendingAuthorizations[].amount` | number | Held amount in USD |
| `pendingAuthorizations[].currency` | string | Currency of the hold (always `USD`) |
| `pendingAuthorizations[].authorizedAt` | string\|null | When the authorization was placed (provider timestamp) |
| `needsReissue` | boolean | `true` when the provider flags the card for reissue (expired/compromised) and a replacement should be requested |
| `spendingLimit` | number | Spending limit amount in USD (0 if no limit) |
| `invoiceDebt` | number | Outstanding unpaid fee debt for this card in USD (already deducted from `balance.available`) |
| `declineCount` | integer | Number of declined transactions (insufficient funds) on this card |
| `billingAddress` | object | Card billing address |
| `createdAt` | string | Card creation timestamp (`YYYY-MM-DD HH:MM:SS`) |
| `suspendedAt` | string\|null | When the card was suspended, or `null` |
| `terminatedAt` | string\|null | When the card was terminated, or `null` |
**Decline Count**: The number of consecutive insufficient-funds declines before automatic suspension depends on the card product — it can be 3, 15, or unlimited depending on the product's configuration. Monitor `declineCount` and notify cardholders before reaching their product's limit.
## OpenAPI
````yaml v3/openapi.json GET /cards/{cardId}
openapi: 3.1.0
info:
title: FYATU API v3
description: >-
FYATU API v3 with JWT authentication for Collections, Payouts, and Card
Issuing.
version: 3.0.0
contact:
name: FYATU Support
url: https://fyatu.com
email: support@fyatu.com
servers:
- url: https://api.fyatu.com/api/v3
description: Production
security: []
tags:
- name: Authentication
description: JWT token management endpoints
- name: Account
description: Business account, wallet, and address management
- name: Collections
description: Accept payments from customers via checkout sessions
- name: Refunds
description: Issue refunds for completed collections
- name: Payouts
description: Send money to Fyatu account holders
- name: Cardholders
description: Cardholder management for card issuing programs
- name: Cards
description: Issue, fund, freeze, and manage virtual cards
- name: Webhooks
description: Webhook configuration and management
paths:
/cards/{cardId}:
get:
tags:
- Cards
summary: Get Card Details
description: >-
Retrieve full card details including the card number, CVV, and
expiration date. Handle this data securely and never expose it in
client-side code.
operationId: getCard
parameters:
- name: cardId
in: path
required: true
description: Card ID
schema:
type: string
responses:
'200':
description: Card details retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/CardDetailResponse'
example:
success: true
status: 200
message: Card retrieved successfully
data:
id: crd_8f3a2b1c4d5e6f7890abcdef12345678
cardholderId: ch_1a2b3c4d5e6f7890abcdef1234567890
name: JAMES WILSON
last4: '4829'
maskedNumber: '****4829'
cardNumber: '5412750000004829'
cvv: '847'
expiryMonth: '09'
expiryYear: '2028'
expiration: 09/28
brand: MASTERCARD
status: ACTIVE
suspendedReason: null
isReloadable: true
balance:
available: 245.5
holding: 3
pendingAuthorizations:
- merchantName: LOTUS'S 5121 CHALONG
mcc: '5411'
amount: 3
currency: USD
authorizedAt: '2026-07-08 14:32:10'
needsReissue: false
spendingLimit: 5000
invoiceDebt: 0
declineCount: 0
billingAddress:
line1: 123 Example Street
city: Springfield
state: Illinois
country: US
zipCode: '62701'
createdAt: '2026-01-10 14:30:00'
suspendedAt: null
terminatedAt: null
meta:
requestId: req_a1b2c3d4e5f6
timestamp: '2026-01-17T10:00:00+00:00'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
security:
- BearerAuth: []
components:
schemas:
CardDetailResponse:
type: object
properties:
success:
type: boolean
example: true
status:
type: integer
example: 200
message:
type: string
data:
$ref: '#/components/schemas/CardDetail'
meta:
$ref: '#/components/schemas/Meta'
CardDetail:
type: object
properties:
id:
type: string
description: Unique card identifier
cardholderId:
type: string
description: The cardholder this card belongs to
name:
type: string
description: Name printed on the card
last4:
type: string
description: Last 4 digits of the card number
maskedNumber:
type: string
description: Masked card number (e.g. ****4829)
cardNumber:
type: string
description: Full 16-digit card number (PCI sensitive)
cvv:
type: string
description: 3-digit security code (PCI sensitive)
expiryMonth:
type: string
description: Expiry month (MM)
expiryYear:
type: string
description: Expiry year (YYYY)
expiration:
type: string
description: Short expiration date (MM/YY, e.g. 09/28)
brand:
type: string
enum:
- MASTERCARD
- VISA
description: Card network brand
status:
type: string
enum:
- ACTIVE
- FROZEN
- SUSPENDED
- TERMINATED
description: Current card status
suspendedReason:
type: string
nullable: true
description: Reason for suspension, or null
isReloadable:
type: boolean
description: Whether the card can be funded
balance:
$ref: '#/components/schemas/CardBalance'
pendingAuthorizations:
type: array
description: >-
Individual pending authorization holds making up balance.holding.
Empty when there are no active holds.
items:
type: object
properties:
merchantName:
type: string
nullable: true
description: Merchant that placed the hold
mcc:
type: string
nullable: true
description: Merchant category code
amount:
type: number
description: Held amount in USD
currency:
type: string
description: Currency of the hold (always USD)
authorizedAt:
type: string
nullable: true
description: When the authorization was placed (provider timestamp)
needsReissue:
type: boolean
description: >-
True when the provider flags the card for reissue
(expired/compromised) and a replacement should be requested
spendingLimit:
type: number
description: Spending limit amount in USD (0 if no limit)
invoiceDebt:
type: number
description: >-
Outstanding unpaid fee debt for this card in USD (already deducted
from balance.available)
declineCount:
type: integer
description: Number of declined transactions (insufficient funds) on this card
billingAddress:
$ref: '#/components/schemas/BillingAddress'
createdAt:
type: string
description: Card creation timestamp (YYYY-MM-DD HH:MM:SS)
suspendedAt:
type: string
nullable: true
description: When the card was suspended, or null
terminatedAt:
type: string
nullable: true
description: When the card was terminated, or null
Meta:
type: object
properties:
requestId:
type: string
description: Unique request ID for tracking
example: req_abc123def456
timestamp:
type: string
format: date-time
description: ISO 8601 timestamp of the response
ErrorResponse:
type: object
properties:
success:
type: boolean
example: false
status:
type: integer
example: 401
message:
type: string
example: Invalid credentials
error:
$ref: '#/components/schemas/Error'
meta:
$ref: '#/components/schemas/Meta'
CardBalance:
type: object
properties:
available:
type: number
description: >-
Available (spendable) balance, net of any pending authorization
holds
holding:
type: number
description: >-
Total value of pending authorization holds (liens) currently on the
card. Reserved but not yet settled — available already excludes it.
BillingAddress:
type: object
properties:
line1:
type: string
city:
type: string
state:
type: string
zipCode:
type: string
country:
type: string
Error:
type: object
properties:
code:
type: string
description: Error code for programmatic handling
example: AUTH_INVALID_CREDENTIALS
details:
type: array
items:
$ref: '#/components/schemas/ValidationError'
description: Validation error details (for VALIDATION_ERROR)
ValidationError:
type: object
properties:
field:
type: string
description: Field that failed validation
example: appId
message:
type: string
description: Validation error message
example: AppId is required
responses:
Unauthorized:
description: Authentication required or token invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
status: 401
message: Unable to identify business
error:
code: AUTH_TOKEN_INVALID
meta:
requestId: req_abc123
timestamp: '2026-01-05T10:30:00+00:00'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
status: 404
message: Wallet not found
error:
code: RESOURCE_NOT_FOUND
meta:
requestId: req_abc123
timestamp: '2026-01-05T10:30:00+00:00'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT access token obtained from /auth/token
````