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
  }
}
'

import requests

url = "https://api.moflay.com/v1/express"

payload = {
    "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
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
    }
  })
};

fetch('https://api.moflay.com/v1/express', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.moflay.com/v1/express",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.moflay.com/v1/express"

	payload := strings.NewReader("{\n  \"amount\": 123,\n  \"description\": \"<string>\",\n  \"phoneNumber\": \"254712345678\",\n  \"customerId\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerDescription\": \"<string>\",\n  \"customerMetadata\": {\n    \"user_preference\": \"dark_mode\",\n    \"last_login\": 1640995200,\n    \"is_premium\": true,\n    \"account_balance\": 1250.75,\n    \"notifications_enabled\": false\n  },\n  \"accountReference\": \"ORDER123\",\n  \"metadata\": {\n    \"user_preference\": \"dark_mode\",\n    \"last_login\": 1640995200,\n    \"is_premium\": true,\n    \"account_balance\": 1250.75,\n    \"notifications_enabled\": false\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.moflay.com/v1/express")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 123,\n  \"description\": \"<string>\",\n  \"phoneNumber\": \"254712345678\",\n  \"customerId\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerDescription\": \"<string>\",\n  \"customerMetadata\": {\n    \"user_preference\": \"dark_mode\",\n    \"last_login\": 1640995200,\n    \"is_premium\": true,\n    \"account_balance\": 1250.75,\n    \"notifications_enabled\": false\n  },\n  \"accountReference\": \"ORDER123\",\n  \"metadata\": {\n    \"user_preference\": \"dark_mode\",\n    \"last_login\": 1640995200,\n    \"is_premium\": true,\n    \"account_balance\": 1250.75,\n    \"notifications_enabled\": false\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.moflay.com/v1/express")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 123,\n  \"description\": \"<string>\",\n  \"phoneNumber\": \"254712345678\",\n  \"customerId\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerDescription\": \"<string>\",\n  \"customerMetadata\": {\n    \"user_preference\": \"dark_mode\",\n    \"last_login\": 1640995200,\n    \"is_premium\": true,\n    \"account_balance\": 1250.75,\n    \"notifications_enabled\": false\n  },\n  \"accountReference\": \"ORDER123\",\n  \"metadata\": {\n    \"user_preference\": \"dark_mode\",\n    \"last_login\": 1640995200,\n    \"is_premium\": true,\n    \"account_balance\": 1250.75,\n    \"notifications_enabled\": false\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "error": {
    "status": 401,
    "code": "missing_api_key",
    "message": "Missing API key in the authorization header."
  }
}

{
  "error": {
    "status": 403,
    "code": "invalid_api_key",
    "message": "API key is invalid."
  }
}

{
  "error": {
    "status": 405,
    "code": "method_not_allowed",
    "message": "Method is not allowed for the requested path."
  }
}

{
  "error": {
    "status": 422,
    "code": "validation_error",
    "message": "We found an error with one or more fields in the request.",
    "validation": [
      {
        "field": "email",
        "message": "Invalid email format"
      },
      {
        "field": "age",
        "message": "Expected number, received string"
      }
    ]
  }
}

{
  "error": {
    "status": 429,
    "code": "rate_limit_exceeded",
    "message": "You have exceeded your request limit. Please try again later."
  }
}

{
  "error": {
    "status": 500,
    "code": "internal_server_error",
    "message": "An unexpected error occurred."
  }
}

POST

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
  }
}
'

import requests

url = "https://api.moflay.com/v1/express"

payload = {
    "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
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
    }
  })
};

fetch('https://api.moflay.com/v1/express', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.moflay.com/v1/express",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.moflay.com/v1/express"

	payload := strings.NewReader("{\n  \"amount\": 123,\n  \"description\": \"<string>\",\n  \"phoneNumber\": \"254712345678\",\n  \"customerId\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerDescription\": \"<string>\",\n  \"customerMetadata\": {\n    \"user_preference\": \"dark_mode\",\n    \"last_login\": 1640995200,\n    \"is_premium\": true,\n    \"account_balance\": 1250.75,\n    \"notifications_enabled\": false\n  },\n  \"accountReference\": \"ORDER123\",\n  \"metadata\": {\n    \"user_preference\": \"dark_mode\",\n    \"last_login\": 1640995200,\n    \"is_premium\": true,\n    \"account_balance\": 1250.75,\n    \"notifications_enabled\": false\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.moflay.com/v1/express")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 123,\n  \"description\": \"<string>\",\n  \"phoneNumber\": \"254712345678\",\n  \"customerId\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerDescription\": \"<string>\",\n  \"customerMetadata\": {\n    \"user_preference\": \"dark_mode\",\n    \"last_login\": 1640995200,\n    \"is_premium\": true,\n    \"account_balance\": 1250.75,\n    \"notifications_enabled\": false\n  },\n  \"accountReference\": \"ORDER123\",\n  \"metadata\": {\n    \"user_preference\": \"dark_mode\",\n    \"last_login\": 1640995200,\n    \"is_premium\": true,\n    \"account_balance\": 1250.75,\n    \"notifications_enabled\": false\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.moflay.com/v1/express")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 123,\n  \"description\": \"<string>\",\n  \"phoneNumber\": \"254712345678\",\n  \"customerId\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerDescription\": \"<string>\",\n  \"customerMetadata\": {\n    \"user_preference\": \"dark_mode\",\n    \"last_login\": 1640995200,\n    \"is_premium\": true,\n    \"account_balance\": 1250.75,\n    \"notifications_enabled\": false\n  },\n  \"accountReference\": \"ORDER123\",\n  \"metadata\": {\n    \"user_preference\": \"dark_mode\",\n    \"last_login\": 1640995200,\n    \"is_premium\": true,\n    \"account_balance\": 1250.75,\n    \"notifications_enabled\": false\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "error": {
    "status": 401,
    "code": "missing_api_key",
    "message": "Missing API key in the authorization header."
  }
}

{
  "error": {
    "status": 403,
    "code": "invalid_api_key",
    "message": "API key is invalid."
  }
}

{
  "error": {
    "status": 405,
    "code": "method_not_allowed",
    "message": "Method is not allowed for the requested path."
  }
}

{
  "error": {
    "status": 422,
    "code": "validation_error",
    "message": "We found an error with one or more fields in the request.",
    "validation": [
      {
        "field": "email",
        "message": "Invalid email format"
      },
      {
        "field": "age",
        "message": "Expected number, received string"
      }
    ]
  }
}

{
  "error": {
    "status": 429,
    "code": "rate_limit_exceeded",
    "message": "You have exceeded your request limit. Please try again later."
  }
}

{
  "error": {
    "status": 500,
    "code": "internal_server_error",
    "message": "An unexpected error occurred."
  }
}

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"

CORE CONCEPTS

APIS

Initiate express payment

Authorizations

Headers

Body

Response