--- updatedAt: 2026-05-12T14:02:14.000Z agentTools: projectIndex: https://docs.mollie.com/llms.txt --- # Create payout Request a payout from one of your balances to the balance's configured bank account. The payout will be executed on the next scheduled business day. If no `amount` is specified, the full available balance minus any configured balance reserve is paid out. Once the payout is created with status `requested`, you can cancel it via the [Cancel payout](cancel-payout) endpoint, up until the payout moves to `initiated`. Creating a payout via the API automatically sets the balance's `transferFrequency` to `never`, pausing any previously configured automatic settlement schedule. To resume automatic settlements, update the transfer frequency via the dashboard. ### Webhooks Subscribe to the following webhook events to track payout status changes. See the [Webhook Subscriptions API](list-webhooks) for details on subscribing. | Event | Description | |---|---| | `payout.initiated` | The payout is being executed and funds are reserved. | | `payout.processing-at-bank` | The payout has been submitted to the bank. | | `payout.completed` | The payout has been sent to the destination bank account. | | `payout.canceled` | The payout was canceled via the API before being submitted to the bank. | | `payout.failed` | The payout failed after creation, including bank rejections and post-submission cancellations. | ### Payout failure reasons A payout request may fail immediately if one of the following conditions applies: - A payout is already scheduled for the next business day for this balance. - The balance has insufficient funds. - The balance is not active. - Payouts are blocked for this organization. - The balance has queued refunds. - One of the organization's balances is below the negative balance threshold. - The payout destination (bank account) is invalid or not configured. > 🔑 Access with > > [API key](/reference/authentication) > > [Advanced access token with **payouts.write**](/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": { "/payouts": { "post": { "summary": "Create payout", "x-speakeasy-name-override": "create", "tags": [ "Payouts API" ], "operationId": "create-payout", "security": [ { "apiKey": [] }, { "advancedAccessToken": [ "payouts.write" ] } ], "description": "Request a payout from one of your balances to the balance's configured bank account.\n\nThe payout will be executed on the next scheduled business day. If no `amount` is specified, the full available balance minus any configured balance reserve is paid out.\n\nOnce the payout is created with status `requested`, you can cancel it via the [Cancel payout](cancel-payout) endpoint, up until the payout moves to `initiated`.\n\nCreating a payout via the API automatically sets the balance's `transferFrequency` to `never`, pausing any previously configured automatic settlement schedule. To resume automatic settlements, update the transfer frequency via the dashboard.\n\n### Webhooks\n\nSubscribe to the following webhook events to track payout status changes. See the [Webhook Subscriptions API](list-webhooks) for details on subscribing.\n\n| Event | Description |\n|---|---|\n| `payout.initiated` | The payout is being executed and funds are reserved. |\n| `payout.processing-at-bank` | The payout has been submitted to the bank. |\n| `payout.completed` | The payout has been sent to the destination bank account. |\n| `payout.canceled` | The payout was canceled via the API before being submitted to the bank. |\n| `payout.failed` | The payout failed after creation, including bank rejections and post-submission cancellations. |\n\n### Payout failure reasons\n\nA payout request may fail immediately if one of the following conditions applies:\n\n- A payout is already scheduled for the next business day for this balance.\n- The balance has insufficient funds.\n- The balance is not active.\n- Payouts are blocked for this organization.\n- The balance has queued refunds.\n- One of the organization's balances is below the negative balance threshold.\n- The payout destination (bank account) is invalid or not configured.\n\n> 🔑 Access with\n>\n> [API key](/reference/authentication)\n>\n> [Advanced access token with **payouts.write**](/reference/authentication)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "resource", "id", "balanceId", "status", "statusReason", "createdAt", "mode" ], "properties": { "resource": { "type": "string", "description": "Indicates the response contains a payout object. Will always contain the string `payout` for this endpoint.", "readOnly": true, "example": "payout" }, "id": { "type": "string", "description": "The identifier uniquely referring to this payout. Mollie assigns this identifier at payout creation time. Mollie will always refer to the payout by this ID. Example: `payout_j8NvRAM2WNZtsykpLEX8J`.", "readOnly": true, "example": "payout_j8NvRAM2WNZtsykpLEX8J" }, "balanceId": { "type": "string", "description": "The identifier of the balance that will be paid out. Example: `bal_gVMhHKqSSRYJyPsuoPNFH`.", "example": "bal_gVMhHKqSSRYJyPsuoPNFH" }, "amount": { "description": "The amount to pay out. When omitted from the request, the full available balance minus any configured balance reserve is paid out.\n\nMerchants registered in the United Kingdom cannot specify a custom amount — omit this field to pay out the full available balance.\n\nThe value in the response reflects the amount paid out, excluding any applicable fees.", "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" } } }, "description": { "type": [ "string", "null" ], "description": "The description that will appear on the bank statement for this payout.", "maxLength": 255, "example": "My payout description" }, "status": { "type": "string", "description": "The status of the payout.\n\nPossible values: `requested` `initiated` `processing-at-bank` `completed` `failed` `canceled`", "x-enumDescriptions": { "requested": "The payout has been requested and will be executed on the next scheduled date.", "initiated": "The payout is being executed. Funds are reserved on the balance.", "processing-at-bank": "The payout has been submitted to the bank and is being processed.", "completed": "The payout has been successfully sent to the destination bank account.", "failed": "The payout failed. Refer to the `statusReason` field for more details.", "canceled": "The payout was canceled before it could be executed." }, "readOnly": true, "example": "requested" }, "statusReason": { "type": "object", "description": "The reason for the payout's current status.", "readOnly": true, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A machine-readable code describing the reason for the payout's current status.\n\nPossible values: `requested` `initiated` `processing_at_bank` `completed` `canceled` `failed` `insufficient_funds` `returned` `invalid_request` `organization_inactive` `payouts_blocked` `bank_processing_failed` `balance_not_found` `expired`", "x-enumDescriptions": { "requested": "The payout has been requested.", "initiated": "The payout has been initiated.", "processing_at_bank": "The payout is being processed by the bank.", "completed": "The payout has been completed successfully.", "canceled": "The payout has been canceled.", "failed": "The payout has failed for an unknown reason.", "insufficient_funds": "Insufficient funds on the balance to complete the payout.", "returned": "The payout has been returned by the bank.", "invalid_request": "The payout request contained invalid data.", "organization_inactive": "The organization has been deactivated.", "payouts_blocked": "Payouts have been blocked for this organization.", "bank_processing_failed": "The payout could not be completed due to a processing error.", "balance_not_found": "The balance associated with this payout has been deleted.", "expired": "The payout expired before it could be processed." }, "readOnly": true, "example": "requested" }, "message": { "type": "string", "description": "A human-readable description of the status reason.", "example": "The payout has been requested." } } }, "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" }, "initiatedAt": { "type": [ "string", "null" ], "description": "The date and time the payout was initiated, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. This is the moment Mollie attempted to reserve the funds on the balance.", "readOnly": true, "example": "2024-03-20T09:13:40+00:00" }, "completedAt": { "type": [ "string", "null" ], "description": "The date and time the payout was sent to the destination bank account, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. `null` if the payout has not completed yet.", "readOnly": true, "example": "2024-03-20T14:00:00+00:00" }, "canceledAt": { "type": [ "string", "null" ], "description": "The date and time the payout was canceled, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. `null` if the payout was not canceled.", "readOnly": true, "example": null }, "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" }, "testmode": { "type": [ "boolean", "null" ], "description": "Whether to create the entity in test mode or live mode.\n\nMost API credentials are specifically created for either live mode or test mode, in which case this parameter must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting `testmode` to `true`.", "writeOnly": true, "example": false }, "_links": { "type": "object", "description": "An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.", "readOnly": true, "required": [ "self", "documentation" ], "properties": { "self": { "description": "The URL to the current resource.", "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" } } }, "documentation": { "description": "The URL to the documentation of the current resource.", "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" } } } } } } }, { "type": "object", "required": [ "balanceId" ] } ] } } } }, "responses": { "201": { "description": "The newly created payout object.", "content": { "application/hal+json": { "schema": { "type": "object", "required": [ "resource", "id", "balanceId", "status", "statusReason", "createdAt", "mode" ], "properties": { "resource": { "type": "string", "description": "Indicates the response contains a payout object. Will always contain the string `payout` for this endpoint.", "readOnly": true, "example": "payout" }, "id": { "type": "string", "description": "The identifier uniquely referring to this payout. Mollie assigns this identifier at payout creation time. Mollie will always refer to the payout by this ID. Example: `payout_j8NvRAM2WNZtsykpLEX8J`.", "readOnly": true, "example": "payout_j8NvRAM2WNZtsykpLEX8J" }, "balanceId": { "type": "string", "description": "The identifier of the balance that will be paid out. Example: `bal_gVMhHKqSSRYJyPsuoPNFH`.", "example": "bal_gVMhHKqSSRYJyPsuoPNFH" }, "amount": { "description": "The amount to pay out. When omitted from the request, the full available balance minus any configured balance reserve is paid out.\n\nMerchants registered in the United Kingdom cannot specify a custom amount — omit this field to pay out the full available balance.\n\nThe value in the response reflects the amount paid out, excluding any applicable fees.", "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" } } }, "description": { "type": [ "string", "null" ], "description": "The description that will appear on the bank statement for this payout.", "maxLength": 255, "example": "My payout description" }, "status": { "type": "string", "description": "The status of the payout.\n\nPossible values: `requested` `initiated` `processing-at-bank` `completed` `failed` `canceled`", "x-enumDescriptions": { "requested": "The payout has been requested and will be executed on the next scheduled date.", "initiated": "The payout is being executed. Funds are reserved on the balance.", "processing-at-bank": "The payout has been submitted to the bank and is being processed.", "completed": "The payout has been successfully sent to the destination bank account.", "failed": "The payout failed. Refer to the `statusReason` field for more details.", "canceled": "The payout was canceled before it could be executed." }, "readOnly": true, "example": "requested" }, "statusReason": { "type": "object", "description": "The reason for the payout's current status.", "readOnly": true, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A machine-readable code describing the reason for the payout's current status.\n\nPossible values: `requested` `initiated` `processing_at_bank` `completed` `canceled` `failed` `insufficient_funds` `returned` `invalid_request` `organization_inactive` `payouts_blocked` `bank_processing_failed` `balance_not_found` `expired`", "x-enumDescriptions": { "requested": "The payout has been requested.", "initiated": "The payout has been initiated.", "processing_at_bank": "The payout is being processed by the bank.", "completed": "The payout has been completed successfully.", "canceled": "The payout has been canceled.", "failed": "The payout has failed for an unknown reason.", "insufficient_funds": "Insufficient funds on the balance to complete the payout.", "returned": "The payout has been returned by the bank.", "invalid_request": "The payout request contained invalid data.", "organization_inactive": "The organization has been deactivated.", "payouts_blocked": "Payouts have been blocked for this organization.", "bank_processing_failed": "The payout could not be completed due to a processing error.", "balance_not_found": "The balance associated with this payout has been deleted.", "expired": "The payout expired before it could be processed." }, "readOnly": true, "example": "requested" }, "message": { "type": "string", "description": "A human-readable description of the status reason.", "example": "The payout has been requested." } } }, "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" }, "initiatedAt": { "type": [ "string", "null" ], "description": "The date and time the payout was initiated, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. This is the moment Mollie attempted to reserve the funds on the balance.", "readOnly": true, "example": "2024-03-20T09:13:40+00:00" }, "completedAt": { "type": [ "string", "null" ], "description": "The date and time the payout was sent to the destination bank account, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. `null` if the payout has not completed yet.", "readOnly": true, "example": "2024-03-20T14:00:00+00:00" }, "canceledAt": { "type": [ "string", "null" ], "description": "The date and time the payout was canceled, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. `null` if the payout was not canceled.", "readOnly": true, "example": null }, "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" }, "testmode": { "type": [ "boolean", "null" ], "description": "Whether to create the entity in test mode or live mode.\n\nMost API credentials are specifically created for either live mode or test mode, in which case this parameter must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting `testmode` to `true`.", "writeOnly": true, "example": false }, "_links": { "type": "object", "description": "An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.", "readOnly": true, "required": [ "self", "documentation" ], "properties": { "self": { "description": "The URL to the current resource.", "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" } } }, "documentation": { "description": "The URL to the documentation of the current resource.", "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" } } } } } } }, "examples": { "create-payout-201": { "summary": "Requested payout", "value": { "resource": "payout", "id": "payout_j8NvRAM2WNZtsykpLEX8J", "balanceId": "bal_gVMhHKqSSRYJyPsuoPNFH", "amount": { "currency": "EUR", "value": "10.00" }, "description": "My payout description", "status": "requested", "statusReason": { "code": "requested", "message": "The payout has been requested." }, "createdAt": "2024-03-20T09:13:37+00:00", "initiatedAt": null, "completedAt": null, "canceledAt": null, "mode": "live", "_links": { "self": { "href": "https://api.mollie.com/v2/payouts/payout_j8NvRAM2WNZtsykpLEX8J", "type": "application/hal+json" }, "documentation": { "href": "https://docs.mollie.com/reference/get-payout", "type": "text/html" } } } } } } } }, "422": { "description": "The request contains issues. For example, the `balanceId` is invalid or the balance has insufficient funds.", "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": 422, "title": "Unprocessable Entity", "detail": "The 'balanceId' field is invalid.", "field": "balanceId", "_links": { "documentation": { "href": "https://docs.mollie.com/errors", "type": "text/html" } } } } } }, "429": { "$ref": "#/components/responses/429-rate-limit" } }, "x-readme": { "code-samples": [ { "language": "shell", "code": "curl -i -X POST \\\nhttps://api.mollie.com/v2/payouts \\\n-H 'Authorization: Bearer ' \\\n-H 'Content-Type: application/json' \\\n -d '{\n \"balanceId\": \"bal_gVMhHKqSSRYJyPsuoPNFH\",\n \"amount\": {\n \"currency\": \"EUR\",\n \"value\": \"10.00\"\n },\n \"description\": \"My payout description\"\n }'" }, { "language": "php", "code": "setApiKey(\"access_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM\");\n\n$payout = $mollie->payouts->create([\n \"balanceId\" => \"bal_gVMhHKqSSRYJyPsuoPNFH\",\n \"amount\" => [\n \"currency\" => \"EUR\",\n \"value\" => \"10.00\",\n ],\n \"description\" => \"My payout description\",\n]);", "install": "composer require mollie/mollie-api-php" }, { "language": "node", "code": "const { createMollieClient } = require('mollie-api-typescript');\nconst mollieClient = createMollieClient({ apiKey: 'access_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM' });\n\nconst payout = await mollieClient.payouts.create({\n balanceId: 'bal_gVMhHKqSSRYJyPsuoPNFH',\n amount: {\n currency: 'EUR',\n value: '10.00'\n },\n description: 'My payout description'\n});", "install": "npm install mollie-api-typescript" }, { "language": "python", "code": "from mollie.api.client import Client\n\nmollie_client = Client()\nmollie_client.set_api_key(\"access_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM\")\n\npayout = mollie_client.payouts.create({\n \"balanceId\": \"bal_gVMhHKqSSRYJyPsuoPNFH\",\n \"amount\": {\n \"currency\": \"EUR\",\n \"value\": \"10.00\",\n },\n \"description\": \"My payout description\",\n})", "install": "pip install mollie-api-py" }, { "language": "ruby", "code": "require 'mollie-api-ruby'\n\nMollie::Client.configure do |config|\n config.api_key = 'access_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM'\nend\n\npayout = Mollie::Payout.create(\n balance_id: 'bal_gVMhHKqSSRYJyPsuoPNFH',\n amount: {\n currency: 'EUR',\n value: '10.00'\n },\n description: 'My payout description'\n)", "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" ] } } ```