---
title: "Create a Connect balance transfer"
method: POST
path: "/v2/connect/balance-transfers"
tags: ["Balance Transfers API"]
---

# Create a Connect balance transfer

`POST /v2/connect/balance-transfers`

This API endpoint allows you to create a balance transfer from your organization's balance to a connected organization's balance, or vice versa.
You can also create a balance transfer between two connected organizations.
To create a balance transfer, you must be authenticated as the source organization, and the destination organization must be a connected organization
that has authorized the `balance-transfers.write` scope for your organization.

## Headers

- `idempotency-key` string

## Request body

- EntityBalanceTransfer
  - `resource` string, required — Indicates the response contains a balance transfer object. Will always contain the string `connect-balance-transfer` for this endpoint.
  - `id` string, required
  - `amount` Amount, required — In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.
    - `currency` string, required — A three-character ISO 4217 currency code.
    - `value` string, required — A string containing an exact monetary amount in the given currency.
  - `source` EntityBalanceTransferParty, required — A party involved in the balance transfer, either the sender or the receiver.
    - `type` 'organization', required — Defines the type of the party. At the moment, only `organization` is supported.
    - `id` string, required
    - `description` string, required — The transfer description for the transfer party. This is the description that will appear in the financial reports of the party.
  - `destination` EntityBalanceTransferParty, required — A party involved in the balance transfer, either the sender or the receiver.
    - `type` 'organization', required — Defines the type of the party. At the moment, only `organization` is supported.
    - `id` string, required
    - `description` string, required — The transfer description for the transfer party. This is the description that will appear in the financial reports of the party.
  - `description` string, required — The transfer description for initiating party.
  - `status` 'created' | 'failed' | 'succeeded', required — The status of the transfer.
  - `statusReason` object, required — The reason for the current status of the transfer, if applicable.
    - `code` 'request_created' | 'success' | 'source_not_allowed' | 'destination_not_allowed' | 'insufficient_funds' | 'invalid_source_balance' | 'invalid_destination_balance' | 'transfer_request_expired' | 'transfer_limit_reached', required — A machine-readable code that indicates the reason for the transfer's status.
    - `message` string, required — A description of the status reason, localized according to the transfer.
  - `category` 'invoice_collection' | 'purchase' | 'chargeback' | 'refund' | 'service_penalty' | 'discount_compensation' | 'manual_correction' | 'other_fee' — The type of the transfer. Different fees may apply to different types of transfers.
  - `metadata` object — 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.
  - `createdAt` string, required — The entity's date and time of creation, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
  - `executedAt` string, nullable — The date and time when the transfer was completed, in ISO 8601 format. This parameter is omitted if the transfer is not executed (yet).
  - `testmode` boolean — Whether to create the entity in test mode or live mode. You can enable test mode by setting `testmode` to `true`.
  - `mode` 'live' | 'test', required — Whether this entity was created in live mode or in test mode.

## Response `201`

The balance transfer object.

## Other responses

- `422` — The request contains issues. For example, if the amount is missing.
- `429` — Rate Limit has been reached.

---

[API](https://skmtc.net/mollie/apis/mollie-api.md) · [All operations](https://skmtc.net/mollie/apis/mollie-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mollie/mollie-api/revisions/d2a3bd80c1fa/schema)