Skip to main content
POST
/
v1
/
express
Initiate express payment
curl --request POST \
  --url https://api.moflay.com/v1/express \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 123,
  "description": "<string>",
  "phoneNumber": "254712345678",
  "customerId": "<string>",
  "customerName": "<string>",
  "customerDescription": "<string>",
  "customerMetadata": {
    "user_preference": "dark_mode",
    "last_login": 1640995200,
    "is_premium": true,
    "account_balance": 1250.75,
    "notifications_enabled": false
  },
  "accountReference": "ORDER123",
  "metadata": {
    "user_preference": "dark_mode",
    "last_login": 1640995200,
    "is_premium": true,
    "account_balance": 1250.75,
    "notifications_enabled": false
  }
}
'
{
  "paymentId": "pay_ABC123DEF456GHI",
  "transactionId": "trxn_ABC123DEF456GHI",
  "customerId": "cus_GqfKXLmg61LURZhB",
  "phoneNumber": "254712345678",
  "amount": 1000,
  "currency": "KES",
  "status": "pending",
  "description": "Premium plan",
  "accountReference": "ORDER123",
  "environment": "sandbox",
  "timestamp": "2024-12-19T10:25:00.000Z",
  "message": "Payment request sent to customer"
}

Documentation Index

Fetch the complete documentation index at: https://docs.moflay.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

The API key to use for authentication

Headers

​
Idempotency-Key
string

Optional idempotency key used to safely retry the same Express payment request without creating duplicate payment attempts.

Required string length: 1 - 256
Example:

"express_order_12345"

Body

application/json
​
amount
integer
required
Required range: x <= 250000
​
description
string
required
Required string length: 1 - 13
​
phoneNumber
string

Safaricom phone number in local (e.g., 0712345678, 0110123456) or international (e.g., 254712345678, 254110123456) format, transformed to 254XXXXXXXXX for M-PESA STK Push. Supports all Safaricom prefixes (070X, 074X, 0757–0759, 0768–0769, 079X, 0110–0117).

Example:

"254712345678"

​
customerId
string
Maximum string length: 255
​
customerName
string
Minimum string length: 1
​
customerDescription
string
Required string length: 1 - 255
​
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
Example:
{
  "user_preference": "dark_mode",
  "last_login": 1640995200,
  "is_premium": true,
  "account_balance": 1250.75,
  "notifications_enabled": false
}
​
accountReference
string

Short alphanumeric reference shown by M-Pesa and stored with the payment, such as an order or invoice number. If omitted, Moflay uses your configured default account reference.

Required string length: 1 - 12
Pattern: ^[a-zA-Z0-9]+$
Example:

"ORDER123"

​
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
Example:
{
  "user_preference": "dark_mode",
  "last_login": 1640995200,
  "is_premium": true,
  "account_balance": 1250.75,
  "notifications_enabled": false
}

Response

Payment Response

Payment Response

​
paymentId
string
required

Unique identifier for the payment, prefixed with 'pay_'

Example:

"pay_ABC123DEF456GHI"

​
transactionId
string
required

Unique identifier for the related transaction, prefixed with 'trxn_'

Example:

"trxn_ABC123DEF456GHI"

​
customerId
string
required

Unique identifier for the customer attached to the payment, prefixed with 'cus_'

Example:

"cus_GqfKXLmg61LURZhB"

​
phoneNumber
string
required

Customer Safaricom phone number that received the M-Pesa STK Push

Example:

"254712345678"

​
amount
number
required

Payment amount in the smallest currency unit

Example:

1000

​
currency
string
required

Three-letter ISO currency code for the payment

Example:

"KES"

​
status
enum<string>
required

Initial payment status after the STK Push request is accepted

Available options:
pending
Example:

"pending"

​
description
string
required

Short customer-facing payment description

Example:

"Premium plan"

​
accountReference
string
required

Short alphanumeric reference that was sent to M-Pesa and stored with this payment, such as an order or invoice number.

Example:

"ORDER123"

​
environment
enum<string>
required

Environment where the payment was created. Either 'sandbox' or 'production'

Available options:
sandbox,
production
Example:

"sandbox"

​
timestamp
string<date-time>
required

Timestamp when the payment request was accepted (ISO 8601 format)

Example:

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

​
message
string
required

Human-readable message describing the initiation result

Example:

"Payment request sent to customer"