Skip to main content
POST
/
cards
Issue a card
curl --request POST \
  --url https://api.fyatu.com/api/v3.20/cards \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cardholderId": "chl_01HXYZ1234ABCDEF5678",
  "productId": "prd_01HXYZ1111ABCDEF0001",
  "amount": 100,
  "customName": "Travel Card"
}
'
{
  "success": true,
  "status": 201,
  "message": "Card issued",
  "data": {
    "id": "crd_01HXYZ5555ABCDEF1111",
    "cardholderId": "chl_01HXYZ1234ABCDEF5678",
    "productId": "prd_01HXYZ1111ABCDEF0001",
    "status": "ACTIVE",
    "cardType": "VIRTUAL",
    "cardBrand": "VISA",
    "maskedPan": "445123******4123",
    "last4": "4123",
    "createdAt": "2026-05-26T10:00:00Z",
    "updatedAt": "2026-05-26T10:00:00Z",
    "nameOnCard": "Travel Card",
    "expirationDate": "06/2030",
    "balance": 100,
    "currency": "USD",
    "features": {
      "has3DS": true,
      "hasApplePay": false,
      "hasGooglePay": false,
      "hasJIT": false,
      "hasSpendControl": true,
      "hasMccControl": false,
      "isReloadable": true,
      "isOneTimeUse": false
    },
    "spendingLimit": 1000,
    "spendingPeriod": "TRANSAMOUNT",
    "billingAddress": {
      "address": "1234 Main St",
      "city": "New York",
      "state": "NY",
      "zipCode": "10001",
      "country": "US"
    }
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-26T10:00:00Z"
  }
}

​
Overview

Issue a virtual prepaid card to a cardholder under one of your programs. Pass productId — the program, card type, and spend limits are all derived from the product automatically. JIT vs pre-funded cards:
  • JIT-enabled products (features.hasJIT: true): The card is funded on-demand at the point of each transaction. amount is optional.
  • Standard products (features.hasJIT: false): The card requires an initial balance at issuance. amount is required.

​
Request Body

FieldTypeRequiredDescription
cardholderIdstringYesThe cardholder to issue the card to
productIdstringYesThe card product — program, card type, and spend limits are derived from this
amountnumberConditionalInitial balance in USD. Required when the product is not JIT-enabled
customNamestringNoCard label. Defaults to the cardholder’s full name

​
Example

curl -X POST https://api.fyatu.com/api/v3.20/cards \
  -H "Authorization: Bearer $FYATU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cardholderId": "chl_01HXYZ1234ABCDEF5678",
    "productId":    "prd_01HXYZ1111ABCDEF0001",
    "amount":       100.00,
    "customName":   "Travel Card"
  }'

​
Success Response (201)

{
  "success": true,
  "status":  201,
  "message": "Card issued",
  "data": {
    "id":           "crd_01HXYZ5555ABCDEF1111",
    "cardholderId": "chl_01HXYZ1234ABCDEF5678",
    "productId":    "prd_01HXYZ1111ABCDEF0001",
    "status":       "ACTIVE",
    "cardType":     "VIRTUAL",
    "cardBrand":    "VISA",
    "maskedPan":    "445123******4123",
    "last4":        "4123",
    "createdAt":    "2026-05-26T10:00:00Z",
    "updatedAt":    "2026-05-26T10:00:00Z",
    "nameOnCard":     "Travel Card",
    "expirationDate": "06/2030",
    "balance":        100.00,
    "currency":       "USD",
    "features": {
      "has3DS":          true,
      "hasApplePay":     false,
      "hasGooglePay":    false,
      "hasJIT":          false,
      "hasSpendControl": true,
      "hasMccControl":   false,
      "isReloadable":    true,
      "isOneTimeUse":    false
    },
    "spendingLimit":  1000.00,
    "spendingPeriod": "TRANSAMOUNT",
    "billingAddress": {
      "address": "1234 Main St",
      "city":    "New York",
      "state":   "NY",
      "zipCode": "10001",
      "country": "US"
    }
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform":  "Fyatu CaaS",
    "timestamp": "2026-05-26T10:00:00Z"
  }
}

​
Response Fields

FieldTypeDescription
idstringCard identifier (prefix crd_)
cardholderIdstringThe cardholder this card belongs to
productIdstringThe product the card was issued under
statusstringAlways ACTIVE at issuance
cardTypestringVIRTUAL or PHYSICAL
cardBrandstringVISA or MASTERCARD
maskedPanstringBIN-masked PAN — first 6 digits + 6 stars + last 4 (e.g. 445123******4123)
last4stringLast 4 digits of the PAN
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 last-update timestamp
nameOnCardstringName displayed on the card — customName if provided, otherwise the cardholder’s full name
expirationDatestringCard expiry in MM/YYYY format (e.g. 06/2030)
balancenumberCurrent card balance in USD
currencystringCard currency (always USD)
featuresobjectCard capability flags inherited from the product
features.has3DSboolean3D Secure enabled
features.hasApplePaybooleanApple Pay tokenisation supported
features.hasGooglePaybooleanGoogle Pay tokenisation supported
features.hasJITbooleanJust-In-Time funding enabled (no pre-fund required)
features.hasSpendControlbooleanSpend limit control active
features.hasMccControlbooleanMCC (merchant category) control active
features.isReloadablebooleanCard can be topped up via POST /cards/{id}/fund
features.isOneTimeUsebooleanCard terminates automatically after its first settled transaction
spendingLimitnumberSpend cap per spendingPeriod in USD, inherited from the product
spendingPeriodstringPeriod over which the spend cap applies — TRANSAMOUNT, DAILY, WEEKLY, MONTHLY, QUARTERLY, YEARLY, or LIFETIME
billingAddressobjectBilling address registered with the card provider
billingAddress.addressstringStreet address
billingAddress.citystringCity
billingAddress.statestringState or region
billingAddress.zipCodestringPostal code
billingAddress.countrystringTwo-letter ISO 3166-1 country code

​
Webhook

A CARD_ISSUED event fires after successful provisioning: 
{
  "event":      "CARD_ISSUED",
  "eventId":    "evt_01HXY123456ABCDEF",
  "businessId": "BUS1A2B3C4D5E6F",
  "environment": "LIVE",
  "timestamp":  "2026-05-26T10:00:00Z",
  "data": {
    "cardId":         "crd_01HXYZ5555ABCDEF1111",
    "status":         "ACTIVE",
    "cardType":       "VIRTUAL",
    "cardBrand":      "VISA",
    "cardholderId":   "chl_01HXYZ1234ABCDEF5678",
    "maskedPan":      "445123******4123",
    "last4":          "4123",
    "expirationDate": "06/2030",
    "balance":        100.00,
    "currency":       "USD",
    "is3ds":          true,
    "isTokenized":    false,
    "isJitfEnabled":  false
  }
}

​
Error Codes

CodeHTTPCause
CARD_AMOUNT_REQUIRED400amount was not provided for a non-JIT product
INVALID_REQUEST400Missing required field or unsupported card type
CARDHOLDER_NOT_FOUND404Cardholder does not exist or belongs to another business
PRODUCT_NOT_FOUND404Product does not exist or belongs to another business
PROGRAM_NOT_FOUND404Program linked to the product not found
PRODUCT_INACTIVE422Product is not active
PROGRAM_INACTIVE422Program is not active
CARDHOLDER_INACTIVE422Cardholder is suspended or terminated
CARDHOLDER_KYC_NOT_APPROVED422Cardholder KYC is not APPROVED or WAIVED
CARDHOLDER_CARD_LIMIT_EXCEEDED409Cardholder has reached the maxCardsPerCardholder limit for this product
PROVIDER_CREATE_FAILED422Card creation was rejected by the card provider
INSUFFICIENT_SCOPE403Key lacks cards:write scope
INTERNAL_ERROR500Server error

Authorizations

​
Authorization
string
header
required

API key from the FYATU CaaS portal. Pass as Authorization: Bearer <key>.

Body

application/json
​
cardholderId
string
required

The cardholder to issue the card to

Example:

"chl_01HXYZ1234ABCDEF5678"

​
productId
string
required

The card product — card type and program are derived from this

Example:

"prd_01HXYZ1111ABCDEF0001"

​
amount
number<float>

Initial balance in USD. Required for non-JIT products; optional for JIT-enabled products.

Example:

100

​
customName
string

Card label. Defaults to the cardholder's full name when omitted.

Example:

"Travel Card"

Response

Card issued

​
success
boolean
Example:

true

​
status
integer
Example:

201

​
message
string
Example:

"Card issued"

​
data
object

Card object returned at issuance. Also includes the one-time CVV — identical to GET /cards/{id} except nameOnCard is only present here.

​
meta
object