Sign in
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.

Changes

Changed in 2 of the 92 revisions of this API.3

  • 7cab62b218301See the full diff
    • ○

      added the non-success response with the status

      response-non-success-status-added

  • ef4b5a97b56a2See the full diff
    • ○

      the endpoint scheme security advancedAccessToken was added to the API

      api-security-added

    • ○

      the endpoint scheme security organizationAccessToken was removed from the API

      api-security-removed

    This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Of the 92 revisions, 9 have no diff computed.