--- updatedAt: 2026-05-27T08:26:36.000Z agentTools: projectIndex: https://docs.mollie.com/llms.txt --- # Get settlement Retrieve a single settlement by its ID. To lookup settlements by their bank reference, replace the ID in the URL by a reference. For example: `1234567.2404.03`. A settlement represents a transfer of your balance funds to your external bank account. Settlements will typically include a report that details what balance transactions have taken place between this settlement and the previous one. For more accurate bookkeeping, refer to the [balance report](get-balance-report) endpoint or the [balance transactions](list-balance-transactions) endpoint. > 🔑 Access with > > [Advanced access token with **settlements.read**](/reference/authentication) > > [OAuth access with **settlements.read**](/reference/authentication) # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Business operations", "version": "1.0.0", "license": { "name": "Attribution-NonCommercial-ShareAlike 4.0 International", "identifier": "CC-BY-NC-SA-4.0" } }, "servers": [ { "url": "https://api.mollie.com/v2" } ], "security": [ { "apiKey": [] }, { "advancedAccessToken": [] }, { "oAuth": [] } ], "paths": { "/settlements/{settlementId}": { "parameters": [ { "name": "settlementId", "description": "Provide the ID of the related settlement.", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^stl_.+$", "example": "stl_5B8cwPMGnU" } } ], "get": { "summary": "Get settlement", "x-speakeasy-name-override": "get", "tags": [ "Settlements API" ], "operationId": "get-settlement", "security": [ { "advancedAccessToken": [ "settlements.read" ] }, { "oAuth": [ "settlements.read" ] } ], "description": "Retrieve a single settlement by its ID.\n\nTo lookup settlements by their bank reference, replace the ID in the URL by a reference. For example: `1234567.2404.03`.\n\nA settlement represents a transfer of your balance funds to your external bank account.\n\nSettlements will typically include a report that details what balance transactions have taken place between this settlement and the previous one.\n\nFor more accurate bookkeeping, refer to the [balance report](get-balance-report) endpoint or the [balance transactions](list-balance-transactions) endpoint.\n\n> 🔑 Access with\n>\n> [Advanced access token with **settlements.read**](/reference/authentication)\n>\n> [OAuth access with **settlements.read**](/reference/authentication)", "responses": { "200": { "description": "The settlement object.", "content": { "application/hal+json": { "schema": { "allOf": [ { "type": "object", "required": [ "resource", "id", "status", "amount", "balanceId", "_links" ], "properties": { "resource": { "type": "string", "description": "Indicates the response contains a settlement object. Will always contain the string `settlement` for this endpoint.", "readOnly": true, "default": "settlement", "example": "settlement" }, "id": { "type": "string", "description": "The identifier uniquely referring to this settlement.", "readOnly": true, "example": "stl_5B8cwPMGnU" }, "createdAt": { "type": "string", "description": "The entity's date and time of creation, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.", "readOnly": true, "example": "2024-03-20T09:13:37+00:00" }, "reference": { "type": [ "string", "null" ], "description": "The settlement's bank reference, as found in your Mollie account and on your bank statement.", "readOnly": true, "example": "07049691.2406.01" }, "settledAt": { "type": [ "string", "null" ], "description": "The date on which the settlement was settled, in ISO 8601 format.\n\nFor an [open settlement](get-open-settlement) or for the [next settlement](get-next-settlement), no settlement date is available.", "readOnly": true, "example": "2025-03-31T12:54:39+00:00" }, "status": { "allOf": [ { "type": "string", "description": "The status of the settlement.\n\nPossible values: `open` `pending` `processing` `processing-at-bank` `paidout` `failed`", "x-enumDescriptions": { "open": "The settlement has not been closed yet", "pending": "The settlement has been closed and is queued for processing", "processing": "The settlement is being processed", "processing-at-bank": "The settlement has been sent to the bank and is being processed", "paidout": "The settlement has been paid out", "failed": "The settlement could not be paid out" }, "example": "paidout" } ], "readOnly": true }, "amount": { "allOf": [ { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } }, { "description": "The total amount of the settlement." } ], "readOnly": true }, "balanceId": { "allOf": [ { "type": "string", "pattern": "^bal_.+$", "example": "bal_gVMhHKqSSRYJyPsuoPNFH" } ], "description": "The balance token that the settlement was settled to.", "readOnly": true }, "invoiceId": { "allOf": [ { "type": "string", "pattern": "^inv_.+$", "example": "inv_aHbjjdrUdm" } ], "type": [ "string", "null" ], "description": "The ID of the oldest invoice created for all the periods, if the invoice has been created yet.", "readOnly": true }, "periods": { "type": "object", "description": "For bookkeeping purposes, the settlement includes an overview of transactions included in the settlement. These transactions are grouped into 'period' objects — one for each calendar month.\n\nFor example, if a settlement includes funds from 15 April until 4 May, it will include two period objects. One for all transactions processed between 15 April and 30 April, and one for all transactions between 1 May and 4 May.\n\nPeriod objects are grouped by year, and then by month. So in the above example, the full `periods` collection will look as follows: `{\"2024\": {\"04\": {...}, \"05\": {...}}}`. The year and month in this documentation are referred as `` and ``.\n\nThe example response should give a good idea of what this looks like in practise.", "properties": { "": { "type": "object", "properties": { "": { "type": "object", "properties": { "costs": { "type": "array", "description": "An array of cost objects, describing the fees withheld for each payment method during this period.", "items": { "type": "object", "required": [ "description", "method", "count", "rate", "amountNet", "amountVat", "amountGross" ], "properties": { "description": { "type": "string", "description": "A description of the cost subtotal", "example": "Credit card - Visa debit consumer domestic" }, "method": { "type": [ "string", "null" ], "description": "The method the cost or revenue subtotal applies to. This is usually a payment method, but can also represent a correction or transaction type that is not tied to a specific payment method.\n\nPossible values: `alma` `applicationfee` `authorizationreversal` `bacs` `bancomatpay` `bancontact` `banktransfer` `belfius` `billie` `billink` `bitcoin` `bizum` `blik` `capture` `chargeback` `creditcard` `directdebit` `eps` `giftcard` `giropay` `ideal` `in3` `inghomepay` `kbc` `kickback` `klarna` `klarnapaylater` `klarnapaynow` `klarnasliceit` `mbway` `mobilepay` `multibanco` `mybank` `paybybank` `paypal` `paysafecard` `podiumcadeaukaart` `pointofsale` `przelewy24` `refund` `riverty` `rollingreserve` `satispay` `shiftedfee` `sofort` `swish` `trustly` `twint` `vipps` `voucher` `wero`", "x-deprecated-enum": [ "payconiq" ], "x-speakeasy-enum-descriptions": { "payconiq": "No longer available" }, "example": "creditcard" }, "count": { "type": "integer", "description": "The number of fees", "example": 10 }, "rate": { "type": "object", "description": "The service rates, further divided into `fixed` and `percentage` costs.", "properties": { "fixed": { "type": "object", "description": "In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } }, "percentage": { "type": "string", "example": "2.5" } } }, "amountNet": { "description": "The net total cost, i.e. excluding VAT", "type": "object", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } }, "amountVat": { "description": "The applicable VAT", "type": [ "object", "null" ], "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } }, "amountGross": { "description": "The gross total cost, i.e. including VAT", "type": "object", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } } } } }, "revenue": { "type": "array", "description": "An array of revenue objects containing the total revenue for each payment method during this period.", "items": { "type": "object", "required": [ "description", "method", "count", "amountNet", "amountVat", "amountGross" ], "properties": { "description": { "type": "string", "description": "A description of the revenue subtotal", "example": "Credit card" }, "method": { "type": [ "string", "null" ], "description": "The method the cost or revenue subtotal applies to. This is usually a payment method, but can also represent a correction or transaction type that is not tied to a specific payment method.\n\nPossible values: `alma` `applicationfee` `authorizationreversal` `bacs` `bancomatpay` `bancontact` `banktransfer` `belfius` `billie` `billink` `bitcoin` `bizum` `blik` `capture` `chargeback` `creditcard` `directdebit` `eps` `giftcard` `giropay` `ideal` `in3` `inghomepay` `kbc` `kickback` `klarna` `klarnapaylater` `klarnapaynow` `klarnasliceit` `mbway` `mobilepay` `multibanco` `mybank` `paybybank` `paypal` `paysafecard` `podiumcadeaukaart` `pointofsale` `przelewy24` `refund` `riverty` `rollingreserve` `satispay` `shiftedfee` `sofort` `swish` `trustly` `twint` `vipps` `voucher` `wero`", "x-deprecated-enum": [ "payconiq" ], "x-speakeasy-enum-descriptions": { "payconiq": "No longer available" }, "example": "creditcard" }, "count": { "type": "integer", "description": "The number of payments", "example": 10 }, "amountNet": { "description": "The net total of received funds, i.e. excluding VAT", "type": "object", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } }, "amountVat": { "description": "The applicable VAT", "type": [ "object", "null" ], "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } }, "amountGross": { "description": "The gross total of received funds, i.e. including VAT", "type": "object", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "description": "A three-character ISO 4217 currency code.", "example": "EUR" }, "value": { "type": "string", "description": "A string containing an exact monetary amount in the given currency.", "example": "10.00" } } } } } }, "invoiceId": { "type": [ "string", "null" ], "description": "The ID of the invoice created for this period, if the invoice has been created already.", "pattern": "^inv_.+$", "example": "inv_aHbjjdrUdm" }, "invoiceReference": { "type": [ "string", "null" ], "description": "The invoice reference, if the invoice has been created already.", "example": "MOLR2021.0001399669" } } } } } }, "readOnly": true }, "_links": { "type": "object", "description": "An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.", "readOnly": true } } }, { "properties": { "id": { "allOf": [ { "type": "string", "pattern": "^stl_.+$", "example": "stl_5B8cwPMGnU" } ], "description": "The identifier uniquely referring to this settlement.", "readOnly": true }, "_links": { "type": "object", "description": "An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.", "required": [ "self" ], "properties": { "self": { "type": "object", "description": "In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "payments": { "description": "The API resource URL of the [payments](list-payments) included in this settlement.", "type": "object", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "captures": { "description": "The API resource URL of the [captures](list-captures) included in this settlement.", "type": "object", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "refunds": { "description": "The API resource URL of the [refunds](list-refunds) deducted from this settlement.", "type": "object", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "chargebacks": { "description": "The API resource URL of the [chargebacks](list-chargebacks) deducted from this settlement.", "type": "object", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "invoice": { "description": "The API resource URL of the [invoice](list-invoices).", "type": [ "object", "null" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "documentation": { "type": "object", "description": "In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } } }, "readOnly": true } } } ] }, "examples": { "get-settlement-200-1": { "summary": "The settlement object", "value": { "resource": "settlement", "id": "stl_jDk30akdN", "reference": "1234567.2404.03", "createdAt": "2024-04-06T09:41:44+00:00", "status": "paidout", "amount": { "currency": "EUR", "value": "39.75" }, "balanceId": "bal_3kUf4yU2nT", "invoiceId": "inv_FrvewDA3Pr", "periods": { "2024": { "04": { "revenue": [ { "description": "iDEAL", "method": "ideal", "count": 6, "amountNet": { "currency": "EUR", "value": "86.1000" }, "amountVat": null, "amountGross": { "currency": "EUR", "value": "86.1000" } }, { "description": "Refunds iDEAL", "method": "refund", "count": 2, "amountNet": { "currency": "EUR", "value": "-43.2000" }, "amountVat": null, "amountGross": { "currency": "EUR", "value": "-43.2000" } } ], "costs": [ { "description": "iDEAL", "method": "ideal", "count": 6, "rate": { "fixed": { "currency": "EUR", "value": "0.3500" }, "percentage": null }, "amountNet": { "currency": "EUR", "value": "2.1000" }, "amountVat": { "currency": "EUR", "value": "0.4410" }, "amountGross": { "currency": "EUR", "value": "2.5410" } }, { "description": "Refunds iDEAL", "method": "refund", "count": 2, "rate": { "fixed": { "currency": "EUR", "value": "0.2500" }, "percentage": null }, "amountNet": { "currency": "EUR", "value": "0.5000" }, "amountVat": { "currency": "EUR", "value": "0.1050" }, "amountGross": { "currency": "EUR", "value": "0.6050" } } ], "invoiceId": "inv_FrvewDA3Pr" } } }, "settledAt": "2024-04-06T09:41:44+00:00", "_links": { "self": { "href": "...", "type": "application/hal+json" }, "payments": { "href": "https://api.mollie.com/v2/settlements/stl_jDk30akdN/payments", "type": "application/hal+json" }, "refunds": { "href": "https://api.mollie.com/v2/settlements/stl_jDk30akdN/refunds", "type": "application/hal+json" }, "chargebacks": { "href": "https://api.mollie.com/v2/settlements/stl_jDk30akdN/chargebacks", "type": "application/hal+json" }, "captures": { "href": "https://api.mollie.com/v2/settlements/stl_jDk30akdN/captures", "type": "application/hal+json" }, "invoice": { "href": "https://api.mollie.com/v2/invoices/inv_FrvewDA3Pr", "type": "application/hal+json" }, "documentation": { "href": "...", "type": "text/html" } } } } } } } }, "404": { "description": "No entity with this ID exists.", "content": { "application/hal+json": { "schema": { "type": "object", "description": "An error response object.", "required": [ "status", "title", "detail", "_links" ], "properties": { "status": { "type": "integer", "description": "The status code of the error message. This is always the same code as the status code of the HTTP message itself.", "minimum": 400, "maximum": 599, "example": 404 }, "title": { "type": "string", "description": "The HTTP reason phrase of the error. For example, for a `404` error, the `title` will be `Not Found`.", "example": "Not Found" }, "detail": { "type": "string", "description": "A detailed human-readable description of the error that occurred.", "example": "The resource does not exist" }, "field": { "type": "string", "description": "If the error was caused by a value provided by you in a specific field, the `field` property will contain the name of the field that caused the issue.", "example": "description" }, "_links": { "type": "object", "required": [ "documentation" ], "properties": { "documentation": { "type": "object", "description": "The URL to the generic Mollie API error handling guide.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "example": "https://docs.mollie.com/errors" }, "type": { "type": "string", "example": "text/html" } } } } } } }, "example": { "status": 404, "title": "Not Found", "detail": "No entity exists with token 'uct_abcDEFghij123456789'", "_links": { "documentation": { "href": "...", "type": "text/html" } } } } } }, "429": { "$ref": "#/components/responses/429-rate-limit" } }, "x-readme": { "code-samples": [ { "language": "shell", "code": "curl -X GET https://api.mollie.com/v2/settlements/stl_jDk30akdN \\\n -H \"Authorization: Bearer access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ\"" }, { "language": "php", "code": "setAccessToken('access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ');\n\n$request = new GetSettlementRequest('stl_jDk30akdN');\n\n$settlement = $mollie->send($request);", "install": "composer require mollie/mollie-api-php" }, { "language": "node", "code": "const { createMollieClient } = require('mollie-api-typescript');\nconst mollieClient = createMollieClient({ accessToken: 'access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ' });\n\nconst settlement = await mollieClient.settlements.get('stl_jDk30akdN');", "install": "npm install mollie-api-typescript" }, { "language": "python", "code": "from mollie.api.client import Client\n\nmollie_client = Client()\nmollie_client.set_access_token(\"access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ\")\n\nsettlement = mollie_client.settlements.get(\"stl_jDk30akdN\")", "install": "pip install mollie-api-py" }, { "language": "ruby", "code": "require 'mollie-api-ruby'\n\nMollie::Client.configure do |config|\n config.api_key = 'access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ'\nend\n\nsettlement = Mollie::settlement.get('stl_jDk30akdN')", "install": "gem install mollie-api-ruby" } ] } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Authenticates API requests for a single website profile. Each key targets\neither live mode (`live_...`) or test mode (`test_...`).\n\nKeys are shown only once, at creation. Store the key securely — it cannot\nbe retrieved afterwards. If lost, create a new key under Developers → API\naccess tokens in the Dashboard and revoke the old one.", "x-default": "live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" }, "advancedAccessToken": { "type": "http", "scheme": "bearer", "description": "Authenticates API requests with configurable permissions. Can access\norganization-level resources and optionally scope to a specific payment\nprofile (`access_...`). Use for advanced integrations — such as bookkeeping\nor reporting tools — that need fine-grained control over API access.\n\nTokens are shown only once, at creation. Store it securely — it cannot be\nretrieved afterwards. If lost, create a new token under Developers → API\naccess tokens in the Dashboard and revoke the old one.", "x-default": "access_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" }, "oAuth": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://my.mollie.com/oauth2/authorize", "tokenUrl": "https://api.mollie.com/oauth2/tokens", "scopes": {} } } } }, "responses": { "429-rate-limit": { "description": "Rate Limit has been reached.", "content": { "application/hal+json": { "schema": { "type": "object", "description": "An error response object.", "required": [ "status", "title", "detail", "_links" ], "properties": { "status": { "type": "integer", "description": "The status code of the error message. This is always the same code as the status code of the HTTP message itself.", "minimum": 400, "maximum": 599, "example": 404 }, "title": { "type": "string", "description": "The HTTP reason phrase of the error. For example, for a `404` error, the `title` will be `Not Found`.", "example": "Not Found" }, "detail": { "type": "string", "description": "A detailed human-readable description of the error that occurred.", "example": "The resource does not exist" }, "field": { "type": "string", "description": "If the error was caused by a value provided by you in a specific field, the `field` property will contain the name of the field that caused the issue.", "example": "description" }, "_links": { "type": "object", "required": [ "documentation" ], "properties": { "documentation": { "type": "object", "description": "The URL to the generic Mollie API error handling guide.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "example": "https://docs.mollie.com/errors" }, "type": { "type": "string", "example": "text/html" } } } } } } }, "example": { "status": 429, "title": "Too Many Requests", "detail": "You have exceeded the rate limit. Please slow down your requests.", "_links": { "documentation": { "href": "https://docs.mollie.com/overview/handling-errors", "type": "text/html" } } } } } } } }, "x-readme": { "explorer-enabled": false, "samples-languages": [ "shell", "php", "node", "python", "ruby" ] } } ```