> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pay.plexos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Payment

> Initiate a mobile money debit on the customer's phone.



## OpenAPI

````yaml POST /v1/payments
openapi: 3.1.0
info:
  title: Plexos Pay API
  description: Mobile Money Payment Gateway for African Markets
  version: 1.0.0
  contact:
    name: Plexos Pay
    url: https://plexospay.com
servers:
  - url: https://api.plexospay.com
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/payments:
    post:
      tags:
        - Payments
      summary: Create a payment
      description: Initiate a mobile money debit on the customer's phone.
      operationId: createPayment
      parameters:
        - name: Idempotency-Key
          in: header
          schema:
            type: string
          description: Unique key to prevent duplicate payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - operator
                - operatorPhone
              properties:
                amount:
                  type: integer
                  minimum: 1
                  maximum: 100000000
                  description: Amount in centavos
                  example: 10000
                operator:
                  $ref: '#/components/schemas/Operator'
                operatorPhone:
                  type: string
                  description: Customer's phone number
                  example: '+2389001234'
                currency:
                  $ref: '#/components/schemas/Currency'
                customerId:
                  type: string
                externalId:
                  type: string
                  description: Your reference ID
                customer:
                  type: object
                  properties:
                    phone:
                      type: string
                    operator:
                      $ref: '#/components/schemas/Operator'
                    name:
                      type: string
                    email:
                      type: string
                description:
                  type: string
                statementDescriptor:
                  type: string
                metadata:
                  $ref: '#/components/schemas/Metadata'
      responses:
        '200':
          description: Payment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Operator:
      type: string
      enum:
        - CVMOVEL
        - UNITEL_TMAIS
        - MOCK
      description: Mobile money operator
    Currency:
      type: string
      enum:
        - CVE
        - AOA
      description: ISO currency code
    Metadata:
      type: object
      additionalProperties: true
      description: Arbitrary key-value metadata (max 50 keys)
      nullable: true
    Payment:
      type: object
      properties:
        id:
          type: string
          example: pi_abc123
        externalId:
          type: string
          nullable: true
        amount:
          type: string
          description: Amount in centavos
          example: '10000'
        currency:
          $ref: '#/components/schemas/Currency'
        feeAmount:
          type: string
          example: '200'
        netAmount:
          type: string
          example: '9800'
        operator:
          $ref: '#/components/schemas/Operator'
        operatorPhone:
          type: string
          example: '+2389001234'
        operatorTxId:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/PaymentStatus'
        failureCode:
          type: string
          nullable: true
        failureMessage:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        statementDescriptor:
          type: string
          nullable: true
        customerId:
          type: string
          nullable: true
        metadata:
          $ref: '#/components/schemas/Metadata'
        expiresAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: string
    PaymentStatus:
      type: string
      enum:
        - CREATED
        - OPERATOR_PENDING
        - USER_CONFIRMING
        - DEBITED
        - SETTLED
        - FAILED
        - EXPIRED
        - REFUNDED
        - PARTIALLY_REFUNDED
        - CANCELLED
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key starting with `sk_live_` or `sk_test_`

````