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

# Initiate Refund/Reversal

> Create a refund or reversal request for a collection payment.

## Overview

Use this endpoint to initiate a refund or reversal for a collection payment. The request is asynchronous: you receive a `request_uuid` immediately, then check the final outcome via the status endpoint.

> **Auth**: Requires a **Collection token** (`Authorization: Bearer <collection_token>`).

***

## Endpoint

```http theme={null}
POST {BASE_URL}/payments/api/v1/refund-reversal
```

***

## Request body

| Field                   | Type   | Required | Notes                                             |
| ----------------------- | ------ | -------- | ------------------------------------------------- |
| `transaction_reference` | string | Yes      | Original transaction reference to refund/reverse. |
| `payment_uuid`          | string | Yes      | Original Waftpay payment UUID.                    |
| `amount`                | number | Yes      | Amount to refund/reverse in major units.          |
| `notification_url`      | string | Yes      | HTTPS URL to receive the final status callback.   |
| `remarks`               | string | No       | Optional reason or notes.                         |

***

## Example request

```json theme={null}
{
  "transaction_reference": "TRC94513697913522",
  "payment_uuid": "803556523944079845",
  "amount": 400,
  "notification_url": "https://webhook.site/679ced79-7dac-4977-be7a-3d600b39c245",
  "remarks": "Test remarks"
}
```

***

## Example response (accepted)

```json theme={null}
{
  "code": 102,
  "status": "SUCCESS",
  "description": "Request accepted",
  "results": {
    "request_uuid": "A333RTYUT"
  }
}
```

***

## Next step

Use the `request_uuid` to check the final outcome: [Refund/Reversal status](/api-reference/collections/collections-refund).


## OpenAPI

````yaml POST /payments/api/v1/refund-reversal
openapi: 3.1.0
info:
  title: Waftpay Payments API
  description: >-
    Process payments, collect funds, and remit payouts with Waftpay. Includes
    Authentication Token, idempotency, webhooks, and sandbox support.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://dev.waftpay.io
    description: Sandbox (dev)
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: Obtain and manage access tokens
  - name: Payments
    description: Charge a customer and track status
  - name: Collections
    description: Customer-initiated payments and hosted checkouts
  - name: Checkout
    description: >-
      Hosted checkout flow for customer payments.


      Flow:

      1. Ensure the Collections service is enabled for your account.

      2. Use `consumer_key` and `consumer_secret` to generate a Bearer token via
      **Get Authentication Token**.

      3. Cache the token and refresh only on expiry.

      4. Call **Create Checkout Request** with customer details, amount, and
      redirect URLs.

      5. Use the returned `checkout_url` for redirect or iframe.

      6. The `callback_url` receives a payload matching the `CheckoutCallback`
      schema.
  - name: Remittance
    description: Send payouts to mobile wallets and bank accounts
  - name: Webhooks
    description: Receive asynchronous notifications
  - name: Utilities
    description: Common utilities (idempotency, health)
paths:
  /payments/api/v1/refund-reversal:
    post:
      tags:
        - Refunds
      summary: Initiate Refund/Reversal
      description: >-
        Create a refund or reversal request for a collection payment. Returns a
        request_uuid for status checks.
      operationId: initiateRefundReversal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundReversalInitiateRequest'
            examples:
              default:
                value:
                  transaction_reference: TRC94513697913522
                  payment_uuid: '803556523944079845'
                  amount: 400
                  notification_url: https://webhook.site/679ced79-7dac-4977-be7a-3d600b39c245
                  remarks: Test remarks
      responses:
        '201':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundReversalInitiateResponse'
              examples:
                accepted:
                  value:
                    code: 102
                    status: SUCCESS
                    description: Request accepted
                    results:
                      request_uuid: A333RTYUT
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    RefundReversalInitiateRequest:
      type: object
      required:
        - transaction_reference
        - payment_uuid
        - amount
        - notification_url
      properties:
        transaction_reference:
          type: string
          description: Original transaction reference to refund/reverse.
        payment_uuid:
          type: string
          description: Original Waftpay payment UUID.
        amount:
          type: number
          description: Amount to refund/reverse in major units.
        notification_url:
          type: string
          format: uri
          description: HTTPS URL to receive final status callbacks.
        remarks:
          type: string
          description: Optional reason or notes.
    RefundReversalInitiateResponse:
      type: object
      required:
        - code
        - status
        - description
        - results
      properties:
        code:
          type: integer
          description: Application code, e.g., 102 for SUCCESS.
        status:
          type: string
          description: Semantic status, e.g., SUCCESS.
        description:
          type: string
          description: Human-readable description.
        results:
          type: object
          description: Request metadata for status checks.
          required:
            - request_uuid
          properties:
            request_uuid:
              type: string
              description: Refund/reversal request UUID returned for status checks.
          additionalProperties: true
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Machine readable error code
        message:
          type: string
          description: Human readable message
        param:
          type: string
        request_id:
          type: string
    WaftpayErrorEnvelope:
      type: object
      required:
        - code
        - status
        - description
      properties:
        code:
          type: string
          description: >-
            Application code. Can be a top-level code (e.g., 400.600) or a
            granular code (e.g., 404.001.000).
        status:
          type: string
          description: >-
            Semantic status, e.g., REJECTED, FAILED, UNAUTHORIZED, FORBIDDEN,
            NOT_FOUND, ACCEPTED.
        description:
          type: string
          description: Human-readable description.
        data:
          type: object
          description: Additional details (may be empty).
          additionalProperties: true
          nullable: true
      examples:
        notFoundGranular:
          summary: 404 with granular code
          value:
            code: 404.001.000
            status: REJECTED
            description: Requested resource not found
            data: {}
        validationFailed:
          summary: 400 validation failed
          value:
            code: '400.100'
            status: REJECTED
            description: Validation failed
            data:
              field_errors:
                - field: recipient.account
                  message: Invalid account
        unauthorized:
          summary: 401 failed authentication
          value:
            code: '400.200'
            status: REJECTED
            description: Failed Authentication
            data: null
        forbidden:
          summary: 403 failed authorization
          value:
            code: '403.300'
            status: REJECTED
            description: Failed Authorization
            data: null
        internal:
          summary: 500 internal server error
          value:
            code: '400.500'
            status: FAILED
            description: Internal server error
            data: null
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WaftpayErrorEnvelope'
          examples:
            unauthorized:
              value:
                code: 400.001.100
                status: REJECTED
                description: Invalid or expired token
                data: {}
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````