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
Request Body schema: application/hal+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" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYR" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SOS" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"
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 avalible 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

Key value pair for annotating custom meta data (e.g. order numbers).

Responses
201

Single balance_transfer object

Response Schema: application/hal+json
object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

amount
integer <int64>

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

created_at
string <date-time>

Timestamp of when the object was created.

currency
string

ISO 4217 3 letter currency code.

Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYR" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SOS" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"
description
string

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

destination
string

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.

external_reference_id
string

ID generated by partner and returned to Finix.

id
string

ID of the balance_transfer resource.

processor_type
string

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

reference_id
string

ID generated by Finix and sent to the partner.

source
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.

state
string

The state of the balance_transfer.

Enum: "CREATED" "SUBMITTING" "SUBMITTED" "SUCCEEDED" "FAILED" "RETURNED" "UNKNOWM"
object

Key value pair for annotating custom meta data (e.g. order numbers).

updated_at
string <date-time>

Timestamp of when the object was last updated.

400

Error

401

Authentication information is missing or invalid

403

Forbidden

406

Not Acceptable

post/balance_transfers
Request samples
Response samples
application/hal+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"
    },
}

List Balance Transfers

Retrieve a list of balance_transfers.

Request
query Parameters
amount
integer

Filter by an amount equal to the given value.

created_at.gte
string

Filter where created_at is after the given date.

Example: created_at.gte=2022-09-27T11:21:23
created_at.lte
string

Filter where created_at is before the given date.

Example: created_at.lte=2022-09-27T11:21:23
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.

idempotency_id
string

Filter by idempotency_id.

limit
integer

The numbers of items to return.

Example: limit=10
offset
integer

The number of items to skip before starting to collect the result set.

Example: offset=20
pageNumber
integer

The page number to list.

pageSize
integer

The size of the page.

reference_id
string

Filter by the value saved in reference_id.

source
string

Filter by the Payment Instrument saved in source.

updated_at.gte
string

Filter where updated_at is after the given date.

updated_at.lte
string

Filter where updated_at is before the given date.

Responses
200

List of balance_transfer objects

Response Schema: application/hal+json
object

List of balance_transfer objects.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

object

Details the page that's returned.

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 "Content-Type: application/vnd.json+api" \
  -u USbkjk46XqUTQHN3i2jaVnc1:ac915962-2757-49ea-aeee-10960a408b99
Response samples
application/hal+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.

Responses
200

Single balance_transfer object

Response Schema: application/hal+json
object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

amount
integer <int64>

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

created_at
string <date-time>

Timestamp of when the object was created.

currency
string

ISO 4217 3 letter currency code.

Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYR" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SOS" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"
description
string

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

destination
string

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.

external_reference_id
string

ID generated by partner and returned to Finix.

id
string

ID of the balance_transfer resource.

processor_type
string

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

reference_id
string

ID generated by Finix and sent to the partner.

source
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.

state
string

The state of the balance_transfer.

Enum: "CREATED" "SUBMITTING" "SUBMITTED" "SUCCEEDED" "FAILED" "RETURNED" "UNKNOWM"
object

Key value pair for annotating custom meta data (e.g. order numbers).

updated_at
string <date-time>

Timestamp of when the object was last updated.

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 "Content-Type: application/vnd.json+api" \
  -u USbkjk46XqUTQHN3i2jaVnc1:ac915962-2757-49ea-aeee-10960a408b99
Response samples
application/hal+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"
    },
}