Customers API

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.

cURL
Node.js

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"
    }
  }'

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",
      },
    }),
  },
);

Response (201 Created):

{
  "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.

cURL

curl -X GET https://api-production.fossapay.com/api/v1/customers \
  -H "x-api-key: YOUR_API_KEY"

Response (200 OK):

[
  {
    "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.

cURL

curl -X GET https://api-production.fossapay.com/api/v1/customers/cust_123456789 \
  -H "x-api-key: YOUR_API_KEY"

Response (200 OK):

{
  "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.

cURL
Node.js

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"
  }'

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",
    }),
  },
);

Response (201 Created):

{
  "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.

cURL

curl -X GET https://api-production.fossapay.com/v1/wallets/crypto/user:u3d \
  -H "x-api-key: YOUR_API_KEY"

Response (200 OK):

{
  "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.

cURL

curl -X GET https://api-production.fossapay.com/v1/wallets/crypto/address/YcnysYh3Y***PxkazFyiTx76Upv12iP4sNGeHA2H4z2 \
  -H "x-api-key: YOUR_API_KEY"

Response (200 OK):

{
  "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.

cURL

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"

Response (200 OK):

{
  "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.

cURL

curl -X GET https://api-production.fossapay.com/v1/wallets/crypto/transactions/85503565-cb04-4ba7-abfb-b75193553086 \
  -H "x-api-key: YOUR_API_KEY"

Response (200 OK):

{
  "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

Customers

Virtual Wallets

Fiat Transfers

Crypto Wallets

Crypto Transfers

Webhooks

Overview

Authentication

Endpoints

Create Customer

Get All Customers

Get Customer by ID

Crypto Wallet Endpoints

Create Crypto Wallet

Get Crypto Wallet by ID

Get Crypto Wallet by Address

Get Crypto Wallet Transactions

Get Single Crypto Wallet Transaction

Webhooks

​Overview

​Authentication

​Endpoints

​Create Customer

​Get All Customers

​Get Customer by ID

​Crypto Wallet Endpoints

​Create Crypto Wallet

​Get Crypto Wallet by ID

​Get Crypto Wallet by Address

​Get Crypto Wallet Transactions

​Get Single Crypto Wallet Transaction

​Webhooks

Overview

Authentication

Endpoints

Create Customer

Get All Customers

Get Customer by ID

Crypto Wallet Endpoints

Create Crypto Wallet

Get Crypto Wallet by ID

Get Crypto Wallet by Address

Get Crypto Wallet Transactions

Get Single Crypto Wallet Transaction

Webhooks