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

# Preview USSD-PUSH request

> Validates push details like phone number, amount, order-reference and verifies payment channels availability



## OpenAPI

````yaml POST /payments/preview-ussd-push-request
openapi: 3.0.1
info:
  title: CORE API OpenAPI Specification
  description: This is the API documentation for the ClickPesa CORE API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.clickpesa.com/third-parties
security:
  - bearerAuth: []
paths:
  /payments/preview-ussd-push-request:
    post:
      tags:
        - Payments
        - Preview
      description: >-
        Validates push details like phone number, amount, order-reference and
        verifies payment channels availability
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - orderReference
                - currency
              properties:
                amount:
                  type: string
                  description: Your payment amount
                currency:
                  type: string
                  enum:
                    - TZS
                orderReference:
                  type: string
                  description: Your unique Order reference
                phoneNumber:
                  type: string
                  description: >-
                    Mobile phone number to receive USSD-PUSH and make payment,
                    starting with country code and without the plus sign e.g.,
                    255712345678
                fetchSenderDetails:
                  type: boolean
                  description: If `true`, fetch sender details. Defaults to false.
                  default: false
                checksum:
                  type: string
                  description: >-
                    If enabled, this is the generated checksum of the payload.
                    Refer to the [documentation](/home/checksum) for more
                    details.
      responses:
        '200':
          description: Preview USSD Push response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewUSSDPushResponse'
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewUssdPushValidationError'
        '401':
          description: Invalid or Expired Token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Not Found Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewUssdPushNotFoundError'
        '409':
          description: Conflict Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewUSSDPushConflictError'
components:
  schemas:
    PreviewUSSDPushResponse:
      type: object
      properties:
        activeMethods:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Payment method name (e.g., TIGO-PESA, M-PESA, AIRTEL-MONEY)
              status:
                type: string
                enum:
                  - AVAILABLE
                  - UNAVAILABLE
                description: Status of the payment method
              fee:
                type: integer
                description: Fee amount if the payment method is available.
              message:
                type: integer
                description: Message if the payment method is unavailable.
        sender:
          type: object
          properties:
            accountName:
              type: string
              description: Sender name
              example: Mathayo John
            accountNumber:
              type: string
              description: Sender phone number
              example: '255712345678'
            accountProvider:
              type: string
              description: Sender mobile money provider
              example: TIGO-PESA
    PreviewUssdPushValidationError:
      type: object
      properties:
        message:
          type: string
          enum:
            - Valid Client ID is required
            - >-
              Application has no access to COLLECTION API feature. Enable it on
              your application.
            - >-
              Invalid Order Reference, should only contain alphanumeric
              characters and cannot be blank
          example: >-
            Invalid Order Reference, should only contain alphanumeric characters
            and cannot be blank
    UnauthorizedError:
      type: object
      properties:
        message:
          type: string
          description: Unauthorized Error
          example: Unauthorized
    PreviewUssdPushNotFoundError:
      type: object
      properties:
        message:
          type: string
          enum:
            - Account has no payment collection methods
            - Account has no valid payment method
          example: Account has no payment collection methods
    PreviewUSSDPushConflictError:
      type: object
      properties:
        message:
          type: string
          description: Conflict message when an order reference is already used
          example: >-
            Order reference {Your reference} already used: Create a different
            reference
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authorization header containing the JWT access token returned from the
        generate token endpoint. The token already includes the Bearer prefix.
        Example: `Authorization: Bearer eyJhbGciOi...`
      bearerFormat: JWT

````