Quick Start Guide

This guide will walk you through making your first FYATU API call. By the end, you’ll have:

Authenticated with the API using JWT
Created a cardholder (Issuing App) or a collection (Collection App)

Prerequisites

Create Account

Verify Your Identity (KYC)

Submit your identity documents to verify your account

Upgrade to Business

Upgrade your account to Business from the dashboard

Create an App

Create a Collection App or Issuing App from your Business Console

Fund Your Wallet

Deposit USDT to your business wallet (minimum $10 to get started)

Step 1: Get Your Credentials

Log into your Business Console, select your app, and go to Settings > API Keys & Credentials: You’ll need two credentials for authentication:

Credential	Description	Example
App ID	Your app’s unique identifier	`DD123FR45446CECES`
Secret Key	Your app’s secret key	`sk_live_xxxxxxxxxxxxx`

Keep your secret key safe! It’s only shown once when generated. Never expose it in client-side code or public repositories.

Step 2: Get an Access Token

Exchange your credentials for a JWT access token:

curl -X POST "https://api.fyatu.com/api/v3/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "DD123FR45446CECES",
    "secretKey": "your_secret_key_here",
    "grantType": "client_credentials"
  }'

You should receive a response like:

{
  "success": true,
  "status": 200,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 86400,
    "expiresAt": "2026-01-16T21:31:39+00:00"
  }
}

Your token is valid for 24 hours. Use it in the Authorization header for all subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Step 3: Make Your First API Call

Use the access token to make authenticated requests. Here are examples for each app type:

Issuing App
Collection App

Create a Cardholder

curl -X POST "https://api.fyatu.com/api/v3/cardholders" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "F45786646",
    "firstName": "John",
    "lastName": "Smith",
    "email": "[email protected]",
    "phone": "+12025551234",
    "dateOfBirth": "1990-05-15",
    "gender": "MALE",
    "address": "123 Main Street, Apt 4B",
    "city": "Newark",
    "state": "Delaware",
    "country": "US",
    "zipCode": "000000"
  }'

Response (201)

{
  "success": true,
  "status": 201,
  "message": "Cardholder created successfully",
  "data": {
    "id": "ch_1a2b3c4d5e6f7890abcdef1234567890",
    "externalId": "F45786646",
    "firstName": "John",
    "lastName": "Smith",
    "email": "[email protected]",
    "phone": "+12025551234",
    "dateOfBirth": "1990-05-15",
    "gender": "MALE",
    "address": {
      "line1": "123 Main Street, Apt 4B",
      "city": "Newark",
      "state": "Delaware",
      "country": "US",
      "zipCode": "000000"
    },
    "status": "ACTIVE",
    "kycStatus": "UNSUBMITTED",
    "createdAt": "2026-01-15T21:31:39+00:00"
  },
  "meta": {
    "requestId": "req_2f7fb4227a1007418773122f",
    "timestamp": "2026-01-15T21:31:39+00:00"
  }
}

Save the cardholder id — you’ll need it to create a card.

Issue a Virtual Card

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

Response (201)

{
  "success": true,
  "status": 201,
  "message": "Card created successfully",
  "data": {
    "id": "crd_9x8y7z6w5v4u3t2s",
    "cardholderId": "ch_1a2b3c4d5e6f7890abcdef1234567890",
    "name": "JOHN SMITH",
    "last4": "4829",
    "maskedNumber": "****4829",
    "expiryDate": "03/2029",
    "brand": "MASTERCARD",
    "currency": "USD",
    "status": "ACTIVE",
    "initialBalance": 100.00,
    "createdAt": "2026-01-15T21:35:00+00:00"
  },
  "meta": {
    "requestId": "req_8ce95a4f1b3d67ea2c09458f",
    "timestamp": "2026-01-15T21:35:00+00:00"
  }
}

Card details (full number, CVV) are returned only on the Get Card endpoint. Always handle them securely and never log or expose them.

Create a Collection (Payment)

curl -X POST "https://api.fyatu.com/api/v3/collections" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.00,
    "orderId": "INV-001",
    "description": "Premium Subscription",
    "callbackUrl": "https://yoursite.com/payment/complete",
    "webhookUrl": "https://yoursite.com/webhook/fyatu",
    "metadata": {
      "userId": "12345",
      "plan": "premium"
    }
  }'

Response (201)

{
  "success": true,
  "status": 201,
  "message": "Checkout session created successfully",
  "data": {
    "collectionId": "SCI679A1B2C3D4E5",
    "reference": "A2B4C6D8E0F2",
    "orderId": "INV-001",
    "amount": 25.00,
    "fee": 0.75,
    "netAmount": 24.25,
    "currency": "USD",
    "status": "PENDING",
    "checkoutUrl": "https://checkout.fyatu.com/sci/checkout?batch=SCI679A1B2C3D4E5",
    "expiresAt": "2026-01-08T12:30:00+00:00"
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2026-01-08T11:30:00+00:00"
  }
}

Redirect your customer to the checkoutUrl to complete payment. The session expires in 60 minutes.After payment, the customer is redirected to your callbackUrl:

https://yoursite.com/payment/complete?batch=SCI679A1B2C3D4E5&status=COMPLETED

And your webhookUrl receives a server-to-server notification:

{
  "event": "collection.received",
  "version": "3.0",
  "sign": "hmac_sha256_signature",
  "data": {
    "reference": "A2B4C6D8E0F2",
    "externalReference": "INV-001",
    "amount": 25.00,
    "charge": 0.75,
    "netAmount": 24.25,
    "currency": "USD",
    "paymentMethod": "WALLET",
    "customerName": "John Doe",
    "status": "SUCCESS",
    "appId": "DD123FR45446CECES",
    "timestamp": "2026-01-08T11:35:00+00:00"
  }
}

Step 4: Set Up Webhooks

Configure a webhook URL to receive real-time notifications for all events (payments received, cards funded, eSIMs activated, etc.):

curl -X PUT "https://api.fyatu.com/api/v3/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://yoursite.com/webhooks/fyatu"
  }'

Response (200)

{
  "success": true,
  "status": 200,
  "message": "Webhook URL updated successfully",
  "data": {
    "webhookUrl": "https://yoursite.com/webhooks/fyatu",
    "hasWebhookSecret": true,
    "isConfigured": true,
    "webhookSecret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "secretNote": "This is your webhook secret. Store it securely - it will not be shown again."
  },
  "meta": {
    "requestId": "req_abc123xyz789",
    "timestamp": "2026-01-15T10:30:00+00:00"
  }
}

Your webhookSecret is only shown once when first generated. Store it securely — you’ll need it to verify webhook signatures.

See the Webhooks guide for the full list of events and payload structures.

What’s Next?

Authentication Deep Dive

Token refresh, scopes, and best practices

Payment Collections

Accept payments from Fyatu users

Card Issuing

Learn about card lifecycle and operations

Error Handling

Handle API errors gracefully

Getting Started

Core Concepts

Quick Start

Quick Start Guide

Prerequisites

Step 1: Get Your Credentials

Step 2: Get an Access Token

Step 3: Make Your First API Call

Create a Cardholder

Issue a Virtual Card

Create a Collection (Payment)

Step 4: Set Up Webhooks

What’s Next?

Authentication Deep Dive

Payment Collections

Card Issuing

Error Handling

Getting Started

Core Concepts

​Quick Start Guide

​Prerequisites

​Step 1: Get Your Credentials

​Step 2: Get an Access Token

​Step 3: Make Your First API Call

​Create a Cardholder

​Issue a Virtual Card

​Create a Collection (Payment)

​Step 4: Set Up Webhooks

​What’s Next?

Authentication Deep Dive

Payment Collections

Card Issuing

Error Handling

Quick Start Guide

Prerequisites

Step 1: Get Your Credentials

Step 2: Get an Access Token

Step 3: Make Your First API Call

Create a Cardholder

Issue a Virtual Card

Create a Collection (Payment)

Step 4: Set Up Webhooks

What’s Next?