Balance Adjustments

A Balance Adjustment modifies the account Balance by adding funds (a 'top-up') or reducing funds for Payouts. Each adjustment is linked to a specific payment rail (e.g., ACH, card, wire).

Create a Balance Adjustment

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

Request
header Parameters
Finix-Version
string
Default: 2018-01-01

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

Example: 2022-02-01
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.

Value: "USD"
description
required
string

A description of the Balance Adjustment.

instrument_id
required
string

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

processor
required
string

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

Value: "DUMMY_V1"
rail
required
string

The method of adjustment.

Value: "ACH"
type
string

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

  • TOP_UP - Adds funds to the balance (e.g., a deposit or manual funding).
Value: "TOP_UP"
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

Response examples for a request to create a Balance Adjustment.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

422

Invalid field

post/balance_adjustments
Request samples 
Response samples 
application/json
{
  • "id": "balance_adjustment_jfR7V18CMWaGBmRYAto8Lw",
  • "created_at": "2024-05-22T17:13:15.810963Z",
  • "updated_at": "2024-05-22T17:13:16.05664Z",
  • "amount": 66,
  • "balance_entry_id": "balance_entry_4Zsrw3ccS64vjpzZmNMdUi",
  • "currency": "USD",
  • "failure_code": null,
  • "failure_message": null,
  • "description": "Sample Balance Adjustment",
  • "rail": "ACH",
  • "instrument_id": "PIwyL8J2KRu8qnvGF7EDeviQ",
  • "state": "SUCCEEDED",
  • "type": "TOP_UP",
  • "tags": {
    • "name": "create a balance adjustment"
    },
  • "trace_id": "872d2e13-2e56-47b6-94a3-64ec06a1f982",
  • "_links": {}
}
List Balance Adjustments
Retrieve a list of Balance Adjustment resources for an Application.


Only ROLE_PARTNER or ROLE_PLATFORM credentials can be used to retrieve Balance Adjustment objects.


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
after_cursor
string
Return every resource created after the cursor value.


 
 Example:  after_cursor=TRnasXQ5AmjsLnPMwnme7TL4
before_cursor
string
Return every resource created before the cursor value.


 
 Example:  before_cursor=TRnasXQ5AmjsLnPMwnme7TL4
header Parameters
Finix-Version
string
 Default:  2018-01-01
Specify the API version of your request. For more details, see Versioning.


 
 Example:  2022-02-01
Responses 
200
List of Balance Adjustment objects


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


422
Invalid field


get/balance_adjustments
Request samples 
curl "https://finix.sandbox-payments-api.com/balance_adjustments" \
  -H "Finix-Version: 2022-02-01" \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda
Response samples 
application/json
{
  • "_embedded": {
    • "balance_adjustments": [
      ]
    },
  • "_links": {},
  • "page": {
    • "limit": 100,
    • "next_cursor": "balance_adjustment_nvc873btpDtA7KbPySdCny"
    }
}