Skip to main content
POST
https://api.fossapay.com
/
v1
/
wallets
Create Wallet
curl --request POST \
  --url https://api.fossapay.com/v1/wallets \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "customer_id": "<string>",
  "customer_name": "<string>",
  "customer_email": "<string>",
  "currencies": [
    {}
  ],
  "metadata": {}
}
'
{
  "status": "success",
  "message": "Wallet created successfully",
  "data": {
    "wallet_id": "wal_abc123",
    "type": "customer",
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "currencies": ["NGN", "USDT"],
    "status": "active",
    "balances": [
      {
        "currency": "NGN",
        "available_balance": 0,
        "ledger_balance": 0
      },
      {
        "currency": "USDT",
        "available_balance": 0,
        "ledger_balance": 0
      }
    ],
    "metadata": {
      "user_id": "12345"
    },
    "created_at": "2024-01-15T10:00:00Z"
  }
}

​
Request

​
type
string
required
Wallet type: customer, merchant, or system
​
customer_id
string
Your internal customer ID
​
customer_name
string
required
Customer or wallet name
​
customer_email
string
required
Customer email address
​
currencies
array
required
Array of currency codes to support (e.g., [“NGN”, “USDT”])
​
metadata
object
Custom metadata

​
Request Example

curl -X POST https://api.fossapay.com/v1/wallets \
  -H "Authorization: Bearer fp_live_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "customer",
    "customer_id": "cus_123",
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "currencies": ["NGN", "USDT"],
    "metadata": {
      "user_id": "12345"
    }
  }'

const wallet = await client.wallets.create({
  type: 'customer',
  customer_name: 'John Doe',
  customer_email: '[email protected]',
  currencies: ['NGN', 'USDT']
});

​
Response

{
  "status": "success",
  "message": "Wallet created successfully",
  "data": {
    "wallet_id": "wal_abc123",
    "type": "customer",
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "currencies": ["NGN", "USDT"],
    "status": "active",
    "balances": [
      {
        "currency": "NGN",
        "available_balance": 0,
        "ledger_balance": 0
      },
      {
        "currency": "USDT",
        "available_balance": 0,
        "ledger_balance": 0
      }
    ],
    "metadata": {
      "user_id": "12345"
    },
    "created_at": "2024-01-15T10:00:00Z"
  }
}