Quick Start

Get started with the Wakapay Business API in minutes. This guide walks you through your first authenticated API call.

Prerequisites

Before you begin, you’ll need:

A tool to make HTTP requests (curl, Postman, or your favorite programming language)
Your API credentials (sent to your email)

Step 1: Authenticate

First, let’s verify your API key works by authenticating:


curl -X POST https://api.test.wakapay.io/business/auth \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "apiSecret": "YOUR_API_SECRET"
  }'

You should receive a response with an access token:


{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600,
    "tokenType": "Bearer"
  }
}

Store this token securely. You’ll use it for all subsequent requests.

Step 2: Check Your Balance

Let’s check your account balance:


curl https://api.test.wakapay.io/business/balance \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:


{
  "success": true,
  "data": {
    "balances": [
      {
        "currency": "UGX",
        "available": 1000000,
        "pending": 50000
      },
      {
        "currency": "KES",
        "available": 250000,
        "pending": 0
      }
    ]
  }
}

Step 3: Get Current FX Rates

Before making a cross-border payment, check the exchange rates:


curl "https://api.test.wakapay.io/business/rate?from=UGX&to=KES&amount=100000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:


{
  "success": true,
  "data": {
    "from": "UGX",
    "to": "KES",
    "rate": 0.0295,
    "amount": 100000,
    "convertedAmount": 2950,
    "fee": 500,
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Step 4: Verify a Recipient

Before sending money, verify the recipient’s details:


curl -X POST https://api.test.wakapay.io/business/verify-transfer \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "countryCode": "UG",
    "phoneNumber": "+256700000001"
  }'

Response:


{
  "displayName": "Amina Mjema",
  "receiverPhone": "+256700000001",
  "verified": true
}

Step 5: Send a Payment

Now you’re ready to send your first payment:


curl -X POST https://api.test.wakapay.io/business/payout/transfer \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderCurrency": "USD",
    "receiverCurrency": "KES",
    "amount": 100,
    "senderFirstName": "Alice",
    "senderLastName": "Smith",
    "senderDob": "1985-03-15",
    "senderIdType": "passport",
    "senderIdNumber": "AB1234567",
    "senderNationality": "TZ",
    "senderTelephoneNo": "+255712345678",
    "receiverFirstName": "Amina",
    "receiverLastName": "Mjema",
    "receiverPhone": "+254700000001",
    "relationship": "Family",
    "payoutCountry": "KE",
    "purposeOfTransfer": "family_support",
    "sourceOfFunds": "salary",
    "businessReference": "QUICKSTART-KE-0001",
    "callbackUrl": "https://partner.example.com/webhooks/wakapay/QUICKSTART-KE-0001"
  }'

Response:


{
  "wakapayReference": "0ad0a4a6-364b-11f1-8c14-0242ac120008",
  "businessReference": "QUICKSTART-KE-0001",
  "status": "termination_pending",
  "senderCurrency": "USD",
  "receiverCurrency": "KES",
  "senderAmount": 0.7751937984496124,
  "receiverAmount": 100,
  "totalDebited": 0.7906976744186047
}

Step 6: Check Transaction Status

Track your payment using the business reference:


curl https://api.test.wakapay.io/business/transactions/QUICKSTART-KE-0001 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:


{
  "wakapayReference": "0ad0a4a6-364b-11f1-8c14-0242ac120008",
  "businessReference": "QUICKSTART-KE-0001",
  "status": "termination_success",
  "senderCurrency": "USD",
  "receiverCurrency": "KES",
  "senderAmount": 0.7751937984496124,
  "receiverAmount": 100,
  "createdAt": "2026-06-22T07:00:00Z",
  "updatedAt": "2026-06-22T07:00:45Z"
}

What’s Next?

You’ve successfully made your first Wakapay API calls. Here’s what to explore next:

Authentication - Learn about secure authentication methods
Payouts - Explore all payout options
Webhooks - Set up real-time notifications
Error Handling - Handle errors gracefully

Code Examples

Node.js


const axios = require("axios");
 
const wakapay = axios.create({
  baseURL: "https://api.test.wakapay.io",
  headers: {
    Authorization: `Bearer ${process.env.WAKAPAY_TOKEN}`,
    "Content-Type": "application/json",
  },
});
 
// Send a payment
async function sendPayment() {
  try {
    const response = await wakapay.post("/business/payout/transfer", {
      senderCurrency: "USD",
      receiverCurrency: "KES",
      amount: 100,
      senderFirstName: "Alice",
      senderLastName: "Smith",
      senderDob: "1985-03-15",
      senderIdType: "passport",
      senderIdNumber: "AB1234567",
      senderNationality: "TZ",
      senderTelephoneNo: "+255712345678",
      receiverFirstName: "Amina",
      receiverLastName: "Mjema",
      receiverPhone: "+254700000001",
      relationship: "Family",
      payoutCountry: "KE",
      purposeOfTransfer: "family_support",
      sourceOfFunds: "salary",
      businessReference: "QUICKSTART-KE-0001",
      callbackUrl:
        "https://partner.example.com/webhooks/wakapay/QUICKSTART-KE-0001",
    });
 
    console.log("Payment sent:", response.data);
  } catch (error) {
    console.error("Error:", error.response.data);
  }
}

Python


import requests
 
WAKAPAY_API_URL = 'https://api.test.wakapay.io'
WAKAPAY_TOKEN = 'your_access_token'
 
headers = {
    'Authorization': f'Bearer {WAKAPAY_TOKEN}',
    'Content-Type': 'application/json'
}
 
def send_payment():
    payload = {
        'senderCurrency': 'USD',
        'receiverCurrency': 'KES',
        'amount': 100,
        'senderFirstName': 'Alice',
        'senderLastName': 'Smith',
        'senderDob': '1985-03-15',
        'senderIdType': 'passport',
        'senderIdNumber': 'AB1234567',
        'senderNationality': 'TZ',
        'senderTelephoneNo': '+255712345678',
        'receiverFirstName': 'Amina',
        'receiverLastName': 'Mjema',
        'receiverPhone': '+254700000001',
        'relationship': 'Family',
        'payoutCountry': 'KE',
        'purposeOfTransfer': 'family_support',
        'sourceOfFunds': 'salary',
        'businessReference': 'QUICKSTART-KE-0001',
        'callbackUrl': 'https://partner.example.com/webhooks/wakapay/QUICKSTART-KE-0001'
    }
 
    response = requests.post(
        f'{WAKAPAY_API_URL}/business/payout/transfer',
        json=payload,
        headers=headers
    )
 
    if response.status_code == 201:
        print('Payment sent:', response.json())
    else:
        print('Error:', response.json())
 
send_payment()

Testing

Use the documented TESTENV test recipients. Test payouts begin as termination_pending and later reach a final status. You can use forceStatus to test success, failure, and insufficient-balance handling.

Need Help?

Check the API Reference for detailed endpoint documentation