Skip to Content
DocumentationQuick start

Quick Start

Get started with the Wakapay Business API in minutes. This guide will walk you through making your first API call.

Prerequisites

Before you begin, you’ll need:

  1. A tool to make HTTP requests (curl, Postman, or your favorite programming language)
  2. 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 '{
    "type": "mobile_money",
    "phone": "+256700000000",
    "network": "MTN",
    "country": "UG"
  }'

Response:

{
  "success": true,
  "data": {
    "verified": true,
    "recipientName": "John Doe",
    "phone": "+256700000000",
    "network": "MTN",
    "country": "UG"
  }
}

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 '{
    "amount": 50000,
    "currency": "UGX",
    "recipient": {
      "type": "mobile_money",
      "phone": "+256700000000",
      "name": "John Doe",
      "network": "MTN"
    },
    "reference": "INV-2024-001",
    "description": "Payment for services rendered",
    "callbackUrl": "https://yourdomain.com/webhook"
  }'

Response:

{
  "success": true,
  "data": {
    "transactionId": "txn_abc123def456",
    "businessReference": "INV-2024-001",
    "status": "processing",
    "amount": 50000,
    "currency": "UGX",
    "recipient": {
      "phone": "+256700000000",
      "name": "John Doe"
    },
    "createdAt": "2024-01-15T10:35:00Z"
  }
}

Step 6: Check Transaction Status

Track your payment using the business reference:

curl https://api.test.wakapay.io/business/transactions/INV-2024-001 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "success": true,
  "data": {
    "transactionId": "txn_abc123def456",
    "businessReference": "INV-2024-001",
    "status": "completed",
    "amount": 50000,
    "currency": "UGX",
    "recipient": {
      "phone": "+256700000000",
      "name": "John Doe"
    },
    "createdAt": "2024-01-15T10:35:00Z",
    "completedAt": "2024-01-15T10:35:45Z"
  }
}

What’s Next?

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

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", {
      amount: 50000,
      currency: "UGX",
      recipient: {
        type: "mobile_money",
        phone: "+256700000000",
        name: "John Doe",
        network: "MTN",
      },
      reference: "INV-2024-001",
      description: "Payment for services",
    });
 
    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 = {
        'amount': 50000,
        'currency': 'UGX',
        'recipient': {
            'type': 'mobile_money',
            'phone': '+256700000000',
            'name': 'John Doe',
            'network': 'MTN'
        },
        'reference': 'INV-2024-001',
        'description': 'Payment for services'
    }
 
    response = requests.post(
        f'{WAKAPAY_API_URL}/business/payout/transfer',
        json=payload,
        headers=headers
    )
 
    if response.status_code == 200:
        print('Payment sent:', response.json())
    else:
        print('Error:', response.json())
 
send_payment()

Testing

Use these test credentials for integration:

  • Phone numbers: Use any number starting with +256700000000 to +256700000099
  • Test amounts: Any amount between 1,000 and 10,000,000
  • Test networks: MTN, Airtel, Africell

All test transactions will succeed immediately without processing real money.

Need Help?

Last updated on
IntroductionAuthentication