Sign in

v55

OpenAPI 3.1.0CC-BY-NC-SA-4.0raw.githubusercontent.com2026-08-011243791.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.

post/v2/connect/balance-transfers

Headers

idempotency-keystring
Example:123e4567-e89b-12d3-a456-426

A unique key to ensure idempotent requests. This key should be a UUID v4 string.

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
descriptionstring required

The transfer description for initiating party.

status'created' | 'failed' | 'succeeded' required

The status of 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.

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.

mode'live' | 'test' required

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

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.