openapi: 3.1.0
info:
  title: Flutterwave Settlements API
  description: |
    Flutterwave v4 settlement, refund, chargeback, and fee endpoints used by
    finance and operations teams to reconcile transaction volume with
    merchant payouts.
  version: '4.0.0'
  contact:
    name: Flutterwave
    url: https://developer.flutterwave.com
    email: developers@flutterwavego.com
  license:
    name: Flutterwave Terms of Service
    url: https://flutterwave.com/us/terms
servers:
  - url: https://api.flutterwave.cloud/f4b/production
    description: Production
  - url: https://api.flutterwave.cloud/f4b/sandbox
    description: Sandbox
security:
  - OAuth2: []
tags:
  - name: Settlements
    description: List and retrieve merchant settlements.
  - name: Refunds
    description: Initiate and inspect refunds against successful charges.
  - name: Chargebacks
    description: Manage and respond to chargebacks raised by customers.
  - name: Fees
    description: Retrieve Flutterwave's fee calculation for a transaction.
paths:
  /settlements:
    get:
      summary: List Settlements
      operationId: listSettlements
      tags: [Settlements]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementList'
  /settlements/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string }
    get:
      summary: Retrieve A Settlement
      operationId: getSettlement
      tags: [Settlements]
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Settlement'
  /refunds:
    get:
      summary: List Refunds
      operationId: listRefunds
      tags: [Refunds]
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundList'
    post:
      summary: Create A Refund
      operationId: createRefund
      tags: [Refunds]
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequest'
      responses:
        '201':
          description: Refund Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
  /refunds/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string }
    get:
      summary: Retrieve A Refund
      operationId: getRefund
      tags: [Refunds]
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
  /chargebacks:
    get:
      summary: List Chargebacks
      operationId: listChargebacks
      tags: [Chargebacks]
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargebackList'
    post:
      summary: Create A Chargeback
      operationId: createChargeback
      tags: [Chargebacks]
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargebackRequest'
      responses:
        '201':
          description: Chargeback Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chargeback'
  /chargebacks/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string }
    get:
      summary: Get Chargeback By Id
      operationId: getChargeback
      tags: [Chargebacks]
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chargeback'
    put:
      summary: Update A Chargeback
      operationId: updateChargeback
      tags: [Chargebacks]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                evidence: { type: object }
                resolution: { type: string }
      responses:
        '200':
          description: Chargeback Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chargeback'
  /fees:
    get:
      summary: Retrieve Fees
      description: Retrieve transaction fees for a payment amount, currency, and method combination.
      operationId: getFees
      tags: [Fees]
      parameters:
        - in: query
          name: amount
          required: true
          schema: { type: number }
        - in: query
          name: currency
          required: true
          schema: { type: string }
        - in: query
          name: payment_method
          schema: { type: string }
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fee'
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://idp.flutterwave.com/realms/flutterwave/protocol/openid-connect/token
          scopes: {}
  parameters:
    Limit:
      in: query
      name: limit
      schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
    Page:
      in: query
      name: page
      schema: { type: integer, minimum: 1, default: 1 }
    IdempotencyKey:
      in: header
      name: X-Idempotency-Key
      required: false
      schema: { type: string, format: uuid }
  schemas:
    Settlement:
      type: object
      properties:
        id: { type: string }
        gross_amount: { type: number }
        fee: { type: number }
        net_amount: { type: number }
        currency: { type: string }
        status: { type: string }
        reference: { type: string }
        period_start: { type: string, format: date-time }
        period_end: { type: string, format: date-time }
        created_datetime: { type: string, format: date-time }
    SettlementList:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/Settlement' }
    Refund:
      type: object
      properties:
        id: { type: string }
        charge_id: { type: string }
        amount: { type: number }
        currency: { type: string }
        status:
          type: string
          enum: [pending, processing, succeeded, failed]
        reason: { type: string }
        created_datetime: { type: string, format: date-time }
    RefundRequest:
      type: object
      required: [charge_id, amount]
      properties:
        charge_id: { type: string }
        amount: { type: number }
        reason: { type: string }
    RefundList:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/Refund' }
    Chargeback:
      type: object
      properties:
        id: { type: string }
        charge_id: { type: string }
        amount: { type: number }
        currency: { type: string }
        reason: { type: string }
        status:
          type: string
          enum: [pending, accepted, contested, lost, won]
        evidence: { type: object }
        created_datetime: { type: string, format: date-time }
    ChargebackRequest:
      type: object
      required: [charge_id, amount, reason]
      properties:
        charge_id: { type: string }
        amount: { type: number }
        reason: { type: string }
        evidence: { type: object }
    ChargebackList:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/Chargeback' }
    Fee:
      type: object
      properties:
        amount: { type: number }
        currency: { type: string }
        fee: { type: number }
        merchant_fee: { type: number }
        flutterwave_fee: { type: number }
        stamp_duty_fee: { type: number }