v1

latestOpenAPI 3.0.22026-08-061303782.1 MB

Balance Adjustments

Create a Balance Adjustment

Create a Balance Adjustment to increase (i.e., 'Top-up') or decrease your account balance for Payouts.

post/balance_adjustments

Headers

Finix-Versionstring

Example:2022-02-01

Specify the API version of your request. For more details, see Versioning.

Content-Typestring

Example:application/json

The data type being sent in the request body must be application/json.

Request body

amountinteger required

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

currency'USD' required

ISO 4217 3 letter currency code.

descriptionstring required

A description of the Balance Adjustment.

instrument_idstring required

The account, card, or bank account that is credited or debited as part of the adjustment.

processor'DUMMY_V1' required

The payment processing entity responsible for handling transactions, fund movements, etc., between different financial accounts.

rail'ACH' required

The method of adjustment.

tagsTags nullable

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)

top_up_config_idstring nullable

The ID of the top-up configuration that created the adjustment.

type'TOP_UP'

Specifies whether the Balance Adjustment increases or decreases the account balance.

Acceptable values:

TOP_UP - Adds funds to the balance (e.g., a deposit or manual funding).

Example request

{
  "amount": 5000
}

Response

A single Balance Adjustment

idstring

The ID of the resource.

created_atstring date-time

Timestamp of when the object was created.

updated_atstring date-time

Timestamp of when the object was last updated.

amountinteger

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

balance_entry_idstring

A ledger record that tracks individual financial movements within a Balance Adjustment.

currency'USD'

ISO 4217 3 letter currency code.

descriptionstring

A description of the Balance Adjustment.

failure_codestring nullable

The code of the failure so the decline can be handled programmatically. For more info on how to handle the failure, see Failure Codes.

failure_messagestring nullable

The code of the failure so the decline can be handled programmatically. For more info on how to handle the failure, see Failure Codes.

instrument_idstring

The account, card, or bank account that is credited or debited as part of the adjustment.

processor'DUMMY_V1' | 'FINIX_V1'

The payment processing entity responsible for handling transactions, fund movements, etc., between different financial accounts.

rail'ACH'

The method of adjustment.

state'FAILED' | 'RETURNED' | 'SUBMITTED' | 'SUCCEEDED'

The status of the Balance Adjustment, indicating whether the adjustment was successful or failed.

SUBMITTED - The balance adjustment has been initiated but is not yet confirmed.
SUCCEEDED - The adjustment was successful, and the funds are available. This typically occurs 1-3 business days after SUBMITTED.
FAILED - Finix was unable to process the adjustment, and the balance was not updated.
RETURN - The adjustment was initially successful, but a subsequent return resulted in a reversal of the balance increase.

trace_idstring

A unique identifier for tracking the Balance Adjustment across its lifecycle.

type'TOP_UP'

Specifies whether the Balance Adjustment increases or decreases the account balance.

Acceptable values:

TOP_UP - Adds funds to the balance (e.g., a deposit or manual funding).

tagsTags nullable

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)

Example response

{
  "amount": 5000
}