Skip to main content
POST
/
api
/
billing
/
payments
/
initiate
{
  "amount": 50.00,
  "currency": "USD",
  "payment_method": "mobile_money",
  "provider": "mpesa",
  "phone_number": "+255614853618"
}

{
  "success": true,
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "order_id": "ORD-1234567890",
    "amount": 50.00,
    "currency": "USD",
    "status": "pending",
    "payment_url": "https://payment.gateway.com/pay/xyz123",
    "expires_at": "2025-11-27T11:00:00Z"
  }
}
Initiate a payment transaction.
​
amount
number
required
Payment amount
​
currency
string
required
Currency code (e.g., USD)
​
payment_method
string
required
Payment method (mobile_money, card)
​
provider
string
Payment provider (mpesa, tigopesa, etc.)
​
phone_number
string
Phone number for mobile money payments
Requires authentication. Include the access token in the Authorization header.

​
Request Example

{
  "amount": 50.00,
  "currency": "USD",
  "payment_method": "mobile_money",
  "provider": "mpesa",
  "phone_number": "+255614853618"
}

​
Success Response (201)

​
success
boolean
Operation success status
​
transaction
object
Transaction object
​
transaction.id
string
Transaction ID
​
transaction.order_id
string
Order ID
​
transaction.amount
float
Transaction amount
​
transaction.currency
string
Currency code
​
transaction.status
string
Transaction status
​
transaction.payment_url
string
Payment URL for redirect
​
transaction.expires_at
string
Expiration timestamp (ISO 8601)
{
  "success": true,
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "order_id": "ORD-1234567890",
    "amount": 50.00,
    "currency": "USD",
    "status": "pending",
    "payment_url": "https://payment.gateway.com/pay/xyz123",
    "expires_at": "2025-11-27T11:00:00Z"
  }
}