Finix API Reference

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.

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.

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

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.

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

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 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:

• /transfers
• /authorizations
• /transfers/{id}/reversals

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.

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

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": {
        "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.

• Maximum character length for individual keys is 40.
• Maximum character length for individual values is 500.

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.

Postman Collection

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

Servers

Sandbox server

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

Security

BasicAuth

Type: http Scheme: basic

Download OpenAPI description

Finix API Reference

Authorizations

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.

Create an Authorization

• POST /authorizations: Create an Authorization to process a transaction.

List Authorizations

• GET /authorizations: Retrieve a list of Authorizations.

Fetch an Authorization

• GET /authorizations/{authorization_id}: Retrieve the details of a previously created Authorization.

Capture an Authorization

• PUT /authorizations/{authorization_id}: Use a PUT request to capture an Authorization. If captured successfully, the transfer field of the Authorization will contain the ID of the Transfer resource that moves funds.

Void an Authorization

• PUT /authorizations/{authorization_id_void_to}: Use a PUT request to void an Authorization. If voided successfully, funds get released, and the transaction is incomplete. Additionally, a voided Authorization can no longer be captured. Depending on the cardholder’s issuing bank, voids can take up to seven days to remove the Authorization hold.

Compliance Forms

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.

Fetch a Compliance Form

• GET /compliance_forms/{compliance_form_id}: Finix sends a webhook whenever a new Compliance Form is created for your Merchant. Using the ID, you can retrieve the Compliance Form.

Complete a Compliance Form

• PUT /compliance_forms/{compliance_form_id}: As part of onboarding, your Merchants need to review and agree to their Compliance Form. Afterward, you need to update their Compliance Form with details about their digital signature. Finix will update their Compliance Form with those details, along with a reference to the new signed_file with their digital signature.

List Compliance Forms

• GET /compliance_forms: Retrieve a list of Compliance Form resources.

Devices

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

List Devices

• GET /devices: Retrieve a list of Devices.

Fetch a Device

• GET /devices/{device_id}: Retrieve the details of an existing Device.

Update Device

• PUT /devices/{device_id}: You can either update the configuration of a device or take an action on the device.

Terminals must be online and connected to the network in order for the request to be successful.

You can initiate an action on a Device. Actions supported vary by gateway.

FINIX_V1 and DUMMY_V1 terminals support the following actions:

• ACTIVATE - Activate the device to enable processing
• DEACTIVATE - Deactivate the device to disable processing
• CANCEL - Cancel any active transaction and return to the idle screen

For processors other than FINIX_V1 and DUMMY_V1, contact your Finix point of contact or email Finix Support for device update instructions.

You can also use a PUT request to update the configuration, description, name, and serial_number of the Device.

Check Device Connection

• GET /devices/{device_id_connection}: To check the connection of the Device, include ?include_connection=true at the end of the request endpoint.

List Device Metrics

• GET /devices/{device_id}/device_metrics: Finix collects and analyzes data from payment devices and terminals to generate logs, known as Device Metric objects. Each Device Metric log provides insights into device health, network connectivity, and payment processing performance.

Use this endpoint to retrieve a device's Device Metric logs.

Create a Merchant Device

• POST /merchants/{merchant_id}/devices: Create a Device under a Merchant.

Disputes

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.

List Disputes

• GET /disputes: Retrieve a list of Dispute resources.

Fetch a Dispute

• GET /disputes/{dispute_id}: Retrieve the details of an existing Dispute.

Update Dispute

• PUT /disputes/{dispute_id}: Update tags on a Dispute.

Upload Files as Dispute Evidence

• POST /disputes/{dispute_id}/evidence: Upload a file as evidence for a Dispute.

You can upload up to 8 files; the total size of the uploaded files combined cannot exceed 10 MB. The allowed file formats include JPEG, PDF, PNG. Individual JPEG, PDF, PNG files can't exceed 1 MB. PNG files will be automatically converted and returned as JPEG files.

List Dispute Evidence

• GET /disputes/{dispute_id}/evidence: Retrieve a list of Dispute Evidence for a Dispute.

Fetch Dispute Evidence

• GET /disputes/{dispute_id}/evidence/{evidence_id}: Fetch evidence uploaded for a Dispute.

If the Finix Dashboard is unavailable, you can fetch the evidence to review the upload state and confirm it was sent to the processor.

Update Dispute Evidence

• PUT /disputes/{dispute_id}/evidence/{evidence_id}: Update tags on Dispute Evidence.

Delete Dispute Evidence

• DELETE /disputes/{dispute_id}/evidence/{evidence_id}: Delete a Dispute Evidence file. You can delete evidence files only before a Dispute and its uploaded evidence are submitted for the first time, and only on FINIX_V1 or DUMMY_V1.

List Dispute Adjustment Transfers

• GET /disputes/{dispute_id}/adjustment_transfers: List the adjustment Transfers for a Dispute. Depending on the stage of the Dispute, different adjustment Transfer subtypes can be applied.

Submit Dispute Evidence

• POST /disputes/{dispute_id}/submit: You can submit evidence to the issuing bank, confirming that the Merchant has completed submitting evidence and is ready to proceed with the Dispute.

Accept a Dispute

• POST /disputes/{dispute_id}/accept: You can accept a Dispute to prevent a long (and potentially expensive) process. When you accept a Dispute, you concede that the Dispute is not worth challenging or representing.

Download Dispute Evidence

• GET /disputes/{dispute_id}/evidence/{evidence_id}/download: Download a file uploaded as Dispute Evidence. Note: The file extension included in output must match the extension of the original uploaded file.

Fees

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

List Fees

• GET /fees: 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:

• Transfer fees: ?linked_to=TRnErBfrHLgdAi3BqAkWLN27
• Authorization fees: ?linked_to=AUg8unYpnWBEY1AdVUDkdQYJ
• Split transfer fees: ?linked_to=split_transfer_split_transfer_97gaitUpcmzqjYYpQbei9j
• Compliance Form fees: ?linked_to=cf_uwErNm23TKYNEiqrEdJK59
• Payment Instrument fees: ?linked_to=PInVUXZLswZi6pdcK1T41MuE
• Merchant-specific fees: ?linked_to=MUwfZPNW3r4EqLMzwgr6txw4

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

Example: ?merchant_id=MUeDVrf2ahuKc9Eg5TeZugvs&created_at.lte=2025-01-01&created_at.gte=2025-02-01

Create a Custom Fee

• POST /fees: Create a custom (i.e. one-time) Fee.

Fetch a Fee

• GET /fees/{fee_id}: Retrieve the details of an existing Fee.

Update Fee

• PUT /fees/{fee_id}: Update the details of a Fee.

List Fees

• GET /fees: 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:

• Transfer fees: ?linked_to=TRnErBfrHLgdAi3BqAkWLN27
• Authorization fees: ?linked_to=AUg8unYpnWBEY1AdVUDkdQYJ
• Split transfer fees: ?linked_to=split_transfer_split_transfer_97gaitUpcmzqjYYpQbei9j
• Compliance Form fees: ?linked_to=cf_uwErNm23TKYNEiqrEdJK59
• Payment Instrument fees: ?linked_to=PInVUXZLswZi6pdcK1T41MuE
• Merchant-specific fees: ?linked_to=MUwfZPNW3r4EqLMzwgr6txw4

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

Example: ?merchant_id=MUeDVrf2ahuKc9Eg5TeZugvs&created_at.lte=2025-01-01&created_at.gte=2025-02-01

List Split Transfers

• GET /split_transfers: Retrieve a list of Split Transfer resources created for a specific split Transfer.

Fee Profiles

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

Create a Fee Profile

• POST /fee_profiles: Create a Fee Profile.

List Fee Profiles

• GET /fee_profiles: Retrieve a list of Fee Profile resources.

Fetch a Fee Profile

• GET /fee_profiles/{fee_profile_id}: Retrieve the details of an existing Fee Profile.

Files

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

Create a File

• POST /files: Before uploading a file, you must create a File resource.

List Files

• GET /files: Retrieve a list of File resources.

Fetch a File

• GET /files/{file_id}: Retrieve the details of an existing File.

Identities

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.

Create an Identity

• POST /identities: Create an Identity for your Buyer, Recipient, or Seller, using identity_roles and type to indicate the type of Identity you're creating.

List Identities

• GET /identities: Retrieve a list of the previously created Identities.

Fetch an Identity

• GET /identities/{identity_id}: Retrieve the details of a previously created Identity.

Update an Identity

• PUT /identities/{identity_id}: Update an existing Identity.

Create an Associated Identity

• POST /identities/{identity_id}/associated_identities: Create an associated Identity for every owner with 25% or more ownership over the merchant.

List Associated Identities

• GET /identities/{identity_id}/associated_identities: Retrieve a list of Associated Identities for an Identity.

Fetch an Identity's Merchant

• GET /identities/{identity_id}/merchants: Retrieve the Merchant resource for an Identity.

Merchants

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

Create a Merchant

• POST /identities/{identity_id}/merchants: Create a Merchant to start the underwriting process for your seller. Merchants must be created under an Identity.

List Merchants

• GET /merchants: Retrieve a list of Merchant resources.

Fetch a Merchant

• GET /merchants/{merchant_id}: Retrieve the details of a Merchant.

Update a Merchant

• PUT /merchants/{merchant_id}: Update a Merchant.

Verify a Merchant

• POST /merchants/{merchant_id}/verifications: Create a Verification on a Merchant to get them Approved.

Onboarding Forms

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

Create an Onboarding Form

• POST /onboarding_forms: Create an Onboarding Form by entering the processor’s name you want to onboard users to.

Fetch an Onboarding Form

• GET /onboarding_forms/{onboarding_form_id}: Retrieve the details of an existing Onboarding Form.

Create an Onboarding Form Link

• POST /onboarding_forms/{onboarding_form_id}/links: Create a link that lets users resume their Onboarding Form.

Payment Instruments

A Payment Instrument resource represents the payment details of a credit card or bank account.

Create a Payment Instrument

• POST /payment_instruments: Create a Payment Instrument resource using a card or bank account.

List Payment Instruments

• GET /payment_instruments: Retrieve a list of Payment Instrument resources.

Fetch a Payment Instrument

• GET /payment_instruments/{payment_instrument_id}: Retrieve the details of an existing Payment Instrument.

Update a Payment Instrument

• PUT /payment_instruments/{payment_instrument_id}: Update a Payment Instrument.

List Instrument History Entries

• GET /payment_instruments/{payment_instrument_id}/instrument_history: Whenever a stored payment card's details are updated, an Instrument History Entry is created.

Verify CVV, AVS, and Name

• PUT /payment_instruments/{payment_instrument_id_verify}: Verify a Payment Instrument to determine CVV, AVS, and name verification results.

Create an Apple Pay Session

• POST /apple_pay_sessions: Create an apple_pay_session to process Apple Pay transactions on the web.

Transfers

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

Create a Transfer

• POST /transfers: Create a Transfer.

List Transfers

• GET /transfers: Retrieve a list of Transfers.

Fetch a Transfer

• GET /transfers/{transfer_id}: Retrieve a Transfer.

Update a Transfer

• PUT /transfers/{transfer_id}: Update a Transfer.

Refund or Reverse a Transfer

• POST /transfers/{transfer_id}/reversals: Reverse a transfer with a type of DEBIT.

List Transfer Reversals

• GET /transfers/{transfer_id}/reversals: Retrieve a list of reversals for a Transfer.

Users

A User resource represents a pair of API keys which are used to perform authenticated requests against the Finix API.

List Users

• GET /users: Retrieve a list of User resources.

Fetch a User by ID

• GET /users/{user_id}: Retrieve the details of an existing User.

Update a User

• PUT /users/{user_id}: Update a User with new tags or disable the User and their credentials.