Create a Custom Fee

Finix API Reference Copy - Copy for LLM Copy page as Markdown for LLMs - View as Markdown\ \ Open this page as Markdown - Open in ChatGPT\ \ Get insights from ChatGPT - Open in Claude\ \ Get insights from Claude - Connect to Cursor Install MCP server on Cursor - Connect to VS Code Install MCP server on VS Code

The Finix API is resource oriented, relying heavily on common REST principles. Our API uses JSON encoded requests and responses.

You will receive separate Sandbox and Live accounts, as well as corresponding API credentials to access the Finix API.

link to section/Authentication Authentication

To communicate with the Finix API, you must authenticate your requests via HTTP Basic Authentication with a username:password combination, which you can get from your Finix Dashboard. If you do not have a Dashboard yet, you can test our APIs with the Sandbox credentials below.

Parameter Value
Sandbox Username USsRhsHYZGBPnQw8CByJyEQW
Sandbox Password 8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Request Format

curl "https://finix.sandbox-payments-api.com/" \
    -H "Content-Type: application/json" \
    -H "Finix-Version: 2022-02-01" \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

link to section/Environments Environments

Finix provides two environments with distinct base URLs to make API requests.

  1. A Sandbox environment for developing and testing your integration.
  2. A Live environment for processing payments.

These environments are entirely separate and do not share API Credentials.

Environment Endpoint URL
Sandbox https://finix.sandbox-payments-api.com
Live https://finix.live-payments-api.com

Live Access

To get access to the Live environment, please reach out to your Finix point-of-contact.

link to section/HTTP-Codes-and-Errors HTTP Codes and Errors

Finix uses HTTP codes to communicate whether requests succeeded or failed. Requests to Finix's API return responses within less than one second.

However, communications between card networks and processors can increase response latency. Additionally, response latency for card-present devices can be higher depending on how quickly buyers complete the transaction on payment terminals.

Due of this, requests to the Finix API have a maximum timeout of 5 minutes.

For more details, see Error Codes. Also, you can test for specific errors and responses.

Code Definition Explanation
400 Bad Request We could not parse your request. Verify you are providing valid JSON.
401 Unauthorized We could not authenticate your request. Verify your username and password are correct.
402 Upstream Processor Error Errors caused by 3rd-party service(s).
403 Forbidden Your credentials do not have the correct permissions to perform the request.
404 Not Found We could not find the specified resource.
405 Method Not Allowed The specified resource does not support the HTTP Method used to submit the request.
406 Not Acceptable The server could accept the submitted request. Confirm how the request was formatted and submitted.
409 Conflict The submitted request conflicts with the current state of the server.
422 Unprocessable Entity The parameters were valid, but the request failed. Usually, the error involves misunderstanding of how to perform the request (e.g., creating a transfer with a seller that is not-yet-approved).
500 Internal Server Error We had a problem with our server. Try again later.

link to section/Idempotent-Requests Idempotent Requests

The Authorization and Transfer resources both have an idempotency_id field. Use this field to ensure the API Request is performed only once.

Why is this important? We've all experienced a checkout page that hangs on a request or payment, and feared that if we refresh or submit the payment again, we'd be charged twice.

Finix removes this ambiguity with the idempotency_id. You or the user can generate a unique ID that can be included as an idempotency_id with the usual request payload. If anyone attempts a request with the same idempotency_id, the response will raise an exception.

By passing an idempotency_id in the body of your requests, you can be rest assured that when you create an Authorization or Transfer, the user will be protected from potential network issues.

idempotency_id is available on the following three endpoints:

`idempotency_id` scope

idempotency_id checks against previous requests made on the same endpoint.

link to section/Query-Parameters Query Parameters

Every Finix resource (e.g., Authorizations, Transfers) can be listed and reviewed using GET requests. Additionally, every endpoint has query parameters available to help you filter the resources that are returned.

See the following example of how to query the Transfers endpoint for Transfer resources with type: DEBIT.

Query Parameter Example

curl "https://finix.sandbox-payments-api.com/transfers?type=DEBIT" \
    -H "Finix-Version: 2022-02-01" \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

link to section/Tags Tags

Many Finix resources (e.g., Authorization, Transfer) let you include tags to add key-value metadata to your Finix API resources. For example, when creating a Transfer, you might include customerId: Customer123 to tag the Transfer with your internal customer ID. You can update tags as many times as needed, as well as filter resources by tags.

Tags Example

{
    ...,
    "tags": {
        "card-type": "business card",
        "order_number": "H-1257",
        "customer_order_reference": "order1234",
        "item_type": "hardware",
        "vendor": "finix"
    }
}

The tags object accepts up to 50 key: value pairs to annotate resources with custom metadata.

Special Characters

Finix does not allow special characters on tags (e.g., \, ,, ", ')

link to section/Versioning Versioning

As Finix improves our products and features, we will make changes to our APIs. When breaking changes are made to Finix's API, we may release a new dated API version.

The API version your requests use controls how API responses and webhooks behave (for example, the values you see in responses and the parameters you can include in requests). For more information, see Versioning.

link to section/Postman-Collection Postman Collection

Finix has a Postman collection to help in your development. You can fork it using the button below.

Overview

URL https://finix.com

Finix support@finix.com

Languages

cURL

Servers

Sandbox server

https://finix.sandbox-payments-api.com

link to Authorizations Authorizations

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

An Authorization (also known as a card hold) reserves a specific amount on a card to be captured (i.e. debited) at a later date, usually within seven days. When an Authorization is captured it produces a Transfer resource.

Related Guides:

Operations

post

/authorizations

get

/authorizations

get

/authorizations/{authorization_id}

put

/authorizations/{authorization_id}

put

/authorizations/{authorization_id_void_to}

+ Show

link to Compliance Forms Compliance Forms

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

To process payments, your Merchants must validate their compliance with PCI DSS requirements annually. To do this, your Merchants must attest to PCI Self-Assessment Questionnaire (SAQ) compliance forms.

Related Guides:

Operations

get

/compliance_forms/{compliance_form_id}

put

/compliance_forms/{compliance_form_id}

get

/compliance_forms

+ Show

link to Devices Devices

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

A Device resource represents a Point-of-Sale terminal. Devices are used for In-Person transactions.

Related Guides:

Operations

get

/devices

get

/devices/{device_id}

put

/devices/{device_id}

get

/devices/{device_id_connection}

get

/devices/{device_id}/device_metrics

post

/merchants/{merchant_id}/devices

+ Show

link to Disputes Disputes

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

Disputes, also known as chargebacks, are customer-disputed charges. A core part of the dispute lifecycle is the ability for a Merchant to upload evidence supporting their side.

Related Guides:

Operations

get

/disputes

get

/disputes/{dispute_id}

put

/disputes/{dispute_id}

post

/disputes/{dispute_id}/evidence

get

/disputes/{dispute_id}/evidence

get

/disputes/{dispute_id}/evidence/{evidence_id}

put

/disputes/{dispute_id}/evidence/{evidence_id}

delete

/disputes/{dispute_id}/evidence/{evidence_id}

Show4more...

+ Show

link to Fees Fees

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

A Fee is a charge levied against a Merchant. It represents how a platform charges its sellers for all various types of Fees.

Operations

get

/fees

post

/fees

get

/fees/{fee_id}

put

/fees/{fee_id}

link to List Fees List Fees

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

link to /fees/listfees#fees/listfees/request Request

Retrieve a list of Fee resources.

Filter fees by linked entity: You can filter fees by the entity that generated them using the linked_to query parameter:

Merchant-specific fees include monthly dues and assessments and any custom fees.

To show fees charged to a specific entity during a period, pass the created_at.gte and created_at.lte query parameters.

SecurityView security details

BasicAuth

link to /fees/listfees#fees/listfees/request/query Query

link to /fees/listfees#fees/listfees/t=request&in=query&path=after_cursor after_cursor string

Return every resource created after the cursor value.

link to /fees/listfees#fees/listfees/t=request&in=query&path=before_cursor before_cursor string

Return every resource created before the cursor value.

link to /fees/listfees#fees/listfees/t=request&in=query&path=created_at.gte created_at.gte string (date-time)

Filter where created_at is after the given date.

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

link to /fees/listfees#fees/listfees/t=request&in=query&path=created_at.lte created_at.lte string (date-time)

Filter where created_at is before the given date.

Example:created_at.lte=2026-09-27T11:21:23

link to /fees/listfees#fees/listfees/t=request&in=query&path=limit limit integer <= 100

The numbers of items to return.

Example:limit=10

link to /fees/listfees#fees/listfees/t=request&in=query&path=linked_to linked_to string

The ID of the resource that generated the Fee.

Example:linked_to=TRrB2VG7H84LmRgSTkfR2Cb6

link to /fees/listfees#fees/listfees/t=request&in=query&path=merchant_id merchant_id string

The ID of the Merchant that was charged fees.

Example:merchant_id=MUeDVrf2ahuKc9Eg5TeZugvs

link to /fees/listfees#fees/listfees/t=request&in=query&path=tags.key tags.key string

Filter by the tag's key. For more information, see Tags.

Example:tags.key=card_type

link to /fees/listfees#fees/listfees/t=request&in=query&path=tags.value tags.value string

Filter by the tag's value. For more information, see Tags.

Example:tags.value=business_card

link to /fees/listfees#fees/listfees/t=request&in=query&path=updated_at.gte updated_at.gte string (date-time)

Filter where updated_at is after the given date.

Example:updated_at.gte=2022-09-27T11:21:23

link to /fees/listfees#fees/listfees/t=request&in=query&path=updated_at.lte updated_at.lte string (date-time)

Filter where updated_at is before the given date.

Example:updated_at.lte=2026-09-27T11:21:23

link to /fees/listfees#fees/listfees/request/header Headers

link to /fees/listfees#fees/listfees/t=request&in=header&path=finix-version Finix-Version string

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

Default2022-02-01

Example:2022-02-01

get

/fees

curl

curl "https://finix.sandbox-payments-api.com/fees" \
-H "Finix-Version: 2022-02-01" \
-u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda

link to /fees/listfees#fees/listfees/response&c=200 Responses

  1. 200
  2. 401
  3. 403
  4. 406
  5. 422

Expand all

List of Fee resources

link to /fees/listfees#fees/listfees/response&c=200/headers Headers

link to /fees/listfees#fees/listfees/t=response&c=200&path=date date string

A response header indicating the date and time of the API request.

Example:"Tue, 08 Jul 2025 17:38:01 GMT"

link to /fees/listfees#fees/listfees/t=response&c=200&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example:"ROLE_PARTNER"

link to /fees/listfees#fees/listfees/t=response&c=200&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example:"055972f6534f92a896fbb61b11313ebb"

link to /fees/listfees#fees/listfees/response&c=200/body Bodyapplication/json

link to /fees/listfees#fees/listfees/t=response&c=200&path=page page object

Details the page that's returned.

+Show 2 properties

link to /fees/listfees#fees/listfees/t=response&c=200&path=_embedded_embedded object

+Show property

link to /fees/listfees#fees/listfees/t=response&c=200&path=_links_links object

+Show 2 properties

Response

  1. 200
  2. 401
  3. 403
  4. 406
  5. 422

application/json

{
  "_embedded": {
    "fees": [ … ]
  },
  "_links": {
    "self": { … }
  },
  "page": {
    "offset": 0,
    "limit": 20,
    "count": 7
  }
}

Was this helpful?

link to Create a Custom Fee Create a Custom Fee

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

link to /fees/createfee#fees/createfee/request RequestExpand all

Create a custom (i.e. one-time) Fee.

SecurityView security details

BasicAuth

link to /fees/createfee#fees/createfee/request/header Headers

link to /fees/createfee#fees/createfee/t=request&in=header&path=finix-version Finix-Version string

Default2022-02-01

Example:2022-02-01

link to /fees/createfee#fees/createfee/t=request&in=header&path=content-type Content-Type string

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

Example:application/json

link to /fees/createfee#fees/createfee/request/body Bodyapplication/jsonrequired

link to /fees/createfee#fees/createfee/t=request&path=amount amount integer (int64) required

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

Example:5000

link to /fees/createfee#fees/createfee/t=request&path=currency currency string required

ISO 4217 3-letter currency code.

Enum"CAD""USD"

link to /fees/createfee#fees/createfee/t=request&path=display_name display_name string

The display name of the Fee that can be used for filtering purposes.

link to /fees/createfee#fees/createfee/t=request&path=fee_subtype fee_subtype string required

Subtype of the fee. Set to CUSTOM.

Value"CUSTOM"

link to /fees/createfee#fees/createfee/t=request&path=fee_type fee_type string required

The type of the fee. Must be set to CUSTOM.

Value"CUSTOM"

link to /fees/createfee#fees/createfee/t=request&path=merchant merchant string required

The ID of the Merchant resource used to create the Fee.

link to /fees/createfee#fees/createfee/t=request&path=tags tags object or null

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

+Show property

post

/fees

cURL

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/fees \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "amount": 100,
    "currency": "USD",
    "display_name": "April_Monthly_Fee",
    "fee_subtype": "CUSTOM",
    "fee_type": "CUSTOM",
    "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm",
    "tags": {
      "test": "tag"
    }
  }'

link to /fees/createfee#fees/createfee/response&c=201 Responses

  1. 201
  2. 400
  3. 401
  4. 403
  5. 406

Expand all

Single Custom Fee object

link to /fees/createfee#fees/createfee/response&c=201/headers Headers

link to /fees/createfee#fees/createfee/t=response&c=201&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example:"ROLE_PARTNER"

link to /fees/createfee#fees/createfee/t=response&c=201&path=date date string

A response header indicating the date and time of the API request.

Example:"Tue, 08 Jul 2025 17:38:01 GMT"

link to /fees/createfee#fees/createfee/t=response&c=201&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example:"055972f6534f92a896fbb61b11313ebb"

link to /fees/createfee#fees/createfee/response&c=201/body Bodyapplication/json

link to /fees/createfee#fees/createfee/t=response&c=201&path=id id string non-empty

The ID of the resource.

link to /fees/createfee#fees/createfee/t=response&c=201&path=created_at created_at string (date-time)

Timestamp of when the object was created.

link to /fees/createfee#fees/createfee/t=response&c=201&path=updated_at updated_at string (date-time)

Timestamp of when the object was last updated.

link to /fees/createfee#fees/createfee/t=response&c=201&path=amount amount number (double)

Represents the total amount. The value may be returned as either:

Example:2.393

link to /fees/createfee#fees/createfee/t=response&c=201&path=application application string non-empty

ID of the Application the resource was created under.

link to /fees/createfee#fees/createfee/t=response&c=201&path=category category string or null

The Fee category.

Enum"PROCESSOR""INTERCHANGE""DUES_AND_ASSESSMENTS""THIRD_PARTY_SERVICE_PROVIDER"

link to /fees/createfee#fees/createfee/t=response&c=201&path=currency currency string

ISO 4217 3-letter currency code.

Enum"CAD""USD"

link to /fees/createfee#fees/createfee/t=response&c=201&path=display_name display_name string or null

It is used for subscription fees and allows free-form text to be passed from the subscription fee product. Note that this product is mostly deprecated.

link to /fees/createfee#fees/createfee/t=response&c=201&path=fee_profile fee_profile string

The ID of the Fee Profile used to calculate fees for the Transfer related to this Fee. The specific Transfer is identified by the linked_to field.

link to /fees/createfee#fees/createfee/t=response&c=201&path=fee_subtype fee_subtype string

The subtype of the Fee.

Enum"CUSTOM""APPLICATION_FEE""PLATFORM_FEE"

link to /fees/createfee#fees/createfee/t=response&c=201&path=fee_type fee_type string

The type of Fee. Finix may return more enums than those provided. Ensure your code accepts additional enums returned by Finix.

Enum"ACH_BASIS_POINTS""ACH_CREDIT_RETURN_FIXED_FEE""ACH_DEBIT_RETURN_FIXED_FEE""ACH_FIXED""ACH_MAX_FIXED""ACH_NOTICE_OF_CHANGE_CREDIT_FIXED""ACH_NOTICE_OF_CHANGE_DEBIT_FIXED""AMERICAN_EXPRESS_ASSESSMENT_BASIS_POINTS""AMERICAN_EXPRESS_BASIS_POINTS""AMERICAN_EXPRESS_FIXED"+83 more

link to /fees/createfee#fees/createfee/t=response&c=201&path=label label string or null

It is used for subscription fees and allows free-form text to be passed from the subscription fee product. Note that this product is mostly deprecated.

link to /fees/createfee#fees/createfee/t=response&c=201&path=linked_id linked_id string

The ID of the linked resource. Note that this field will be deprecated soon, use linked_to instead.

link to /fees/createfee#fees/createfee/t=response&c=201&path=linked_to linked_to string

The ID of the linked resource.

link to /fees/createfee#fees/createfee/t=response&c=201&path=linked_type linked_type string

The type of entity the Fee is linked to.

Enum"TRANSFER""AUTHORIZATION"

link to /fees/createfee#fees/createfee/t=response&c=201&path=merchant merchant string

The ID of the Merchant resource that was charged the fee.

link to /fees/createfee#fees/createfee/t=response&c=201&path=ready_to_settle_at ready_to_settle_at string or null (date-time)

The timestamp indicating when the Transfer related to this Fee is ready to be settled. The specific Transfer is identified by the linked_to field.

link to /fees/createfee#fees/createfee/t=response&c=201&path=tags tags object or null

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

+Show property

link to /fees/createfee#fees/createfee/t=response&c=201&path=_links_links 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.

+Show 3 properties

Response

  1. 201
  2. 400
  3. 401
  4. 403
  5. 406

application/json

{
  "id": "FEnaYWyrTzF2BqxKtvPHwkPM",
  "created_at": "2026-01-08T16:04:10.85Z",
  "updated_at": "2026-01-08T16:04:10.85Z",
  "amount": 100,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "category": "PROCESSOR",
  "currency": "USD",
  "display_name": "April_Monthly_Fee",
  "fee_profile": null,
  "fee_subtype": "CUSTOM",
  "fee_type": "CUSTOM",
  "label": "April_Monthly_Fee",
  "linked_id": null,
  "linked_to": null,
  "linked_type": null,
  "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm",
  "ready_to_settle_at": "2026-01-08T16:04:10.85Z",
  "tags": {
    "test": "tag"
  },
  "_links": {
    "self": { … },
    "merchant": { … }
  }
}

Was this helpful?

link to Fetch a Fee Fetch a Fee

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

link to /fees/getfee#fees/getfee/request Request

Retrieve the details of an existing Fee.

SecurityView security details

BasicAuth

link to /fees/getfee#fees/getfee/request/path Path

link to /fees/getfee#fees/getfee/t=request&in=path&path=fee_id fee_id string required

The Fee ID.

Example:FEvjF5iPwy6zuUEsBWgJ9T79

link to /fees/getfee#fees/getfee/request/header Headers

link to /fees/getfee#fees/getfee/t=request&in=header&path=finix-version Finix-Version string

Default2022-02-01

Example:2022-02-01

get

/fees/{fee_id}

cURL

curl -i -X GET \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/fees/FEvjF5iPwy6zuUEsBWgJ9T79 \
  -H 'Finix-Version: 2022-02-01'

link to /fees/getfee#fees/getfee/response&c=200 Responses

  1. 200
  2. 401
  3. 403
  4. 404
  5. 406

Expand all

A single Fee

link to /fees/getfee#fees/getfee/response&c=200/headers Headers

link to /fees/getfee#fees/getfee/t=response&c=200&path=date date string

A response header indicating the date and time of the API request.

Example:"Tue, 08 Jul 2025 17:38:01 GMT"

link to /fees/getfee#fees/getfee/t=response&c=200&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example:"ROLE_PARTNER"

link to /fees/getfee#fees/getfee/t=response&c=200&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example:"055972f6534f92a896fbb61b11313ebb"

link to /fees/getfee#fees/getfee/response&c=200/body Bodyapplication/json

link to /fees/getfee#fees/getfee/t=response&c=200&path=id id string non-empty

The ID of the resource.

link to /fees/getfee#fees/getfee/t=response&c=200&path=created_at created_at string (date-time)

Timestamp of when the object was created.

link to /fees/getfee#fees/getfee/t=response&c=200&path=updated_at updated_at string (date-time)

Timestamp of when the object was last updated.

link to /fees/getfee#fees/getfee/t=response&c=200&path=amount amount number (double)

Represents the total amount. The value may be returned as either:

Example:2.393

link to /fees/getfee#fees/getfee/t=response&c=200&path=application application string non-empty

ID of the Application the resource was created under.

link to /fees/getfee#fees/getfee/t=response&c=200&path=category category string or null

The Fee category.

Enum"PROCESSOR""INTERCHANGE""DUES_AND_ASSESSMENTS""THIRD_PARTY_SERVICE_PROVIDER"

link to /fees/getfee#fees/getfee/t=response&c=200&path=currency currency string

ISO 4217 3-letter currency code.

Enum"CAD""USD"

link to /fees/getfee#fees/getfee/t=response&c=200&path=display_name display_name string or null

It is used for subscription fees and allows free-form text to be passed from the subscription fee product. Note that this product is mostly deprecated.

link to /fees/getfee#fees/getfee/t=response&c=200&path=fee_profile fee_profile string

The ID of the Fee Profile used to calculate fees for the Transfer related to this Fee. The specific Transfer is identified by the linked_to field.

link to /fees/getfee#fees/getfee/t=response&c=200&path=fee_subtype fee_subtype string

The subtype of the Fee.

Enum"CUSTOM""APPLICATION_FEE""PLATFORM_FEE"

link to /fees/getfee#fees/getfee/t=response&c=200&path=fee_type fee_type string

The type of Fee. Finix may return more enums than those provided. Ensure your code accepts additional enums returned by Finix.

link to /fees/getfee#fees/getfee/t=response&c=200&path=label label string or null

It is used for subscription fees and allows free-form text to be passed from the subscription fee product. Note that this product is mostly deprecated.

link to /fees/getfee#fees/getfee/t=response&c=200&path=linked_id linked_id string

The ID of the linked resource. Note that this field will be deprecated soon, use linked_to instead.

link to /fees/getfee#fees/getfee/t=response&c=200&path=linked_to linked_to string

The ID of the linked resource.

link to /fees/getfee#fees/getfee/t=response&c=200&path=linked_type linked_type string

The type of entity the Fee is linked to.

Enum"TRANSFER""AUTHORIZATION"

link to /fees/getfee#fees/getfee/t=response&c=200&path=merchant merchant string

The ID of the Merchant resource that was charged the fee.

link to /fees/getfee#fees/getfee/t=response&c=200&path=ready_to_settle_at ready_to_settle_at string or null (date-time)

The timestamp indicating when the Transfer related to this Fee is ready to be settled. The specific Transfer is identified by the linked_to field.

link to /fees/getfee#fees/getfee/t=response&c=200&path=tags tags object or null

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

+Show property

link to /fees/getfee#fees/getfee/t=response&c=200&path=_links_links object

+Show 3 properties

Response

  1. 200
  2. 401
  3. 403
  4. 404
  5. 406

application/json

{
  "id": "FEdTSCeaF6J68t6bn9z6HTz5",
  "created_at": "2026-03-19T19:54:15.18Z",
  "updated_at": "2026-03-19T19:54:15.18Z",
  "amount": 1,
  "application": "APwCngcNcRj4ARsJihvVxJ1u",
  "category": "PROCESSOR",
  "currency": "USD",
  "display_name": null,
  "fee_profile": "FP5aG7yrDutyZNh5J8mMJuza",
  "fee_subtype": "PLATFORM_FEE",
  "fee_type": "CARD_BASIS_POINTS",
  "label": null,
  "linked_id": "TRdRpaYRXGaHJuKGzFq7HhQ6",
  "linked_to": "TRdRpaYRXGaHJuKGzFq7HhQ6",
  "linked_type": "TRANSFER",
  "merchant": "MU8camsxYfmBbNtPSyDzVMoA",
  "ready_to_settle_at": "2026-03-20T19:54:14.65Z",
  "tags": {},
  "_links": {
    "self": { … },
    "merchant": { … },
    "transfer": { … }
  }
}

Was this helpful?

link to Update Fee Update Fee

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

link to /fees/updatefee#fees/updatefee/request RequestExpand all

Update the details of a Fee.

SecurityView security details

BasicAuth

link to /fees/updatefee#fees/updatefee/request/path Path

link to /fees/updatefee#fees/updatefee/t=request&in=path&path=fee_id fee_id string required

The Fee ID.

Example: FEvjF5iPwy6zuUEsBWgJ9T79

link to /fees/updatefee#fees/updatefee/request/body Bodyapplication/jsonrequired

link to /fees/updatefee#fees/updatefee/t=request&path=tags tags object or null

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

+Show property

put

/fees/{fee_id}

cURL

curl -i -X PUT \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/fees/FEvjF5iPwy6zuUEsBWgJ9T79 \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "test": "test"
    }
  }'

link to /fees/updatefee#fees/updatefee/response&c=200 Responses

  1. 200
  2. 400
  3. 401
  4. 403
  5. 404
  6. 406

Expand all

A single Fee

link to /fees/updatefee#fees/updatefee/response&c=200/headers Headers

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=date date string

A response header indicating the date and time of the API request.

Example: "Tue, 08 Jul 2025 17:38:01 GMT"

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example: "ROLE_PARTNER"

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example: "055972f6534f92a896fbb61b11313ebb"

link to /fees/updatefee#fees/updatefee/response&c=200/body Bodyapplication/json

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=id id string non-empty

The ID of the resource.

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=created_at created_at string (date-time)

Timestamp of when the object was created.

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=updated_at updated_at string (date-time)

Timestamp of when the object was last updated.

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=amount amount number (double)

Represents the total amount. The value may be returned as either:

Example: 2.393

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=application application string non-empty

ID of the Application the resource was created under.

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=category category string or null

The Fee category.

Enum"PROCESSOR""INTERCHANGE""DUES_AND_ASSESSMENTS""THIRD_PARTY_SERVICE_PROVIDER"

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=currency currency string

ISO 4217 3-letter currency code.

Enum"CAD""USD"

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=display_name display_name string or null

It is used for subscription fees and allows free-form text to be passed from the subscription fee product. Note that this product is mostly deprecated.

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=fee_profile fee_profile string

The ID of the Fee Profile used to calculate fees for the Transfer related to this Fee. The specific Transfer is identified by the linked_to field.

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=fee_subtype fee_subtype string

The subtype of the Fee.

Enum"CUSTOM""APPLICATION_FEE""PLATFORM_FEE"

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=fee_type fee_type string

The type of Fee. Finix may return more enums than those provided. Ensure your code accepts additional enums returned by Finix.

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=label label string or null

It is used for subscription fees and allows free-form text to be passed from the subscription fee product. Note that this product is mostly deprecated.

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=linked_id linked_id string

The ID of the linked resource. Note that this field will be deprecated soon, use linked_to instead.

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=linked_to linked_to string

The ID of the linked resource.

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=linked_type linked_type string

The type of entity the Fee is linked to.

Enum"TRANSFER""AUTHORIZATION"

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=merchant merchant string

The ID of the Merchant resource that was charged the fee.

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=ready_to_settle_at ready_to_settle_at string or null (date-time)

The timestamp indicating when the Transfer related to this Fee is ready to be settled. The specific Transfer is identified by the linked_to field.

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=tags tags object or null

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

+Show property

link to /fees/updatefee#fees/updatefee/t=response&c=200&path=_links_links object

+Show 3 properties

Response

  1. 200
  2. 400
  3. 401
  4. 403
  5. 404
  6. 406

application/json

Was this helpful?

link to Fee Profiles Fee Profiles

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

A fee_profiles represents a pricing scheme that automatically applies fees to each transaction. Changes to fee_profiles go into effect immediately.

Related Guides:

Operations

post

/fee_profiles

get

/fee_profiles

get

/fee_profiles/{fee_profile_id}

+ Show

link to Files Files

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

Use Finix's File API to upload and manage files for your merchants.

Related Guides:

Operations

post

/files

get

/files

get

/files/{file_id}

get

/files/{file_id}/external_links

post

/files/{file_id}/external_links

post

/files/{file_id}/upload

get

/files/{file_id}/download

get

/files/{file_id}/external_links/{external_link_id}

+ Show

link to Identities Identities

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

An Identity resource represents either a person or business in Finix. You'll create an Identity to onboard your sellers, and verify the different owners.

Related Guides:

Operations

post

/identities

get

/identities

get

/identities/{identity_id}

put

/identities/{identity_id}

post

/identities/{identity_id}/associated_identities

get

/identities/{identity_id}/associated_identities

get

/identities/{identity_id}/merchants

+ Show

link to Merchants Merchants

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

A Merchant resource represents the entity's merchant account on a processor. Your Merchant must be APPROVED to process payments.

Related Guides:

Operations

post

/identities/{identity_id}/merchants

get

/merchants

get

/merchants/{merchant_id}

put

/merchants/{merchant_id}

post

/merchants/{merchant_id}/verifications

+ Show

link to Onboarding Forms Onboarding Forms

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

Finix offers and hosts pre-built onboarding forms that you can use to collect onboarding and identity verification information from your users.

Related Guides:

Operations

post

/onboarding_forms

get

/onboarding_forms/{onboarding_form_id}

post

/onboarding_forms/{onboarding_form_id}/links

+ Show

link to Payment Instruments Payment Instruments

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

A Payment Instrument resource represents the payment details of a credit card or bank account. Payment details get tokenized multiple times and each tokenization produces a unique Payment Instrument.

A Payment Instrument is associated with a single Identity. Once a Payment Instrument is created, the Identity it's associated with can't be changed.

Including an address when creating a Payment Instrument can lower interchange on credit card transactions.

Related Guides:

Operations

post

/payment_instruments

get

/payment_instruments

get

/payment_instruments/{payment_instrument_id}

put

/payment_instruments/{payment_instrument_id}

get

/payment_instruments/{payment_instrument_id}/instrument_history

put

/payment_instruments/{payment_instrument_id_verify}

post

/payment_instruments/{payment_instrument_id_verify}/verifications

post

/apple_pay_sessions

+ Show

link to Payment Instrument Associations Payment Instrument Associations

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

In Finix, Payment Instruments are tied to the owner of that account. For example, Payment Instruments tied to buyer will be the cards used for purchases while Payment Instruments tied to a Merchant are the bank accounts where they receive settlements.

Therefore when billing events occur that are tied to a buyer's Payment Instrument (e.g. enrolling in account updater, using Plaid for tokenization, etc) Finix cannot automatically map those fees to a specific Merchant. By default, these costs are instead charged to your Application (e.g. the Platform, Marketplace, Vertical Saas owner's account) and will be deducted from your residual. If you wish to monetize these offerings or pass the fees on to your Merchant you must explicitly link the buyers Payment Instrument to a Merchant resource using the Payment Instrument Association

Operations

post

/payment_instrument_associations

get

/payment_instrument_associations

get

/payment_instrument_associations/{payment_instrument_association_id}

put

/payment_instrument_associations/{payment_instrument_association_id}

+ Show

link to Settlements Settlements

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

A Settlement represents a collection (i.e. batch) of Settlement Entries that will get paid out to a specific Merchant. A Settlement Entry can represent a Transfer, custom Fee, or Split Transfer.

Related Guides:

Operations

get

/settlements

get

/settlements/{settlement_id}

put

/settlements/{settlement_id}

get

/settlements/{settlement_id}/entries

delete

/settlements/{settlement_id}/entries

get

/settlements/{settlement_id}/fees

get

/settlements/{settlement_id}/funding_transfers

delete

/settlements/{settlement_id}/transfers

Show3more...

+ Show

link to Settlement Queue Entries Settlement Queue Entries

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

A Settlement Queue Entry resource represents an entry in the settlement queue used to track when and how a transfer is queued to be processed.

If a merchant's settlement_queue_mode is set to MANUAL, all transfers will have a Settlement Queue Entry created and will not be placed into settlement until the Settlement Queue Entry is explicitly released.

Related Guides:

Operations

get

/settlement_queue_entries

put

/settlement_queue_entries

get

/settlement_queue_entries/{settlement_queue_entry_id}

+ Show

link to Split Transfers Split Transfers

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

Transactions can be split among different merchants. A Split Transfer shows how funds from a split Transfer were distributed into a merchant's Settlement.

Related Guides:

Operations

get

/fees

get

/split_transfers

get

/split_transfers/{split_transfer_id}

+ Show

link to Transfers Transfers

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

A Transfer represents any flow of funds either to or from a Payment Instrument. All payments in Finix are represented by a Transfer.

Related Guides:

Operations

post

/transfers

get

/transfers

get

/transfers/{transfer_id}

put

/transfers/{transfer_id}

post

/transfers/{transfer_id}/reversals

get

/transfers/{transfer_id}/reversals

+ Show

link to Users Users

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

A User resource represents a pair of API keys which are used to perform authenticated requests against the Finix API. When making authenticated requests via HTTP basic access authentication the ID of a User resource maps to the username, while the password corresponds to the password (i.e. secret key).

The password field for a User resource is only returned during the initial creation. Any following GET requests to the resource returns the password field as null for security purposes.

Related Guides:

Operations

get

/users

get

/users/{user_id}

put

/users/{user_id}

+ Show

link to Verifications Verifications

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

Verifications are used to verify Merchants and Payment Instruments.

For Merchants, a verification represents an attempt to onboard and underwrite a Merchant.

For Payment Instruments, a verification represents getting additional information from the card brands to verify a card is eligible for push to card.

Related Guides:

Operations

get

/merchants/{merchant_id}/verifications

get

/verifications

get

/verifications/{verification_id}

+ Show

link to Webhooks Webhooks

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

Webhooks let you set up integrations that subscribe to automated notifications (events) on the Finix API. When an enabled event occurs, Finix sends an HTTP POST payload to the Webhook's configured URL.

Related Guides:

Operations

post

/webhooks

get

/webhooks

get

/webhooks/{webhook_id}

put

/webhooks/{webhook_id}

+ Show

link to Gateway Integrations Gateway Integrations

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

A Gateway Integration represents a connection to a third-party payment gateway. At this time, the only supported gateway is Cybersource.

Cybersource is a Visa-owned payment gateway that integrates with Finix to provide secure payment processing and fraud management. Finix handles merchant onboarding and payouts through a unified API, while Cybersource manages gateway routing and fraud prevention for global card acceptance.

Operations

post

/gateway_integrations

get

/gateway_integrations

get

/gateway_integrations/{gateway_integration_id}

+ Show

link to Receipts Receipts

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

The Receipt resource generates a receipt for Transfers or Authorizations. You can then send the Receipt via Email, SMS, or use the information from the Receipt to send it yourself.

Related Guides:

Operations

post

/receipts

get

/receipts/{receipt_id}

post

/receipts/{receipt_id}/delivery_attempts

get

/receipts/{receipt_id}/delivery_attempts

+ Show

link to Subscriptions Subscriptions

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

A Subscription resource represents a recurring charge to a Payment Instrument at regular intervals. Subscribers can be buyers, customers, or merchants.

Subscriptions are supported for USA and Canadian merchants.

When creating a Subscription, you have the option to use a Subscription Plan.

Limitations:

Related Guides:

Operations

post

/subscriptions

get

/subscriptions

get

/subscriptions/{subscription_id}

put

/subscriptions/{subscription_id}

delete

/subscriptions/{subscription_id}

post

/subscriptions/{subscription_id}/subscription_balance_entries

get

/subscriptions/{subscription_id}/subscription_balance_entries

put

/subscriptions/{subscription_id}/subscription_balance_entries/{subscription_balance_entry_id}

+ Show

link to Subscription Plans Subscription Plans

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

A Subscription Plan resource is a template with set recurring costs and frequencies that can be reused across multiple Subscription resources.

Related Guides:

Operations

post

/subscription_plans

get

/subscription_plans

get

/subscription_plans/{subscription_plan_id}

put

/subscription_plans/{subscription_plan_id}

+ Show

link to Transfer Attempts Transfer Attempts

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

When a user attempts to make a payment using a Checkout Form or Payment Link, or a recipient submitting details with a Payout Link—a Transfer Attempt is created.

Using transfer attempts, you can track the lifecycle of a payment or a series of payments if you are using a multi-use Payment Link.

Checkout Forms and Payment Links support authorizations. If a payment made with them is an authorization, the Transfer Attempt result shows is_authorization: true and references the authorization (authorization_id).

Each Transfer Attempt has as reference to a transfer_id to allow you to query it for additional data.

Related Guides:

Operations

get

/transfer_attempts

get

/transfer_attempts/{transfer_attempt_id}

+ Show

link to Balances Balances

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

A Balance resource represents the current financial state of an Application identified by the linked_to query parameter.

It tracks the state of funds processed through the system, including amounts that are:

Operations

get

/balances

get

/balances/{balance_id}

get

/balances/{balance_id}/balance_entries

get

/balance_entries/{balance_entry_id}

+ Show

link to Balance Adjustments Balance Adjustments

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

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

Related Guides:

Operations

post

/balance_adjustments

get

/balance_adjustments

+ Show

link to Disbursement Rules Disbursement Rules

Copy

Copy page as Markdown for LLMs

Install MCP server on Cursor

Install MCP server on VS Code

For the Payouts product, when a payout is executed, such as a Push-To-Card or ACH transaction, Finix checks the transaction against velocity rules and balance rules.

Rules establish limits on transactions. For example, there may be a daily transaction limit of 100 transactions (count_limit) or a monthly volume limit of $100,000 (volume_limit). If a transaction exceeds any defined limit, the transaction is rejected.

Rules are set for entities involved in transactions, including the application, senders, and recipients.

The "Application" represents the customer to whom Finix is applying the rules. Application rules are set solely by Finix and are applied to every single transaction.

You can establish rules for "senders" and "recipients," referring to the parties involved in transactions:

Operations

get

/disbursement_rules

get

/disbursement_rules/current_usages

+ Show