Create Card - FYATU API Docs

Create Card

curl --request POST \
  --url https://api.fyatu.com/api/v3/cards \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cardholderId": "ch_a1b2c3d4e5f6",
  "name": "ALICE EXAMPLE",
  "amount": 100,
  "productId": "MCUSD1"
}
'

{
  "success": true,
  "status": 201,
  "message": "Card created successfully",
  "data": {
    "id": "crd_8f3a2b1c4d5e6f7890abcdef12345678",
    "cardholderId": "ch_1a2b3c4d5e6f7890abcdef1234567890",
    "name": "JAMES WILSON",
    "last4": "4829",
    "maskedNumber": "****4829",
    "expiryDate": "01/2030",
    "brand": "MASTERCARD",
    "currency": "USD",
    "status": "ACTIVE",
    "initialBalance": 100,
    "createdAt": "2026-01-17 10:00:00"
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-01-17T10:00:00+00:00"
  }
}

POST

cards

Create Card

curl --request POST \
  --url https://api.fyatu.com/api/v3/cards \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cardholderId": "ch_a1b2c3d4e5f6",
  "name": "ALICE EXAMPLE",
  "amount": 100,
  "productId": "MCUSD1"
}
'

{
  "success": true,
  "status": 201,
  "message": "Card created successfully",
  "data": {
    "id": "crd_8f3a2b1c4d5e6f7890abcdef12345678",
    "cardholderId": "ch_1a2b3c4d5e6f7890abcdef1234567890",
    "name": "JAMES WILSON",
    "last4": "4829",
    "maskedNumber": "****4829",
    "expiryDate": "01/2030",
    "brand": "MASTERCARD",
    "currency": "USD",
    "status": "ACTIVE",
    "initialBalance": 100,
    "createdAt": "2026-01-17 10:00:00"
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-01-17T10:00:00+00:00"
  }
}

Overview

Issue a new virtual card to a cardholder. The cardholder must have verified KYC status and your business wallet must have sufficient balance for the card amount plus fees.

Prerequisites

Verified Cardholder: The cardholder must exist and have status: ACTIVE
Sufficient Balance: Wallet must cover: amount (in USD) + issuanceFee
Active Application: Your app must be in ACTIVE status

Request Body

Field	Type	Required	Description
`cardholderId`	string	Yes	ID of the cardholder to issue card to
`amount`	number	Yes	Initial funding amount in product currency (minimum $5 or €5)
`name`	string	No	Name on card (defaults to cardholder name)
`productId`	string	No	Card product to issue (from List Products). Defaults to the product marked `isDefault: true`
`spendingLimit`	integer	No	Deprecated — Use `productId` instead. Monthly spending limit: `5000` or `10000` (default: 5000)

Deprecation Notice: The spendingLimit field is deprecated and will be removed in a future version. Use productId to select the card product, which determines the spending limit, brand, and currency automatically. If both productId and spendingLimit are provided, productId takes precedence.

Example Usage

<?php
// Recommended: use productId
$data = [
    'cardholderId' => 'ch_a1b2c3d4e5f6',
    'amount' => 100.00,
    'name' => 'ALICE EXAMPLE',
    'productId' => 'MCUSD1'
];

$ch = curl_init('https://api.fyatu.com/api/v3/cards');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $accessToken,
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode($data)
]);

$response = curl_exec($ch);
$result = json_decode($response, true);

if ($result['success']) {
    echo "Card created: " . $result['data']['id'] . "\n";
    echo "Brand: " . $result['data']['brand'] . "\n";
    echo "Currency: " . $result['data']['currency'] . "\n";
    echo "Balance: " . $result['data']['initialBalance'] . "\n";
}

EUR Card Example

When issuing a EUR-denominated card, the amount is specified in EUR. Your wallet (USD) is debited the equivalent in USD at the current exchange rate.

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_a1b2c3d4e5f6',
    amount: 100.00,        // €100 EUR
    productId: 'MCEUR1'
  })
});

// Response:
// {
//   "data": {
//     "id": "crd_...",
//     "brand": "MASTERCARD",
//     "currency": "EUR",
//     "initialBalance": 100.00   // €100 on card
//   }
// }
// Wallet debited: ~$108.70 USD (100 / EUR rate) + issuance fee

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 \| null	Last 4 digits of the card number. `null` when status is `PROCESSING`
`maskedNumber`	string \| null	Masked card number (e.g., `****4829`). `null` when status is `PROCESSING`
`expiryDate`	string \| null	Card expiration date (MM/YYYY). `null` when status is `PROCESSING`
`brand`	string	Card brand: `MASTERCARD` or `VISA`
`currency`	string	Card currency: `USD` or `EUR`
`status`	string	Card status: `ACTIVE` or `PROCESSING` (see below)
`initialBalance`	number	Initial funding amount in card currency
`createdAt`	string	Card creation timestamp

Card Status on Creation

Some card products are created asynchronously. When this happens, the API returns immediately with status: PROCESSING and card details (last4, maskedNumber, expiryDate) will be null. Once the card is ready, a card.created webhook is sent with the full card details and status: ACTIVE. If creation fails, a card.failed webhook is sent and the held balance is released.

Status	Meaning
`ACTIVE`	Card is ready to use immediately
`PROCESSING`	Card is being created — listen for `card.created` or `card.failed` webhook

You can poll GET /cards/{cardId} to check the card status, but we strongly recommend using webhooks instead of polling.

Webhook Events

`card.created`

Sent when a PROCESSING card becomes active:

{
  "event": "card.created",
  "data": {
    "cardId": "crd_a1b2c3...",
    "cardholderId": "CH-ABC123",
    "type": "VIRTUAL",
    "brand": "MASTERCARD",
    "currency": "USD",
    "last4": "4532",
    "status": "ACTIVE"
  }
}

`card.failed`

Sent when a PROCESSING card fails to be created. The held balance is automatically released.

{
  "event": "card.failed",
  "data": {
    "cardId": "crd_a1b2c3...",
    "cardholderId": "CH-ABC123",
    "status": "FAILED",
    "reason": "Card provider creation failed"
  }
}

Error Responses

Error Code	Description
`APP_INACTIVE`	Application is not active
`CARDHOLDER_INACTIVE`	Cardholder is not active (KYC not verified)
`INSUFFICIENT_BALANCE`	Business wallet balance is too low
`PRODUCT_NOT_FOUND`	Card product not found
`PRODUCT_INACTIVE`	Card product is currently inactive
`PRODUCT_UNAVAILABLE`	Card product is temporarily unavailable for new issuance
`RATE_UNAVAILABLE`	Unable to fetch exchange rate for EUR products
`HOLD_FAILED`	Failed to hold balance from business wallet
`PROVIDER_NOT_CONFIGURED`	Card provider account not configured
`CARD_CREATION_FAILED`	Failed to create card at the bank partner
`CARDHOLDER_REGISTRATION_FAILED`	Failed to register cardholder with card provider
`CARDHOLDER_RESTRICTED`	Cardholder has been restricted by the card provider
`BUSINESS_KYB_REQUIRED`	Business KYB verification incomplete

Use the List Products endpoint to discover available card products and their fees before creating a card.

Authorizations

Authorization

string

header

required

JWT access token obtained from /auth/token

Body

application/json

cardholderId

string

required

ID of the cardholder to issue card to

amount

number

required

Initial funding amount in product currency (minimum $5 or €5)

Required range: x >= 5

name

string

Name on card (defaults to cardholder name if not provided)

Minimum string length: 4

productId

string

Card product to issue (from List Products endpoint). Determines brand, currency, and spending limit. Defaults to the product marked isDefault if not provided.

Example:

"MCUSD1"

spendingLimit

enum<integer>

default:5000

deprecated

Deprecated — Use productId instead. Monthly spending limit in USD.

Available options:

5000,

10000

Response

Card created successfully

success

boolean

Example:

true

status

integer

message

string

data

object

Show child attributes

Documentation Index

​Overview

​Prerequisites

​Request Body

​Example Usage

​EUR Card Example

​Response Fields

​Card Status on Creation

​Webhook Events

​card.created

​card.failed

​Error Responses

Authorizations

Body

Response

Overview

Prerequisites

Request Body

Example Usage

EUR Card Example

Response Fields

Card Status on Creation

Webhook Events

`card.created`

`card.failed`

Error Responses