Skip to main content
POST
/
cards
Issue Card
curl --request POST \
  --url https://api.fyatu.com/api/v3.20/cards \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cardholderId": "CH-A1B2C3D4E5F6G7H8",
  "productId": "PRDX1Y2Z3A4B5C6D7",
  "nameOnCard": "JANE DOE",
  "amount": 100
}
'
{
  "success": true,
  "status": 123,
  "data": {
    "id": "<string>",
    "cardholderId": "<string>",
    "productId": "<string>",
    "programId": "<string>",
    "nameOnCard": "<string>",
    "maskedNumber": "4111 **** **** 1234",
    "lastDigits": "1234",
    "expiration": "12/29",
    "scheme": "VISA",
    "type": "VIRTUAL",
    "currency": "USD",
    "balance": 100,
    "status": "ACTIVE",
    "is3DSEnabled": true,
    "isTokenizationEnabled": true,
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "requestId": "req_9f3e2a1b4c5d67e8",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

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.

​
Overview

Issue a new virtual card to a cardholder. Specify productId — all card settings (scheme, currency, limits, 3DS, tokenization) are resolved from the product automatically. Your business wallet is debited for the card amount plus applicable fees.

​
Prerequisites

  1. Approved KYC: The cardholder must have kycStatus: APPROVED
  2. Active Cardholder: The cardholder must have status: ACTIVE
  3. Sufficient Balance: Wallet must cover amount + issuanceFee
  4. Active Product: The productId must be in your program and status: ACTIVE

​
Request Body

FieldTypeRequiredDescription
cardholderIdstringYesID of the cardholder to issue the card to
productIdstringYesCard product ID from GET /programs/{id}/products
nameOnCardstringNoName embossed on the card (defaults to cardholder’s full name)
amountnumberYesInitial funding amount in product currency (minimum: $5 or €5)

​
Key Difference from V3

In V3, you specify card settings directly: 
{ "scheme": "VISA", "type": "VIRTUAL", "currency": "USD", "transactionLimit": 500, "is3DSEnabled": true }
In V3.20, you specify only the productId: 
{ "productId": "PRDX1Y2Z3A4B5C" }
The API resolves scheme, currency, limits, and features from the product. This ensures consistency — all cards of a given product type have identical settings, and feature changes require creating a new product (protecting existing cardholders).

​
Example

curl -X POST "https://api.fyatu.com/api/v3.20/cards" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cardholderId": "CH-ABC123DEF456",
    "productId": "PRDX1Y2Z3A4B5C",
    "nameOnCard": "JOHN SMITH",
    "amount": 100.00
  }'

​
Response

{
  "success": true,
  "status": 201,
  "message": "Card created successfully",
  "data": {
    "id": "crd_9x8y7z6w5v4u3t2s",
    "cardholderId": "CH-ABC123DEF456",
    "productId": "PRDX1Y2Z3A4B5C",
    "programId": "PGM1A2B3C4D5E6",
    "nameOnCard": "JOHN SMITH",
    "last4": "4829",
    "maskedNumber": "****4829",
    "expiryDate": "04/2031",
    "scheme": "VISA",
    "currency": "USD",
    "status": "ACTIVE",
    "initialBalance": 100.00,
    "createdAt": "2026-04-30T10:35:00+00:00"
  },
  "meta": {
    "requestId": "req_8ce95a4f1b3d67ea",
    "timestamp": "2026-04-30T10:35:00+00:00"
  }
}

​
Card Status on Creation

Some products create cards asynchronously. When this happens, status is PROCESSING and last4, maskedNumber, expiryDate are null. Listen for webhooks:
Webhook EventMeaning
card.createdCard is now ACTIVE — full details in payload
card.failedCard creation failed — balance refunded to wallet

​
Error Codes

CodeDescription
CARDHOLDER_INACTIVECardholder not active or KYC not approved
PRODUCT_NOT_FOUNDproductId not found in your program
PRODUCT_INACTIVEProduct is currently inactive
INSUFFICIENT_BALANCEWallet balance too low for amount + fees
HOLD_FAILEDBalance reservation failed
PROVIDER_NOT_CONFIGUREDCard provider not configured for your business
CARD_CREATION_FAILEDProvider rejected card creation
BUSINESS_KYB_REQUIREDBusiness KYB verification required
Use GET /programs/{programId}/products to discover available productId values and their fee structures before issuing cards.

Authorizations

​
Authorization
string
header
required

JWT access token obtained from POST /auth/token

Body

application/json
​
cardholderId
string
required

ID of the cardholder to issue the card to

Example:

"CH-A1B2C3D4E5F6G7H8"

​
productId
string
required

ID of the Card Product — determines scheme, type, currency, limits, and feature flags

Example:

"PRDX1Y2Z3A4B5C6D7"

​
nameOnCard
string
required

Name printed on the card (alphanumeric, max 26 chars)

Example:

"JANE DOE"

​
amount
number
required

Initial funding amount in the product's currency

Required range: x >= 1
Example:

100

Response

Card issued

​
success
boolean
​
status
integer
​
data
object
​
meta
object