v1

latestOpenAPI 3.1.0CC-BY-NC-SA-4.02026-07-2413803.8 MB

Balance Transfers API

Create a Connect balance transfer

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.

🔑 Access with

Advanced access token with balance-transfers.write

OAuth access with balance-transfers.write

post/v2/connect/balance-transfers

Request body

resourcestring required

Indicates the response contains a balance transfer object. Will always contain the string connect-balance-transfer for this endpoint.

idstring required

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.

descriptionstring required

The transfer description for initiating party.

statusstring required

The status of the transfer.

Possible values: created failed succeeded

categorystring

The type of the transfer. Different fees may apply to different types of transfers.

Possible values: invoice_collection purchase chargeback refund service_penalty discount_compensation manual_correction other_fee

metadataobject

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.

createdAtstring required

The entity's date and time of creation, in ISO 8601 format.

executedAtstring 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).

testmodeboolean

Whether to create the entity in test mode or live mode.

You can enable test mode by setting testmode to true.

modestring required

Whether this entity was created in live mode or in test mode.

Possible values: live test

Example request

{
  "resource": "connect-balance-transfer",
  "id": "cbtr_j8NvRAM2WNZtsykpLEX8J",
  "amount": {
    "currency": "EUR",
    "value": "10.00"
  },
  "source": {
    "type": "organization",
    "id": "org_1234567",
    "description": "Invoice fee"
  },
  "destination": {
    "type": "organization",
    "id": "org_1234567",
    "description": "Invoice fee"
  },
  "description": "Invoice fee",
  "status": "created",
  "statusReason": {
    "code": "insufficient_funds",
    "message": "Insufficient funds in the source balance."
  },
  "category": "invoice_collection",
  "metadata": {
    "order_id": 12345,
    "customer_id": 9876
  },
  "createdAt": "2024-03-20T09:13:37+00:00",
  "executedAt": "2024-03-20T09:28:37+00:00",
  "mode": "live"
}

Response

The balance transfer object.