--- title: Quick Start description: Make your first API call in 5 minutes --- Get up and running with the RizPay API in 5 minutes. ## Prerequisites - A RizPay business account - API access enabled in your settings - Your API key from [Settings > API Keys](https://my.rizpay.app/settings/api) > **Using Postman?** Download our [Postman Collection](/downloads/rizpay-partners-api.postman_collection.json) to get started quickly with pre-configured requests. ## Step 1: Get Your API Key 1. Log in at [my.rizpay.app](https://my.rizpay.app) 2. Go to **Settings > API Keys** 3. Click **Create New Key** 4. Select scopes and environment 5. Copy your secret key (shown only once!) Your key looks like: `sk_live_xxxxxxxxxxxx` (production) or `sk_test_xxxxxxxxxxxx` (sandbox) > **Warning:** Never share your secret key or commit it to version control. ## Step 2: Check Your Balance Verify your API key works: ```bash curl -X GET \ -H "Authorization: Bearer sk_live_your_secret_key" \ https://my.rizpay.app/api/partners/v1/account/balance ``` Response: ```json { "status": { "code": 200, "message": "Balance retrieved" }, "data": { "balance": "50000.00", "currency": "NGN", "updated_at": "2026-05-18T10:30:00+01:00" } } ``` ## Step 3: List Products See available airtime products: ```bash curl -X GET \ -H "Authorization: Bearer sk_live_your_secret_key" \ "https://my.rizpay.app/api/partners/v1/products/airtimes?network=MTN" ``` Response: ```json { "status": { "code": 200, "message": "Airtime products retrieved" }, "data": [ { "id": "prd_42", "type": "airtime", "attributes": { "display_name": "MTN Airtime", "network": "MTN", "min_amount": "50.0", "max_amount": "50000.0", "price": { "currency": "NGN", "basis": "face_value", "min_amount": "50.00", "max_amount": "50000.00" } } } ], "pagination": { "page": 1, "per_page": 20, "total_pages": 1, "total_count": 1 } } ``` Product ids are numeric with a `prd_` prefix (e.g. `prd_42`). Use the `id` from your own response in the next step. ## Step 4: Make a Purchase Purchase airtime: ```bash curl -X POST \ -H "Authorization: Bearer sk_live_your_secret_key" \ -H "Content-Type: application/json" \ -d '{ "product_id": "prd_42", "phone_number": "08012345678", "amount": "100.00", "external_reference": "1736234400A1B2C3" }' \ https://my.rizpay.app/api/partners/v1/purchases ``` Response: ```json { "status": { "code": 201, "message": "Purchase created successfully" }, "data": { "id": "txn_abc123", "type": "transaction", "attributes": { "amount": "100.0", "currency": "NGN", "status": "pending", "category": "purchase", "description": "Purchase of MTN Airtime", "reference": "a1b2c3d4e5f607181736234400", "external_reference": "1736234400A1B2C3", "product_type": "airtime", "phone_number": "08012345678", "meter_number": null, "price": { "product_amount": "100.00", "fee_amount": "0.00", "total_debit": "100.00", "currency": "NGN", "basis": "face_value" }, "created_at": "2026-05-18T10:35:00+01:00", "updated_at": "2026-05-18T10:35:00+01:00" } } } ``` > **Tip:** The `external_reference` must be exactly 16 characters: 10-digit Unix timestamp + 6 alphanumeric. See [Duplicate Prevention](/docs/core-concepts/duplicate-prevention) for code examples. ## Step 5: Check Status Poll the transaction status: ```bash curl -X GET \ -H "Authorization: Bearer sk_live_your_secret_key" \ https://my.rizpay.app/api/partners/v1/purchases/txn_abc123 ``` Response (when complete): ```json { "status": { "code": 200, "message": "Purchase details retrieved" }, "data": { "id": "txn_abc123", "type": "transaction", "attributes": { "amount": "100.0", "currency": "NGN", "status": "successful", "category": "purchase", "description": "Purchase of MTN Airtime", "reference": "a1b2c3d4e5f607181736234400", "external_reference": "1736234400A1B2C3", "product_type": "airtime", "phone_number": "08012345678", "meter_number": null, "price": { "product_amount": "100.00", "fee_amount": "0.00", "total_debit": "100.00", "currency": "NGN", "basis": "face_value" }, "created_at": "2026-05-18T10:35:00+01:00", "updated_at": "2026-05-18T10:35:02+01:00" } } } ``` The transaction is done when `status` reaches `successful`, `failed`, or `reversed`. There is no separate completion timestamp: use `updated_at`. ## Simple Node.js Example ```javascript const API_KEY = "sk_live_your_secret_key"; const BASE_URL = "https://my.rizpay.app/api/partners/v1"; // Generate external reference: 10-digit timestamp + 6 alphanumeric function generateReference() { const timestamp = Math.floor(Date.now() / 1000); const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"; let suffix = ""; for (let i = 0; i < 6; i++) { suffix += chars.charAt(Math.floor(Math.random() * chars.length)); } return `${timestamp}${suffix}`; } async function purchaseAirtime(phoneNumber, amount) { const response = await fetch(`${BASE_URL}/purchases`, { method: "POST", headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ product_id: "prd_42", // use a product id from GET /products/airtimes phone_number: phoneNumber, amount: amount, external_reference: generateReference(), }), }); return response.json(); } // Usage purchaseAirtime("08012345678", "500.00") .then((result) => console.log(result)) .catch((error) => console.error(error)); ``` ## Using the Sandbox For testing, use sandbox credentials: 1. Create a sandbox API key (`sk_test_*`) 2. Use the sandbox endpoint: `/api/partners/sandbox/v1` ```bash curl -X GET \ -H "Authorization: Bearer sk_test_your_test_key" \ https://my.rizpay.app/api/partners/sandbox/v1/account/balance ``` Sandbox purchases don't charge your account or deliver real airtime. The sandbox only recognizes specific test phone numbers (e.g. `08011111111` for an instant success); any other number fails with `PURCHASE_FAILED`. The [First Purchase guide](/docs/getting-started/first-purchase) lists them all and walks the full flow. ## Next Steps - [First Purchase](/docs/getting-started/first-purchase) - Complete a sandbox purchase end to end - [Authentication](/docs/getting-started/authentication) - Understand scopes and environments - [Error Handling](/docs/getting-started/errors) - Handle errors gracefully - [Airtime Guide](/docs/products/airtime) - Complete airtime integration - [Webhooks](/docs/webhooks/overview) - Get real-time notifications