Authentication

FYATU API v3 uses JWT (JSON Web Tokens) for secure, stateless authentication. Exchange your app credentials for a short-lived access token, then use that token to authenticate all subsequent requests.

Overview

Getting Your Credentials

Go to FYATU Dashboard and login to your account

Open Business Console

Navigate to the Business Console from your dashboard

Select Your App

Click on your Collection App or Issuing App depending on which APIs you need

Get API Keys

Go to Settings tab, then click API Keys & Credentials

App Types & Scopes

Your access token’s scopes depend on the app type:

App Type	Available APIs	Scopes
Collection App	Collections, Payouts	`collect:write`, `collect:read`, `payout:write`, `payout:read`
Issuing App	Cards, Cardholders	`cards:write`, `cards:read`, `cardholders:write`, `cardholders:read`

Token Lifecycle

Property	Value
Token Type	JWT (HS256)
Token Expiry	24 hours
Refresh Window	Up to 5 minutes after expiry
Token Format	Bearer token

Step 1: Obtain Access Token

Exchange your app 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"
  }'

const response = await fetch('https://api.fyatu.com/api/v3/auth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    appId: 'DD123FR45446CECES',
    secretKey: 'your_secret_key_here',
    grantType: 'client_credentials'
  })
});

const data = await response.json();
const accessToken = data.data.accessToken;

$ch = curl_init('https://api.fyatu.com/api/v3/auth/token');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'appId' => 'DD123FR45446CECES',
        'secretKey' => 'your_secret_key_here',
        'grantType' => 'client_credentials'
    ])
]);

$response = json_decode(curl_exec($ch), true);
$accessToken = $response['data']['accessToken'];

import requests

response = requests.post(
    'https://api.fyatu.com/api/v3/auth/token',
    json={
        'appId': 'DD123FR45446CECES',
        'secretKey': 'your_secret_key_here',
        'grantType': 'client_credentials'
    }
)

data = response.json()
access_token = data['data']['accessToken']

Response

{
  "success": true,
  "status": 200,
  "message": "Token generated successfully",
  "data": {
    "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJERDEyM0ZSNDQ0NjZDRUNFUyIsImJ1cyI6Ik4xUzBXM1E4UDBWMUU1TTZRNFIzRDhaOSIsInR5cGUiOiJjb2xsZWN0aW9uIiwic2NvcGVzIjpbImNvbGxlY3Q6d3JpdGUiLCJjb2xsZWN0OnJlYWQiLCJwYXlvdXQ6d3JpdGUiLCJwYXlvdXQ6cmVhZCJdLCJpYXQiOjE3MzYwNzU4MDAsImV4cCI6MTczNjE2MjIwMCwianRpIjoiand0XzdhZjRkMmI4ZTkxYzM1ZmE0YjIxODkwZSJ9.x2kPqR7mN5vL8wT3fA9sD6gH1jK4cB0eW7yU2iO3pVn",
    "tokenType": "Bearer",
    "expiresIn": 86400,
    "expiresAt": "2026-01-06T10:30:00+00:00",
    "appType": "collection",
    "scopes": ["collect:write", "collect:read", "payout:write", "payout:read"]
  },
  "meta": {
    "requestId": "req_7af4d2b8e91c35fa4b21890e",
    "timestamp": "2026-01-05T10:30:00+00:00"
  }
}

Step 2: Use Token in Requests

Include the access token in the Authorization header for all API requests:

curl -X GET https://api.fyatu.com/api/v3/collections \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Step 3: Refresh Token (Optional)

Before your token expires, you can refresh it to get a new token. Refresh is allowed up to 5 minutes after expiry.

curl -X POST https://api.fyatu.com/api/v3/auth/refresh \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

{
  "success": true,
  "status": 200,
  "message": "Token refreshed successfully",
  "data": {
    "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJERDEyM0ZSNDQ0NjZDRUNFUyIsImJ1cyI6Ik4xUzBXM1E4UDBWMUU1TTZRNFIzRDhaOSIsInR5cGUiOiJjb2xsZWN0aW9uIiwic2NvcGVzIjpbImNvbGxlY3Q6d3JpdGUiLCJjb2xsZWN0OnJlYWQiLCJwYXlvdXQ6d3JpdGUiLCJwYXlvdXQ6cmVhZCJdLCJpYXQiOjE3MzYxNjIyMDAsImV4cCI6MTczNjI0ODYwMCwianRpIjoiand0XzhjZTk1YTRmMWIzZDY3ZWEyYzA5NDU4ZiJ9.m8nK3pW6rY1qL5vJ0hS9dF2gB4eA7xC3wU8tZ0iV5oR",
    "tokenType": "Bearer",
    "expiresIn": 86400,
    "expiresAt": "2026-01-07T10:30:00+00:00",
    "appType": "collection",
    "scopes": ["collect:write", "collect:read", "payout:write", "payout:read"]
  },
  "meta": {
    "requestId": "req_8ce95a4f1b3d67ea2c09458f",
    "timestamp": "2026-01-06T10:30:00+00:00"
  }
}

Error Responses

Invalid Credentials

{
  "success": false,
  "status": 401,
  "message": "Invalid credentials. Secret key mismatch.",
  "error": {
    "code": "AUTH_INVALID_CREDENTIALS"
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2026-01-05T10:30:00+00:00"
  }
}

Token Expired

{
  "success": false,
  "status": 401,
  "message": "Invalid or expired token",
  "error": {
    "code": "AUTH_TOKEN_INVALID"
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2026-01-05T10:30:00+00:00"
  }
}

Insufficient Scope

{
  "success": false,
  "status": 403,
  "message": "Access denied. Required scope: cards:write",
  "error": {
    "code": "AUTH_SCOPE_DENIED"
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2026-01-05T10:30:00+00:00"
  }
}

JWT Payload Structure

When decoded, the JWT token contains:

{
  "sub": "DD123FR45446CECES",
  "bus": "BUS_xxxxxxxxxxxx",
  "type": "collection",
  "scopes": ["collect:write", "collect:read", "payout:write", "payout:read"],
  "iat": 1704451800,
  "exp": 1704455400,
  "jti": "jwt_xxxxxxxxxxxxxxxxxxxx"
}

Claim	Description
`sub`	App ID (subject)
`bus`	Business ID
`type`	App type (`collection` or `issuing`)
`scopes`	Array of granted permissions
`iat`	Issued at timestamp
`exp`	Expiration timestamp
`jti`	Unique token identifier

Best Practices

Token Storage

Store tokens securely in memory or encrypted storage
Never expose tokens in client-side code or logs
Implement automatic token refresh before expiry

Token Refresh Strategy

Check token expiry before each request
Refresh when less than 5 minutes remain
Handle refresh failures by re-authenticating

Error Handling

Catch 401 errors and re-authenticate
Catch 403 errors and check required scopes
Log request IDs for debugging with FYATU support

Rate Limits

Authentication endpoints have the following rate limits:

Endpoint	Rate Limit
`POST /v3/auth/token`	10 requests per minute
`POST /v3/auth/refresh`	30 requests per minute

Exceeding rate limits will result in a 429 Too Many Requests response. Implement exponential backoff in your retry logic.

Getting Started

Payments

Cardholders

Cards

Authentication

Authentication

Overview

Getting Your Credentials

App Types & Scopes

Token Lifecycle

Step 1: Obtain Access Token

Response

Step 2: Use Token in Requests

Step 3: Refresh Token (Optional)

Response

Error Responses

Invalid Credentials

Token Expired

Insufficient Scope

JWT Payload Structure

Best Practices

Rate Limits

​Authentication

​Overview

​Getting Your Credentials

​App Types & Scopes

​Token Lifecycle

​Step 1: Obtain Access Token

​Response

​Step 2: Use Token in Requests

​Step 3: Refresh Token (Optional)

​Response

​Error Responses

​Invalid Credentials

​Token Expired

​Insufficient Scope

​JWT Payload Structure

​Best Practices

​Rate Limits

Authentication

Overview

Getting Your Credentials

App Types & Scopes

Token Lifecycle

Step 1: Obtain Access Token

Response

Step 2: Use Token in Requests

Step 3: Refresh Token (Optional)

Response

Error Responses

Invalid Credentials

Token Expired

Insufficient Scope

JWT Payload Structure

Best Practices

Rate Limits