> ## 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.

# Customers API

> Customer management endpoints

## Overview

The Customers API provides endpoints for managing third-party customer accounts, including creating new customers, retrieving customer information

## Authentication

All endpoints require API key authentication via the `x-api-key` header.

## Endpoints

### Create Customer

Create a new customer account.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api-production.fossapay.com/api/v1/customers \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": "+1234567890",
        "metadata": {
          "source": "api"
        }
      }'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await fetch(
      "https://api-production.fossapay.com/api/v1/customers",
      {
        method: "POST",
        headers: {
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "John Doe",
          email: "john.doe@example.com",
          phone: "+1234567890",
          metadata: {
            source: "api",
          },
        }),
      },
    );
    ```
  </Tab>
</Tabs>

**Response (201 Created):**

```json theme={null}
{
  "id": "cust_123456789",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z"
}
```

### Get All Customers

Retrieve a list of all customers.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET https://api-production.fossapay.com/api/v1/customers \
      -H "x-api-key: YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

**Response (200 OK):**

```json theme={null}
[
  {
    "id": "cust_123456789",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "createdAt": "2023-01-01T00:00:00.000Z",
    "updatedAt": "2023-01-01T00:00:00.000Z"
  }
]
```

### Get Customer by ID

Retrieve a specific customer by their ID.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET https://api-production.fossapay.com/api/v1/customers/cust_123456789 \
      -H "x-api-key: YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

**Response (200 OK):**

```json theme={null}
{
  "id": "cust_123456789",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z"
}
```

## Crypto Wallet Endpoints

**Note:** Crypto wallet endpoints are separate from customer endpoints and have their own dedicated API paths.

The crypto wallet functionality provides endpoints for managing blockchain-based wallets.

### Create Crypto Wallet

Create a new crypto wallet for a customer.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api-production.fossapay.com/v1/wallets/crypto/create \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "network": "solana",
        "customerId": "550e8400-e29b-41d4-a716-446655440000"
      }'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await fetch(
      "https://api-production.fossapay.com/v1/wallets/crypto/create",
      {
        method: "POST",
        headers: {
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          network: "solana",
          customerId: "550e8400-e29b-41d4-a716-446655440000",
        }),
      },
    );
    ```
  </Tab>
</Tabs>

**Response (201 Created):**

```json theme={null}
{
  "success": true,
  "message": "Crypto wallet created successfully",
  "data": {
    "walletId": "user:u3d",
    "address": "2nNrjVxaAv***1JBn52FqyHMjZ76SaHmsBv6Zz7Xoo5v",
    "network": "solana"
  }
}
```

### Get Crypto Wallet by ID

Retrieve crypto wallet details by wallet ID.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET https://api-production.fossapay.com/v1/wallets/crypto/user:u3d \
      -H "x-api-key: YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

**Response (200 OK):**

```json theme={null}
{
  "status": "success",
  "statusCode": 200,
  "message": "Crypto wallet retrieved successfully",
  "data": [
    {
      "address": "YcnysYh3Y***PxkazFyiTx76Upv12iP4sNGeHA2H4z2",
      "network": "solana",
      "tokens": {
        "usdc": {
          "amount": "0",
          "rawAmount": "0"
        },
        "usdt": {
          "amount": "0",
          "rawAmount": "0"
        }
      }
    }
  ]
}
```

### Get Crypto Wallet by Address

Retrieve crypto wallet details by wallet address.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET https://api-production.fossapay.com/v1/wallets/crypto/address/YcnysYh3Y***PxkazFyiTx76Upv12iP4sNGeHA2H4z2 \
      -H "x-api-key: YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

**Response (200 OK):**

```json theme={null}
{
  "status": "success",
  "statusCode": 200,
  "message": "Crypto wallet retrieved successfully",
  "data": [
    {
      "address": "YcnysYh3Y***PxkazFyiTx76Upv12iP4sNGeHA2H4z2",
      "network": "solana",
      "tokens": {
        "usdc": {
          "amount": "0",
          "rawAmount": "0"
        },
        "usdt": {
          "amount": "0",
          "rawAmount": "0"
        }
      }
    }
  ]
}
```

### Get Crypto Wallet Transactions

Retrieve all transactions for a crypto wallet.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET "https://api-production.fossapay.com/v1/wallets/crypto/user:u3d/transactions?page=1&limit=10" \
      -H "x-api-key: YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

**Response (200 OK):**

```json theme={null}
{
  "status": "success",
  "statusCode": 200,
  "message": "Wallet transactions retrieved successfully",
  "data": {
    "transactions": [
      {
        "id": "9495d974-4807-4c44-bd01-f5a69283aecc",
        "reference": "PTY_CRYPTO_16TY0WY7MM717C9",
        "transactionType": "deposit",
        "status": "failed",
        "amountInCrypto": "10.00000000",
        "tokenSymbol": "usdxm",
        "blockchain": "solana",
        "createdAt": "2026-01-08T00:43:44+01:00"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 1,
      "totalItems": 1,
      "itemsPerPage": 10
    }
  }
}
```

### Get Single Crypto Wallet Transaction

Retrieve a single crypto wallet transaction by transaction ID.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET https://api-production.fossapay.com/v1/wallets/crypto/transactions/85503565-cb04-4ba7-abfb-b75193553086 \
      -H "x-api-key: YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

**Response (200 OK):**

```json theme={null}
{
  "status": "success",
  "statusCode": 200,
  "message": "Transaction retrieved successfully",
  "data": {
    "id": "85503565-cb04-4ba7-abfb-b75193553086",
    "reference": "PTY_CRYPTO_NWC3GZ6832M9VFQ",
    "transactionType": "deposit",
    "status": "failed",
    "amountInCrypto": "10.00000000",
    "tokenSymbol": "usdxm",
    "blockchain": "solana",
    "createdAt": "2026-01-08T00:38:24+01:00"
  }
}
```

## Webhooks

Customer-related events are available via webhooks:

* `customer.created`: Triggered when a new customer is created
* `customer.updated`: Triggered when customer information is updated