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

# Quickstart

> Start building with FossaPay in 10 minutes

## Get Started with FossaPay

This quickstart guide will have you making your first API call in minutes. We'll create a fiat wallet, simulate a payment, and handle the webhook notification.

## Prerequisites

Before you begin, make sure you have:

* A FossaPay account ([Sign up here](https://dashboard.fossapay.com/register))
* Your API keys from the [dashboard](https://dashboard.fossapay.com/settings?tab=api-keys)
* Node.js installed (or your preferred programming language)

## Step 1: Get Your API Keys

<Steps>
  <Step title="Sign up">
    Create an account at [dashboard.fossapay.com](https://dashboard.fossapay.com/register)
  </Step>

  <Step title="Get Test Keys">
    Navigate to **Settings** → **API Keys** and copy your test secret key (starts with `fp_test_sk_`)
  </Step>

  <Step title="Store Securely">
    Save your API key as an environment variable:

    ```bash theme={null}
    export FOSSAPAY_SECRET_KEY="fp_test_sk_xxxxxxxx"
    ```
  </Step>
</Steps>

## Step 2: Make Your First API Call

Use cURL for direct API calls.

## Step 3: Create Your First Fiat Wallet

Let's create a fiat wallet for collecting payments:

```bash theme={null}
curl -X POST https://api-production.fossapay.com/api/v1/wallets/fiat/create \
  -H "x-api-key: $FOSSAPAY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_123456789",
    "walletName": "Main Wallet",
    "walletReference": "wallet_ref_001"
  }'
```

**Expected Response:**

```json theme={null}
{
  "success": true,
  "message": "Fiat wallet created successfully",
  "data": {
    "walletId": "wal_abc123xyz",
    "bankName": "Wema Bank",
    "bankCode": "035",
    "accountNumber": "1234567890"
  }
}
```

<Success>
  **You created your first fiat wallet!** Customers can now transfer money to this account number.
</Success>

## Step 4: Handle Webhook Notification

When a payment is received, FossaPay sends a webhook to your server. Here's how to handle it:

<CodeGroup>
  ```javascript Express.js theme={null}
  const express = require('express');
  const crypto = require('crypto');
  const app = express();

  app.use(express.json());

  app.post('/webhooks/fossapay', (req, res) => {
    // 1. Verify webhook signature
    const signature = req.headers['x-fossapay-signature'];
    const isValid = verifySignature(req.body, signature);

    if (!isValid) {
      return res.status(401).send('Invalid signature');
    }

    // 2. Respond immediately
    res.status(200).send('Webhook received');

    // 3. Process the webhook
    const { event, data } = req.body;

    if (event === 'payment.received') {
      console.log('Payment received!');
      console.log('Amount:', data.amount);
      console.log('From:', data.sender_name);
      console.log('Transaction ID:', data.transaction_id);

      // Credit user wallet, update database, send notification, etc.
      creditUserWallet(data.metadata.customer_id, data.amount);
    }
  });

  function verifySignature(payload, signature) {
    const secret = process.env.FOSSAPAY_WEBHOOK_SECRET;
    const hash = crypto
      .createHmac('sha256', secret)
      .update(JSON.stringify(payload))
      .digest('hex');

    return hash === signature;
  }

  app.listen(3000, () => {
    console.log('Webhook server running on port 3000');
  });
  ```

  ```python Flask theme={null}
  from flask import Flask, request
  import hmac
  import hashlib
  import json
  import os

  app = Flask(__name__)

  @app.route('/webhooks/fossapay', methods=['POST'])
  def handle_webhook():
      # 1. Verify signature
      signature = request.headers.get('X-FossaPay-Signature')
      is_valid = verify_signature(request.data, signature)

      if not is_valid:
          return 'Invalid signature', 401

      # 2. Respond immediately
      payload = request.json

      # 3. Process webhook
      event = payload['event']
      data = payload['data']

      if event == 'payment.received':
          print('Payment received!')
          print(f'Amount: {data["amount"]}')
          print(f'From: {data["sender_name"]}')
          print(f'Transaction ID: {data["transaction_id"]}')

          # Credit user wallet, update database, etc.
          credit_user_wallet(data['metadata']['user_id'], data['amount'])

      return 'Webhook received', 200

  def verify_signature(payload, signature):
      secret = os.environ['FOSSAPAY_WEBHOOK_SECRET']
      hash = hmac.new(
          secret.encode(),
          payload,
          hashlib.sha256
      ).hexdigest()

      return hmac.compare_digest(hash, signature)

  if __name__ == '__main__':
      app.run(port=3000)
  ```
</CodeGroup>

<Tip>
  **Local Testing:** Use [ngrok](https://ngrok.com) to expose your local server for webhook testing:

  ```bash theme={null}
  ngrok http 3000
  ```

  Then set the ngrok URL in your [webhook settings](https://dashboard.fossapay.com/settings/webhooks).
</Tip>

## Step 6: Send a Payout

Now let's send money from your wallet to a bank account:

```bash theme={null}
curl -X POST https://api-production.fossapay.com/api/v1/transfers/fiat/inter-bank \
  -H "x-api-key: $FOSSAPAY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "550e8400-e29b-41d4-a716-446655440000",
    "destinationBankCode": "044",
    "destinationAccountName": "Test Recipient",
    "destinationAccountNumber": "0000000001",
    "destinationBankName": "ACCESS BANK",
    "reference": "payout-'$(date +%s)'",
    "remarks": "Test payout",
    "amount": 25000
  }'
```

## Complete Example

Here's a complete example that ties everything together:

```javascript theme={null}
const express = require('express');
const app = express();

app.use(express.json());

// Handle incoming payments
app.post('/webhooks/fossapay', async (req, res) => {
  res.status(200).send('OK');

  const { event, data } = req.body;

  if (event === 'deposit.completed') {
    // Credit user's balance
    await creditUserBalance(data.customerId, data.amount);

    // Send notification
    await sendNotification(data.customerId, {
      title: 'Payment Received',
      message: `Your account was credited with ₦${data.amount / 100}`
    });
  }
});

app.listen(3000);
```

## Next Steps

<CardGroup cols={2}>
  <Card color="#0080FF" title="Authentication" icon="lock" href="/authentication">
    Learn about API authentication and security
  </Card>

  <Card color="#0080FF" title="Collections Guide" icon="book" href="/guides/collections">
    Complete guide to accepting payments
  </Card>

  <Card color="#0080FF" title="Payouts Guide" icon="money-bill-transfer" href="/guides/payouts">
    Send money to bank accounts
  </Card>

  <Card color="#0080FF" title="Webhooks" icon="webhook" href="/concepts/webhooks">
    Handle real-time notifications
  </Card>
</CardGroup>

## Testing Checklist

Before going to production, make sure you've tested:

* [ ] Creating a customer
* [ ] Creating virtual accounts
* [ ] Receiving and processing webhooks
* [ ] Handling webhook failures
* [ ] Sending payouts
* [ ] Error handling
* [ ] Webhook signature verification

## Going Live

When you're ready for production:

1. **Complete business verification** in the [dashboard](https://dashboard.fossapay.com)
2. **Switch to live API keys** (starts with `fp_live_sk_`)
3. **Update webhook URL** to your production server
4. **Test with small amounts** before full launch
5. **Monitor the dashboard** for any issues

<Card color="#0080FF" title="Get Live API Keys" icon="rocket" href="https://dashboard.fossapay.com/settings?tab=api-keys">
  Complete verification to get live access
</Card>

## Need Help?

<CardGroup cols={2}>
  <Card color="#0080FF" title="Join Community" icon="users" href="https://t.me/+N1-Gq6L5WStmYWM8">
    Get help from the FossaPay community
  </Card>

  <Card color="#0080FF" title="Contact Support" icon="headset" href="mailto:product@fossapay.com">
    Email our support team
  </Card>

  <Card color="#0080FF" title="API Reference" icon="code" href="/api-reference/">
    Explore the full API documentation
  </Card>

  <Card color="#0080FF" title="Dashboard" icon="chart-line" href="https://dashboard.fossapay.com">
    View your transactions and settings
  </Card>
</CardGroup>