​
Get Your API Keys

First, you’ll need to obtain your API credentials:
1

Register Your Application

Log in to the HOST Pay dashboard and register your application
2

Generate API Credentials

Navigate to your application settings and generate Test Mode credentials
3

Save Your Keys

Securely store your api-key and secret-key
Never share your secret keys or commit them to version control. Use environment variables to store credentials.

​
Make Your First API Call

Let’s create a user and their wallet: 
curl --request POST \
  --url https://hpay-api.host-sl.com/api/v1/users/create/ \
  --header 'api-key: YOUR_API_KEY' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_user_id": 1001,
    "name": "John Doe",
    "email": "john@example.com",
    "phone_number": "+23279123456"
  }'

​
Response

{
  "id": "9b2c1f0e-8a3d-4c7b-9e1a-2f5d6c8b0a11",
  "app_user_id": 1001,
  "name": "John Doe",
  "email": "john@example.com",
  "phone_number": "+23279123456",
  "is_active": true,
  "created_at": "2025-01-16T10:30:00Z",
  "updated_at": "2025-01-16T10:30:00Z"
}
app_user_id is your identifier for the user in your own system — it’s required so you can reconcile HOST Pay users with your database. id (a UUID) is HOST Pay’s identifier; use it for the wallet and transaction calls below.

​
Create a Wallet for the User

After creating a user, you need to create a wallet for them: 
curl --request POST \
  --url https://hpay-api.host-sl.com/api/v1/wallets/create/user_abc123xyz/ \
  --header 'api-key: YOUR_API_KEY' \
  --header 'secret-key: YOUR_SECRET_KEY'

​
Get the User’s Wallet

Now retrieve the wallet for the user you just created: 
curl --request GET \
  --url https://hpay-api.host-sl.com/api/v1/wallets/user_abc123xyz/ \
  --header 'api-key: YOUR_API_KEY' \
  --header 'secret-key: YOUR_SECRET_KEY'

​
Response

{
  "id": "wallet_def456uvw",
  "user_id": "user_abc123xyz",
  "balance": 0.0,
  "currency": "USD",
  "is_active": true,
  "created_at": "2025-01-16T10:30:00Z",
  "updated_at": "2025-01-16T10:30:00Z"
}

​
Make a Deposit

You can add funds to wallets using either card payments (Stripe) or mobile money (Monime). You’ll need to provide your Stripe and Monime credentials when setting up your application.

​
Option 1: Card Deposit (Stripe)

Test card deposits using Stripe test cards in Test Mode: 
curl --request POST \
  --url https://hpay-api.host-sl.com/api/v1/transactions/wallet/card-deposit/create \
  --header 'api-key: YOUR_API_KEY' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "wallet_id": "wallet_def456uvw",
    "amount": 50.00
  }'
Test Cards for Stripe:
  • 4242 4242 4242 4242 - Visa (succeeds)
  • 4000 0000 0000 0002 - Visa (card declined)
  • Use any future expiry date and any 3-digit CVC
Card deposits use your Stripe credentials. In test mode, use Stripe test cards. In live mode, real cards are charged.

​
Option 2: Mobile Money Deposit (Monime)

Add funds using mobile money in Sierra Leone: 
curl --request POST \
  --url https://hpay-api.host-sl.com/api/v1/transactions/wallet/mobile-money-deposit \
  --header 'api-key: YOUR_API_KEY' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "wallet_id": "wallet_def456uvw",
    "amount": 100.00
  }'

​
Response

{
  "transaction_id": "txn_ghi789rst",
  "payment_code": {
    "success": true,
    "result": {
      "id": "pmc_123456",
      "ussdCode": "*715*1234567890#",
      "status": "pending",
      "amount": {
        "currency": "USD",
        "value": 100.0
      }
    }
  },
  "transaction": {
    "id": "txn_ghi789rst",
    "wallet_id": "wallet_def456uvw",
    "amount": 100.0,
    "currency": "USD",
    "status": "pending",
    "payment_method": "mobile_money"
  }
}
Currency Conversion: When using mobile money, users enter amounts in Sierra Leone Leones (SLE). The system automatically converts to USD using real-time exchange rates and credits the wallet in USD.
Mobile money deposits use your Monime credentials. In test mode, the deposit will use our Mock Monime service. In live mode, customers will receive a real USSD code to complete payment.

​
Next Steps

Authentication

Learn about API authentication in detail

Test vs Live

Understand test and live environments

Webhooks

Set up real-time event notifications

API Reference

Explore all available endpoints

​
Common Patterns

​
Creating Multiple Users

users = [
    {"app_user_id": 1001, "name": "Alice", "email": "alice@example.com", "phone_number": "+23279111111"},
    {"app_user_id": 1002, "name": "Bob", "email": "bob@example.com", "phone_number": "+23279222222"},
    {"app_user_id": 1003, "name": "Charlie", "email": "charlie@example.com", "phone_number": "+23279333333"}
]

for user_data in users:
    response = requests.post(
        "https://hpay-api.host-sl.com/api/v1/users/create/",
        json=user_data,
        headers=headers
    )
    print(f"Created user: {response.json()['id']}")

​
Checking Transaction Status

transaction_id = "txn_ghi789rst"
response = requests.get(
    f"https://hpay-api.host-sl.com/api/v1/transactions/{transaction_id}",
    headers=headers
)

transaction = response.json()
print(f"Status: {transaction['status']}")

​
Troubleshooting

Check that your api-key and secret-key are correct and properly included in the headers.
Verify that the resource ID (user_id, wallet_id, etc.) exists and is spelled correctly.
The user or wallet may be disabled. Check the is_active status of the resource. Additionally, for client-managed applications, this error is raised if your prepaid wallet balance drops below the overdraft limit. Top up your balance via the dashboard’s Billing page.
Contact support with the error details and timestamp for assistance.