# Create a Balance Adjustment Create a to increase (i.e., 'Top-up') or decrease your account balance for Payouts. Endpoint: POST /balance_adjustments Version: 2022-02-01 Security: BasicAuth ## Header parameters: - `Finix-Version` (string) Specify the API version of your request. For more details, see Versioning. Example: "2022-02-01" ## Request fields (application/json): - `amount` (integer, required) The total amount that will be debited in cents (e.g. 100 cents to debit $1.00). - `currency` (string, required) ISO 4217 3 letter currency code. Enum: "USD" - `description` (string, required) A description of the . - `instrument_id` (string, required) The account, card, or bank account that is credited or debited as part of the adjustment. - `processor` (string, required) The payment processing entity responsible for handling transactions, fund movements, etc., between different financial accounts. Enum: "DUMMY_V1" - `rail` (string, required) The method of adjustment. Enum: "ACH" - `type` (string) Specifies whether the increases or decreases the account balance. - - Adds funds to the balance (e.g., a deposit or manual funding). Enum: "TOP_UP" - `tags` (object,null) Include up to 50 pairs to annotate requests with custom metadata. - Maximum character length for individual is 40. - Maximum character length for individual is 500. (For example, , , ) ## Response 201 fields (application/json): - `id` (string) The ID of the resource. - `created_at` (string) Timestamp of when the object was created. - `updated_at` (string) Timestamp of when the object was last updated. - `amount` (integer) The total amount that will be debited in cents (e.g. 100 cents to debit $1.00). - `balance_entry_id` (string) A ledger record that tracks individual financial movements within a . - `currency` (string) ISO 4217 3 letter currency code. Enum: "USD" - `description` (string) A description of the . - `failure_code` (string,null) The code of the failure so the decline can be handled programmatically. For more info on how to handle the failure, see [Failure Codes](/guides/payouts/handling-payout-failures). - `failure_message` (string,null) The code of the failure so the decline can be handled programmatically. For more info on how to handle the failure, see [Failure Codes](/guides/payouts/handling-payout-failures). - `instrument_id` (string) The account, card, or bank account that is credited or debited as part of the adjustment. - `processor` (string) The payment processing entity responsible for handling transactions, fund movements, etc., between different financial accounts. Enum: "DUMMY_V1", "FINIX_V1" - `rail` (string) The method of adjustment. Enum: "ACH" - `state` (string) The status of the balance adjustment, indicating whether the adjustment was successful or failed. - - The balance adjustment has been initiated but is not yet confirmed. - - The adjustment was successful, and the funds are available. This typically occurs 1-3 business days after . - - Finix was unable to process the adjustment, and the balance was not updated. - - The adjustment was initially successful, but a subsequent return resulted in a reversal of the balance increase. Enum: "FAILED", "RETURNED", "SUBMITTED", "SUCCEEDED" - `trace_id` (string) A unique identifier for tracking the across its lifecycle. - `type` (string) Specifies whether the increases or decreases the account balance. - - Adds funds to the balance (e.g., a deposit or manual funding). Enum: "TOP_UP" - `tags` (object,null) Include up to 50 pairs to annotate requests with custom metadata. - Maximum character length for individual is 40. - Maximum character length for individual is 500. (For example, , , ) - `_links` (object) An object containing link(s) relevant to the request. You can store these links for follow-up requests. - `_links.self` (object) - `_links.self.href` (string) The path to the new resource. ## Response 401 fields (application/json): - `total` (integer) - `_embedded` (object) - `_embedded.errors` (array) - `_embedded.errors.code` (string) Enum: "UNKNOWN" - `_embedded.errors.logref` (object) - `_embedded.errors.message` (string) - `_embedded.errors._links` (object) - `_embedded.errors._links.self` (object) - `_embedded.errors._links.self.href` (string) - `_embedded.errors._links.source` (object) ## Response 403 fields (application/json): - `total` (integer) - `_embedded` (object) - `_embedded.errors` (array) - `_embedded.errors.code` (string) Enum: "FORBIDDEN" - `_embedded.errors.logref` (object) - `_embedded.errors.message` (string) - `_embedded.errors._links` (object) - `_embedded.errors._links.source` (object) - `_embedded.errors._links.source.href` (string) ## Response 404 fields (application/json): - `total` (integer) - `_embedded` (object) - `_embedded.errors` (array) - `_embedded.errors.code` (string) Enum: "NOT_FOUND" - `_embedded.errors.logref` (object) - `_embedded.errors.message` (string) - `_embedded.errors._links` (object) - `_embedded.errors._links.source` (object) - `_embedded.errors._links.source.href` (string) ## Response 422 fields (application/json): - `total` (integer) - `_embedded` (object) - `_embedded.errors` (array) - `_embedded.errors.code` (string) Enum: "INVALID_FIELD" - `_embedded.errors.field` (string) - `_embedded.errors.logref` (object) - `_embedded.errors.message` (string) - `_embedded.errors._links` (object) - `_embedded.errors._links.source` (object) - `_embedded.errors._links.source.href` (string)