Skip to main content
POST
/
v1
/
express
Express Payment
curl --request POST \
  --url https://api.moflay.com/v1/express \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "phoneNumber": "254712345678",
  "customerId": "cus_GqfKXLmg61LURZhB",
  "customerName": "John Doe",
  "customerEmail": "johndoe@example.com",
  "customerDescription": "VIP Customer",
  "customerMetadata": {
    "user_preference": "dark_mode",
    "last_login": 1640995200,
    "is_premium": true,
    "account_balance": 1250.75,
    "notifications_enabled": false
  },
  "amount": 100,
  "description": "Invoice #1234",
  "accountReference": "moflay",
  "metadata": {
    "user_preference": "dark_mode",
    "last_login": 1640995200,
    "is_premium": true,
    "account_balance": 1250.75,
    "notifications_enabled": false,
    "order_id": "ord_123456",
    "invoice_number": "INV-2024-001",
    "tax_amount": 16,
    "discount_applied": false
  }
}'
{
  "status": "completed",
  "amount": 1000,
  "fee": 15,
  "netAmount": 985,
  "currency": "KES",
  "transactionId": "trxn_ABC123DEF456GHI",
  "phoneNumber": "254712345678",
  "customerId": "cus_GqfKXLmg61LURZhB",
  "description": "Payment for Order #12345",
  "accountReference": "store_001",
  "environment": "sandbox",
  "timestamp": "2024-12-19T10:30:00.000Z",
  "message": "Payment completed successfully"
}

Authorizations

​
Authorization
string
header
required

The API key to use for authentication

Body

application/json

The payment body details

Daraja Express Payment Request - flat structure combining customer and payment data

​
phoneNumber
string
required

Customer phone number in format 254XXXXXXXXX (required if customerId is not provided)

Example:

"254712345678"

​
amount
integer
required

Amount transacted (KES). Only whole numbers are supported. Money that the customer pays to the Shortcode.

Required range: 0 < x <= 250000
Example:

100

​
description
string
required

The description of the payment

Required string length: 1 - 13
Example:

"Invoice #1234"

​
customerId
string

Existing customer ID - if provided, other customer fields are ignored

Maximum length: 255
Example:

"cus_GqfKXLmg61LURZhB"

​
customerName
string

Customer full name (ignored if customerId is provided)

Minimum length: 1
Example:

"John Doe"

​
customerEmail
string<email>

Customer email address (ignored if customerId is provided)

Minimum length: 5
Example:

"johndoe@example.com"

​
customerDescription
string

Customer description (ignored if customerId is provided)

Required string length: 1 - 255
Example:

"VIP Customer"

​
customerMetadata
object

Key-value object allowing you to store additional information.

Key Requirements:

  • Must be a string
  • Maximum length of 40 characters

Value Types:

  • String (maximum 500 characters)
  • Integer
  • Floating-point number
  • Boolean

Limits:

  • Maximum of 50 key-value pairs Additional customer metadata (ignored if customerId is provided)
Example:
{
  "user_preference": "dark_mode",
  "last_login": 1640995200,
  "is_premium": true,
  "account_balance": 1250.75,
  "notifications_enabled": false
}
​
accountReference
string

Account reference for the payment

Required string length: 1 - 12
Example:

"moflay"

​
metadata
object

Key-value object allowing you to store additional information.

Key Requirements:

  • Must be a string
  • Maximum length of 40 characters

Value Types:

  • String (maximum 500 characters)
  • Integer
  • Floating-point number
  • Boolean

Limits:

  • Maximum of 50 key-value pairs Additional payment metadata
Example:
{
  "user_preference": "dark_mode",
  "last_login": 1640995200,
  "is_premium": true,
  "account_balance": 1250.75,
  "notifications_enabled": false,
  "order_id": "ord_123456",
  "invoice_number": "INV-2024-001",
  "tax_amount": 16,
  "discount_applied": false
}

Response

Payment Response

Daraja Express Payment Response

​
status
enum<string>
required

Current status of the transaction

Available options:
pending,
completed,
failed
Example:

"completed"

​
amount
number
required

Payment amount in the smallest currency unit (e.g., cents for KES)

Required range: x > 0
Example:

1000

​
fee
number
required

Platform fee charged for the transaction

Required range: x >= 0
Example:

15

​
netAmount
number
required

Amount received by business after fees (amount - fee)

Required range: x > 0
Example:

985

​
currency
string
required

Transaction currency code

Example:

"KES"

​
transactionId
string
required

Unique transaction identifier prefixed with 'trxn_'

Example:

"trxn_ABC123DEF456GHI"

​
phoneNumber
string
required

Customer phone number used for payment

Example:

"254712345678"

​
customerId
string
required

Unique customer ID (existing or newly created) prefixed with 'cus_'

Example:

"cus_GqfKXLmg61LURZhB"

​
environment
enum<string>
required

Environment where transaction was processed

Available options:
sandbox,
production
Example:

"sandbox"

​
timestamp
string<date-time>
required

Transaction timestamp in ISO 8601 format

Example:

"2024-12-19T10:30:00.000Z"

​
message
string
required

Response message from M-Pesa

Example:

"Payment completed successfully"

​
description
string

Transaction description

Example:

"Payment for Order #12345"

​
accountReference
string

Account reference for the transaction (provided in request or auto-generated)

Example:

"store_001"

⌘I