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

> Opening balance, turnover by category and closing balance for every wallet on your account, over whole UTC calendar days from `startDate` to `endDate` (both inclusive). The figures are the ones shown on the Dashboard under Wallets → Breakdown.

Each entry carries the wallet identity and a nested `breakdown` object. Categories with no movement are omitted (absent means zero).


# Wallet breakdowns

The wallet breakdowns endpoint returns, for every wallet on your account, the opening balance, the turnover by category and the closing balance for a period. These are the same figures as on the Dashboard under Wallets → Breakdown, so you can reconcile your wallets without exporting them by hand.

Learn more about the wallet breakdown from our [Dashboard docs](https://docs.pawapay.io/dashboard/finances/wallets.md#wallet-breakdown).

* The period is whole **UTC calendar days** from `startDate` to `endDate`, both inclusive, and at most **31 days**.
* One request returns **all your wallets**. Use the optional `country` filter to limit it to one country. Identify each wallet by `country`, `currency` and `provider`, as in [Wallet Balances](https://docs.pawapay.io/v2/api-reference/finances/wallet-balances.md).
* Wallets with no movement are included, with only their opening and closing balance.
* **Categories with no movement are omitted**: treat a missing category as zero.
* Amounts are signed: **credits are positive, debits negative**. They are the values shown on the Dashboard, rounded to 2 decimals the same way the Dashboard rounds them, so a value exactly halfway between two cents can round down (for example `2.675` shows as `2.67`).
* `openingBalance` plus all present categories equals `closingBalance`. Because each amount is rounded on its own, a sum of the published figures can differ by a cent.
* Breakdown data starts in 2021. Earlier periods return zero balances and no categories.

### What is in `withdrawals`?

`withdrawals` holds your settlement withdrawals, outgoing wallet-to-wallet transfers and float reallocations. It is therefore not the same as the sum of your settlements for the period.

When a settlement is cancelled, the withdrawn amount returns to your wallet and is netted in `withdrawals`. For example, 27.00 withdrawn with a 7.00 settlement cancelled shows `withdrawals` as `-20`. If the cancellation falls in a later period than the withdrawal, the returned amount is added to `withdrawals` of that later period, which can make it positive.

### Which operations make up each category?

Every operation on your wallet belongs to exactly one category. The mapping below is version 1. A change that moves an operation to another category is announced at least 30 days in advance.

| Operation type | Category |
| - | - |
| `ADJUSTMENT_BANK_CHARGES` | `adjustments` |
| `ADJUSTMENT_EXCISE_TAX` | `adjustments` |
| `ADJUSTMENT_MMO_PAYOUT_REVERSAL` | `adjustments` |
| `ADJUSTMENT_MNO_INTEREST` | `adjustments` |
| `ADJUSTMENT_NON_DEDUCTED_SUCCESSFUL_PAYOUTS` | `adjustments` |
| `ADJUSTMENT_OTHER` | `adjustments` |
| `ADJUSTMENT_OTHER_POSITIVE` | `adjustments` |
| `ADJUSTMENT_PASSTHROUGHFEE_REBATE` | `adjustments` |
| `ADJUSTMENT_PASSTHROUGHFEE_REIMBURSEMENT` | `adjustments` |
| `ADJUSTMENT_PAYOUTS_DEBIT_IN_ERROR` | `adjustments` |
| `ADJUSTMENT_WITHHOLDING_TAX` | `adjustments` |
| `ADJUSTMENT_WRONGFUL_CREDIT_OF_DEPOSITS` | `adjustments` |
| `CANCELLED_WITHDRAWAL_REVERSAL` | `withdrawals` |
| `COMBINED_DEPOSIT_FEE` | `fees` |
| `COMBINED_PAYOUT_FEE` | `fees` |
| `COMBINED_REFUND_FEE` | `fees` |
| `COMBINED_REMITTANCE_FEE` | `fees` |
| `COMBINED_SPLIT_DEPOSIT_FEE` | `fees` |
| `COMBINED_SPLIT_PAYOUT_FEE` | `fees` |
| `COMPENSATION_FEES_REIMBURSEMENT` | `compensations` |
| `COMPENSATION_NON_CREDITED_SUCCESSFUL_DEPOSITS` | `adjustments` |
| `COMPENSATION_OTHER` | `compensations` |
| `COMPENSATION_WALLET_PASS_THROUGH_FEES` | `fees` (legacy type, not in use) |
| `COMPENSATION_WALLET_PAWAPAY_FEES` | `fees` (legacy type, not in use) |
| `COMPENSATION_WRONGFUL_DEBIT_FROM_PAYOUTS` | `compensations` |
| `CONS_DEPOSIT_FEE` | `fees` |
| `CONS_PAYOUT_FEE` | `fees` |
| `CONS_REFUND_FEE` | `fees` |
| `CONS_REMITTANCE_FEE` | `fees` |
| `CONS_SPLIT_DEPOSIT_FEE` | `fees` |
| `CONS_SPLIT_PAYOUT_FEE` | `fees` |
| `DEPOSIT` | `deposits` |
| `DEPOSIT_PASS_THROUGH_FEE` | `fees` |
| `FAILED_PAYOUT_REFUND` | `payouts` |
| `FAILED_REFUND_REVERSAL` | `refunds` |
| `FAILED_REMITTANCE_REFUND` | `remittances` |
| `FAILED_SPLIT_PAYOUT_REFUND` | `splitPayouts` |
| `LOC_MANUAL_PAWAPAY_FEES` | `fees` |
| `LOC_PAWAPAY_DEPOSIT_FEE` | `fees` |
| `LOC_PAWAPAY_PAYOUT_FEE` | `fees` |
| `LOC_PAWAPAY_REFUND_FEE` | `fees` |
| `LOC_PAWAPAY_REMITTANCE_FEE` | `fees` |
| `LOC_PAWAPAY_SPLIT_DEPOSIT_FEE` | `fees` |
| `LOC_PAWAPAY_SPLIT_PAYOUT_FEE` | `fees` |
| `MANUAL_PASS_THROUGH_FEES` | `fees` |
| `MANUAL_PAWAPAY_FEES` | `fees` |
| `PASS_THROUGH_FEE` | `fees` (legacy type, not in use) |
| `PAWAPAY_DEPOSIT_FEE` | `fees` |
| `PAWAPAY_FEE` | `fees` (legacy type, not in use) |
| `PAWAPAY_FLOAT_WALLET_TOP_UP_WALLET_TO_WALLET_TRANSFER` | `topUps` |
| `PAWAPAY_FLOAT_WALLET_WITHDRAWAL_WALLET_TO_WALLET_TRANSFER` | `withdrawals` |
| `PAWAPAY_PAYOUT_FEE` | `fees` |
| `PAWAPAY_REFUND_FEE` | `fees` |
| `PAWAPAY_REMITTANCE_FEE` | `fees` |
| `PAWAPAY_SPLIT_DEPOSIT_FEE` | `fees` |
| `PAWAPAY_SPLIT_PAYOUT_FEE` | `fees` |
| `PAYOUT` | `payouts` |
| `PAYOUT_PASS_THROUGH_FEE` | `fees` |
| `PAYOUT_REVERSAL` | `uncategorized` (legacy type, not in use) |
| `REFUND` | `refunds` |
| `REFUND_PASS_THROUGH_FEE` | `fees` |
| `REMITTANCE` | `remittances` |
| `REMITTANCE_PASS_THROUGH_FEE` | `fees` |
| `SPLIT_DEPOSIT` | `splitDeposits` |
| `SPLIT_DEPOSIT_PASS_THROUGH_FEE` | `fees` |
| `SPLIT_PAYOUT` | `splitPayouts` |
| `SPLIT_PAYOUT_PASS_THROUGH_FEE` | `fees` |
| `SUMMED_DEPOSIT_FEE` | `fees` |
| `SUMMED_PAYOUT_FEE` | `fees` |
| `SUMMED_REFUND_FEE` | `fees` |
| `SUMMED_REMITTANCE_FEE` | `fees` |
| `SUMMED_SPLIT_DEPOSIT_FEE` | `fees` |
| `SUMMED_SPLIT_PAYOUT_FEE` | `fees` |
| `TOP_UP` | `topUps` |
| `TOP_UP_ALLOCATION_FROM_PPAY_FLOAT` | `topUps` |
| `TOP_UP_WALLET_TO_WALLET_TRANSFER` | `topUps` |
| `UNMAPPED_OPERATION_TYPE` | `uncategorized` |
| `WITHDRAWAL` | `withdrawals` |
| `WITHDRAWAL_REALLOCATION_TO_PPAY_FLOAT` | `withdrawals` |
| `WITHDRAWAL_WALLET_TO_WALLET_TRANSFER` | `withdrawals` |


## OpenAPI

````yaml openapi_v2 get /v2/wallet-breakdowns
openapi: 3.0.0
info:
  title: PawaPay Merchant API V2
  description: Please find complete documentation from https://docs.pawapay.io/.
  version: v2
  x-logo:
    url: >-
      https://global-uploads.webflow.com/62824591015aa314fd308df1/6411b26596e3de3f52551c00_Logopawapay-p-500.png
    href: https://docs.pawapay.io/
    altText: PawaPay logo
servers:
  - url: https://api.sandbox.pawapay.io
    description: PawaPay Merchant API sandbox
  - url: https://api.pawapay.io
    description: PawaPay Merchant API production
security:
  - bearerAuth: []
tags:
  - name: deposits
    x-displayName: Deposits
  - name: split-payments
    x-displayName: Split Payments
  - name: checkouts
    x-displayName: Checkouts
  - name: payouts
    x-displayName: Payouts
  - name: refunds
    x-displayName: Refunds
  - name: remittances
    x-displayName: Remittances
  - name: payment-page
    x-displayName: Payment Page
  - name: toolkit
    x-displayName: Toolkit
  - name: finances
    x-displayName: Finances
paths:
  /v2/wallet-breakdowns:
    get:
      tags:
        - finances
      summary: Wallet breakdowns
      description: >
        Opening balance, turnover by category and closing balance for every
        wallet on your account, over whole UTC calendar days from `startDate` to
        `endDate` (both inclusive). The figures are the ones shown on the
        Dashboard under Wallets → Breakdown.


        Each entry carries the wallet identity and a nested `breakdown` object.
        Categories with no movement are omitted (absent means zero).
      operationId: wallet-breakdowns
      parameters:
        - in: query
          name: startDate
          required: true
          description: |
            First UTC calendar day of the period, inclusive.

            Format is `YYYY-MM-DD`. Date-times are rejected.
          schema:
            type: string
            format: date
            example: '2026-06-01'
        - in: query
          name: endDate
          required: true
          description: >
            Last UTC calendar day of the period, inclusive. Must be on or after
            `startDate` and not in the future. The period from `startDate` to
            `endDate`, both days included, is at most 31 days: for example,
            `2026-06-01` to `2026-07-01`.


            Format is `YYYY-MM-DD`. Date-times are rejected.
          schema:
            type: string
            format: date
            example: '2026-06-30'
        - $ref: '#/components/parameters/FilterCountry'
      responses:
        '200':
          description: Request has been succesfully processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletBreakdownsResponse'
              examples:
                Successful:
                  value:
                    startDate: '2026-06-01'
                    endDate: '2026-06-30'
                    wallets:
                      - country: TZA
                        currency: TZS
                        provider: ''
                        breakdown:
                          openingBalance: '75000'
                          closingBalance: '75000'
                      - country: ZMB
                        currency: ZMW
                        provider: ''
                        breakdown:
                          openingBalance: '148734.21'
                          deposits: '512400'
                          payouts: '-301200.5'
                          refunds: '-1200'
                          fees: '-8123.4'
                          topUps: '50000'
                          withdrawals: '-250000'
                          adjustments: '310.5'
                          closingBalance: '150920.81'
                Filtered by country:
                  value:
                    startDate: '2026-06-01'
                    endDate: '2026-06-30'
                    country: UGA
                    wallets:
                      - country: UGA
                        currency: UGX
                        provider: AIRTEL_OAPI_UGA
                        breakdown:
                          openingBalance: '2500000'
                          deposits: '9100000'
                          payouts: '-7400000'
                          fees: '-182000'
                          withdrawals: '-3000000'
                          closingBalance: '1018000'
                      - country: UGA
                        currency: UGX
                        provider: MTN_MOMO_UGA
                        breakdown:
                          openingBalance: '4100000'
                          deposits: '15250000'
                          payouts: '-11900000'
                          refunds: '-50000'
                          fees: '-305000'
                          withdrawals: '-5000000'
                          closingBalance: '2095000'
        '400':
          description: >-
            Request was rejected due to incompatibility with PawaPay API
            specification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletBreakdownsFailureResponse'
              examples:
                MISSING_PARAMETER:
                  value:
                    failureReason:
                      failureCode: MISSING_PARAMETER
                      failureMessage: >-
                        Request does not include the required parameter
                        'startDate'.
                INVALID_PARAMETER:
                  value:
                    failureReason:
                      failureCode: INVALID_PARAMETER
                      failureMessage: >-
                        Value for parameter 'endDate' is invalid. Please consult
                        API documentation for validation rules.
        '401':
          description: >-
            Authentication failed. Make sure you have added the API token into
            the header. If using signatures, make sure they are valid.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationFailureResponse'
              examples:
                AUTHENTICATION_ERROR:
                  value:
                    failureReason:
                      failureCode: AUTHENTICATION_ERROR
                      failureMessage: The API token in the request is invalid.
        '403':
          description: >-
            Authorization failure. The API token needs read access to both
            deposits and payouts.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthorizationFailureResponse'
              examples:
                AUTHORISATION_ERROR:
                  value:
                    failureReason:
                      failureCode: AUTHORISATION_ERROR
                      failureMessage: >-
                        The API token in the request is not authorised for this
                        endpoint.
        '500':
          description: An unknown failure has occurred.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/UnknownFailureResponse'
              examples:
                UNKNOWN_ERROR:
                  value:
                    failureReason:
                      failureCode: UNKNOWN_ERROR
                      failureMessage: Unable to process request due to an unknown problem.
components:
  parameters:
    FilterCountry:
      in: query
      name: country
      description: >
        The country you wish to limit the results to.


        Format is ISO 3166-1 alpha-3, three character country code in upper
        case. Read more from
        [wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements).
      required: false
      schema:
        type: string
        minLength: 3
        maxLength: 3
        example: ZMB
  schemas:
    WalletBreakdownsResponse:
      required:
        - startDate
        - endDate
        - wallets
      type: object
      properties:
        startDate:
          type: string
          format: date
          description: The `startDate` of the request.
          example: '2026-06-01'
        endDate:
          type: string
          format: date
          description: The `endDate` of the request.
          example: '2026-06-30'
        country:
          type: string
          description: >-
            The `country` filter of the request, in upper case. Only present
            when the filter was sent.
          example: UGA
        wallets:
          type: array
          items:
            $ref: '#/components/schemas/WalletWithBreakdown'
          description: >
            One entry per wallet on your account (or in `country`, when
            filtered), including wallets with no movement. Ordered by `country`,
            then `currency`, then `provider`.


            Identify an entry by `country` + `currency` + `provider`: one
            country can hold several wallets.
    WalletBreakdownsFailureResponse:
      required:
        - failureReason
      type: object
      properties:
        failureReason:
          $ref: '#/components/schemas/WalletBreakdownsFailureReason'
    AuthenticationFailureResponse:
      required:
        - failureCode
        - failureMessage
      type: object
      properties:
        status:
          type: string
          enum:
            - REJECTED
          description: The status of the response will always be `REJECTED`
          example: REJECTED
        failureReason:
          $ref: '#/components/schemas/AuthenticationFailureReason'
    AuthorizationFailureResponse:
      required:
        - failureCode
        - failureMessage
      type: object
      properties:
        status:
          type: string
          enum:
            - REJECTED
          description: The status of the response will always be `REJECTED`
          example: REJECTED
        failureReason:
          $ref: '#/components/schemas/AuthorizationFailureReason'
    UnknownFailureResponse:
      required:
        - failureCode
        - failureMessage
      type: object
      properties:
        failureReason:
          type: object
          properties:
            failureCode:
              type: string
              description: >
                Reason for the failure:

                * `UNKNOWN_ERROR` - Unable to process request due to an unknown
                problem.
              example: UNKNOWN_ERROR
            failureMessage:
              type: string
              description: A description of the failure
              example: Unable to process request due to an unknown problem.
    WalletWithBreakdown:
      required:
        - country
        - currency
        - provider
        - breakdown
      type: object
      properties:
        country:
          type: string
          format: text
          description: >
            Country of the wallet.


            Format is ISO 3166-1 alpha-3, three character country code in upper
            case. Read more from
            [Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements).
          example: ZMB
        currency:
          type: string
          description: Currency of the wallet.
          format: text
          example: ZMW
        provider:
          type: string
          description: >-
            If you are using a wallet that is only used by a single provider,
            that providers code will be shown here. Empty for country wallets.
          example: MTN_MOMO_BEN
        breakdown:
          $ref: '#/components/schemas/WalletBreakdown'
    WalletBreakdownsFailureReason:
      required:
        - failureCode
        - failureMessage
      type: object
      properties:
        failureCode:
          type: string
          description: >
            Possible failure codes:

            * `MISSING_PARAMETER` - A mandatory parameter was missing from the
            request.

            * `INVALID_PARAMETER` - A parameter had an incorrect value: a
            malformed date, `endDate` before `startDate` or in the future, a
            period longer than 31 days, or an unsupported `country`.
          example: INVALID_PARAMETER
          enum:
            - MISSING_PARAMETER
            - INVALID_PARAMETER
        failureMessage:
          type: string
          description: >-
            A human-readable description of the failure. Names the offending
            parameter.
          example: >-
            Value for parameter 'endDate' is invalid. Please consult API
            documentation for validation rules.
    AuthenticationFailureReason:
      required:
        - failureReason
      type: object
      properties:
        failureCode:
          type: string
          description: >
            Reason for the failure:

            * `NO_AUTHENTICATION` - The API token was not found in the request
            headers.

            * `AUTHENTICATION_ERROR` - The API token in the request headers is
            not valid.

            * `HTTP_SIGNATURE_ERROR` - The signature you have passed with the
            request did not pass verification.
          enum:
            - NO_AUTHENTICATION
            - AUTHENTICATION_ERROR
            - HTTP_SIGNATURE_ERROR
        failureMessage:
          type: string
          description: A description of the failure
    AuthorizationFailureReason:
      required:
        - failureReason
      type: object
      properties:
        failureCode:
          type: string
          description: >
            Reason for the failure:

            * `AUTHORISATION_ERROR` - The API Token in the request header is not
            authorised to make this request.

            * `DEPOSITS_NOT_ALLOWED` - Deposits are not enabled with the
            provider on your PawaPay account.

            * `PAYOUTS_NOT_ALLOWED` - Payouts are not enabled with the provider
            on your PawaPay account.

            * `REMITTANCES_NOT_ALLOWED` - Remittances are not enabled with the
            provider on your PawaPay account.

            * `REFUNDS_NOT_ALLOWED` - Refunds are not enabled with the provider
            on your PawaPay account.
          enum:
            - AUTHORISATION_ERROR
            - DEPOSITS_NOT_ALLOWED
            - PAYOUTS_NOT_ALLOWED
            - REMITTANCES_NOT_ALLOWED
            - REFUNDS_NOT_ALLOWED
        failureMessage:
          type: string
          description: A description of the failure
    WalletBreakdown:
      required:
        - openingBalance
        - closingBalance
      type: object
      description: >
        Figures for the wallet and period. Categories with no movement are
        omitted (absent means zero).


        All amounts are signed decimal strings: credits positive, debits
        negative. They are the values shown on the Dashboard, rounded to 2
        decimals, without thousands separators or trailing zeros.


        `openingBalance` plus the present categories equals `closingBalance`.
        Because each amount is rounded on its own, a sum of the published
        figures can differ by a cent.
      properties:
        openingBalance:
          type: string
          description: Balance at 00:00:00 UTC on `startDate`.
          example: '148734.21'
        deposits:
          type: string
          description: >-
            Collections credited to the wallet, across all channels (API,
            Payment Page, checkouts and customer-initiated deposits).
          example: '512400'
        splitDeposits:
          type: string
          description: Split-payment deposit legs.
          example: '1500'
        payouts:
          type: string
          description: Payouts, net of failed-payout refunds.
          example: '-301200.5'
        splitPayouts:
          type: string
          description: Split-payment payout legs, net of their refunds.
          example: '-900'
        remittances:
          type: string
          description: Remittances, net of their refunds.
          example: '-12000'
        refunds:
          type: string
          description: Deposit refunds, net of failed-refund reversals.
          example: '-1200'
        fees:
          type: string
          description: >-
            All pawaPay and pass-through fees. Fee reimbursements are in
            `compensations`.
          example: '-8123.4'
        topUps:
          type: string
          description: Top ups, incoming wallet-to-wallet transfers and float allocations.
          example: '50000'
        withdrawals:
          type: string
          description: >-
            Settlement withdrawals, outgoing wallet-to-wallet transfers and
            float reallocations, net of cancelled-settlement reversals. Because
            of the transfers, this is not the sum of your settlements for the
            period.
          example: '-250000'
        adjustments:
          type: string
          description: >-
            Manual ledger adjustments (for example taxes, bank charges and
            corrections).
          example: '310.5'
        compensations:
          type: string
          description: Manual compensations.
          example: '25'
        uncategorized:
          type: string
          description: >-
            Payout reversals (a legacy type) and operations without a known
            type, exactly as on the Dashboard.
          example: '0'
        closingBalance:
          type: string
          description: Balance at the end of `endDate`, or now if `endDate` is today.
          example: '150920.81'
  securitySchemes:
    bearerAuth:
      type: http
      description: >-
        See
        [Authentication](/v2/docs/how_to_start#how-to-authenticate-calls-to-the-merchant-api).
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.