> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get started with Fyatu's card issuing API in under 5 minutes. Authenticate, create a cardholder, issue your first virtual Mastercard, and set up webhooks.

# Quick Start Guide

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

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

## Prerequisites

<Steps>
  <Step title="Create Account">
    Sign up for a free FYATU account at [web.fyatu.com/auth/register](https://web.fyatu.com/auth/register)
  </Step>

  <Step title="Verify Your Identity (KYC)">
    Submit your identity documents to verify your account
  </Step>

  <Step title="Upgrade to Business">
    Upgrade your account to Business from the dashboard
  </Step>

  <Step title="Create an App">
    Create a **Collection App** or **Issuing App** from your Business Console
  </Step>

  <Step title="Fund Your Wallet">
    Deposit USDT to your business wallet (minimum \$10 to get started)
  </Step>
</Steps>

## Step 1: Get Your Credentials

Log into your [Business Console](https://web.fyatu.com/business/apps), 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` |

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

## Step 2: Get an Access Token

Exchange your credentials for a JWT access token:

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  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.accessToken;
  ```

  ```python Python theme={null}
  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']
  ```

  ```php PHP theme={null}
  $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'];
  ```
</CodeGroup>

You should receive a response like:

```json theme={null}
{
  "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:

```bash theme={null}
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:

<Tabs>
  <Tab title="Issuing App">
    ### Create a Cardholder

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.fyatu.com/api/v3/cardholders" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "externalId": "EXT-0001",
          "firstName": "Alice",
          "lastName": "Example",
          "email": "alice@example.com",
          "phone": "+15550001234",
          "dateOfBirth": "1990-01-01",
          "gender: 'FEMALE'",
          "address": "123 Main Street, Apt 4B",
          "city": "Newark",
          "state": "Delaware",
          "country": "US",
          "zipCode": "000000"
        }'
      ```

      ```javascript Node.js theme={null}
      const response = await fetch('https://api.fyatu.com/api/v3/cardholders', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          externalId: 'EXT-0001',
          firstName: 'Alice',
          lastName: 'Example',
          email: 'alice@example.com',
          phone: '+15550001234',
          dateOfBirth: '1990-01-01',
          gender: 'FEMALE'',
          address: '123 Main Street, Apt 4B',
          city: 'Newark',
          state: 'Delaware',
          country: 'US',
          zipCode: '000000'
        })
      });

      const result = await response.json();
      console.log('Cardholder ID:', result.data.id);
      ```

      ```php PHP theme={null}
      $data = [
          'externalId' => 'EXT-0001',
          'firstName' => 'Alice',
          'lastName' => 'Example',
          'email' => 'alice@example.com',
          'phone' => '+15550001234',
          'dateOfBirth' => '1990-01-01',
          'gender: 'FEMALE'',
          'address' => '123 Main Street, Apt 4B',
          'city' => 'Newark',
          'state' => 'Delaware',
          'country' => 'US',
          'zipCode' => '000000'
      ];

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

      $result = json_decode(curl_exec($ch), true);
      echo 'Cardholder ID: ' . $result['data']['id'];
      ```
    </CodeGroup>

    ```json Response (201) theme={null}
    {
      "success": true,
      "status": 201,
      "message": "Cardholder created successfully",
      "data": {
        "id": "CH1a2b3c4d5e6f",
        "externalId": "EXT-0001",
        "firstName": "Alice",
        "lastName": "Example",
        "email": "alice@example.com",
        "phone": "+15550001234",
        "dateOfBirth": "1990-01-01",
        "gender: 'FEMALE'",
        "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

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.fyatu.com/api/v3/cards" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "cardholderId": "CH1a2b3c4d5e6f",
          "amount": 100.00,
          "name": "JOHN SMITH",
          "productId": "MCUSD1"
        }'
      ```

      ```javascript Node.js theme={null}
      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: 'CH1a2b3c4d5e6f',
          amount: 100.00,
          name: 'JOHN SMITH',
          productId: 'MCUSD1'
        })
      });

      const result = await response.json();
      console.log('Card ID:', result.data.id);
      console.log('Last 4:', result.data.last4);
      ```

      ```php PHP theme={null}
      $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([
              'cardholderId' => 'CH1a2b3c4d5e6f',
              'amount' => 100.00,
              'name' => 'JOHN SMITH',
              'productId' => 'MCUSD1'
          ])
      ]);

      $result = json_decode(curl_exec($ch), true);
      echo 'Card ID: ' . $result['data']['id'];
      ```
    </CodeGroup>

    ```json Response (201) theme={null}
    {
      "success": true,
      "status": 201,
      "message": "Card created successfully",
      "data": {
        "id": "crd_9x8y7z6w5v4u3t2s",
        "cardholderId": "CH1a2b3c4d5e6f",
        "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"
      }
    }
    ```

    <Warning>
      Card details (full number, CVV) are returned only on the [Get Card](/v3/api-reference/cards/get) endpoint. Always handle them securely and never log or expose them.
    </Warning>
  </Tab>

  <Tab title="Collection App">
    ### Create a Collection (Payment)

    <CodeGroup>
      ```bash cURL theme={null}
      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"
          }
        }'
      ```

      ```javascript Node.js theme={null}
      const response = await fetch('https://api.fyatu.com/api/v3/collections', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          amount: 25.00,
          orderId: `INV-${Date.now()}`,
          description: 'Premium Subscription',
          callbackUrl: 'https://yoursite.com/payment/complete',
          webhookUrl: 'https://yoursite.com/webhook/fyatu',
          metadata: {
            userId: '12345',
            plan: 'premium'
          }
        })
      });

      const result = await response.json();

      if (result.success) {
        // Redirect your customer to the checkout page
        console.log('Checkout URL:', result.data.checkoutUrl);
      }
      ```

      ```php PHP theme={null}
      $ch = curl_init('https://api.fyatu.com/api/v3/collections');
      curl_setopt_array($ch, [
          CURLOPT_RETURNTRANSFER => true,
          CURLOPT_POST => true,
          CURLOPT_HTTPHEADER => [
              'Authorization: Bearer ' . $accessToken,
              'Content-Type: application/json'
          ],
          CURLOPT_POSTFIELDS => json_encode([
              'amount' => 25.00,
              'orderId' => 'INV-' . time(),
              'description' => 'Premium Subscription',
              'callbackUrl' => 'https://yoursite.com/payment/complete',
              'webhookUrl' => 'https://yoursite.com/webhook/fyatu',
              'metadata' => [
                  'userId' => '12345',
                  'plan' => 'premium'
              ]
          ])
      ]);

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

      if ($result['success']) {
          // Redirect customer to checkout
          header('Location: ' . $result['data']['checkoutUrl']);
          exit;
      }
      ```
    </CodeGroup>

    ```json Response (201) theme={null}
    {
      "success": true,
      "status": 201,
      "message": "Checkout session created successfully",
      "data": {
        "collectionId": "col_a1b2c3d4e5f6",
        "reference": "A2B4C6D8E0F2",
        "orderId": "ORD-0001",
        "amount": 25.00,
        "fee": 0.75,
        "netAmount": 24.25,
        "currency": "USD",
        "status": "PENDING",
        "checkoutUrl": "https://checkout.fyatu.com/sci/checkout?batch=col_a1b2c3d4e5f6",
        "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=col_a1b2c3d4e5f6&status=COMPLETED
    ```

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

    ```json theme={null}
    {
      "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": "Alice Example",
        "status": "SUCCESS",
        "appId": "DD123FR45446CECES",
        "timestamp": "2026-01-08T11:35:00+00:00"
      }
    }
    ```
  </Tab>
</Tabs>

## Step 4: Set Up Webhooks

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

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.fyatu.com/api/v3/webhooks', {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      webhookUrl: 'https://yoursite.com/webhooks/fyatu'
    })
  });

  const result = await response.json();
  // Store the webhook secret securely — it's only shown once!
  console.log('Webhook Secret:', result.data.webhookSecret);
  ```
</CodeGroup>

```json Response (200) theme={null}
{
  "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"
  }
}
```

<Warning>
  Your `webhookSecret` is only shown once when first generated. Store it securely — you'll need it to verify webhook signatures.
</Warning>

<Info>
  See the [Webhooks guide](/v3/concepts/webhooks) for the full list of events and payload structures.
</Info>

## What's Next?

<CardGroup cols={2}>
  <Card title="Authentication Deep Dive" icon="key" href="/v3/authentication">
    Token refresh, scopes, and best practices
  </Card>

  <Card title="Payment Collections" icon="money-bill-transfer" href="/v3/concepts/payments">
    Accept payments from Fyatu users
  </Card>

  <Card title="Card Issuing" icon="credit-card" href="/v3/concepts/cards">
    Learn about card lifecycle and operations
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/v3/errors">
    Handle API errors gracefully
  </Card>
</CardGroup>