# 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. | Parameter | Value | |----------------------|-----------------------------------------------| | Sandbox Username | `USsRhsHYZGBPnQw8CByJyEQW` | | Sandbox Password | `8a14c2f9-d94b-4c72-8f5c-a62908e5b30e` | ```shell 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. | Environment | Endpoint URL | |-------------|------------------------------------------------| | Sandbox | `https://finix.sandbox-payments-api.com` | | Live | `https://finix.live-payments-api.com` | ## 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](/additional-resources/developers/implementation-and-testing/error-codes/). Also, you can [test for specific errors and responses](/additional-resources/developers/implementation-and-testing/testing-your-integration/). | 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. | ## 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`. ```shell 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. ```json { "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](/additional-resources/developers/authentication-and-api-basics/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](https://docs.finix.com/_bundle/api/index.yaml) ## 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](https://docs.finix.com/api/authorizations/createauthorization.md): Create an Authorization to process a transaction. ### List Authorizations - [GET /authorizations](https://docs.finix.com/api/authorizations/listauthorizations.md): Retrieve a list of Authorizations. ### Fetch an Authorization - [GET /authorizations/{authorization_id}](https://docs.finix.com/api/authorizations/getauthorization.md): Retrieve the details of a previously created Authorization. ### Capture an Authorization - [PUT /authorizations/{authorization_id}](https://docs.finix.com/api/authorizations/captureauthorization.md): 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}](https://docs.finix.com/api/authorizations/voidauthorization.md): 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}](https://docs.finix.com/api/compliance-forms/getcomplianceform.md): 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}](https://docs.finix.com/api/compliance-forms/updatecomplianceform.md): 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](https://docs.finix.com/api/compliance-forms/listcomplianceforms.md): Retrieve a list of Compliance Form resources. ## Devices A `Device` resource represents a Point-of-Sale terminal. Devices are used for [In-Person transactions](/guides/in-person-payments). ### List Devices - [GET /devices](https://docs.finix.com/api/devices/listdevices.md): Retrieve a list of Devices. ### Fetch a Device - [GET /devices/{device_id}](https://docs.finix.com/api/devices/getdevice.md): Retrieve the details of an existing Device. ### Update Device - [PUT /devices/{device_id}](https://docs.finix.com/api/devices/updatedevice.md): 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}](https://docs.finix.com/api/devices/getdeviceconnection.md): 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](https://docs.finix.com/api/devices/listdevicemetrics.md): 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](https://docs.finix.com/api/devices/createmerchantdevice.md): 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](https://docs.finix.com/api/disputes/listdisputes.md): Retrieve a list of Dispute resources. ### Fetch a Dispute - [GET /disputes/{dispute_id}](https://docs.finix.com/api/disputes/getdispute.md): Retrieve the details of an existing Dispute. ### Update Dispute - [PUT /disputes/{dispute_id}](https://docs.finix.com/api/disputes/updatedispute.md): Update tags on a Dispute. ### Upload Files as Dispute Evidence - [POST /disputes/{dispute_id}/evidence](https://docs.finix.com/api/disputes/createdisputeevidence.md): 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](https://docs.finix.com/api/disputes/listdisputesevidence.md): Retrieve a list of Dispute Evidence for a Dispute. ### Fetch Dispute Evidence - [GET /disputes/{dispute_id}/evidence/{evidence_id}](https://docs.finix.com/api/disputes/getdisputeevidence.md): 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}](https://docs.finix.com/api/disputes/updatedisputeevidence.md): Update tags on Dispute Evidence. ### Delete Dispute Evidence - [DELETE /disputes/{dispute_id}/evidence/{evidence_id}](https://docs.finix.com/api/disputes/deletedisputeevidence.md): 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](https://docs.finix.com/api/disputes/listdisputesadjustments.md): 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](https://docs.finix.com/api/disputes/submitdisputeevidence.md): 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](https://docs.finix.com/api/disputes/acceptdispute.md): 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](https://docs.finix.com/api/disputes/downloaddisputeevidence.md): 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](https://docs.finix.com/api/fees/listfees.md): 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](https://docs.finix.com/api/fees/createfee.md): Create a custom (i.e. one-time) Fee. ### Fetch a Fee - [GET /fees/{fee_id}](https://docs.finix.com/api/fees/getfee.md): Retrieve the details of an existing Fee. ### Update Fee - [PUT /fees/{fee_id}](https://docs.finix.com/api/fees/updatefee.md): Update the details of a Fee. ### List Fees - [GET /fees](https://docs.finix.com/api/split-transfers/listfees.md): 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](https://docs.finix.com/api/split-transfers/listsplittransfers.md): 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](https://docs.finix.com/api/fee-profiles/createfeeprofile.md): Create a Fee Profile. ### List Fee Profiles - [GET /fee_profiles](https://docs.finix.com/api/fee-profiles/listfeeprofiles.md): Retrieve a list of Fee Profile resources. ### Fetch a Fee Profile - [GET /fee_profiles/{fee_profile_id}](https://docs.finix.com/api/fee-profiles/getfeeprofile.md): 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](https://docs.finix.com/api/files/createfile.md): Before uploading a file, you must create a File resource. ### List Files - [GET /files](https://docs.finix.com/api/files/listfiles.md): Retrieve a list of File resources. ### Fetch a File - [GET /files/{file_id}](https://docs.finix.com/api/files/getfile.md): 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](https://docs.finix.com/api/identities/createidentity.md): 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](https://docs.finix.com/api/identities/listidentities.md): Retrieve a list of the previously created Identities. ### Fetch an Identity - [GET /identities/{identity_id}](https://docs.finix.com/api/identities/getidentity.md): Retrieve the details of a previously created Identity. ### Update an Identity - [PUT /identities/{identity_id}](https://docs.finix.com/api/identities/updateidentity.md): Update an existing Identity. ### Create an Associated Identity - [POST /identities/{identity_id}/associated_identities](https://docs.finix.com/api/identities/createassociatedidentity.md): Create an associated Identity for every owner with 25% or more ownership over the merchant. ### List Associated Identities - [GET /identities/{identity_id}/associated_identities](https://docs.finix.com/api/identities/listidentityassociatedidentities.md): Retrieve a list of Associated Identities for an Identity. ### Fetch an Identity's Merchant - [GET /identities/{identity_id}/merchants](https://docs.finix.com/api/identities/getidentitymerchant.md): 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](https://docs.finix.com/api/merchants/createmerchant.md): Create a Merchant to start the underwriting process for your seller. Merchants must be created under an Identity. ### List Merchants - [GET /merchants](https://docs.finix.com/api/merchants/listmerchants.md): Retrieve a list of Merchant resources. ### Fetch a Merchant - [GET /merchants/{merchant_id}](https://docs.finix.com/api/merchants/getmerchant.md): Retrieve the details of a Merchant. ### Update a Merchant - [PUT /merchants/{merchant_id}](https://docs.finix.com/api/merchants/updatemerchant.md): Update a Merchant. ### Verify a Merchant - [POST /merchants/{merchant_id}/verifications](https://docs.finix.com/api/merchants/createmerchantverification.md): 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](https://docs.finix.com/api/onboarding-forms/createonboardingform.md): 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}](https://docs.finix.com/api/onboarding-forms/getonboardingform.md): Retrieve the details of an existing Onboarding Form. ### Create an Onboarding Form Link - [POST /onboarding_forms/{onboarding_form_id}/links](https://docs.finix.com/api/onboarding-forms/createonboardingformlink.md): 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](https://docs.finix.com/api/payment-instruments/createpaymentinstrument.md): Create a Payment Instrument resource using a card or bank account. ### List Payment Instruments - [GET /payment_instruments](https://docs.finix.com/api/payment-instruments/listpaymentinstruments.md): Retrieve a list of Payment Instrument resources. ### Fetch a Payment Instrument - [GET /payment_instruments/{payment_instrument_id}](https://docs.finix.com/api/payment-instruments/getpaymentinstrument.md): Retrieve the details of an existing Payment Instrument. ### Update a Payment Instrument - [PUT /payment_instruments/{payment_instrument_id}](https://docs.finix.com/api/payment-instruments/updatepaymentinstrument.md): Update a Payment Instrument. ### List Instrument History Entries - [GET /payment_instruments/{payment_instrument_id}/instrument_history](https://docs.finix.com/api/payment-instruments/listinstrumenthistoryentries.md): 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}](https://docs.finix.com/api/payment-instruments/createpaymentinstrumentverification.md): Verify a Payment Instrument to determine CVV, AVS, and name verification results. ### Create an Apple Pay Session - [POST /apple_pay_sessions](https://docs.finix.com/api/payment-instruments/createapplepaysession.md): 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](https://docs.finix.com/api/transfers/createtransfer.md): Create a Transfer. ### List Transfers - [GET /transfers](https://docs.finix.com/api/transfers/listtransfers.md): Retrieve a list of Transfers. ### Fetch a Transfer - [GET /transfers/{transfer_id}](https://docs.finix.com/api/transfers/gettransfer.md): Retrieve a Transfer. ### Update a Transfer - [PUT /transfers/{transfer_id}](https://docs.finix.com/api/transfers/updatetransfer.md): Update a Transfer. ### Refund or Reverse a Transfer - [POST /transfers/{transfer_id}/reversals](https://docs.finix.com/api/transfers/createtransferreversal.md): Reverse a transfer with a type of DEBIT. ### List Transfer Reversals - [GET /transfers/{transfer_id}/reversals](https://docs.finix.com/api/transfers/listtransferreversals.md): 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](https://docs.finix.com/api/users/listusers.md): Retrieve a list of User resources. ### Fetch a User by ID - [GET /users/{user_id}](https://docs.finix.com/api/users/getuser.md): Retrieve the details of an existing User. ### Update a User - [PUT /users/{user_id}](https://docs.finix.com/api/users/updateuser.md): Update a User with new tags or disable the User and their credentials.