Skip to main content

​
Overview

The Customers API provides endpoints for managing third-party customer accounts, including creating new customers, retrieving customer information, and checking tier status.

​
Authentication

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

​
Endpoints

​
Create Customer

Create a new customer account. 
curl -X POST https://api-staging.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"
    }
  }'
Response (201 Created): 
{
  "id": "cust_123456789",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "tier": "basic",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z"
}

​
Get All Customers

Retrieve a list of all customers. 
curl -X GET https://api-staging.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",
    "tier": "basic",
    "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 -X GET https://api-staging.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",
  "tier": "basic",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z"
}

​
Get Customer Tier Status

Retrieve the tier status and limits for a specific customer. 
curl -X GET https://api-staging.fossapay.com/api/v1/customers/cust_123456789/tier-status \
  -H "x-api-key: YOUR_API_KEY"
Response (200 OK): 
{
  "tier": "basic",
  "limits": {
    "maxTransactions": 100,
    "maxAmount": 10000
  },
  "status": "active"
}

​
Error Responses

​
400 Bad Request

{
  "error": 400,
  "message": "Validation failed"
}

​
401 Unauthorized

{
  "error": 401,
  "message": "Invalid API key"
}

​
404 Not Found

{
  "error": 404,
  "message": "Customer not found"
}

​
Customer Tiers

  • Basic: Standard tier with basic limits
  • Premium: Enhanced features and higher limits
  • Enterprise: Custom solutions and maximum limits

​
Rate Limits

  • Maximum 100 requests per minute per API key
  • Burst limit of 20 requests per second

​
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 -X POST https://api.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"
  }'
Response (201 Created): 
{
  "success": true,
  "message": "Crypto wallet created successfully",
  "data": {
    "walletId": "user:u3d",
    "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "network": "solana"
  }
}

​
Get Crypto Wallet by ID

Retrieve crypto wallet details by wallet ID. 
curl -X GET https://api.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": "CcnysYh3Y1ZLqPxkazFyiTx76Upv12iP4sNGeHA2H4z2",
      "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 -X GET https://api.fossapay.com/v1/wallets/crypto/address/CcnysYh3Y1ZLqPxkazFyiTx76Upv12iP4sNGeHA2H4z2 \
  -H "x-api-key: YOUR_API_KEY"
Response (200 OK): 
{
  "status": "success",
  "statusCode": 200,
  "message": "Crypto wallet retrieved successfully",
  "data": [
    {
      "address": "CcnysYh3Y1ZLqPxkazFyiTx76Upv12iP4sNGeHA2H4z2",
      "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 -X GET "https://api.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 -X GET https://api.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
  • customer.tier_changed: Triggered when customer tier is modified