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 '
{
  "amount": 100,
  "description": "Invoice #1234",
  "phoneNumber": "254712345678",
  "customerId": "cus_GqfKXLmg61LURZhB",
  "customerName": "John Doe",
  "customerEmail": "[email protected]",
  "customerDescription": "VIP Customer",
  "customerMetadata": {
    "user_preference": "dark_mode",
    "last_login": 1640995200,
    "is_premium": true,
    "account_balance": 1250.75,
    "notifications_enabled": false
  },
  "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",
  "message": "Payment completed successfully",
  "amount": 1000,
  "fee": 15,
  "netAmount": 985,
  "currency": "KES",
  "transactionId": "trxn_ABC123DEF456GHI",
  "phoneNumber": "254712345678",
  "customerId": "cus_GqfKXLmg61LURZhB",
  "accountReference": "store_001",
  "environment": "sandbox",
  "timestamp": "2024-12-19T10:30:00.000Z",
  "description": "Payment for Order #12345"
}

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

​
amount
integer
required

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

Required range: x <= 250000
Example:

100

​
description
string
required

The description of the payment

Required string length: 1 - 13
Example:

"Invoice #1234"

​
phoneNumber
string

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

Example:

"254712345678"

​
customerId
string

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

Maximum string length: 255
Example:

"cus_GqfKXLmg61LURZhB"

​
customerName
string

Customer full name (ignored if customerId is provided)

Minimum string length: 1
Example:

"John Doe"

​
customerEmail
string<email>

Customer email address (ignored if customerId is provided)

Minimum string length: 5
Example:

"[email protected]"

​
customerDescription
string

Customer description (ignored if customerId is provided)

Required string length: 1 - 255
Example:

"VIP Customer"

​
customerMetadata
object

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

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"

​
message
string
required

Response message

Example:

"Payment completed successfully"

​
amount
number
required

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

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)

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"

​
accountReference
string
required

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

Example:

"store_001"

​
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"

​
description
string

Transaction description

Example:

"Payment for Order #12345"