# Fyatu API — Complete Reference for AI Assistants

> This file contains the complete Fyatu API v3 reference with all endpoints, parameters, code examples, webhook events, and error codes. Use this to generate accurate integration code for developers.

## API Base

- **Base URL:** `https://api.fyatu.com/api/v3`
- **Authentication:** Bearer JWT token
- **Content-Type:** `application/json`
- **OpenAPI Spec:** https://docs.fyatu.com/v3/openapi.json

## Authentication

### Generate Token

**POST** `/auth/token`

Request:
```json
{
  "appId": "YOUR_APP_ID",
  "secretKey": "sk_live_xxxxxxxxxxxxx",
  "grantType": "client_credentials"
}
```

Response:
```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "tokenType": "Bearer",
  "expiresIn": 86400,
  "expiresAt": "2026-03-24T10:00:00Z"
}
```

Use the token in all subsequent requests:
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

### Refresh Token — **POST** `/auth/refresh`
### Revoke Token — **POST** `/auth/revoke`

---

## Card Products (BINs)

**GET** `/cards/products`

Available products:

| Product ID | Brand | Currency | Type | Issuance Fee | New Cards |
|-----------|-------|----------|------|-------------|-----------|
| `MCWORLDUSD` | MASTERCARD | USD | PREPAID | $5.00 | Yes (default) |
| `MCWORLDEUR` | MASTERCARD | EUR | PREPAID | $5.00 | Yes |
| `VISAPLATINUMUSD` | VISA | USD | PREPAID | $10.00 | No (existing only) |

All cards support 3D Secure. VISAPLATINUMUSD supports Apple Pay and Google Pay tokenization.

---

## Cardholders

### Create Cardholder

**POST** `/cardholders`

```json
{
  "externalId": "user-123",
  "firstName": "James",
  "lastName": "Wilson",
  "email": "james@example.com",
  "phone": "+243810000000",
  "dateOfBirth": "1990-01-15",
  "gender": "male",
  "address": "123 Main Street",
  "city": "Kinshasa",
  "state": "Kinshasa",
  "country": "CD",
  "zipCode": "00000"
}
```

Response includes `id`, `status`, `kycStatus`, and timestamps.

### Other Cardholder Endpoints

- **GET** `/cardholders` — List all cardholders
- **GET** `/cardholders/{id}` — Get cardholder details
- **PATCH** `/cardholders/{id}` — Update cardholder
- **DELETE** `/cardholders/{id}` — Delete cardholder
- **POST** `/cardholders/{id}/kyc` — Submit KYC documents

---

## Cards

### Create Card (Issue a Virtual Card)

**POST** `/cards`

| Field | Type | Required | Details |
|-------|------|----------|---------|
| `cardholderId` | string | Yes | Cardholder ID |
| `amount` | number | Yes | Initial funding (min $5 or €5) |
| `name` | string | No | Card name (defaults to cardholder name) |
| `productId` | string | No | Card product (defaults to `MCWORLDUSD`) |

#### Node.js Example

```javascript
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_1a2b3c4d5e6f7890abcdef1234567890',
    amount: 100.00,
    name: 'JAMES WILSON',
    productId: 'MCWORLDUSD'
  })
});

const result = await response.json();
// result.data.id — card ID
// result.data.last4 — last 4 digits
// result.data.maskedNumber — masked card number
// result.data.expiryDate — MM/YYYY
// result.data.brand — MASTERCARD
// result.data.status — ACTIVE
```

#### PHP Example

```php
$data = [
    'cardholderId' => 'ch_1a2b3c4d5e6f7890abcdef1234567890',
    'amount' => 100.00,
    'name' => 'JAMES WILSON',
    'productId' => 'MCWORLDUSD'
];

$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);
// $result['data']['id'] — card ID
// $result['data']['maskedNumber'] — 5xxx xxxx xxxx 1234
```

#### EUR Card Example

```javascript
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_1a2b3c4d5e6f7890abcdef1234567890',
    amount: 100.00,
    productId: 'MCWORLDEUR'
  })
});
```

Response (201):
```json
{
  "success": true,
  "status": 201,
  "data": {
    "id": "crd_8f3a2b1c4d5e6f7890abcdef12345678",
    "cardholderId": "ch_1a2b3c4d5e6f7890abcdef1234567890",
    "name": "JAMES WILSON",
    "last4": "1234",
    "maskedNumber": "5xxx xxxx xxxx 1234",
    "expiryDate": "12/2028",
    "brand": "MASTERCARD",
    "currency": "USD",
    "status": "ACTIVE",
    "initialBalance": 100.00,
    "createdAt": "2026-03-23T10:00:00Z"
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-23T10:00:00Z"
  }
}
```

### Fund Card

**POST** `/cards/{cardId}/fund`

| Field | Type | Required | Details |
|-------|------|----------|---------|
| `amount` | number | Yes | USD amount (minimum $5) |
| `reference` | string | No | Custom reference for reconciliation |

```javascript
const response = await fetch(`https://api.fyatu.com/api/v3/cards/${cardId}/fund`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ amount: 50.00, reference: 'my-order-12345' })
});
```

Response:
```json
{
  "success": true,
  "status": 200,
  "message": "Card funded successfully",
  "data": {
    "cardId": "crd_8f3a2b1c4d5e6f7890abcdef12345678",
    "amountFunded": 50,
    "fee": 0.5,
    "reference": "my-order-12345"
  }
}
```

### Other Card Endpoints

- **POST** `/cards/{cardId}/unload` — Withdraw card balance
- **POST** `/cards/{cardId}/freeze` — Freeze card
- **POST** `/cards/{cardId}/unfreeze` — Unfreeze card
- **DELETE** `/cards/{cardId}` — Terminate card permanently
- **POST** `/cards/{cardId}/replace` — Replace card
- **GET** `/cards` — List all cards
- **GET** `/cards/{cardId}` — Get card details
- **GET** `/cards/{cardId}/transactions` — Get card transactions

---

## Collections

### Create Collection (Payment Session)

**POST** `/collections`

```json
{
  "amount": 25.00,
  "orderId": "order-456",
  "description": "Premium subscription",
  "callbackUrl": "https://yoursite.com/payment/success",
  "webhookUrl": "https://yoursite.com/webhooks/fyatu",
  "metadata": { "userId": "user-789" }
}
```

Returns `checkoutUrl` to redirect customers. Sessions expire after 60 minutes.

- **GET** `/collections` — List collections
- **GET** `/collections/{id}` — Get collection details

---

## Payouts

- **POST** `/payouts` — Create payout
- **GET** `/payouts` — List payouts
- **GET** `/payouts/{id}` — Get payout details
- **POST** `/payouts/verify-account` — Verify recipient account

---

## Refunds

- **POST** `/refunds` — Create refund
- **GET** `/refunds` — List refunds
- **GET** `/refunds/reasons` — Get refund reasons

---

## eSIM

- **GET** `/esim/countries` — List supported countries
- **GET** `/esim/destinations` — List destinations
- **GET** `/esim/destinations/{id}` — Destination details
- **GET** `/esim/packages` — List packages
- **GET** `/esim/packages/{id}` — Package details
- **POST** `/esim/purchase` — Purchase eSIM
- **POST** `/esim/{id}/topup` — Top up data
- **GET** `/esim/{id}/topups` — Top-up packages
- **GET** `/esim` — List eSIMs
- **GET** `/esim/{id}` — eSIM details
- **POST** `/esim/{id}/refresh` — Refresh usage
- **GET** `/esim/devices` — Compatible devices
- **GET** `/esim/{id}/installation` — Installation instructions

---

## Account & Wallet

- **GET** `/account/wallet` — Wallet balance
- **GET** `/account/transactions` — Transaction history
- **GET** `/account/transactions/{id}` — Transaction details
- **GET** `/account/pricing` — Current fees
- **POST** `/account/deposit-address` — Generate USDT deposit address
- **POST** `/account/withdraw` — Request withdrawal
- **POST** `/account/withdrawal-address` — Register withdrawal address
- **GET** `/account/withdrawals` — List withdrawals

---

## Webhooks

### Configuration

- **PUT** `/webhooks` — Set webhook URL (returns webhookSecret, shown once)
- **GET** `/webhooks` — Get current webhook config
- **POST** `/webhooks/regenerate-secret` — Regenerate signing secret
- **POST** `/webhooks/test` — Send test event
- **GET** `/webhooks/events` — List available event types

### Payload Structure

```json
{
  "event": "card.transaction.approved",
  "version": "2.0",
  "sign": "hmac-sha256-signature",
  "data": { ... }
}
```

### All Webhook Events (31 total)

**Card Events (11):**
- `card.created` — Virtual card issued
- `card.funded` — Balance increased
- `card.unloaded` — Balance withdrawn
- `card.frozen` — Card frozen
- `card.unfrozen` — Card unfrozen
- `card.terminated` — Card permanently deactivated
- `card.replaced` — Card replaced
- `card.transaction.approved` — Purchase successful
- `card.transaction.declined` — Purchase rejected
- `card.transaction.reversed` — Merchant refund
- `card.tokenization_otp` — Digital wallet OTP code

**Cardholder Events (4):**
- `cardholder.created` — Account created
- `cardholder.kyc_submitted` — Documents uploaded
- `cardholder.kyc_approved` — Verification passed
- `cardholder.kyc_rejected` — Verification failed

**Collection Events (4):**
- `collection.initiated` — Payment request created
- `collection.received` — Payment processed
- `collection.failed` — Payment failed
- `collection.expired` — Payment request expired

**Payout Events (3):**
- `payout.initiated` — Payout created
- `payout.completed` — Funds transferred
- `payout.failed` — Payout failed

**Refund Events (3):**
- `refund.initiated` — Refund created
- `refund.completed` — Refund processed
- `refund.failed` — Refund failed

**eSIM Events (6):**
- `esim.purchased` — eSIM acquired
- `esim.topped_up` — Data renewed
- `esim.activated` — First use in coverage area
- `esim.data_warning` — Usage at 80%
- `esim.data_exhausted` — Data consumed
- `esim.expired` — Validity ended

### Signature Verification

```javascript
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
```

### Best Practices
- Respond within 5 seconds with HTTP 200
- Always verify HMAC signatures before processing
- Implement idempotency using reference fields
- Process events asynchronously (queue for background work)

---

## Error Codes

| Code | HTTP | Meaning |
|------|------|---------|
| `VALIDATION_ERROR` | 400 | Invalid input parameters |
| `CARDHOLDER_INACTIVE` | 400 | Cardholder KYC not verified |
| `INSUFFICIENT_BALANCE` | 400 | Wallet lacks funds |
| `PRODUCT_NOT_FOUND` | 400 | Invalid card product ID |
| `BUSINESS_KYB_REQUIRED` | 400 | Business verification incomplete |
| `CARD_NOT_ACTIVE` | 400 | Card frozen/suspended/terminated |
| `CARD_FROZEN` | 400 | Card frozen by bank partner |
| `CARD_TERMINATED` | 400 | Card permanently closed |
| `AUTH_TOKEN_INVALID` | 401 | Invalid or expired token |
| `RESOURCE_NOT_FOUND` | 404 | Resource not found |
| `CARD_CREATION_FAILED` | 500 | Provider-side error |
| `PROVIDER_NOT_CONFIGURED` | 500 | Setup incomplete |
| `DEBIT_FAILED` | 500 | Wallet debit failed |
| `FUNDING_FAILED` | 500 | Card funding failed |

---

## Prerequisites to Use the API

1. Create account at https://web.fyatu.com/auth/register
2. Complete identity verification (KYC)
3. Upgrade to Business account
4. Create an app (Collection or Issuing type)
5. Fund wallet with minimum $10 USDT
6. Generate API credentials (appId + secretKey)

---

## About

- **Company:** Fyatu Financial Technologies Limited
- **Users:** 1,000,000+ across Africa
- **Countries:** 180+ supported for transfers
- **Compliance:** PCI DSS, GDPR, SSL certified
- **API Uptime:** 99.9% SLA
- **Support:** developers@fyatu.com
- **Documentation:** https://docs.fyatu.com
- **Website:** https://fyatu.com