> ## Documentation Index
> Fetch the complete documentation index at: https://doc.hpay.host-sl.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Get started with HOST Pay API in under 5 minutes
## Get Your API Keys
First, you'll need to obtain your API credentials:
Log in to the HOST Pay dashboard and register your application
Navigate to your application settings and generate Test Mode credentials
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](https://pypi.org/project/hostpay/) or [TypeScript](https://www.npmjs.com/package/@hostpay/sdk)):
```bash Python theme={null}
pip install hostpay
```
```bash TypeScript theme={null}
npm install @hostpay/sdk
```
Then create a client with your Test Mode keys. Credentials are set once — every
call is authenticated automatically:
```python Python theme={null}
from hostpay import HostPay
client = HostPay(
api_key="YOUR_API_KEY",
secret_key="YOUR_SECRET_KEY",
)
```
```typescript TypeScript theme={null}
import { HostPay } from "@hostpay/sdk";
const client = new HostPay({
apiKey: "YOUR_API_KEY",
secretKey: "YOUR_SECRET_KEY",
});
```
Prefer raw HTTP? Every example below includes a cURL tab, and the [API
reference](/api-reference/introduction) documents every endpoint. See
[SDKs](/sdks) for the full client library guide.
## Make Your First API Call
Let's create a user and their wallet:
```python Python theme={null}
user = client.users.create(
app_user_id="user_1001",
name="John Doe",
email="john@example.com",
phone_number="+23279123456",
)
print(user["id"])
```
```typescript TypeScript theme={null}
const user = await client.users.create({
appUserId: "user_1001",
name: "John Doe",
email: "john@example.com",
phoneNumber: "+23279123456",
});
console.log(user.id);
```
```bash cURL theme={null}
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": "user_1001",
"name": "John Doe",
"email": "john@example.com",
"phone_number": "+23279123456"
}'
```
### Response
```json theme={null}
{
"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:
```python Python theme={null}
wallet = client.wallets.create(user["id"])
print(wallet["id"], wallet["balance"], wallet["currency"])
```
```typescript TypeScript theme={null}
const wallet = await client.wallets.create(user.id);
console.log(wallet.id, wallet.balance, wallet.currency);
```
```bash cURL theme={null}
curl --request POST \
--url https://hpay-api.host-sl.com/api/v1/wallets/create/USER_ID/ \
--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:
```python Python theme={null}
wallet = client.wallets.get(user["id"])
```
```typescript TypeScript theme={null}
const wallet = await client.wallets.get(user.id);
```
```bash cURL theme={null}
curl --request GET \
--url https://hpay-api.host-sl.com/api/v1/wallets/USER_ID/ \
--header 'api-key: YOUR_API_KEY' \
--header 'secret-key: YOUR_SECRET_KEY'
```
### Response
```json theme={null}
{
"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:
```python Python theme={null}
deposit = client.deposits.card(
wallet_id=wallet["id"],
amount=50.00,
)
```
```typescript TypeScript theme={null}
const deposit = await client.deposits.card({
walletId: wallet.id,
amount: 50.0,
});
```
```bash cURL theme={null}
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:
```python Python theme={null}
deposit = client.deposits.mobile_money(
wallet_id=wallet["id"],
amount=100,
)
print(deposit["transaction_id"], deposit["transaction"]["status"])
```
```typescript TypeScript theme={null}
const deposit = await client.deposits.mobileMoney({
walletId: wallet.id,
amount: 100,
});
console.log(deposit.transaction_id, deposit.transaction.status);
```
```bash cURL theme={null}
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
}'
```
### Response
```json theme={null}
{
"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](/guides/testing#magic-test-numbers)). In
live mode, customers will receive a real USSD code to complete payment.
## Next Steps
The full Python and TypeScript client library guide
Understand test and live environments
Set up real-time event notifications
Explore all available endpoints
## Common Patterns
### Creating Multiple Users
```python theme={null}
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:
```python theme={null}
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.