Cards Overview

FYATU’s Card Issuing API enables you to issue branded payment cards to your verified cardholders. Cards can be used for online payments, subscriptions, in-store purchases, and ATM withdrawals (physical cards).

Card Concept

A card represents a set of identifiers used for purchases: the PAN (16-digit “long number”), expiry date, CVV (3-digit verification code), and for physical cards, cryptographic data stored on the chip. When a card is deactivated (lost, expired, or terminated) and a replacement is issued, it creates a completely new card with a new ID, different CVV, and potentially different expiry date. Over time, multiple cards may accumulate under a cardholder account, some of which are no longer active. Cards are bound to a spending limit and period determined by the card product selected. Use the List Products endpoint to discover available products with their limits, currencies, tokenization support, and features.

Card Types

Virtual Cards

Digital cards for online transactions. Issued instantly and active by default. Available in both standard and tokenized variants.

Feature	Standard	Tokenized
Issuance	Instant	Instant
Initial Status	Active (ready to use)	Active (ready to use)
Use Cases	Online shopping, subscriptions, digital services	Online + Apple Pay, Google Pay
Card Networks	Mastercard, Visa	Visa
Apple Pay / Google Pay	No	Yes
3D Secure	Yes	Yes

Standard vs Tokenized: Standard cards work for all online transactions. Tokenized cards additionally support provisioning to digital wallets (Apple Pay, Google Pay) for contactless in-store payments. Use the List Products endpoint to see which products are tokenized (isTokenized: true).

Physical Cards (Coming Soon)

Plastic or metal cards shipped to the cardholder’s address. Physical cards are inactive by default and require activation.

Feature	Plastic	Metal
Material	PVC plastic	Stainless steel
Delivery	7-14 business days	7-14 business days
Initial Status	Inactive (requires activation)
Use Cases	In-store, ATM, online	Premium experience
Contactless	Yes	Yes
Can be tokenized	Yes	Yes

Crypto Cards (Coming Soon)

Cards funded directly from cryptocurrency balances with automatic conversion.

Card Lifecycle

Card Statuses

Status	Description	Can Transact	Can Fund	Can Unfreeze
`INACTIVE`	Card issued but not yet activated. Applies to physical cards only.	No	No	N/A
`ACTIVE`	Card is currently usable for all transactions.	Yes	Yes	N/A
`FROZEN`	Temporarily frozen by cardholder or business. Transactions rejected but card can be unfrozen.	No	Yes	Yes
`SUSPENDED`	Suspended by system due to fraud detection, compliance issues, or excessive declined transactions.	No	Yes*	Contact support
`TERMINATED`	Permanently closed. Covers: Cancelled, Lost, Stolen, Expired, or Deleted cards. Cannot be reactivated.	No	No	No

SUSPENDED vs FROZEN: A FROZEN card is temporarily disabled by the cardholder/business and can be unfrozen via API. A SUSPENDED card is disabled by the system (fraud, compliance, or 15+ insufficient funds declines) and requires support intervention or funding (for decline suspensions) to resolve.

Status Transitions

User Action	Previous Status	New Status
Create physical card	—	`INACTIVE`
Create virtual card (standard or tokenized)	—	`ACTIVE`
Activate with code	`INACTIVE`	`ACTIVE`
Freeze	`ACTIVE`	`FROZEN`
Unfreeze	`FROZEN`	`ACTIVE`
System detects fraud	`ACTIVE`/`FROZEN`	`SUSPENDED`
15 insufficient funds declines	`ACTIVE`	`SUSPENDED`
Fund card (resets decline count)	`SUSPENDED` (decline)	`ACTIVE`
Support resolves issue	`SUSPENDED`	`ACTIVE`
Revoke / Delete	`ACTIVE`/`FROZEN`/`SUSPENDED`	`TERMINATED`
Report lost	`ACTIVE`/`FROZEN`	`TERMINATED`
Report stolen	`ACTIVE`/`FROZEN`	`TERMINATED`
Card expires	Any non-terminated	`TERMINATED`

Decline Count & Auto-Suspension

Cards track the number of declined transactions due to insufficient funds:

Decline limit: 15 consecutive insufficient funds declines
Auto-suspension: Card is automatically suspended after reaching the limit
Reset: Funding the card resets the decline count and reactivates the card (if not at limit)
Prevention: Monitor declineCount in card details to warn users before suspension

Fee Structure

Fees are configured per business and can be customized. Use the Get Pricing endpoint to retrieve your current fee structure.

Fee Types

Issuance & Maintenance

Fee Code	Description	Type	When Applied
`CARD_ISSUANCE_FEE_UNTOKENIZED`	Standard card creation fee	Fixed	When a standard card is issued
`CARD_ISSUANCE_FEE_TOKENIZED`	Tokenized card creation fee	Fixed	When a tokenized card is issued
`CARD_MONTHLY_FEE_UNTOKENIZED`	Monthly maintenance for standard cards	Fixed	Monthly
`CARD_MONTHLY_FEE_TOKENIZED`	Monthly maintenance for tokenized cards	Fixed	Monthly
`CARD_REPLACEMENT_FEE`	Replacement card fee	Fixed	When replacing a card
`CARD_DELETION_FEE`	Card termination fee	Fixed	When terminating a card
`CARD_PLASTIC_FEE`	Physical plastic card surcharge	Fixed	For physical cards
`CARD_METAL_FEE`	Physical metal card surcharge	Fixed	For metal cards

Funding & Unloading

Fee Code	Description	Type	When Applied
`CARD_FUNDING_FEE`	Fee for loading funds onto a card	Percentage	When funding card
`CARD_UNLOADING_FEE`	Fee for withdrawing funds from a card	Percentage	When unloading card

Transaction Fees

Fee Code	Description	Type	When Applied
`CARD_AUTHORIZATION_FEE`	Fee per transaction authorization	Fixed	Per authorized transaction
`CARD_SETTLEMENT_FEE`	Fee per settled transaction	Fixed	Per settled transaction
`CARD_CROSSBORDER_FEE`	Cross-border transaction fee	Percentage	When card is used in a different currency than the card’s currency
`DECLINE_FEE`	Declined transaction fee	Fixed	Per declined transaction

Verified businesses (KYB approved) may receive reduced fees. Use the Get Pricing endpoint to retrieve your current rates.

Card Products

Each card is issued from a specific product that determines the brand, currency, spending limit, tokenization support, and available features. Use the List Products endpoint to discover available products.

Selecting a Product

Pass the productId when creating a card:

POST /cards
{
  "cardholderId": "ch_xyz789ghi012",
  "amount": 100.00,
  "productId": "MCWORLDUSD"   // Specific product
}

If no productId is provided, the default product (the one marked isDefault: true) is used.

Product Availability

Each product exposes availability flags that indicate what operations are currently supported:

Flag	Description
`canIssue`	Whether this product can be used to create new cards. Only products with `canIssue: true` are accepted in the create card endpoint.
`canFund`	Whether cards of this product can receive funding (loading money onto the card).
`canUnload`	Whether cards of this product support unloading (withdrawing money from the card).
`isDefault`	The fallback product used during card replacement when the original card type is unavailable.

Card Replacement Fallback: When replacing a card, the system first attempts to issue the same product type. If that product has canIssue: false, the product marked as isDefault: true is automatically used instead. The card balance is transferred seamlessly regardless of which product is issued.

Multi-Currency Support

Cards are available in multiple currencies (USD, EUR). For non-USD cards, the amount is specified in the card’s currency, and your USD wallet is debited the equivalent at the current exchange rate.

Currency	Wallet Debit	Card Balance
USD	Direct (1:1)	Same as amount
EUR	Converted at market rate	Amount in EUR

Spending Limits

Each card product has a spendingLimit and spendingPeriod that define how much can be spent within a given time window. For example, a product with spendingLimit: 25000 and spendingPeriod: DAILY allows up to $25,000 in purchases per day. Limits apply to purchase transactions only (not funding/unloading).

Integration Flow

Creating a Card

Business KYB Required: Your business must have completed KYB verification (with a primary director and ID document) before creating cards. Individual cardholder KYC is not required for card creation - the business owner’s verified identity is used for card provisioning.

Example Request

const response = await fetch('https://api.fyatu.com/api/v3/cards', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    cardholderId: 'ch_xyz789ghi012',
    amount: 100.00,
    name: 'JOHN DOE',            // Optional, defaults to cardholder name
    productId: 'MCWORLDUSD'      // Optional, defaults to MCWORLDUSD
  })
});

Card Operations

Funding

Add funds to a card from your business wallet:

POST /cards/{cardId}/fund
{ "amount": 50.00 }

Funding fee is calculated as a percentage with a minimum
Full amount is added to card balance
Fee is deducted from business wallet separately

Unloading

Withdraw funds from card back to your wallet:

POST /cards/{cardId}/unload
{ "amount": 25.00 }

Unloading fee may apply based on your pricing
Cannot unload more than available balance

Freeze / Unfreeze

Temporarily disable a card:

POST /cards/{cardId}/freeze    // Disable transactions
POST /cards/{cardId}/unfreeze  // Re-enable transactions

Frozen cards cannot make purchases
Balance is preserved while frozen
Can still fund/unload while frozen

Terminate

Permanently close a card:

DELETE /cards/{cardId}
{
  "reason": "Customer requested closure",  // Optional, defaults to "Terminated by the user"
  "reference": "REF123456"                  // Optional, defaults to cardId
}

Balance Refund: When a card is terminated, any remaining balance on the card is automatically refunded to your business wallet. For example, if the card has $25.00 remaining, that amount is credited back to your wallet balance.

No termination fee - balance is refunded in full
Card cannot be reactivated
Cardholder can still have other active cards
Provide a custom reason for record-keeping (visible in webhooks and logs)

Terminate Response

{
  "status": true,
  "message": "Card terminated successfully",
  "data": {
    "id": "CRD678E4F2A1B3C9",
    "status": "TERMINATED",
    "reason": "Customer requested closure",
    "refundedBalance": 25.00,
    "terminatedAt": "2026-01-15T10:30:00+00:00",
    "reference": "REF123456"
  }
}

Transactions

Transaction Types

Type	Description
`debit`	Purchase or payment (money out)
`credit`	Refund or cashback (money in)
`funding`	Card funding operation
`unload`	Card unloading operation

Transaction Statuses

Status	Description
`PENDING`	Authorization hold
`COMPLETED`	Successfully settled
`DECLINED`	Transaction rejected
`REVERSED`	Refunded or reversed

Retrieving Transactions

GET /cards/{cardId}/transactions?page=1

Webhooks

Card Events

Event	Trigger
`card.created`	New card issued
`card.activated`	Physical card activated with code
`card.funded`	Funds added to card
`card.unloaded`	Funds withdrawn from card
`card.frozen`	Card frozen by owner
`card.unfrozen`	Card unfrozen by owner
`card.suspended`	Card suspended by system (fraud, compliance, decline limit)
`card.reactivated`	Suspended card reactivated (after funding or support resolution)
`card.terminated`	Card permanently closed (cancelled, lost, stolen, expired)

Transaction Events

Event	Trigger
`card.transaction.authorized`	Transaction approved
`card.transaction.declined`	Transaction declined
`card.transaction.settled`	Transaction completed
`card.transaction.reversed`	Transaction reversed

Webhook Payload Examples

card.funded

{
  "event": "card.funded",
  "data": {
    "cardId": "CRD17368945521234",
    "cardholderId": "ch_xyz789ghi012",
    "amount": 50.00,
    "fee": 0,
    "currency": "USD",
    "reference": "FND17368945527890",
    "status": "SUCCESS"
  },
  "timestamp": "2026-01-15T10:30:00+00:00"
}

card.terminated

{
  "event": "card.terminated",
  "data": {
    "cardId": "CRD678E4F2A1B3C9",
    "cardholderId": "ch_xyz789ghi012",
    "refundedBalance": 25.00,
    "reference": "REF123456",
    "reason": "Customer requested closure",
    "status": "TERMINATED"
  },
  "timestamp": "2026-01-15T10:30:00+00:00"
}

Best Practices

Security

Secure Card Data Handling

Never log or store full card numbers
Use masked numbers in UI displays
Implement proper access controls
Audit all card data access

Fraud Prevention

Monitor transaction patterns
Implement velocity checks
Enable freeze functionality for users
Set appropriate spending limits

Operational

Balance Monitoring: Keep sufficient wallet balance for card operations
Webhook Integration: Handle all card events for real-time updates
Error Handling: Implement retry logic for transient failures
Limit Management: Start with lower limits, increase based on usage

Error Handling

Error Code	Cause	Resolution
`INSUFFICIENT_BALANCE`	Wallet balance too low	Top up business wallet
`INSUFFICIENT_CARD_BALANCE`	Card balance too low	Fund the card
`CARD_NOT_ACTIVE`	Card is frozen/suspended/terminated	Check status, unfreeze if frozen, or use different card
`CARD_INACTIVE`	Physical card not yet activated	Activate the card with activation code
`CARD_SUSPENDED`	Card suspended by system	Fund the card (if decline-suspended) or contact support
`CARD_TERMINATED`	Card permanently closed	Issue a new card
`CARDHOLDER_INACTIVE`	Cardholder not active	Activate cardholder first
`BUSINESS_KYB_REQUIRED`	Business verification incomplete	Complete KYB verification before creating cards
`ALREADY_FROZEN`	Card already frozen	No action needed
`ALREADY_ACTIVE`	Card already active	No action needed
`ALREADY_TERMINATED`	Card already terminated	No action needed
`DECLINE_LIMIT_REACHED`	15 insufficient funds declines	Fund the card to reset and reactivate

Integration Checklist

API Reference

Card Management

List Products - GET /cards/products
List Cards - GET /cards
Create Card - POST /cards
Get Card Details - GET /cards/{id}
Terminate Card - DELETE /cards/{id}

Card Operations

Fund Card - POST /cards/{id}/fund
Unload Card - POST /cards/{id}/unload
Freeze Card - POST /cards/{id}/freeze
Unfreeze Card - POST /cards/{id}/unfreeze
Replace Card - POST /cards/{id}/replace
Get Transactions - GET /cards/{id}/transactions

Getting Started

Core Concepts

​Cards Overview

​Card Concept

​Card Types

​Virtual Cards

​Physical Cards (Coming Soon)

​Crypto Cards (Coming Soon)

​Card Lifecycle

​Card Statuses

​Status Transitions

​Decline Count & Auto-Suspension

​Fee Structure

​Fee Types

​Card Products

​Selecting a Product

​Product Availability

​Multi-Currency Support

​Spending Limits

​Integration Flow

​Creating a Card

​Example Request

​Card Operations

​Funding

​Unloading

​Freeze / Unfreeze

​Terminate

​Terminate Response

​Transactions

​Transaction Types

​Transaction Statuses

​Retrieving Transactions

​Webhooks

​Card Events

​Transaction Events

​Webhook Payload Examples

​card.funded

​card.terminated

​Best Practices

​Security

​Operational

​Error Handling

​Integration Checklist

​API Reference

​Card Management

​Card Operations

Cards Overview

Card Concept

Card Types

Virtual Cards

Physical Cards (Coming Soon)

Crypto Cards (Coming Soon)

Card Lifecycle

Card Statuses

Status Transitions

Decline Count & Auto-Suspension

Fee Structure

Fee Types

Card Products

Selecting a Product

Product Availability

Multi-Currency Support

Spending Limits

Integration Flow

Creating a Card

Example Request

Card Operations

Funding

Unloading

Freeze / Unfreeze

Terminate

Terminate Response

Transactions

Transaction Types

Transaction Statuses

Retrieving Transactions

Webhooks

Card Events

Transaction Events

Webhook Payload Examples

card.funded

card.terminated

Best Practices

Security

Operational

Error Handling

Integration Checklist

API Reference

Card Management

Card Operations