--- updatedAt: 2026-04-21T08:31:19.000Z agentTools: projectIndex: https://docs.mollie.com/llms.txt --- # Get a Connect balance transfer Retrieve a single Connect balance transfer object by its ID. > 🔑 Access with > > [Advanced access token with **balance-transfers.read**](/reference/authentication) > > [OAuth access with **balance-transfers.read**](/reference/authentication) # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Mollie Connect", "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" } ], "security": [ { "apiKey": [] }, { "advancedAccessToken": [] }, { "oAuth": [] } ], "paths": { "/v2/connect/balance-transfers/{balanceTransferId}": { "parameters": [ { "name": "balanceTransferId", "description": "Provide the ID of the related balance transfer.", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cbtr_.+$", "example": "cbtr_j8NvRAM2WNZtsykpLEX8J" } } ], "get": { "summary": "Get a Connect balance transfer", "x-speakeasy-name-override": "get", "tags": [ "Balance Transfers API" ], "operationId": "get-connect-balance-transfer", "security": [ { "advancedAccessToken": [ "balance-transfers.read" ] }, { "oAuth": [ "balance-transfers.read" ] } ], "description": "Retrieve a single Connect balance transfer object by its ID.\n\n> 🔑 Access with\n>\n> [Advanced access token with **balance-transfers.read**](/reference/authentication)\n>\n> [OAuth access with **balance-transfers.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 Connect balance transfer object.", "content": { "application/hal+json": { "schema": { "type": "object", "properties": { "resource": { "type": "string", "description": "Indicates the response contains a balance transfer object. Will always contain the string `connect-balance-transfer` for this endpoint.", "readOnly": true, "example": "connect-balance-transfer" }, "id": { "allOf": [ { "type": "string", "pattern": "^cbtr_.+$", "example": "cbtr_j8NvRAM2WNZtsykpLEX8J" } ], "description": "The identifier uniquely referring to this balance transfer. Mollie assigns this identifier at balance transfer creation time. Mollie will always refer to the balance transfer by this ID. Example: `cbtr_j8NvRAM2WNZtsykpLEX8J`.", "readOnly": true }, "amount": { "description": "The amount to be transferred, e.g. `{\"currency\":\"EUR\", \"value\":\"1000.00\"}` if you would like to transfer €1000.00.", "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" } } }, "source": { "type": "object", "description": "A party involved in the balance transfer, either the sender or the receiver.", "properties": { "type": { "type": "string", "description": "Defines the type of the party. At the moment, only `organization` is supported.\n\nPossible values: `organization`", "example": "organization" }, "id": { "description": "Identifier of the party. For example, this contains the organization token if the type is `organization`.", "type": "string", "pattern": "^org_.+$", "example": "org_1234567" }, "description": { "type": "string", "description": "The transfer description for the transfer party. This is the description that will appear in the financial reports of the party.", "maxLength": 255, "example": "Invoice fee" } }, "required": [ "type", "id", "description" ] }, "destination": { "type": "object", "description": "A party involved in the balance transfer, either the sender or the receiver.", "properties": { "type": { "type": "string", "description": "Defines the type of the party. At the moment, only `organization` is supported.\n\nPossible values: `organization`", "example": "organization" }, "id": { "description": "Identifier of the party. For example, this contains the organization token if the type is `organization`.", "type": "string", "pattern": "^org_.+$", "example": "org_1234567" }, "description": { "type": "string", "description": "The transfer description for the transfer party. This is the description that will appear in the financial reports of the party.", "maxLength": 255, "example": "Invoice fee" } }, "required": [ "type", "id", "description" ] }, "description": { "type": "string", "description": "The transfer description for initiating party.", "maxLength": 255, "example": "Invoice fee" }, "status": { "type": "string", "readOnly": true, "description": "The status of the transfer.\n\nPossible values: `created` `failed` `succeeded`", "example": "created" }, "statusReason": { "type": "object", "readOnly": true, "description": "The reason for the current status of the transfer, if applicable.", "properties": { "code": { "type": "string", "description": "A machine-readable code that indicates the reason for the transfer's status.\n\nPossible values: `request_created` `success` `source_not_allowed` `destination_not_allowed` `insufficient_funds` `invalid_source_balance` `invalid_destination_balance` `transfer_request_expired` `transfer_limit_reached`", "example": "insufficient_funds", "x-enumDescriptions": { "request_created": "Balance transfer request was created.", "success": "Balance transfer completed successfully.", "source_not_allowed": "Balance transfers from the source organization are not allowed.", "destination_not_allowed": "Balance transfers to the destination organization are not allowed.", "insufficient_funds": "Source does not have enough balance.", "invalid_source_balance": "Invalid balance for source organization.", "invalid_destination_balance": "Invalid balance for destination organization.", "transfer_request_expired": "Request for balance transfer has expired.", "transfer_limit_reached": "Transfer limit has been exceeded." } }, "message": { "type": "string", "description": "A description of the status reason, localized according to the transfer.", "example": "Insufficient funds in the source balance." } }, "required": [ "code", "message" ] }, "category": { "type": "string", "description": "The type of the transfer. Different fees may apply to different types of transfers.\n\nPossible values: `invoice_collection` `purchase` `chargeback` `refund` `service_penalty` `discount_compensation` `manual_correction` `other_fee`", "example": "invoice_collection" }, "metadata": { "type": "object", "description": "A JSON object that you can attach to a balance transfer. This can be useful for storing additional information about the transfer in a structured format. Maximum size is approximately 1KB.", "additionalProperties": true, "example": { "order_id": 12345, "customer_id": 9876 } }, "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" }, "executedAt": { "type": [ "string", "null" ], "description": "The date and time when the transfer was completed, in ISO 8601 format. This parameter is omitted if the transfer is not executed (yet).", "readOnly": true, "example": "2024-03-20T09:28:37+00:00" }, "testmode": { "type": "boolean", "description": "Whether to create the entity in test mode or live mode.\n\nYou can enable test mode by setting `testmode` to `true`.", "writeOnly": true, "example": false }, "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" } }, "required": [ "resource", "id", "amount", "source", "destination", "description", "status", "statusReason", "createdAt", "mode" ] }, "examples": { "get-balance-transfer-200-1": { "summary": "Get a successful Connect balance transfer", "value": { "resource": "connect-balance-transfer", "id": "cbtr_nBprRarXeqXi98AXSqCBJ", "amount": { "value": "100.00", "currency": "EUR" }, "source": { "type": "organization", "id": "org_1", "description": "description for source" }, "destination": { "type": "organization", "id": "org_2", "description": "description for destination" }, "description": "description for initiating party", "status": "succeeded", "statusReason": { "code": "success", "message": "Balance transfer completed successfully." }, "metadata": { "order_id": 12345, "customer_id": 9876 }, "createdAt": "2025-05-01T10:00:00+00:00", "executedAt": "2025-05-01T10:05:00+00:00", "mode": "live" } } } } } }, "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/connect/balance-transfers/cbtr_j8NvRAM2WNZtsykpLEX8J \\\n -H \"Authorization: Bearer live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM\"" }, { "language": "php", "install": "composer require mollie/oauth2-mollie-php", "code": "/*\nWe don't have a PHP 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*/" }, { "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-typescript" }, { "language": "python", "code": "'''\nWe don't have a Python 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": "pip install mollie-api-py" }, { "language": "ruby", "code": "# We don't have a Ruby code example for this\n# API call yet.\n#\n# If you have some time to spare, feel free to\n# share suggestions on our Discord:\n# https://discord.gg/VaTVkXB4aQ", "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" ] } } ```