# Get balance When processing payments with Mollie, we put all pending funds — usually minus Mollie fees — on a balance. Once you have linked a bank account to your Mollie account, we can pay out your balance towards this bank account. With the Balances API you can retrieve your current balance. The response includes two amounts: * The *pending amount*. These are payments that have been marked as `paid`, but are not yet available on your balance. * The *available amount*. This is the amount that you can get paid out to your bank account, or use for refunds. With instant payment methods like iDEAL, payments are moved to the available balance instantly. With slower payment methods, like credit card for example, it can take a few days before the funds are available on your balance. These funds will be shown under the *pending amount* in the meanwhile. > 🔑 Access with > > [Organization access token with **balances.read**](/reference/authentication) > > [OAuth access with **balances.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": [] }, { "organizationAccessToken": [] }, { "oAuth": [] } ], "paths": { "/balances/{balanceId}": { "parameters": [ { "name": "balanceId", "description": "Provide the ID of the related balance.", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^bal_.+$", "example": "bal_gVMhHKqSSRYJyPsuoPNFH" } } ], "get": { "summary": "Get balance", "x-speakeasy-name-override": "get", "tags": [ "Balances API" ], "operationId": "get-balance", "security": [ { "organizationAccessToken": [ "balances.read" ] }, { "oAuth": [ "balances.read" ] } ], "description": "When processing payments with Mollie, we put all pending funds — usually minus Mollie fees — on a balance. Once you have linked a bank account to your Mollie account, we can pay out your balance towards this bank account.\n\nWith the Balances API you can retrieve your current balance. The response includes two amounts:\n\n* The *pending amount*. These are payments that have been marked as `paid`, but are not yet available on your balance.\n* The *available amount*. This is the amount that you can get paid out to your bank account, or use for refunds.\n\nWith instant payment methods like iDEAL, payments are moved to the available balance instantly. With slower payment methods, like credit card for example, it can take a few days before the funds are available on your balance. These funds will be shown under the *pending amount* in the meanwhile.\n\n> 🔑 Access with\n>\n> [Organization access token with **balances.read**](/reference/authentication)\n>\n> [OAuth access with **balances.read**](/reference/authentication)", "parameters": [ { "name": "testmode", "description": "You can enable test mode by setting the `testmode` query parameter to `true`.\n\nTest entities cannot be retrieved when the endpoint is set to live mode, and vice versa.", "in": "query", "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "The balance object.", "content": { "application/hal+json": { "schema": { "type": "object", "required": [ "resource", "id", "mode", "createdAt", "currency", "description", "availableAmount", "pendingAmount", "status", "_links" ], "properties": { "resource": { "type": "string", "description": "Indicates the response contains a balance object. Will always contain the string `balance` for this endpoint.", "readOnly": true, "default": "balance", "example": "balance" }, "id": { "allOf": [ { "type": "string", "pattern": "^bal_.+$", "example": "bal_gVMhHKqSSRYJyPsuoPNFH" } ], "description": "The identifier uniquely referring to this balance.", "readOnly": true }, "mode": { "type": "string", "description": "Whether this entity was created in live mode or in test mode.\n\nPossible values: `live` `test`", "readOnly": true, "example": "live" }, "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" }, "currency": { "allOf": [ { "type": "string", "enum": [ "EUR", "GBP", "CHF", "DKK", "NOK", "PLN", "SEK", "USD", "CZK", "HUF", "AUD", "CAD" ], "x-enumDescriptions": { "EUR": "Euro", "GBP": "British Pound", "CHF": "Swiss Franc", "DKK": "Danish Krone", "NOK": "Norwegian Krone", "PLN": "Polish złoty", "SEK": "Swedish Krona", "USD": "United States Dollar", "CZK": "Czech Koruna", "HUF": "Hungarian Forint", "AUD": "Australian Dollar", "CAD": "Canadian Dollar" }, "example": "EUR" } ], "description": "The balance's ISO 4217 currency code.", "readOnly": true }, "description": { "type": "string", "description": "The description or name of the balance. Can be used to denote the purpose of the balance.", "readOnly": true, "example": "Balance description" }, "status": { "allOf": [ { "type": "string", "description": "The status of the balance.\n\nPossible values: `active` `inactive`", "x-enumDescriptions": { "active": "The balance is operational and ready to be used.", "inactive": "The account is being validated by our team, or the balance has been blocked. Contact us for more information." }, "example": "active" } ], "readOnly": true }, "transferFrequency": { "allOf": [ { "type": "string", "description": "The frequency with which the available amount on the balance will be settled to the configured transfer destination.\n\nSettlements created during weekends or on bank holidays will take place on the next business day.\n\nPossible values: `every-day` `daily` `every-monday` `every-tuesday` `every-wednesday` `every-thursday` `every-friday` `monthly` `revenue-day` `never`", "x-enumDescriptions": { "every-day": "Every day (Business Account required)", "daily": "Every business day", "every-monday": "Every Monday", "every-tuesday": "Every Tuesday", "every-wednesday": "Every Wednesday", "every-thursday": "Every Thursday", "every-friday": "Every Friday", "monthly": "On the first of the month", "revenue-day": "Revenue day (eligibility applies)", "never": "Automatic settlements are paused for this balance" }, "example": "daily" } ], "readOnly": true }, "transferThreshold": { "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 minimum amount configured for scheduled automatic settlements. As soon as the amount on the balance exceeds this threshold, the complete balance will be paid out to the transfer destination according to the configured frequency.", "readOnly": true }, "transferReference": { "type": [ "string", "null" ], "description": "The transfer reference set to be included in all the transfers for this balance.", "example": "RF12-3456-7890-1234", "readOnly": true }, "transferDestination": { "type": [ "object", "null" ], "description": "The destination where the available amount will be automatically transferred to according to the configured transfer frequency.", "properties": { "type": { "type": "string", "description": "The default destination of automatic scheduled transfers. Currently only `bank-account` is supported.\n\n* `bank-account` — Transfer the balance amount to an external bank account\n\nPossible values: `bank-account`", "example": "bank-account" }, "bankAccount": { "type": "string", "description": "The configured bank account number of the beneficiary the balance amount is to be transferred to.", "example": 123456 }, "beneficiaryName": { "type": "string", "description": "The full name of the beneficiary the balance amount is to be transferred to.", "example": "John Doe" } }, "readOnly": true }, "availableAmount": { "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 amount directly available on the balance, e.g. `{\"currency\":\"EUR\", \"value\":\"100.00\"}`.", "readOnly": true }, "pendingAmount": { "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 that is queued to be transferred to your balance. For example, a credit card payment can take a few days to clear.", "readOnly": true }, "_links": { "type": "object", "description": "An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.", "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" } } }, "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-balance-200-1": { "summary": "The balance object", "value": { "resource": "balance", "id": "bal_gVMhHKqSSRYJyPsuoPNFH", "mode": "live", "createdAt": "2019-12-06T10:09:32+00:00", "currency": "EUR", "description": "Primary balance", "availableAmount": { "currency": "EUR", "value": "905.25" }, "pendingAmount": { "currency": "EUR", "value": "0.00" }, "transferFrequency": "daily", "transferThreshold": { "currency": "EUR", "value": "5.00" }, "transferReference": "RF12-3456-7890-1234", "transferDestination": { "type": "bank-account", "beneficiaryName": "John Doe", "bankAccount": "NL55INGB0000000000" }, "status": "active", "_links": { "self": { "href": "...", "type": "application/hal+json" }, "documentation": { "href": "...", "type": "text/html" } } } }, "get-balance-200-2": { "summary": "Get balance", "value": { "resource": "balance", "id": "bal_CKjKwQdjCwCSArXFAJNFH", "mode": "live", "createdAt": "2019-12-06T10:09:32+00:00", "description": "Primary balance", "currency": "EUR", "availableAmount": { "value": "3.82", "currency": "EUR" }, "pendingAmount": { "value": "5.41", "currency": "EUR" }, "status": "active", "transferFrequency": "daily", "transferThreshold": { "value": "5.00", "currency": "EUR" }, "transferReference": null, "transferDestination": { "type": "bank-account", "beneficiaryName": "John Doe", "bankAccount": "NL55INGB0000000000" }, "_links": { "self": { "href": "...", "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" } } } } } } }, "x-readme": { "code-samples": [ { "language": "shell", "code": "curl -X GET https://api.mollie.com/v2/balances/bal_gVMhHKqSSRYJyPsuoPNFH \\\n -H \"Authorization: Bearer access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ\"" }, { "language": "php", "code": "setAccessToken(\"access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ\");\n\n$balance = $mollie->send(\n new GetBalanceRequest(\"bal_gVMhHKqSSRYJyPsuoPNFH\")\n);", "install": "composer require mollie/mollie-api-php" }, { "language": "node", "code": "/*\nWe don't have a Node.js code example for this\nAPI call yet.\n\nIf you have some time to spare, feel free to\nshare suggestions on our Discord:\nhttps://discord.gg/VaTVkXB4aQ\n*/", "install": "npm install @mollie/api-client" }, { "language": "python", "code": "from mollie.api.client import Client\n\nmollie_client = Client()\nmollie_client.set_access_token(\"access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ\")\n\nbalance = mollie_client.balances.get(\"bal_gVMhHKqSSRYJyPsuoPNFH\")", "install": "pip install mollie-api-python" }, { "language": "ruby", "code": "require 'mollie-api-ruby'\n\nMollie::Client.configure do |config|\n config.api_key = 'access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ'\nend\n\nbalance = Mollie::Balance.get('bal_gVMhHKqSSRYJyPsuoPNFH')", "install": "gem install mollie-api-ruby" } ] } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "x-default": "live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" }, "organizationAccessToken": { "type": "http", "scheme": "bearer", "x-default": "access_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" }, "oAuth": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://my.mollie.com/oauth2/authorize", "tokenUrl": "https://api.mollie.com/oauth2/tokens", "scopes": {} } } } } }, "x-readme": { "explorer-enabled": false, "samples-languages": [ "shell", "php", "node", "python", "ruby" ] } } ```