> ## 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. > Settlements created in a period of whole UTC calendar days from `startDate` to `endDate`, both inclusive: where the money went, the bank fee, the FX rate and the amounts settled from each wallet. These are the settlements shown on the Dashboard under Settlements → Previous settlements. Settlements are ordered newest first. Account numbers and crypto wallet addresses are masked. # Settlements The settlements endpoint returns the settlements created in a period: which bank account or crypto wallet each one went to, the bank fee, the FX rate and how much was settled from each of your wallets. These are the settlements shown on the Dashboard under Settlements → Previous settlements, so you can match what reached your bank with what left your wallets. Learn more about settlements from our [Dashboard docs](https://docs.pawapay.io/dashboard/finances/settlements.md#track-your-settlements). * The period is whole **UTC calendar days** from `startDate` to `endDate`, both inclusive, and at most **365 days**. * Settlements are selected by the **date they were created** and returned **newest first**. Scheduled and on-request settlements are both included. * Settlements that have not started yet are not returned. A settlement shows as `IN_PROGRESS` from the moment its wallets are being withdrawn. * Settlement data starts on **2024-12-02**. Earlier periods return an empty list. * Identify each wallet by `country`, `currency` and `provider`, as in [Wallet Balances](https://docs.pawapay.io/v2/api-reference/finances/wallet-balances.md). ### How the amounts fit together * For each wallet, `amount` is what was withdrawn, in the wallet currency. `settledAmount` is that amount in the destination's `accountCurrency`: `amount` divided by `fxRate`, rounded half up to 4 decimals. A wallet in the same currency as the account has no `fxRate`, and its `settledAmount` equals `amount`. * `fxRate` is the number of wallet-currency units per one unit of `accountCurrency`, with up to 8 decimals, so small rates such as USD to CDF keep their precision. * For each destination, `totalAmount` is the sum of its wallets' `settledAmount`, and `settledAmount` is `totalAmount` minus `bankFeeAmount`. For a `COMPLETED` settlement, that is **the amount you received** on your bank account or crypto wallet. * Only `COMPLETED` settlements have been paid out. An `IN_PROGRESS` settlement has not been sent yet, and a `CANCELLED` settlement keeps its amounts for reference although nothing was sent: the withdrawn amounts went back to your wallets. * Bank charges are deducted from EUR, USD, GBP and stablecoin settlements and show in `bankFeeAmount`. Local-currency settlements are settled in full; any bank charges for them are deducted from your wallet separately and show in your [Wallet Breakdowns](https://docs.pawapay.io/v2/api-reference/finances/wallet-breakdowns.md), not here. * A skipped wallet carries only its `skippedReason`, a free-text explanation. Don't parse it. * Amounts, rates and fees are returned **as currently recorded**, the same values as on the Dashboard. A correction made later, for example to a bank fee or an FX rate, changes them in later responses. ### Account details * Account numbers and crypto wallet addresses are **masked**: `****` followed by the last 4 characters. Bank and account names are returned in full so you can tell your accounts apart. * Account details are read when you make the request. If you edit a bank account, past settlements to it show the new details, as on the Dashboard. ### Cancelled settlements When a settlement is cancelled, the withdrawn amounts go back to your wallets and the settlement shows as `CANCELLED`, with its wallets `REVERTED`. In your [Wallet Breakdowns](https://docs.pawapay.io/v2/api-reference/finances/wallet-breakdowns.md) the withdrawal and its return both fall in `withdrawals`, so a cancelled settlement nets to zero there. ### Sandbox No settlements run in sandbox. Instead, the sandbox returns **five example settlements** for any period: a completed cross-currency settlement, a completed local settlement, a skipped one, one in progress and a cancelled one. They use your real sandbox wallet identities, are spread evenly over the period, and keep the same `settlementId` when you repeat a request. They are illustrative only: they don't show on the sandbox Dashboard and don't reconcile with your sandbox wallet breakdowns. ## OpenAPI ````yaml openapi_v2 get /v2/settlements 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/settlements: get: tags: - finances summary: Settlements description: > Settlements created in a period of whole UTC calendar days from `startDate` to `endDate`, both inclusive: where the money went, the bank fee, the FX rate and the amounts settled from each wallet. These are the settlements shown on the Dashboard under Settlements → Previous settlements. Settlements are ordered newest first. Account numbers and crypto wallet addresses are masked. operationId: settlements 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 365 days: for example, `2026-01-01` to `2026-12-31`. Format is `YYYY-MM-DD`. Date-times are rejected. schema: type: string format: date example: '2026-07-31' responses: '200': description: Request has been succesfully processed. content: application/json: schema: $ref: '#/components/schemas/SettlementsResponse' examples: Successful: value: startDate: '2026-06-01' endDate: '2026-07-31' settlements: - settlementId: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 status: COMPLETED date: '2026-07-06' destinations: - type: BANK accountCurrency: EUR bankAccount: bankName: Standard Chartered accountName: Remitex Ltd accountNumber: '****8900' country: GBR totalAmount: '20000' bankFeeAmount: '25' settledAmount: '19975' wallets: - country: ZMB currency: ZMW provider: '' status: COMPLETED amount: '546400' fxRate: '27.32' settledAmount: '20000' - settlementId: a3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d status: SKIPPED date: '2026-06-29' destinations: - type: BANK accountCurrency: ZMW bankAccount: bankName: Zanaco accountName: Remitex Ltd accountNumber: '****7788' country: ZMB totalAmount: '0' bankFeeAmount: '0' settledAmount: '0' wallets: - country: ZMB currency: ZMW provider: '' status: SKIPPED skippedReason: >- Balance below the configured minimum settlement amount No settlements: value: startDate: '2023-01-01' endDate: '2023-12-31' settlements: [] '400': description: >- Request was rejected due to incompatibility with PawaPay API specification content: application/json: schema: $ref: '#/components/schemas/SettlementsFailureResponse' 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. The request is read-only and safe to retry. 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: schemas: SettlementsResponse: required: - startDate - endDate - settlements 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-07-31' settlements: type: array items: $ref: '#/components/schemas/Settlement' description: > Settlements created in the period, newest first. Empty when there are none. Scheduled and on-request settlements are both included. Settlements that have not started yet are not returned. SettlementsFailureResponse: required: - failureReason type: object properties: failureReason: $ref: '#/components/schemas/SettlementsFailureReason' 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. Settlement: required: - settlementId - status - date - destinations type: object properties: settlementId: type: string format: uuid description: Identifier of the settlement. It stays the same across requests. example: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 status: type: string description: > Status of the settlement: * `IN_PROGRESS` - The settlement is being processed. This includes the short moment while its wallets are being withdrawn. * `COMPLETED` - The money has been sent to your account. * `CANCELLED` - The settlement was cancelled and the withdrawn amounts returned to your wallets. * `SKIPPED` - Nothing was settled, for example because the balance was below your minimum settlement amount. More statuses may be added in the future. example: COMPLETED enum: - IN_PROGRESS - COMPLETED - CANCELLED - SKIPPED date: type: string format: date description: >- UTC date the settlement was created. The same date the Dashboard shows. example: '2026-07-06' destinations: type: array items: $ref: '#/components/schemas/SettlementDestination' description: >- The bank accounts or crypto wallets the settlement was sent to, each with the wallets settled into it. SettlementsFailureReason: 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, or a period longer than 365 days. example: INVALID_PARAMETER enum: - MISSING_PARAMETER - INVALID_PARAMETER failureMessage: type: string description: Description of the reason for this failure, naming the 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 SettlementDestination: required: - type - accountCurrency - totalAmount - bankFeeAmount - settledAmount - wallets type: object properties: type: type: string description: >- Kind of destination. `bankAccount` is present for `BANK`, `cryptoAccount` for `CRYPTO`. example: BANK enum: - BANK - CRYPTO accountCurrency: type: string description: >- Currency of the destination account. ISO 4217 code, or the crypto currency code (`USDC`, `USDT`). example: EUR bankAccount: $ref: '#/components/schemas/SettlementBankAccount' cryptoAccount: $ref: '#/components/schemas/SettlementCryptoAccount' totalAmount: type: string description: >- Sum of the wallets' `settledAmount`, in `accountCurrency`, before the bank fee. example: '20000' bankFeeAmount: type: string description: > Bank charges deducted from this settlement, in `accountCurrency`, with up to 3 decimals. `0` when there are none. Bank charges are deducted from EUR, USD, GBP and stablecoin settlements. Local-currency settlements are settled in full; any bank charges for them are deducted from your wallet separately and appear in [Wallet Breakdowns](/v2/api-reference/finances/wallet-breakdowns), not here. example: '25' settledAmount: type: string description: > `totalAmount` minus `bankFeeAmount`. For a `COMPLETED` settlement, this is the amount you received on your bank account or crypto wallet. For other statuses it shows the amounts as currently recorded: nothing has been sent yet for an `IN_PROGRESS` settlement, and a `CANCELLED` settlement was not paid out, its withdrawn amounts having returned to your wallets. example: '19975' wallets: type: array items: $ref: '#/components/schemas/SettlementWallet' description: The wallets settled into this destination. SettlementBankAccount: required: - bankName - accountName - accountNumber - country type: object description: > The bank account the settlement was sent to. Account details are read when you make the request, so a later edit of the account also changes how past settlements show it, as on the Dashboard. properties: bankName: type: string example: Standard Chartered accountName: type: string example: Remitex Ltd accountNumber: type: string description: >- Masked account number. `****` followed by the last 4 characters, or just `****` when the number has 4 characters or fewer. example: '****8900' country: type: string description: > Country of the bank account. 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: GBR SettlementCryptoAccount: required: - walletAddress type: object description: The crypto wallet the settlement was sent to. properties: walletAddress: type: string description: Masked wallet address. `****` followed by the last 4 characters. example: '****9f3a' SettlementWallet: required: - country - currency - provider - status 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. 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: '' status: type: string description: > Status of the withdrawal from this wallet: * `COMPLETED` - The amount was withdrawn from the wallet. * `SKIPPED` - Nothing was withdrawn; see `skippedReason`. * `REVERTED` - The amount was withdrawn and later returned to the wallet, because the settlement was cancelled. * `IN_PROGRESS` - The withdrawal is still being processed. More statuses may be added in the future. example: COMPLETED enum: - COMPLETED - SKIPPED - REVERTED - IN_PROGRESS amount: type: string description: >- Amount withdrawn from the wallet, in the wallet currency. Absent when nothing was withdrawn. example: '546400' fxRate: type: string description: >- FX rate used to settle the wallet into `accountCurrency`, as wallet-currency units per one unit of `accountCurrency`, with up to 8 decimals. Present only when the wallet currency differs from `accountCurrency` and a rate is recorded. example: '27.32' settledAmount: type: string description: >- `amount` in `accountCurrency`: `amount` divided by `fxRate` and rounded half up to 4 decimals, or equal to `amount` for a wallet in `accountCurrency`. Absent when there is no amount to settle yet. example: '20000' skippedReason: type: string description: >- Why nothing was withdrawn. Present only for `SKIPPED` wallets. Free text meant for people; do not parse it. example: Balance below the configured minimum settlement amount 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.