# Yolliepay API documentation (full text)

> Source: https://pay.yollie.live/documentation

Yolliepay API Documentation
Yolliepay API Documentation
Africa’s best and cheapest payment gateway
Getting Started
Sign up on
Yolliepay
and log in to your dashboard
Generate an
API Key & Secret
in the API Keys section
Use the API to
collect payments
(STK push) or
disburse payouts
(send money)
Pass a
webhook_url
in each request to receive real-time transaction updates
Base URL:
https://pay.yollie.live/api
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
🔒 Allowed Website (Origin Lock):
Every API key is bound to a single website
(e.g.
mystore.com
) chosen when you created the key. Yolliepay
inspects the
Origin
/
Referer
header on each request and
rejects with 403
if it does not match.
This protects you even if your keys leak — an attacker cannot use them from a different domain.
Rate limiting:
Transaction endpoints allow
60 requests / minute / key
and 30 requests / minute / IP. Read endpoints allow up to 120 requests / minute / key.
Identical collection requests within 30 seconds and payout requests within 10 seconds are rejected
with HTTP 409 unless a unique
Idempotency-Key
is provided.
Security:
Never expose credentials in client-side code. Make API calls from
your server only. The
Origin
header from a server-to-server
call should be set to your website's domain.
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
Parameter
Type
Required
Description
amount
number
Yes
Amount to collect; minimum depends on wallet
wallet
string
No
ugx (default), kes, rwf, cdf, usd, or usdt
phone_number
string
Mobile money
Customer number in local or international format
provider
string
No
mtn, airtel, mpesa, vodacom, orange, or crypto
gateway
string
No
Optional configured gateway override; omit to use your account routing
note
string
Yes
Description, 4–255 characters
email
string
No
Customer email for a USDT collection
network
string
No
Blockchain network for a USDT collection
webhook_url
string
No
URL to receive status callbacks
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
Wallet
Method
Minimum
Required destination
UGX
Uganda mobile money
500 collection / 1,000 payout
phone_number; mtn or airtel
KES
Kenya M-Pesa
10
phone_number; mpesa
RWF
Rwanda mobile money
100
phone_number
CDF
DR Congo mobile money
500
phone_number
USD
DR Congo mobile money
1.00
phone_number
USDT
Crypto
1.00
crypto_address for payouts
USDT collection:
send
wallet: "usdt"
, amount, note, and optionally email and network. Yolliepay returns white-label payment instructions containing the exact amount, currency, network, wallet address, optional memo, QR code and expiry time. Display these details inside your own checkout.
USDT payout:
send
wallet: "usdt"
,
crypto_address
, amount, note, and optionally network. TRC20 is the default; ERC20, BEP20, TON, and POLYGON are accepted when available for the destination.
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
Parameter
Type
Required
Description
amount
number
Yes
Payout amount; minimum depends on wallet
wallet
string
No
ugx (default), kes, rwf, cdf, usd, or usdt
phone_number
string
Mobile money
Recipient number in local or international format
provider
string
No
mtn, airtel, mpesa, vodacom, orange, or crypto
gateway
string
No
Optional configured gateway override; omit to use your account routing
crypto_address
string
USDT
Recipient blockchain address
network
string
No
USDT network; TRC20 is used by default
recipient_name
string
No
Recipient's name
note
string
Yes
Description, 4–255 characters
webhook_url
string
No
URL to receive status callbacks
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
Query
Required
Description
limit
No
1–100; default 20
offset
No
Pagination offset; default 0
type
No
deposit, withdrawal, or transfer
status
No
pending, completed, or failed
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
Parameter
Type
Required
Description
phone_number
string
Yes
Uganda number in 07XXXXXXXX or 256XXXXXXXXX format
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
Status
code
Meaning
400
invalid_phone_number
Missing or badly formatted number
401
-
Invalid API credentials
403
api_disabled_for_account
API access disabled on the account
404
phone_not_found
Number not registered on the network
502 / 503
verification_unavailable
Lookup service temporarily unavailable
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
Event
Description
transaction.completed
Payment/payout successfully processed
transaction.failed
Payment/payout failed or cancelled
transaction.pending
Payment initiated, awaiting approval
payout.completed
Payout successfully sent
payout.failed
Payout failed
Fee Structure
Deposits (Collections)
Type
Fee
All deposits (including API)
5%
Payouts (Withdrawals & Send Money)
Type
Fee
All withdrawals / payouts (including API)
5%
All Transactions
Type
Fee
All transactions, including internal transfers
5%
These are the standard published fees. An account-specific fee configured by Yolliepay may override the default.
Daily Withdrawal Limits
Account Type
Limit
Personal
UGX 500,000/day
Business
UGX 5,000,000/day
Sandbox (unverified)
Withdrawals disabled
Error Codes
Code
Description
400
Bad Request — missing or invalid parameters (validation details in response)
401
Unauthorized — invalid or missing API credentials
403
Forbidden — key deactivated, deposits/withdrawals disabled, or origin not allowed
409
Duplicate — identical request received recently. Wait before retrying.
429
Rate limit exceeded — slow down (60 transaction requests/min/key)
500
Server error — internal processing error
© 2026 Yolliepay. All rights reserved. |
yollie.live
Yolliepay! Secure. Fast. Easy payments.