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

# Request M-Pesa reversal

> Initiate a reversal for a previously completed M-Pesa C2B transaction. The reversal will be processed asynchronously.



## OpenAPI

````yaml api-reference/openapi.json post /v1/mpesa/reverse
openapi: 3.1.0
info:
  title: Fingo Pay API
  description: >-
    Fingo Pay's unified payments API for M-Pesa C2B (STK Push), B2C
    disbursements, B2B transfers, bank transfers, account balances, and
    transactions.
  version: 1.0.0
servers:
  - url: https://api.fingopay.io
security:
  - bearerAuth: []
tags:
  - name: Payments
    description: Receive payments from customers
  - name: Payouts
    description: Send payments to recipients
  - name: Accounts
    description: Account balances and management
  - name: Transactions
    description: Transaction history and lookup
  - name: Verification
    description: Pre-transaction verification and lookup
  - name: Webhooks
    description: Webhook event notifications
paths:
  /v1/mpesa/reverse:
    post:
      tags:
        - Payments
      summary: Request M-Pesa reversal
      description: >-
        Initiate a reversal for a previously completed M-Pesa C2B transaction.
        The reversal will be processed asynchronously.
      operationId: mpesaReverse
      parameters:
        - name: Idempotency-Key
          in: header
          description: >-
            Unique key to safely retry POST without duplicates. Required in live
            environment.
          required: false
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transactionId:
                  type: string
                  description: Original transactionId (public ID) to reverse.
                  example: txn_01j7b6f9p5y9h
                narration:
                  type: string
                  description: >-
                    Optional narration for the reversal request. Maximum 140
                    characters.
                  example: Customer refund
                  maxLength: 140
              required:
                - transactionId
              additionalProperties: false
      responses:
        '202':
          description: Accepted — reversal will be processed asynchronously.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReversalAcceptedResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
        '409':
          $ref: '#/components/responses/ErrorResponse'
        '429':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    ReversalAcceptedResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: Reversal initiated successfully
        data:
          type: object
          properties:
            transactionId:
              type: string
              example: txn_01j7refund
          required:
            - transactionId
      required:
        - status
        - message
        - data
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - rate_limit_error
                - api_error
                - idempotency_error
                - not_found_error
                - conflict_error
              description: Error category
            code:
              type: string
              enum:
                - missing_parameter
                - invalid_parameter
                - unauthorized
                - forbidden
                - too_many_requests
                - internal_error
                - duplicate
                - resource_not_found
                - missing_header
                - validation_error
              description: Specific error code
            message:
              type: string
              description: Human-readable error message
            param:
              type:
                - string
                - 'null'
              description: The parameter that caused the error, if applicable
            requestId:
              type: string
              description: Request ID for support reference
          required:
            - type
            - code
            - message
      required:
        - error
  responses:
    ErrorResponse:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Use your API key as a Bearer token. Example: Authorization: Bearer
        sk_live_...

````