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 monthly (rolling 30-day) spending limit, typically

5,000 or

10,000.

Card Types

Virtual Cards

Digital cards for online transactions. Issued instantly and active by default.

Feature	Description
Issuance	Instant
Initial Status	Active (ready to use)
Use Cases	Online shopping, subscriptions, digital services
Card Networks	Mastercard, Visa (coming soon)
Can be tokenized	Yes

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

Digital Cards / Tokenized (Coming Soon)

Cards provisioned directly to Apple Pay, Google Pay, and Samsung Pay. Digital cards are created from an existing active virtual or physical card and are active by default.

Feature	Description
Requirements	Existing active virtual or physical card
Issuance	Instant (push to wallet)
Initial Status	Active
Has visible card number	No (tokenized)
Can be suspended	No

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	—	`ACTIVE`
Create digital (tokenized) card	—	`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

Fee Code	Description	Type	When Applied
`CARD_ISSUANCE_FEE`	Card creation fee	Fixed	When card is issued
`CARD_FUNDING_FEE`	Fee for loading funds	Percentage	When funding card
`CARD_UNLOADING_FEE`	Fee for withdrawing funds	Percentage	When unloading card
`CARD_MONTHLY_FEE`	Monthly maintenance	Fixed	Monthly
`CARD_REPLACEMENT_FEE`	Replacement card fee	Fixed	When replacing card
`CARD_PLASTIC_FEE`	Physical plastic card	Fixed	For physical cards
`CARD_METAL_FEE`	Physical metal card	Fixed	For metal cards
`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.

Holding Balance

When creating a card, a holding balance is reserved for future monthly fees:

Spending Limit	Holding Balance
$5,000/month	$1.00
$10,000/month	$3.00

Spending Limits

Available Limits

Limit	Monthly Cap	Best For
$5,000	Standard usage	Most use cases
$10,000	High-volume users	Power users, businesses

Limit Behavior

Limits reset on the 1st of each month
Declined transactions when limit is reached
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
    spendingLimit: 5000      // Optional, default 5000
  })
});

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 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)

​Digital Cards / Tokenized (Coming Soon)

​Crypto Cards (Coming Soon)

​Card Lifecycle

​Card Statuses

​Status Transitions

​Decline Count & Auto-Suspension

​Fee Structure

​Fee Types

​Holding Balance

​Spending Limits

​Available Limits

​Limit Behavior

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

Digital Cards / Tokenized (Coming Soon)

Crypto Cards (Coming Soon)

Card Lifecycle

Card Statuses

Status Transitions

Decline Count & Auto-Suspension

Fee Structure

Fee Types

Holding Balance

Spending Limits

Available Limits

Limit Behavior

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