Initiate express payment - Moflay Documentation

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

Show child attributes

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

Show child attributes

Example:

{
  "user_preference": "dark_mode",
  "last_login": 1640995200,
  "is_premium": true,
  "account_balance": 1250.75,
  "notifications_enabled": false
}

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"