# Finix API Reference The Finix API is resource oriented, relying heavily on common REST principles. Our API uses JSON encoded requests and responses. ## 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 ```bash 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` | Live Access To get access to the Live environment, please reach out to your Finix point-of-contact. ## 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](https://docs.finix.com/additional-resources/developers/implementation-and-testing/error-codes/). Also, you can [test for specific errors and responses](https://docs.finix.com/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 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: - `/transfers` - `/authorizations` - `/transfers/{id}/reversals` `idempotency_id` scope `idempotency_id` checks against previous requests made on the same endpoint. ## 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 ```bash 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 Example ```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. Special Characters Finix does **_not_** allow special characters on tags (e.g., `\`, `,`, `"`, `'`) ## 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](https://docs.finix.com/additional-resources/developers/authentication-and-api-basics/versioning/). ## Postman Collection Finix has a Postman collection to help in your development. Overview URL [https://finix.com](/content/site-root.html) ### 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. Operations - post - /authorizations - get - /authorizations - get - /authorizations/{authorization_id} - put - /authorizations/{authorization_id} - put - /authorizations/{authorization_id_void_to} ### 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. Operations - get - /compliance_forms/{compliance_form_id} - put - /compliance_forms/{compliance_form_id} - get - /compliance_forms ### Devices A `Device` resource represents a Point-of-Sale terminal. Devices are used for [In-Person transactions](https://docs.finix.com/guides/in-person-payments). 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 ### 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. 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} ### Fees 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} ### Fee Profiles A `fee_profiles` represents a pricing scheme that automatically applies fees to each transaction. Changes to `fee_profiles` go into effect immediately. Operations - post - /fee_profiles - get - /fee_profiles - get - /fee_profiles/{fee_profile_id} ### Files Use Finix's File API to upload and manage files for your merchants. 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} ### 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. 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 ### Merchants A `Merchant` resource represents the entity's merchant account on a processor. Your `Merchant` must be `APPROVED` to process payments. Operations - post - /identities/{identity_id}/merchants - get - /merchants - get - /merchants/{merchant_id} - put - /merchants/{merchant_id} - post - /merchants/{merchant_id}/verifications ### Onboarding Forms Finix offers and hosts pre-built onboarding forms that you can use to collect onboarding and identity verification information from your users. Operations - post - /onboarding_forms - get - /onboarding_forms/{onboarding_form_id} - post - /onboarding_forms/{onboarding_form_id}/links ### Payment Instruments 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`. 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 ### Payment Instrument Associations In Finix, `Payment Instruments` are tied to the owner of that account. For example, `Payment Instruments` tied to buyers will be the cards used for purchases while `Payment Instruments` tied to a `Merchant` are the bank accounts where they receive settlements. 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} ### Settlements A `Settlement` represents a collection (i.e. batch) of Settlement Entries that will get paid out to a specific [Merchant](https://docs.finix.com/api/merchants). A `Settlement Entry` can represent a [Transfer](https://docs.finix.com/api/transfers), custom [Fee](https://docs.finix.com/api/fees), or [Split Transfer](https://docs.finix.com/api/split-transfers). 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 ### Settlement Queue Entries 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. Operations - get - /settlement_queue_entries - put - /settlement_queue_entries - get - /settlement_queue_entries/{settlement_queue_entry_id} ### Split Transfers Transactions can be split among different merchants. A `Split Transfer` shows how funds from a split `Transfer` were distributed into a merchant's `Settlement`. Operations - get - /fees - get - /split_transfers - get - /split_transfers/{split_transfer_id} ### Transfers A `Transfer` represents any flow of funds either to or from a `Payment Instrument`. All payments in Finix are represented by a `Transfer`. Operations - post - /transfers - get - /transfers - get - /transfers/{transfer_id} - put - /transfers/{transfer_id} - post - /transfers/{transfer_id}/reversals - get - /transfers/{transfer_id}/reversals ### Users 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). Operations - get - /users - get - /users/{user_id} - put - /users/{user_id} ### Verifications `Verifications` are used to verify [Merchants](https://docs.finix.com/api/merchants) and [Payment Instruments](https://docs.finix.com/api/payment-instruments). Operations - get - /merchants/{merchant_id}/verifications - get - /verifications - get - /verifications/{verification_id} ### Webhooks 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. Operations - post - /webhooks - get - /webhooks - get - /webhooks/{webhook_id} - put - /webhooks/{webhook_id} ### Gateway Integrations A `Gateway Integration` represents a connection to a third-party payment gateway. At this time, the only supported gateway is Cybersource. Operations - post - /gateway_integrations - get - /gateway_integrations - get - /gateway_integrations/{gateway_integration_id} ### Receipts The `Receipt` resource generates a receipt for [Transfers](https://docs.finix.com/api#Transfers) or [Authorizations](https://docs.finix.com/api#Authorizations). You can then send the `Receipt` via Email, SMS, or use the information from the `Receipt` to send it yourself. Operations - post - /receipts - get - /receipts/{receipt_id} - post - /receipts/{receipt_id}/delivery_attempts - get - /receipts/{receipt_id}/delivery_attempts ### Subscriptions A `Subscription` resource represents a recurring charge to a `Payment Instrument` at regular intervals. Subscribers can be buyers, customers, or merchants. 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} ### Subscription Plans A `Subscription Plan` resource is a template with set recurring costs and frequencies that can be reused across multiple `Subscription` resources. Operations - post - /subscription_plans - get - /subscription_plans - get - /subscription_plans/{subscription_plan_id} - put - /subscription_plans/{subscription_plan_id} ### Transfer Attempts When a user attempts to make a payment using a Checkout Form or [Payment Link](https://docs.finix.com/low-code-no-code/payment-links), or a recipient submitting details with a [Payout Link](https://docs.finix.com/guides/payouts/payout-links)—a Transfer Attempt is created. Operations - get - /transfer_attempts - get - /transfer_attempts/{transfer_attempt_id} ### Balances A `Balance` resource represents the current financial state of an `Application` identified by the `linked_to` query parameter. Operations - get - /balances - get - /balances/{balance_id} - get - /balances/{balance_id}/balance_entries - get - /balance_entries/{balance_entry_id} ### Balance Adjustments A `Balance Adjustment` modifies the account `Balance` by adding funds (a 'top-up') or reducing funds for Payouts. Each adjustment is linked to a specific payment rail (e.g., ACH, card, wire). Operations - post - /balance_adjustments - get - /balance_adjustments ### Disbursement Rules 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. Operations - get - /disbursement_rules - get - /disbursement_rules/current_usages