Yolliepay API Documentation

Getting Started

1. Sign up on Yolliepay and log in to your dashboard
2. Generate an API Key & Secret in the API Keys section
3. Use the API to collect payments (STK push) or disburse payouts (send money)
4. Pass a webhook_url in each request to receive real-time transaction updates

Authentication & Origin Lock

All API requests require both your API key and API secret in headers:

x-api-key: ypk_your_api_key_here
x-api-secret: yps_your_api_secret_here

Collect Payment (STK Push)

POST /api/api-create-payment

Initiate a payment collection from a customer's mobile money account.

Request Body

{
  "amount": 5000,
  "phone_number": "0712345678",
  "provider": "mtn",
  "note": "Payment for order #123",
  "webhook_url": "https://your-server.com/webhook"
}

Parameters

Success Response (200)

{
  "success": true,
  "message": "Payment initiated successfully",
  "transaction_id": "uuid",
  "reference": "API_COL_...",
  "amount": 5000,
  "phone_number": "256712345678"
}

JavaScript Example

const response = await fetch('https://pay.yollie.live/api/api-create-payment', {
  method: 'POST',
  headers: {
    'x-api-key': 'ypk_your_api_key_here',
    'x-api-secret': 'yps_your_api_secret_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 50000,
    phone_number: '0712345678',
    provider: 'mtn',
    note: 'Payment for services',
    webhook_url: 'https://your-server.com/webhook'
  })
});
const data = await response.json();
console.log('Transaction ID:', data.transaction_id);

Payout / Disburse (Send Money)

POST /api/api-disburse

Send money to a mobile money number. Funds are deducted from your Yolliepay wallet.

Request Body

{
  "amount": 10000,
  "phone_number": "0712345678",
  "provider": "mtn",
  "recipient_name": "John Doe",
  "note": "Salary payment",
  "webhook_url": "https://your-server.com/webhook"
}

Parameters

Success Response (200)

{
  "success": true,
  "message": "Payout initiated successfully",
  "transaction_id": "uuid",
  "reference": "...",
  "amount": 10000,
  "phone_number": "256712345678"
}

JavaScript Example

const response = await fetch('https://pay.yollie.live/api/api-disburse', {
  method: 'POST',
  headers: {
    'x-api-key': 'ypk_your_api_key_here',
    'x-api-secret': 'yps_your_api_secret_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 10000,
    phone_number: '0712345678',
    provider: 'mtn',
    recipient_name: 'John Doe',
    note: 'Salary payment',
    webhook_url: 'https://your-server.com/webhook'
  })
});
const data = await response.json();
console.log('Payout ID:', data.transaction_id);

cURL Example

curl -X POST "https://pay.yollie.live/api/api-disburse" \
  -H "x-api-key: ypk_your_api_key_here" \
  -H "x-api-secret: yps_your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "phone_number": "0712345678",
    "provider": "mtn",
    "recipient_name": "John Doe",
    "note": "Payout"
  }'

Webhooks

Pass a webhook_url in each API request to receive transaction status updates at that URL.

Webhook Payload

{
  "id": "evt_abc12345",
  "type": "transaction.completed",
  "created": 1642000000,
  "data": {
    "id": "transaction-uuid",
    "type": "deposit",
    "amount": 50000,
    "currency": "UGX",
    "status": "completed",
    "description": "Payment for services",
    "recipient_phone": "256712345678",
    "recipient_name": "John Doe",
    "created_at": "2026-01-12T10:30:00Z"
  },
  "api_version": "2025-01"
}

Webhook Headers

User-Agent: Yolliepay-Webhooks/1.0
Content-Type: application/json
X-Yolliepay-Event: transaction.completed
X-Yolliepay-Timestamp: 1642000000

Available Events

Fee Structure

Deposits (Collections)

Payouts (Withdrawals & Send Money)

Yolliepay-to-Yolliepay Transfers

Daily Withdrawal Limits

Error Codes