> ## 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.

# Initiate express payment

> Initiate an M-Pesa Express (STK Push) payment.

**Permissions**: `express.pay`



## OpenAPI

````yaml https://api.moflay.com/openapi post /v1/express
openapi: 3.1.0
info:
  title: Moflay API
  description: The fastest way to add M-Pesa payments.
  version: 1.0.0
  contact:
    name: Moflay Support
    email: support@moflay.com
    url: https://moflay.com
  termsOfService: https://moflay.com/legal/terms-of-service
servers:
  - url: https://api.moflay.com
    description: Production server
security:
  - token: []
tags:
  - name: Customers
    description: Create and manage customers in the organization
  - name: Transactions
    description: Everything about transactions in the organization
  - name: Express
    description: >-
      Create M-Pesa Express payments. Use the returned paymentId with the
      Payments API to read status.
  - name: Payments
    description: >-
      Track payment lifecycle and status for paymentIds returned by Express
      payment creation.
externalDocs:
  url: https://moflay.com/docs
  description: Moflay Documentation
paths:
  /v1/express:
    post:
      tags:
        - Express
      summary: Initiate express payment
      description: |-
        Initiate an M-Pesa Express (STK Push) payment.

        **Permissions**: `express.pay`
      operationId: express
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 256
            example: express_order_12345
            description: >-
              Optional idempotency key used to safely retry the same Express
              payment request without creating duplicate payment attempts.
          required: false
          description: >-
            Optional idempotency key used to safely retry the same Express
            payment request without creating duplicate payment attempts.
          name: Idempotency-Key
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                phoneNumber:
                  type: string
                  description: >-
                    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:
                  type: string
                  maxLength: 255
                customerName:
                  type: string
                  minLength: 1
                customerDescription:
                  type: string
                  minLength: 1
                  maxLength: 255
                customerMetadata:
                  $ref: '#/components/schemas/Metadata'
                amount:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 250000
                description:
                  type: string
                  minLength: 1
                  maxLength: 13
                accountReference:
                  type: string
                  minLength: 1
                  maxLength: 12
                  pattern: ^[a-zA-Z0-9]+$
                  example: ORDER123
                  description: >-
                    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.
                metadata:
                  $ref: '#/components/schemas/Metadata'
              required:
                - amount
                - description
      responses:
        '202':
          description: Payment Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DarajaExpressResponse'
        '401':
          description: Missing API Key Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MissingApiKeyError'
        '403':
          description: Invalid API Key Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidApiKeyError'
        '405':
          description: Method Not Allowed Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowedError'
        '422':
          description: The validation error(s) or invalid access error
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - $ref: '#/components/schemas/InvalidAccessError'
                description: The validation error(s) or invalid access error
        '429':
          description: Rate Limit Exceeded Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      security:
        - token: []
components:
  schemas:
    Metadata:
      type: object
      additionalProperties:
        anyOf:
          - type: string
            maxLength: 500
          - type: integer
          - type: number
          - type: boolean
      description: |-
        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
    DarajaExpressResponse:
      type: object
      properties:
        paymentId:
          type: string
          example: pay_ABC123DEF456GHI
          description: Unique identifier for the payment, prefixed with 'pay_'
        transactionId:
          type: string
          example: trxn_ABC123DEF456GHI
          description: Unique identifier for the related transaction, prefixed with 'trxn_'
        customerId:
          type: string
          example: cus_GqfKXLmg61LURZhB
          description: >-
            Unique identifier for the customer attached to the payment, prefixed
            with 'cus_'
        phoneNumber:
          type: string
          description: Customer Safaricom phone number that received the M-Pesa STK Push
          example: '254712345678'
        amount:
          type: number
          exclusiveMinimum: 0
          example: 1000
          description: Payment amount in the smallest currency unit
        currency:
          type: string
          example: KES
          description: Three-letter ISO currency code for the payment
        status:
          type: string
          enum:
            - pending
          example: pending
          description: Initial payment status after the STK Push request is accepted
        description:
          type: string
          example: Premium plan
          description: Short customer-facing payment description
        accountReference:
          type: string
          example: ORDER123
          description: >-
            Short alphanumeric reference that was sent to M-Pesa and stored with
            this payment, such as an order or invoice number.
        environment:
          type: string
          enum:
            - sandbox
            - production
          example: sandbox
          description: >-
            Environment where the payment was created. Either 'sandbox' or
            'production'
        timestamp:
          type: string
          format: date-time
          example: '2024-12-19T10:25:00.000Z'
          description: Timestamp when the payment request was accepted (ISO 8601 format)
        message:
          type: string
          example: Payment request sent to customer
          description: Human-readable message describing the initiation result
      required:
        - paymentId
        - transactionId
        - customerId
        - phoneNumber
        - amount
        - currency
        - status
        - description
        - accountReference
        - environment
        - timestamp
        - message
      example:
        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
      description: Payment Response
    MissingApiKeyError:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: number
              description: HTTP status code of the error
              example: 401
            code:
              type: string
              description: Machine-readable error name
              example: missing_api_key
            message:
              type: string
              x-speakeasy-error-message: true
              description: Human-readable error message
              example: Missing API key in the authorization header.
          required:
            - status
            - code
            - message
      required:
        - error
      description: Missing API Key Error
    InvalidApiKeyError:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: number
              description: HTTP status code of the error
              example: 403
            code:
              type: string
              description: Machine-readable error name
              example: invalid_api_key
            message:
              type: string
              x-speakeasy-error-message: true
              description: Human-readable error message
              example: API key is invalid.
          required:
            - status
            - code
            - message
      required:
        - error
      description: Invalid API Key Error
    MethodNotAllowedError:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: number
              description: HTTP status code of the error
              example: 405
            code:
              type: string
              description: Machine-readable error name
              example: method_not_allowed
            message:
              type: string
              x-speakeasy-error-message: true
              description: Human-readable error message
              example: Method is not allowed for the requested path.
          required:
            - status
            - code
            - message
      required:
        - error
      description: Method Not Allowed Error
    ValidationError:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: number
              description: HTTP status code of the error
              example: 422
            code:
              type: string
              description: Machine-readable error name
              example: validation_error
            message:
              type: string
              x-speakeasy-error-message: true
              description: Human-readable error message
              example: We found an error with one or more fields in the request.
            validation:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                    description: The name of the field that failed validation
                    example: email
                  message:
                    type: string
                    description: The validation error message for the field
                    example: Invalid email format
                required:
                  - field
                  - message
              description: List of field-specific validation issues
              example:
                - field: email
                  message: Invalid email format
                - field: age
                  message: Expected number, received string
          required:
            - status
            - code
            - message
            - validation
      required:
        - error
    InvalidAccessError:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: number
              description: HTTP status code of the error
              example: 422
          required:
            - status
        code:
          type: string
          description: Machine-readable error name
          example: invalid_access
        message:
          type: string
          x-speakeasy-error-message: true
          description: Human-readable error message
          example: >-
            The API key does not have the necessary permissions to access this
            resource.
      required:
        - error
        - code
        - message
    RateLimitExceededError:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: number
              description: HTTP status code of the error
              example: 429
            code:
              type: string
              description: Machine-readable error name
              example: rate_limit_exceeded
            message:
              type: string
              x-speakeasy-error-message: true
              description: Human-readable error message
              example: You have exceeded your request limit. Please try again later.
          required:
            - status
            - code
            - message
      required:
        - error
      description: Rate Limit Exceeded Error
    InternalServerError:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: number
              description: HTTP status code of the error
              example: 500
            code:
              type: string
              description: Machine-readable error name
              example: internal_server_error
            message:
              type: string
              x-speakeasy-error-message: true
              description: Human-readable error message
              example: An unexpected error occurred.
          required:
            - status
            - code
            - message
      required:
        - error
      description: Internal Server Error
  securitySchemes:
    token:
      type: http
      scheme: bearer
      description: The API key to use for authentication
      x-speakeasy-example: MOFLAY_API_KEY

````