Balance Transfers

Our Balance Transfers API provides platforms the option to create a money movement between their FBO (For the Benefit Of) Settlement account and their operating account. This is only available for Finix Core customers with Litle V12 credentials.

If you have any questions, please reach out to your Finix point of contact or contact Finix Support.

Create a Balance Transfer

Create a balance_transfer.

Request
header Parameters
Accept
string
Default: application/hal+json
Request Body schema: application/json
amount
required
integer <int64>

The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).

currency
required
string

ISO 4217 3 letter currency code.

Enum: "AED" "AFN" "ALL" "AMD" "ANG" … 174 more
description
required
string

Additional information about the balance_transfer (e.g. Transferring funds for Holidays).

destination
required
string or null

The account where funds get credited. For balance transfers, this is an aliased ID and will have the value of FOR_BENEFIT_OF_ACCOUNT or OPERATING_ACCOUNT.

Enum: "FOR_BENEFIT_OF_ACCOUNT" "OPERATING_ACCOUNT"
processor_type
required
string

Pass LITLE_V1; balance_transfers are only available for platforms with LITLE_V1 credentials.

source
required
string

The account where funds get debited. For balance transfers, this is an aliased ID and will have the value of FOR_BENEFIT_OF_ACCOUNT or OPERATING_ACCOUNT.

Enum: "FOR_BENEFIT_OF_ACCOUNT" "OPERATING_ACCOUNT"
object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500. (For example, order_number: 25, item_type: produce, department: sales)
Responses
201

Single balance_transfer object

400

Error

401

Authentication information is missing or invalid

403

Forbidden

406

Not Acceptable

post/balance_transfers
Request samples 
curl "https://finix.sandbox-payments-api.com/balance_transfers" \
  -H "Content-Type: application/json" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -d '
  {
    "amount": 4000,
    "currency": "USD",
    "description": "Need to increase buffer given the high number of NSFs on merchant fee debits",
    "destination": "FOR_BENEFIT_OF_ACCOUNT",
    "processor_type": "LITLE_V1",
    "source": "OPERATING_ACCOUNT",
    "tags": {
      "example": "documentation tag"
    }
  }'
Response samples
application/json
{
  • "id": "BT_9SLA5BdQs6Z3xFpmjUoqhM",
  • "created_at": "2022-08-18T06:37:50.67Z",
  • "updated_at": "2022-08-18T06:37:51.09Z",
  • "amount": 101,
  • "currency": "USD",
  • "description": "setup balance transfer for testing",
  • "destination": "OPERATING_ACCOUNT",
  • "external_reference_id": "84077657260162531",
  • "processor_type": "LITLE_V1",
  • "reference_id": "FNX5ZJEGdPT5odwtRrvxVrYUn",
  • "source": "FOR_BENEFIT_OF_ACCOUNT",
  • "state": "SUCCEEDED",
  • "tags": {
    • "test_key_101": "test_val_101"
    },
  • "_links": {}
}

List Balance Transfers

Retrieve a list of all balance_transfers.

For details on how to query endpoints using the available parameters, see Query Parameters.

Request
query Parameters
limit
integer

The numbers of items to return.

Example: limit=10
pageNumber
integer

The page number to list.

pageSize
integer

The size of the page.

created_at.gte
string <date-time>

Filter where created_at is after the given date.

Example: created_at.gte=2022-09-27T11:21:23
created_at.lte
string <date-time>

Filter where created_at is before the given date.

Example: created_at.lte=2022-09-27T11:21:23
updated_at.gte
string <date-time>

Filter where updated_at is after the given date.

Example: updated_at.gte=2022-09-27T11:21:23
updated_at.lte
string <date-time>

Filter where updated_at is before the given date.

Example: updated_at.lte=2023-01-21T10:17:22
idempotency_id
string

Filter by Idempotency ID.

Example: idempotency_id=15d32948-c766-4033-8d87-dfbdcabcbc5c
amount
integer

Filter by an amount equal to the given value.

Example: amount=100
description
string

Filter by the Description value .

destination
string

Filter by the Payment Instrument saved in Destination.

external_reference_id
string

Filter by the value saved in external_reference_id.

reference_id
string

Filter by the value saved in reference_id.

source
string

Filter by the Payment Instrument saved in source.

header Parameters
Accept
string
Default: application/hal+json
Responses
200

List of balance_transfer objects

400

Error

401

Authentication information is missing or invalid

403

Forbidden

404

Not Found

406

Not Acceptable

get/balance_transfers
Request samples 
curl "https://finix.sandbox-payments-api.com/balance_transfers/" \
  -H "Finix-Version: 2022-02-01" \
  -u USbkjk46XqUTQHN3i2jaVnc1:ac915962-2757-49ea-aeee-10960a408b99
Response samples
application/json
{}

Fetch a Balance Transfer

Retrieve the details of a balance_transfer.

Request
path Parameters
balance_transfers_id
required
string

ID of the balance_transfer resource.

header Parameters
Accept
string
Default: application/hal+json
Responses
200

Single balance_transfer object

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/balance_transfers/{balance_transfers_id}
Request samples 
curl "https://finix.sandbox-payments-api.com/balance_transfers/BT_9SLA5BdQs6Z3xFpmjUoqhM" \
  -H "Finix-Version: 2022-02-01" \
  -u USbkjk46XqUTQHN3i2jaVnc1:ac915962-2757-49ea-aeee-10960a408b99
Response samples
application/json
{
  • "id": "BT_9SLA5BdQs6Z3xFpmjUoqhM",
  • "created_at": "2022-08-18T06:37:50.67Z",
  • "updated_at": "2022-08-18T06:37:51.09Z",
  • "amount": 101,
  • "currency": "USD",
  • "description": "setup balance transfer for testing",
  • "destination": "OPERATING_ACCOUNT",
  • "external_reference_id": "84077657260162531",
  • "processor_type": "LITLE_V1",
  • "reference_id": "FNX5ZJEGdPT5odwtRrvxVrYUn",
  • "source": "FOR_BENEFIT_OF_ACCOUNT",
  • "state": "SUCCEEDED",
  • "tags": {
    • "test_key_101": "test_val_101"
    },
  • "_links": {}
}