http://localhost:8000
Welcome to the PexiLabs API documentation. Our RESTful API allows you to integrate payment processing, transaction management, and merchant services into your applications.
All API endpoints use industry-standard security practices with API key authentication.
Optimized for performance with efficient data structures and caching.
Clean, predictable URLs and standard HTTP methods for easy integration.
You are currently viewing the development environment. Use this for testing and integration.
API keys follow the format: public_key:secret_key
Authorization: Bearer {api_key}
X-API-Key: {api_key}
Read access to transactions and data
Write access to create payments and sessions
API key verification and authentication endpoints
/api/v1/auth/verify/
Verify API key authentication and get partner information
{
"authenticated": true,
"message": "Authentication successful",
"data": {
"partner": {
"id": "uuid",
"name": "Partner Name",
"code": "partner_code",
"is_active": true
},
"app_key": {
"id": "uuid",
"name": "API Key Name",
"key_type": "merchant",
"scopes": [
"read",
"write"
],
"status": "active"
}
}
}curl -X POST "http://localhost:8000/api/v1/auth/verify/" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY_HERE" \
-d '{"key": "value"}'Payment processing and checkout session management
/api/v1/checkout/make-payment/
Create a new payment session for processing payments. Supports two payment flows: Direct Payment (card information provided) and Hosted Payment (redirects to payment page).
Process payment immediately with card information provided in the request. Card details and billing address are required. Minimum amount: 5.00.
Redirect customer to a hosted payment page where they enter their card information. No card details required in request.
Note: For Direct Payment, billing address fields (card_street, card_city, card_state_code, card_post_code, card_country_code) are required when card details are provided. expiry_month and expiry_year must be strings (e.g., "01", "2028").
{
"amount": 5.0,
"currency": "USD",
"customer_email": "omambiadauglous@gmal.com",
"first_name": "Omambia",
"last_name": "Dauglous",
"customer_phone": "+254748885672",
"payment_method": "card",
"description": "Machine Leaning training course",
"title": "Course Core Platform",
"card_number": "4000000000003220",
"cvv": "102",
"expiry_month": "01",
"expiry_year": "2028",
"card_street": "123 Main Street",
"card_city": "New York",
"card_state_code": "NY",
"card_post_code": "10001",
"card_country_code": "US",
"callback_url": "https://app.pexipay.com/callback/payment-success",
"cancel_url": "https://app.pexipay.com/callback/payment-cancel",
"redirect_url": "https://app.pexipay.com"
}{
"amount": 5.0,
"currency": "USD",
"customer_email": "omambiadauglous@gmal.com",
"first_name": "Omambia",
"last_name": "Dauglous",
"customer_phone": "+254748885672",
"payment_method": "card",
"description": "Machine Leaning training course",
"title": "Course Core Platform",
"callback_url": "https://app.pexipay.com/callback/payment-success",
"cancel_url": "https://app.pexipay.com/callback/payment-cancel",
"redirect_url": "https://app.pexipay.com"
}Note: Card fields (card_number, cvv, expiry_month, expiry_year) are required for Direct Payment but not needed for Hosted Payment.
amount
Payment amount (positive number, minimum 5.00 for card payments)
currency
Currency code (USD, EUR, KES, etc.)
customer_email
Customer email address
first_name
Customer first name
last_name
Customer last name
middle_name
Customer middle name (optional)
customer_phone
Customer phone number
description
Payment description
payment_method
Payment Method (card, crypto). Defaults to "card"
title
Payment title/subject
reference_id
Custom reference ID (auto-generated if not provided)
metadata
Additional metadata as JSON object
callback_url
Success callback URL
cancel_url
Cancel/failure callback URL
redirect_url
URL to redirect after payment completion (for hosted payments)
card_number
Card number (Required for Direct Payment, not needed for Hosted Payment)
cvv
Card CVV/CVC (Required for Direct Payment, not needed for Hosted Payment)
expiry_month
Card expiry month in string format with zero-padding (e.g., "01", "12") (Required for Direct Payment, not needed for Hosted Payment)
expiry_year
Card expiry year in string format (e.g., "2028", "2030") (Required for Direct Payment, not needed for Hosted Payment)
customer_date_of_birth
Customer date of birth in YYYY-MM-DD format
customer_state_of_residence
Customer state of residence (required if country is US)
card_street
Billing street address (Required for Direct Payment when card details are provided, e.g., "123 Main Street")
card_city
Billing city (Required for Direct Payment when card details are provided, e.g., "New York")
card_state_code
Billing state/province code (Required for Direct Payment when card details are provided, e.g., "NY", "CA")
card_post_code
Billing postal/ZIP code (Required for Direct Payment when card details are provided, e.g., "10001")
card_country_code
Billing country code in ISO 3166-1 alpha-2 format (Required for Direct Payment when card details are provided, e.g., "US", "CA", "GB")
{
"success": true,
"transaction_id": "uuid",
"reference_id": "PEX-REF-XXXXXXXX",
"expires_at": "2024-01-01T12:00:00Z",
"amount": 100.0,
"currency": "USD",
"payment_url": "https://app.pexipay.com/api/v1/checkout/process-payment/{transaction_id}/?session_id={session_id}",
"status": "pending",
"payment_method": "card",
"message": "Payment session created successfully"
}curl -X POST "http://localhost:8000/api/v1/checkout/make-payment/" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY_HERE" \
-d '{"key": "value"}'/api/v1/checkout/transaction/
Retrieve transaction details using the reference_id returned when creating a payment session
reference_id
The reference ID of the transaction (e.g., PEX-REF-EC0D9370)
{
"success": true,
"transaction_id": "878fe3ef-335b-4b7c-8d2e-c63adb7d7a8d",
"reference_id": "PEX-REF-EC0D9370",
"amount": 3.0,
"currency": "USD",
"payment_url": "http://localhost:8000/api/v1/checkout/process-payment/878fe3ef-335b-4b7c-8d2e-c63adb7d7a8d/?session_id=0a8e46f5-86d8-4b8b-9f80-9ba040b30f14",
"requires_3ds": true,
"status": "pending",
"payment_method": "card",
"message": "Payment authentication required.",
"expires_at": "2025-11-24T21:46:36.055213+00:00"
}curl -X GET "http://localhost:8000/api/v1/checkout/transaction/" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY_HERE"Transaction listing, details, and statistics
/api/v1/transactions/
Get paginated list of transactions with filtering options
page
Page number (default: 1)
page_size
Items per page (default: 20, max: 100)
status
Filter by transaction status
type
Filter by transaction type
payment_method
Filter by payment method(crypto, card)
date_from
Start date (YYYY-MM-DD)
date_to
End date (YYYY-MM-DD)
search
Search by reference or email
amount_min
Minimum amount filter
amount_max
Maximum amount filter
currency
Filter by currency
{
"success": true,
"data": {
"transactions": [],
"pagination": {
"current_page": 1,
"total_pages": 5,
"total_count": 100,
"page_size": 20,
"has_next": true,
"has_previous": false
}
}
}curl -X GET "http://localhost:8000/api/v1/transactions/" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY_HERE"/api/v1/transactions/stats/
Get comprehensive transaction statistics and metrics
date_from
Start date (YYYY-MM-DD)
date_to
End date (YYYY-MM-DD)
period
Predefined period (today, week, month, quarter, year)
{
"success": true,
"data": {
"stats": {
"total_transactions": 150,
"completed_transactions": 142,
"failed_transactions": 8,
"success_rate": 94.67,
"total_volume": "15000.00",
"total_fees": "435.00",
"net_volume": "14565.00"
},
"period": {
"from": "2023-12-01",
"to": "2023-12-31"
}
}
}curl -X GET "http://localhost:8000/api/v1/transactions/stats/" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY_HERE"/api/v1/transactions/choices/
Get available choices for transaction filters
{
"success": true,
"data": {
"transaction_statuses": [
{
"value": "pending",
"display": "Pending",
"description": "Transaction created and awaiting processing. Status remains PENDING during payment processing."
},
{
"value": "processing",
"display": "Processing",
"description": "Transaction is being processed (legacy status, transactions now remain PENDING during processing)"
},
{
"value": "completed",
"display": "Completed",
"description": "Transaction completed successfully"
},
{
"value": "failed",
"display": "Failed",
"description": "Transaction failed"
},
{
"value": "cancelled",
"display": "Cancelled",
"description": "Transaction was cancelled"
},
{
"value": "expired",
"display": "Expired",
"description": "Transaction expired"
},
{
"value": "refunded",
"display": "Refunded",
"description": "Transaction was refunded"
},
{
"value": "partially_refunded",
"display": "Partially Refunded",
"description": "Transaction was partially refunded"
},
{
"value": "disputed",
"display": "Disputed",
"description": "Transaction is under dispute"
},
{
"value": "frozen",
"display": "Frozen",
"description": "Transaction is frozen"
}
],
"transaction_types": [
{
"value": "payment",
"display": "Payment"
},
{
"value": "refund",
"display": "Refund"
}
],
"payment_methods": [
{
"value": "card",
"display": "Card Payment"
},
{
"value": "crypto",
"display": "Cryptocurrency"
}
]
}
}curl -X GET "http://localhost:8000/api/v1/transactions/choices/" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY_HERE"/api/v1/transactions/<uuid:transaction_id>/
Get detailed information about a specific transaction by ID
transaction_id
Transaction UUID
{
"success": true,
"data": {
"transaction": {
"id": "uuid",
"reference": "TXN-REF-123",
"amount": "100.00",
"currency": "USD",
"status": "completed",
"created_at": "2024-01-01T12:00:00Z"
}
}
}curl -X GET "http://localhost:8000/api/v1/transactions/<uuid:transaction_id>/" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY_HERE"/api/v1/transactions/reference/<str:reference>/
Get detailed information about a specific transaction by reference
reference
Transaction reference
{
"success": true,
"data": {
"transaction": {
"id": "uuid",
"reference": "TXN-REF-123",
"amount": "100.00",
"currency": "USD",
"status": "completed",
"created_at": "2024-01-01T12:00:00Z"
}
}
}curl -X GET "http://localhost:8000/api/v1/transactions/reference/<str:reference>/" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY_HERE"Mobile money payments, bank transfers, FX rates, and B2C payouts via Alternative Payment Methods
/api/v1/lamps/mobile-money/payment/
Create a mobile money payment transaction
amount
Payment amount (e.g., 100.00)
currency
Currency code: KES (Kenya), UGX (Uganda), TZS (Tanzania), NGN (Nigeria), XOF (West Africa)
payer_phone
Payer phone number with country code (e.g., 254712345001 for Kenya)
payer_email
Payer email address
payment_method_code
Payment method code for mobile money network (e.g., MPESA_KEN, AIRTEL_KEN, HALOTELTZA, TIGOTZA, VODACOMTZA, AIRTELTZA, MTNBEN, MOOVBEN, MTNCIV, ORANGECIV, ORANGESEN, FREESEN, MTNMOMONGA, AIRTELNGA). See supported countries section for available codes.
country_code
Country code: KEN (Kenya), UG (Uganda), TZ (Tanzania), NG (Nigeria), BJ (Benin), CI (Ivory Coast), SN (Senegal)
reference_id
Custom reference ID for tracking
metadata
Additional metadata as JSON object
webhook_url
Webhook URL for payment notifications
description
Payment description or purpose
{
"success": true,
"data": {
"transaction_id": "123456789",
"reference_id": "alternative_payment_methods_abc123",
"amount": "100.00",
"total_amount": "105.00",
"transaction_charge": "5.00",
"currency": "KES",
"status": "pending",
"message": "Request to charge customer was successfully placed",
"payment_method": "MPESA_KEN",
"country_code": "KEN"
}
}curl -X POST "http://localhost:8000/api/v1/lamps/mobile-money/payment/" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY_HERE" \
-d '{"key": "value"}'/api/v1/lamps/payouts/local/
Create a local B2C payout to mobile money or bank account
amount
Payout amount
recipient_phone
Recipient phone number
recipient_name
Recipient full name
destination_type
Destination type (MOBILE, BANK)
destination_name
Destination name (MPESA_KEN, etc.)
currency
Currency code (default: KES)
reference_id
Custom reference ID
metadata
Additional metadata
callback_url
Callback URL for status updates
description
Payout description
{
"success": true,
"data": {
"payout_reference": "payout_abc123",
"amount": "100.00",
"currency": "KES",
"status": "pending",
"message": "Payout request has been accepted for processing",
"destination_type": "MOBILE",
"destination_name": "MPESA_KEN",
"recipient_phone": "254700000000",
"recipient_name": "John Doe"
}
}curl -X POST "http://localhost:8000/api/v1/lamps/payouts/local/" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY_HERE" \
-d '{"key": "value"}'/api/v1/lamps/fx/rates/
Get real-time foreign exchange rates
base_currency
Base currency (default: USD)
{
"success": true,
"data": {
"base_currency": "USD",
"rates": {
"KES": {
"buying": "158.496617",
"selling": "164.509032"
},
"NGN": {
"buying": "908.749572",
"selling": "956.287051"
}
},
"timestamp": "2024-01-01T12:00:00Z"
}
}curl -X GET "http://localhost:8000/api/v1/lamps/fx/rates/" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY_HERE"/api/v1/lamps/payments/{transaction_id}/status/
Get payment status by transaction ID
transaction_id
Transaction ID
{
"success": true,
"data": {
"transaction_id": "123456789",
"reference_id": "alternative_payment_methods_abc123",
"amount": "100.00",
"currency": "KES",
"status": "completed",
"event": "successful_payment",
"payment_status": 700,
"payer_phone": "254700000000",
"payment_date": "2024-01-01T12:00:00Z",
"payment_method": "MPESA_KEN"
}
}curl -X GET "http://localhost:8000/api/v1/lamps/payments/{transaction_id}/status/" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY_HERE"/api/v1/lamps/payouts/{payout_reference}/status/
Get payout status by reference
payout_reference
Payout reference
{
"success": true,
"data": {
"payout_reference": "payout_abc123",
"amount": "100.00",
"currency": "KES",
"status": "completed",
"payment_status": 700,
"recipient_phone": "254700000000",
"recipient_name": "John Doe",
"transaction_time": "2024-01-01T12:00:00Z",
"destination_name": "MPESA_KEN",
"transaction_cost": "5.00",
"wallet_balance": "1000.00"
}
}curl -X GET "http://localhost:8000/api/v1/lamps/payouts/{payout_reference}/status/" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY_HERE"/api/v1/lamps/test/
Test Alternative Payment Methods integration connection
{
"success": true,
"message": "Alternative Payment Methods integration is working correctly",
"merchant": "Test Merchant",
"config": {
"consumer_key_configured": true,
"consumer_secret_configured": true,
"iv_key_configured": true,
"sandbox_mode": true
}
}curl -X POST "http://localhost:8000/api/v1/lamps/test/" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY_HERE" \
-d '{"key": "value"}'Test API endpoints directly from your browser. All test requests are made to the current environment.
curl -X POST "http://localhost:8000/api/auth/verify/" \
-H "X-API-Key: YOUR_API_KEY"
curl -X GET "http://localhost:8000/api/transactions/" \
-H "X-API-Key: YOUR_API_KEY"