Skip to main content

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

​
Install the SDK

The fastest way to integrate is with an official SDK (Python or TypeScript): 
pip install hostpay
Then create a client with your Test Mode keys. Credentials are set once — every call is authenticated automatically: 
from hostpay import HostPay

client = HostPay(
    api_key="YOUR_API_KEY",
    secret_key="YOUR_SECRET_KEY",
)
Prefer raw HTTP? Every example below includes a cURL tab, and the API reference documents every endpoint. See SDKs for the full client library guide.

​
Make Your First API Call

Let’s create a user and their wallet: 
user = client.users.create(
    app_user_id="user_1001",
    name="John Doe",
    email="john@example.com",
    phone_number="+23279123456",
)
print(user["id"])

​
Response

{
  "id": "9b2c1f0e-8a3d-4c7b-9e1a-2f5d6c8b0a11",
  "app_user_id": "user_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. It’s a string, so you can use any identifier (e.g. user_1001, a UUID, or a plain number — numeric values are accepted and returned as strings). It cannot be changed after creation. 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: 
wallet = client.wallets.create(user["id"])
print(wallet["id"], wallet["balance"], wallet["currency"])

​
Get the User’s Wallet

Now retrieve the wallet for the user you just created: 
wallet = client.wallets.get(user["id"])

​
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: 
deposit = client.deposits.card(
    wallet_id=wallet["id"],
    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: 
deposit = client.deposits.mobile_money(
    wallet_id=wallet["id"],
    amount=100,
)
print(deposit["transaction_id"], deposit["transaction"]["status"])

​
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 — and the user’s phone number controls the outcome (see magic test numbers). In live mode, customers will receive a real USSD code to complete payment.

​
Next Steps

SDKs

The full Python and TypeScript client library guide

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": "user_1001", "name": "Alice", "email": "alice@example.com", "phone_number": "+23279111111"},
    {"app_user_id": "user_1002", "name": "Bob", "email": "bob@example.com", "phone_number": "+23279222222"},
    {"app_user_id": "user_1003", "name": "Charlie", "email": "charlie@example.com", "phone_number": "+23279333333"}
]

for user_data in users:
    user = client.users.create(**user_data)
    print(f"Created user: {user['id']}")

​
Safe Retries with Idempotency

Money-moving calls accept an idempotency key — reuse the same key to retry without double-charging: 
client.deposits.mobile_money(
    wallet_id=wallet["id"],
    amount=100,
    idempotency_key="order-42-deposit",
)

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