# List all Connect balance transfers

Returns a paginated list of balance transfers associated with your organization. These may be a balance transfer that was received or sent from your balance, or a balance transfer that you initiated on behalf of your clients. If no balance transfers are available, the resulting array will be empty. This request should never throw an error.

> 🔑 Access with
>
> [Organization 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": []
    },
    {
      "organizationAccessToken": []
    },
    {
      "oAuth": []
    }
  ],
  "paths": {
    "/v2/connect/balance-transfers": {
      "get": {
        "summary": "List all Connect balance transfers",
        "x-speakeasy-name-override": "list",
        "tags": [
          "Balance Transfers API"
        ],
        "operationId": "list-connect-balance-transfers",
        "security": [
          {
            "organizationAccessToken": [
              "balance-transfers.read"
            ]
          },
          {
            "oAuth": [
              "balance-transfers.read"
            ]
          }
        ],
        "description": "Returns a paginated list of balance transfers associated with your organization. These may be a balance transfer that was received or sent from your balance, or a balance transfer that you initiated on behalf of your clients. If no balance transfers are available, the resulting array will be empty. This request should never throw an error.\n\n> 🔑 Access with\n>\n> [Organization access token with **balance-transfers.read**](/reference/authentication)\n>\n> [OAuth access with **balance-transfers.read**](/reference/authentication)",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "example": "cbtr_j8NvRAM2WNZtsykpLEX8J"
            },
            "name": "from",
            "description": "Provide an ID to start the result set from the item with the given ID and onwards. This allows you to paginate the result set.",
            "in": "query"
          },
          {
            "name": "limit",
            "description": "The maximum number of items to return. Defaults to 50 items.",
            "in": "query",
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 1,
              "maximum": 250,
              "default": 50,
              "example": 50
            }
          },
          {
            "name": "sort",
            "description": "Used for setting the direction of the result set. Defaults to descending order, meaning the results are ordered from newest to oldest.\n\nPossible values: `asc` `desc`",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "desc"
            }
          },
          {
            "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": "A list of Connect balance transfers. For a complete reference of the Connect balance transfer object, refer to the [Get balance transfer endpoint](get-balance-transfer) documentation.",
            "content": {
              "application/hal+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "count",
                    "_embedded",
                    "_links"
                  ],
                  "properties": {
                    "count": {
                      "type": "integer",
                      "description": "The number of items in this result set. If more items are available, a `_links.next` URL will be present in the result as well.\n\nThe maximum number of items per result set is controlled by the `limit` property provided in the request. The default limit is 50 items.",
                      "minimum": 1,
                      "maximum": 250,
                      "example": 5
                    },
                    "_embedded": {
                      "type": "object",
                      "required": [
                        "connect_balance_transfers"
                      ],
                      "properties": {
                        "connect_balance_transfers": {
                          "description": "A list of Connect balance transfers.",
                          "type": "array",
                          "items": {
                            "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"
                            ]
                          }
                        }
                      }
                    },
                    "_links": {
                      "type": "object",
                      "description": "Links to help navigate through the lists of items. Every URL object will contain an `href` and a `type` field.",
                      "required": [
                        "self",
                        "previous",
                        "next",
                        "documentation"
                      ],
                      "properties": {
                        "self": {
                          "description": "The URL to the current set of items.",
                          "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"
                            }
                          }
                        },
                        "previous": {
                          "description": "The previous set of items, if available.",
                          "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"
                            }
                          }
                        },
                        "next": {
                          "description": "The next set of items, if available.",
                          "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"
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "list-balance-transfer-200-1": {
                    "summary": "List Connect balance transfers",
                    "value": {
                      "_embedded": {
                        "connect_balance_transfers": [
                          {
                            "resource": "connect-balance-transfer",
                            "id": "cbtr_bSAG5zQUrqbJGSv3ZSU9J",
                            "amount": {
                              "value": "200.00",
                              "currency": "EUR"
                            },
                            "source": {
                              "type": "organization",
                              "id": "org_1",
                              "description": "description for source"
                            },
                            "destination": {
                              "type": "organization",
                              "id": "org_42",
                              "description": "description for destination"
                            },
                            "description": "description for initiating party",
                            "status": "created",
                            "statusReason": {
                              "code": "request_created",
                              "message": "Balance transfer request created."
                            },
                            "createdAt": "2025-05-01T07:00:00+00:00",
                            "mode": "live"
                          },
                          {
                            "resource": "connect-balance-transfer",
                            "id": "cbtr_aGa49xYozWV8nhUzTSU9J",
                            "amount": {
                              "value": "100.00",
                              "currency": "EUR"
                            },
                            "source": {
                              "type": "organization",
                              "id": "org_42",
                              "description": "description for source"
                            },
                            "destination": {
                              "type": "organization",
                              "id": "org_2",
                              "description": "description for destination"
                            },
                            "description": "description for initiating party",
                            "status": "created",
                            "statusReason": {
                              "code": "request_created",
                              "message": "Balance transfer request created."
                            },
                            "metadata": {
                              "order_id": 12345,
                              "customer_id": 9876
                            },
                            "createdAt": "2025-05-01T06:00:00+00:00",
                            "mode": "live"
                          }
                        ]
                      },
                      "count": 2,
                      "_links": {
                        "self": {
                          "href": "https://api.mollie.com/v2/connect/balance-transfers?limit=50",
                          "type": "application/hal+json"
                        },
                        "previous": null,
                        "next": null,
                        "documentation": {
                          "href": "https://docs.mollie.com/reference/list-balance-transfers",
                          "type": "text/html"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request contains issues. For example, if the specified `from` value is not a valid ID.",
            "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": 400,
                  "title": "Bad Request",
                  "detail": "Invalid cursor value",
                  "field": "from",
                  "_links": {
                    "documentation": {
                      "href": "...",
                      "type": "text/html"
                    }
                  }
                }
              }
            }
          }
        },
        "x-speakeasy-pagination": {
          "type": "url",
          "outputs": {
            "nextUrl": "$._links.next.href"
          }
        },
        "x-readme": {
          "code-samples": [
            {
              "language": "shell",
              "code": "curl -X GET https://api.mollie.com/v2/connect/balance-transfers?limit=5 \\\n  -H \"Authorization: Bearer live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM\""
            },
            {
              "language": "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*/",
              "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": "'''\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-python"
            },
            {
              "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",
        "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"
    ]
  }
}
```