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
Idempotency-Key: unique-request-id  # recommended for POST requests

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",
  "wallet": "ugx",
  "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',
    wallet: 'ugx',
    note: 'Payment for services',
    webhook_url: 'https://your-server.com/webhook'
  })
});
const data = await response.json();
console.log('Transaction ID:', data.transaction_id);

Wallets & Currency Fields

USDT Collection Example

{
  "wallet": "usdt",
  "amount": 25,
  "note": "Order 8891",
  "email": "customer@example.com",
  "network": "TRC20",
  "webhook_url": "https://your-server.com/webhook"
}

USDT Collection Response

{
  "success": true,
  "transaction_id": "transaction-uuid",
  "reference": "your-reference",
  "payment": {
    "pay_amount": 25,
    "pay_currency": "USDT",
    "network": "TRC20",
    "address": "TX...",
    "memo": null,
    "qr_code": "https://...",
    "expired_at": 1790672400
  }
}

USDT Payout Example

{
  "wallet": "usdt",
  "amount": 25,
  "crypto_address": "TX...",
  "network": "TRC20",
  "recipient_name": "John Doe",
  "note": "Payout 8891",
  "webhook_url": "https://your-server.com/webhook"
}

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",
  "wallet": "ugx",
  "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"
  }'

Get Balance

GET /api/api-balance

Returns the available UGX wallet balance for the authenticated API key.

Example

curl "https://pay.yollie.live/api/api-balance" \
  -H "x-api-key: ypk_your_api_key_here" \
  -H "x-api-secret: yps_your_api_secret_here"

Success Response (200)

{
  "success": true,
  "balance": 250000,
  "currency": "UGX",
  "available": 250000,
  "sandbox": false,
  "updated_at": "2026-09-29T06:00:00Z"
}

List Transactions

GET /api/api-transactions

curl "https://pay.yollie.live/api/api-transactions?limit=20&offset=0&type=deposit&status=completed" \
  -H "x-api-key: ypk_your_api_key_here" \
  -H "x-api-secret: yps_your_api_secret_here"

Success Response (200)

{
  "success": true,
  "total": 1,
  "limit": 20,
  "offset": 0,
  "transactions": [{
    "id": "transaction-uuid",
    "reference": "provider-reference",
    "type": "deposit",
    "status": "completed",
    "provider_status": "successful",
    "amount": 50000,
    "currency": "UGX",
    "recipient_phone": "+256712345678",
    "recipient_name": null,
    "description": "Order 8891",
    "created_at": "2026-09-29T06:00:00Z"
  }]
}

Check Transaction Status

GET /api/api-transaction-status?reference=...

Look up one transaction using either reference or transaction_id.

curl "https://pay.yollie.live/api/api-transaction-status?reference=provider-reference" \
  -H "x-api-key: ypk_your_api_key_here" \
  -H "x-api-secret: yps_your_api_secret_here"

Success Response (200)

{
  "success": true,
  "transaction": {
    "id": "transaction-uuid",
    "reference": "provider-reference",
    "type": "withdrawal",
    "status": "completed",
    "provider_status": "successful",
    "amount": 10000,
    "currency": "UGX",
    "recipient_phone": "+256712345678",
    "recipient_name": "John Doe",
    "description": "Payout 8891",
    "created_at": "2026-09-29T06:00:00Z"
  }
}

Verify Phone Number (Name Lookup)

POST /api/api-verify-phone

Confirm who a Uganda mobile money number is registered to before sending a payout, so your customers don't send money to the wrong number.

Request Body

{
  "phone_number": "0712345678"
}

Parameters

Success Response (200)

{
  "success": true,
  "message": "Phone number verified successfully",
  "data": {
    "phone_number": "256712345678",
    "first_name": "JOHN",
    "last_name": "ODO",
    "full_name": "JOHN ODO",
    "verification_status": "verified"
  }
}

Error Responses

cURL Example

curl -X POST "https://pay.yollie.live/api/api-verify-phone" \
  -H "x-api-key: ypk_your_api_key_here" \
  -H "x-api-secret: yps_your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "0712345678" }'

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
X-Yolliepay-Signature: sha256=<hex-digest>

Verify the signature by calculating HMAC SHA-256 over timestamp.raw_request_body using your webhook secret. Return HTTP 200 after accepting the event.

Available Events

Fee Structure

Deposits (Collections)

Payouts (Withdrawals & Send Money)

All Transactions

Daily Withdrawal Limits

Error Codes