Finix API

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.

ParameterValue
Sandbox UsernameUSsRhsHYZGBPnQw8CByJyEQW
Sandbox Password8a14c2f9-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

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.

EnvironmentEndpoint URL
Sandboxhttps://finix.sandbox-payments-api.com
Livehttps://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 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
400Bad RequestWe could not parse your request. Verify you are providing valid JSON.
401UnauthorizedWe could not authenticate your request. Verify your username and password are correct.
402Upstream Processor ErrorErrors caused by 3rd-party service(s).
403ForbiddenYour credentials do not have the correct permissions to perform the request.
404Not FoundWe could not find the specified resource.
405Method Not AllowedThe specified resource does not support the HTTP Method used to submit the request.
406Not AcceptableThe server could accept the submitted request. Confirm how the request was formatted and submitted.
409ConflictThe submitted request conflicts with the current state of the server.
422Unprocessable EntityThe 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).
500Internal Server ErrorWe 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
curl "https://finix.sandbox-payments-api.com/transfers?type=DEBIT" \
    -H "Finix-Version: 2022-02-01" \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Tags

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

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


Overview
URL https://finix.com
Finix support@finixpayments.com
Languages
Servers
Sandbox server
https://finix.sandbox-payments-api.com/
Production server
https://finix.live-payments-api.com/

Authorizations

Operations

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.

Related Guides: Managing PCI Compliance, PCI DSS Compliance

Operations

Devices

Operations

Disputes

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

Related Guides: Managing Disputes

Operations

Fees

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

Operations

Fee Profiles

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

Related Guides: Collecting Fees

Operations

Files

Operations

Identities

Operations

Instrument Updates

With Finix's instrument_updates API, you can update the credit card information you have saved for customers without needing to contact each individual cardholder.

Related Guides: Account Updater

Operations

Merchants

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

Related Guides: Getting Started, Onboarding Sellers

Operations

Create a Merchant

Request

Create a Merchant to start the underwriting (also called provisioning) process for your seller. Merchants must be created under an Identity.

A bank account must be associated with the previously created Identity before a Merchant can be successfully onboarded and verified.

Path
identity_idstringrequired

ID of Identity to fetch.

Example: IDrH4G2VTfNjn1VFkvhcyMYj
Headers
Finix-Versionstring

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

Default 2018-01-01
Example: 2022-02-01
Bodyapplication/json
gatewaystring

Name of the gateway that processes the Merchant's card present transactions. Use gateway only to enable a merchant to accept card present transactions.

Enum"TRIPOS_CLOUD_V1""TRIPOS_MOBILE_V1""DATACAP_V1"
default_partial_authorization_enabledboolean
  • Set to true if you want to enable partial authorizations for a specific Merchant.
  • Partial authorizations enables the Merchant to collect a portion of the amount if the cardholder doesn't have the funds to cover the entire amount on their card.
Default false
processorstring(ProcessorRequest)required

Set the acquiring processor. Use DUMMY_V1 or null for your Sandbox. For more details on which processor to use, reach out to your Finix point of contact or email Finix Support.

Enum"DUMMY_V1""FINIX_V1""LITLE_V1""MASTERCARD_V1""NMI_V1""VANTIV_V1""VISA_V1"
tagsobject or null(tags)

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

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500. (For example, order_number: 25, item_type: produce, department: sales)
curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/identities/IDrH4G2VTfNjn1VFkvhcyMYj/merchants \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "processor": "DUMMY_V1",
    "tags": {
      "key_2": "value_2"
    }
  }'

Responses

Single Merchant object

Headers
finix-apiuser-rolestring
Enum"ROLE_ADMIN""ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"
datestring
x-request-idstring

A unique ID for this specific API request attempt.

Bodyapplication/json
idstring

The ID of the Merchant resource.

created_atstring(date-time)(CreatedAt)

Timestamp of when the object was created.

updated_atstring(date-time)(UpdatedAt)

Timestamp of when the object was last updated.

applicationstring

ID of the Application the Merchant was created under.

card_cvv_requiredboolean

Set to true to require the card's CVV code.

card_expiration_date_requiredboolean

Set to true to require the card's expiration date.

card_network_detailsstring or null
convenience_charges_enabledboolean

Set to true if you want to enable the Merchant to accept convenience fees and/or service fees.

countrystring or null(Country)

The sender’s country.

Enum"ABW""AFG""AGO""AIA""ALA""ALB""AND""ARE""ARG""ARM"
creating_transfer_from_report_enabledboolean

Set to true to automatically create Transfers once settlement reports get generated.

currenciesArray of strings or null(Currency)

ISO 4217 3 letter currency code.

Enum"AED""AFN""ALL""AMD""ANG""AOA""ARS""AUD""AWG""AZN"
default_partial_authorization_enabledboolean

Set to true if you want to enable the Merchant to accept convenience fees and/or service fees

fee_ready_to_settle_uponstring

Details how the Merchant settles fees.

Enum"RECONCILIATION""SUCCESSFUL_CAPTURE""PROCESSOR_WINDOW""CONFIGURABLE_WINDOW"
gatewaystring or null

Name of the gateway that routes the Merchant's transactions to the processor.

Enum"TRIPOS_MOBILE_V1""TRIPOS_CLOUD_V1""DATACAP_V1"
gross_settlement_enabledboolean

Set to true to enable gross settlements.

identitystring

The ID of the Identity resource associated with the Merchant.

instant_payouts_card_push_enabledboolean

Set to true if you want to allow the merchant to be enabled for settlement instant payouts.

Default false
level_two_level_three_data_enabledboolean

Set to true to enable the Merchant for Level 2 and Level 3 processing. Default value is false.

loan_repaymentboolean

Whether the merchant is able to support loan repayment on the card networks.

Default false
mccstring or null
merchant_namestring

The legal name saved in the Merchant resource.

merchant_profilestring

Details if a merchant's info was submitted to third-party processors for provisioning.

midstring or null

MID of the Merchant.

onboarding_statestring

Details the state of the Merchant's onboarding.

Enum"APPROVED""PROVISIONING""REJECTED""UPDATE_REQUESTED"
processing_enabledboolean

Details if transaction processing is enabled for the Merchant. ROLE_PARTNER can only set this value to false.

processorstring

Name of the transaction processor.

processor_detailsobject

Additional details specific to the processor.

ready_to_settle_uponstring

Details how transactions captured by the Merchant are settled.

Enum"RECONCILIATION""SUCCESSFUL_CAPTURE""PROCESSOR_WINDOW""CONFIGURABLE_WINDOW"
ready_to_settle_upon_delay_alignmentstring

Indicates whether transaction settlement should be delayed to synchronize the timing of all transactions, including both card and ACH, ensuring they are settled together.

Possible values include:

  • ACH - Align all transactions to match the timing of ACH settlements, so card transactions settle at the same speed as ACH transactions.
  • NONE - Default behavior where card transactions settle the next day (T+1) and ACH transactions settle two days later (T+2).
Enum"ACH""NONE"
rent_surcharges_enabledboolean

Set to true if you want to enable a Merchant to accept rent charges.

settlement_enabledboolean

Details if settlement approvals are enabled for the Merchant. ROLE_PARTNER can only set this value to false.

settlement_funding_identifierstring

Includes additional information (like the MID or Merchant name) when submitting funding Transfers to processors.

  • UNSET: No additional details get provided to the processor.
  • MID_AND_DATE: The MID of the Merchant and the date the funding Transfer was submitted (Date is in UTC). e.g MID:12345678-20220225
  • MID_AND_MERCHANT_NAME: The MID of the Merchant and the Merchant#name (white spaces will be removed). e.g. MID:12345678-NameOfMerchant

These details appear alongside the seller's payout in their bank account as a description of the deposit.

Default "UNSET"
Enum"UNSET""MID_AND_DATE""MID_AND_MERCHANT_NAME"
settlement_queue_modestring

If settlement_queue_mode is set to MANUAL, Finix will automatically place all transactions (Sales, Fees, Refunds, and ACH Returns) into a settlement queue that you can manage. Each transaction will have a Settlement Queue Entry.

When a Settlement Queue Entry is created, it will not be placed into Settlement until the Settlement Queue Entry is explicitly released.

Note: We require the release of all settlement queue entries within 30 days of creation.

Enum"UNSET""MANUAL"
surcharges_enabledboolean

Set to true if you want to enable a Merchant to accept surcharge fees. For more details, see Buyer Charges.

Default false
tagsobject or null(tags)

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

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500. (For example, order_number: 25, item_type: produce, department: sales)
verificationstring

ID of the Verification that was submitted to verify the Merchant.

_linksobject

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.

Response
application/json
{
  "id": "MUeTBamsYxqr1KSnT4U2x9SP",
  "created_at": "2024-08-16T13:11:36.72Z",
  "updated_at": "2024-08-16T13:11:36.72Z",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "card_cvv_required": false,
  "card_expiration_date_required": true,
  "card_network_details": null,
  "convenience_charges_enabled": false,
  "country": "USA",
  "creating_transfer_from_report_enabled": true,
  "currencies": [
    "USD"
  ],
  "default_partial_authorization_enabled": false,
  "disbursements_ach_pull_enabled": false,
  "disbursements_ach_push_enabled": false,
  "disbursements_card_pull_enabled": false,
  "disbursements_card_push_enabled": false,
  "disbursements_same_day_ach_pull_enabled": false,
  "disbursements_same_day_ach_push_enabled": false,
  "fee_ready_to_settle_upon": "RECONCILIATION",
  "gateway": null,
  "gross_settlement_enabled": false,
  "identity": "ID6ZC4KedcaCwECQcWr7SM4m",
  "instant_payouts_card_push_enabled": false,
  "level_two_level_three_data_enabled": false,
  "loan_repayment": null,
  "mcc": "4900",
  "merchant_name": "Finix Flowers",
  "merchant_profile": "MP8aC84QAtA69Qhv6BJSyvHr",
  "mid": null,
  "onboarding_state": "PROVISIONING",
  "processing_enabled": false,
  "processor": "DUMMY_V1",
  "processor_details": {},
  "ready_to_settle_upon": "RECONCILIATION",
  "ready_to_settle_upon_delay_alignment": "NONE",
  "rent_surcharges_enabled": false,
  "settlement_enabled": false,
  "settlement_funding_identifier": "UNSET",
  "surcharges_enabled": false,
  "tags": {
    "key_2": "value_2"
  },
  "verification": "VI7jopNSiaVMXWKkhxt6dJm7",
  "_links": {
    "self": { … },
    "identity": { … },
    "verifications": { … },
    "merchant_profile": { … },
    "application": { … },
    "verification": { … }
  }
}

List Merchants

Request

Retrieve a list of Merchants.

For details on how to query endpoints using the available parameters, see Query Parameters.

Query
after_cursorstring

Return every resource created after the cursor value.

Example: after_cursor=TRnasXQ5AmjsLnPMwnme7TL4
before_cursorstring

Return every resource created before the cursor value.

Example: before_cursor=TRnasXQ5AmjsLnPMwnme7TL4
limitinteger

The numbers of items to return.

Example: limit=10
application_idstring

Filter by the Merchant's application.

Example: application_id=APgPDQrLD52TYvqazjHJJchM
countrystring

Filter by the Merchant's country (ISO 3166 alpha-3).

Enum"USA""CAN"
Example: country=USA
created_at.gtestring(date-time)

Filter where created_at is after the given date.

Example: created_at.gte=2022-09-27T11:21:23
created_at.ltestring(date-time)

Filter where created_at is before the given date.

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

Filter by the Merchant's currencies (ISO 4217).

Enum"USD""CAD"
Example: currency=USD
idstring

Filter by id.

identity_business_namestring

Filter by the business_name of the Merchant's identity (exact match).

Example: identity_business_name=finix%20flowers
identity_business_name.likestring

Filter by the business_name of the Merchant's identity (partial match).

Example: identity_business_name.like=finix
identity_doing_business_asstring

Filter by the doing_business_as of the Merchant's identity (exact match).

Example: identity_doing_business_as=finix%20flowers
identity_doing_business_as.likestring

Filter by the doing_business_as of the Merchant's identity (partial match).

Example: identity_doing_business_as.like=finix
identity_first_namestring

Filter by the first_name of the Merchant's identity (exact match).

Example: identity_first_name=jonathan
identity_first_name.likestring

Filter by the first_name of the Merchant's identity (partial match).

Example: identity_first_name.like=jon
identity_idstring

Filter by the Merchant's identity.

Example: identity_id=ID6ZC4KedcaCwECQcWr7SM4m
identity_last_namestring

Filter by the last_name of the Merchant's identity (exact match).

Example: identity_last_name=williams
identity_last_name.likestring

Filter by the last_name of the Merchant's identity (partial match).

Example: identity_last_name.like=will
identity_rolestring

Filter by the identity_roles of the Merchant's identity.

Enum"APPLICATION_OWNER""RECIPIENT""SELLER"
Example: identity_role=SELLER
mccstring

Filter by the Merchant's mcc.

Example: mcc=4900
merchant_namestring

Filter by the Merchant's merchant_name (exact match).

Example: merchant_name=finix%20flowers
merchant_name.likestring

Filter by the Merchant's merchant_name (partial match).

Example: merchant_name.like=finix
processing_enabledboolean

Filter by whether the Merchant's processing is enabled (processing_enabled).

Example: processing_enabled=true
processor_typestring

Filter by the Merchant's processor.

Enum"FINIX_V1""LITLE_V1""VANTIV_V1""DUMMY_V1"
Example: processor_type=DUMMY_V1
settlement_enabledboolean

Filter by whether the Merchant's settlements are enabled (settlement_enabled).

Example: settlement_enabled=true
updated_at.gtestring(date-time)

Filter where updated_at is after the given date.

Example: updated_at.gte=2022-09-27T11:21:23
updated_at.ltestring(date-time)

Filter where updated_at is before the given date.

Example: updated_at.lte=2023-01-21T10:17:22
verification_idstring

Filter by the Merchant's verification.

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

Responses

List of Merchants objects

Headers
finix-apiuser-rolestring
Enum"ROLE_ADMIN""ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"
datestring
x-request-idstring

A unique ID for this specific API request attempt.

Bodyapplication/json
pageobject(PageCursor)

Details the page that's returned.

_embeddedobject

List of Merchant objects.

_linksobject(ListLinks)

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.

Response
application/json
{
  "_embedded": {
    "merchants": [ … ]
  },
  "_links": {
    "self": { … },
    "next": { … }
  },
  "page": {
    "limit": 100,
    "next_cursor": "MU7noQ1wdgdAeAfymw2rfBMq"
  }
}

Fetch a Merchant

Request

Retrieve the details of a Merchant.

Path
merchant_idstringrequired

ID of Merchant.

Example: MU7noQ1wdgdAeAfymw2rfBMq
curl "https://finix.sandbox-payments-api.com/merchants/MUogXBgJaxFfTnziXfJNSXHq" \
    -H "Content-Type: application/json" \
    -H "Finix-Version: 2022-02-01" \
    -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda

Responses

Single Merchant object

Headers
finix-apiuser-rolestring
Enum"ROLE_ADMIN""ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"
datestring
x-request-idstring

A unique ID for this specific API request attempt.

Bodyapplication/json
idstring

The ID of the Merchant resource.

created_atstring(date-time)(CreatedAt)

Timestamp of when the object was created.

updated_atstring(date-time)(UpdatedAt)

Timestamp of when the object was last updated.

applicationstring

ID of the Application the Merchant was created under.

card_cvv_requiredboolean

Set to true to require the card's CVV code.

card_expiration_date_requiredboolean

Set to true to require the card's expiration date.

card_network_detailsstring or null
convenience_charges_enabledboolean

Set to true if you want to enable the Merchant to accept convenience fees and/or service fees.

countrystring or null(Country)

The sender’s country.

Enum"ABW""AFG""AGO""AIA""ALA""ALB""AND""ARE""ARG""ARM"
creating_transfer_from_report_enabledboolean

Set to true to automatically create Transfers once settlement reports get generated.

currenciesArray of strings or null(Currency)

ISO 4217 3 letter currency code.

Enum"AED""AFN""ALL""AMD""ANG""AOA""ARS""AUD""AWG""AZN"
default_partial_authorization_enabledboolean

Set to true if you want to enable the Merchant to accept convenience fees and/or service fees

fee_ready_to_settle_uponstring

Details how the Merchant settles fees.

Enum"RECONCILIATION""SUCCESSFUL_CAPTURE""PROCESSOR_WINDOW""CONFIGURABLE_WINDOW"
gatewaystring or null

Name of the gateway that routes the Merchant's transactions to the processor.

Enum"TRIPOS_MOBILE_V1""TRIPOS_CLOUD_V1""DATACAP_V1"
gross_settlement_enabledboolean

Set to true to enable gross settlements.

identitystring

The ID of the Identity resource associated with the Merchant.

instant_payouts_card_push_enabledboolean

Set to true if you want to allow the merchant to be enabled for settlement instant payouts.

Default false
level_two_level_three_data_enabledboolean

Set to true to enable the Merchant for Level 2 and Level 3 processing. Default value is false.

loan_repaymentboolean

Whether the merchant is able to support loan repayment on the card networks.

Default false
mccstring or null
merchant_namestring

The legal name saved in the Merchant resource.

merchant_profilestring

Details if a merchant's info was submitted to third-party processors for provisioning.

midstring or null

MID of the Merchant.

onboarding_statestring

Details the state of the Merchant's onboarding.

Enum"APPROVED""PROVISIONING""REJECTED""UPDATE_REQUESTED"
processing_enabledboolean

Details if transaction processing is enabled for the Merchant. ROLE_PARTNER can only set this value to false.

processorstring

Name of the transaction processor.

processor_detailsobject

Additional details specific to the processor.

ready_to_settle_uponstring

Details how transactions captured by the Merchant are settled.

Enum"RECONCILIATION""SUCCESSFUL_CAPTURE""PROCESSOR_WINDOW""CONFIGURABLE_WINDOW"
ready_to_settle_upon_delay_alignmentstring

Indicates whether transaction settlement should be delayed to synchronize the timing of all transactions, including both card and ACH, ensuring they are settled together.

Possible values include:

  • ACH - Align all transactions to match the timing of ACH settlements, so card transactions settle at the same speed as ACH transactions.
  • NONE - Default behavior where card transactions settle the next day (T+1) and ACH transactions settle two days later (T+2).
Enum"ACH""NONE"
rent_surcharges_enabledboolean

Set to true if you want to enable a Merchant to accept rent charges.

settlement_enabledboolean

Details if settlement approvals are enabled for the Merchant. ROLE_PARTNER can only set this value to false.

settlement_funding_identifierstring

Includes additional information (like the MID or Merchant name) when submitting funding Transfers to processors.

  • UNSET: No additional details get provided to the processor.
  • MID_AND_DATE: The MID of the Merchant and the date the funding Transfer was submitted (Date is in UTC). e.g MID:12345678-20220225
  • MID_AND_MERCHANT_NAME: The MID of the Merchant and the Merchant#name (white spaces will be removed). e.g. MID:12345678-NameOfMerchant

These details appear alongside the seller's payout in their bank account as a description of the deposit.

Default "UNSET"
Enum"UNSET""MID_AND_DATE""MID_AND_MERCHANT_NAME"
settlement_queue_modestring

If settlement_queue_mode is set to MANUAL, Finix will automatically place all transactions (Sales, Fees, Refunds, and ACH Returns) into a settlement queue that you can manage. Each transaction will have a Settlement Queue Entry.

When a Settlement Queue Entry is created, it will not be placed into Settlement until the Settlement Queue Entry is explicitly released.

Note: We require the release of all settlement queue entries within 30 days of creation.

Enum"UNSET""MANUAL"
surcharges_enabledboolean

Set to true if you want to enable a Merchant to accept surcharge fees. For more details, see Buyer Charges.

Default false
tagsobject or null(tags)

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

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500. (For example, order_number: 25, item_type: produce, department: sales)
verificationstring

ID of the Verification that was submitted to verify the Merchant.

_linksobject

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.

Response
application/json
{
  "id": "MUeTBamsYxqr1KSnT4U2x9SP",
  "created_at": "2024-08-16T13:11:36.72Z",
  "updated_at": "2024-08-16T13:11:36.72Z",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "card_cvv_required": false,
  "card_expiration_date_required": true,
  "card_network_details": null,
  "convenience_charges_enabled": false,
  "country": "USA",
  "creating_transfer_from_report_enabled": true,
  "currencies": [
    "USD"
  ],
  "default_partial_authorization_enabled": false,
  "disbursements_ach_pull_enabled": false,
  "disbursements_ach_push_enabled": false,
  "disbursements_card_pull_enabled": false,
  "disbursements_card_push_enabled": false,
  "disbursements_same_day_ach_pull_enabled": false,
  "disbursements_same_day_ach_push_enabled": false,
  "fee_ready_to_settle_upon": "RECONCILIATION",
  "gateway": null,
  "gross_settlement_enabled": false,
  "identity": "ID6ZC4KedcaCwECQcWr7SM4m",
  "instant_payouts_card_push_enabled": false,
  "level_two_level_three_data_enabled": false,
  "loan_repayment": null,
  "mcc": "4900",
  "merchant_name": "Finix Flowers",
  "merchant_profile": "MP8aC84QAtA69Qhv6BJSyvHr",
  "mid": null,
  "onboarding_state": "PROVISIONING",
  "processing_enabled": false,
  "processor": "DUMMY_V1",
  "processor_details": {},
  "ready_to_settle_upon": "RECONCILIATION",
  "ready_to_settle_upon_delay_alignment": "NONE",
  "rent_surcharges_enabled": false,
  "settlement_enabled": false,
  "settlement_funding_identifier": "UNSET",
  "surcharges_enabled": false,
  "tags": {
    "key_2": "value_2"
  },
  "verification": "VI7jopNSiaVMXWKkhxt6dJm7",
  "_links": {
    "self": { … },
    "identity": { … },
    "verifications": { … },
    "merchant_profile": { … },
    "application": { … },
    "verification": { … }
  }
}

Onboarding Forms

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

Related Guides: Onboarding, Onboarding Forms.

Operations

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.

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: Using Hosted Fields, Getting Started

Operations

Settlements

A Settlement is a logical construct representing a collection (i.e. batch) of Settlement Entries that will get paid out to a specific Merchant. A Settlement Entry can represent Transfers or Split Transfers

Related Guides: Payouts

Operations

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.

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 using a PUT Update Settlement Queue Entries request.

Related Guides: Account Structures and Settlements

Operations

Split Transfers

Transfers can be split among several different Merchants. A split_transfer represents how the funds from a split Transfer were distributed into a Merchants Settlement.

Related Guides: Online Payments Quickstart, Split a Transaction

Operations

Transfers

Operations

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

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

Operations

Webhooks

Webhooks lets you build or set up integrations which subscribe to certain automated notifications (i.e. events) on the Finix API. When one of those events is triggered, a HTTP POST payload is sent to the webhook's configured URL.

Related Guides: Webhooks

Operations

Checkout Forms

Checkout Forms are a low-code solution that enables you to create a customizable payment page where buyers can easily enter their payment details and submit a payment on both desktop and mobile devices.

With Checkout Forms, you can quickly create checkout pages and accept payments from buyers with minimal development work.

Related Guides: Checkout Pages

Operations

Payment Links

Payment Links create individual links you can send to buyers to complete a transaction. You can share these links on different platforms such as web pages, email, text, or QR codes.

Related Guides: Payment Links

Operations

Payout Links

A Payout Link is a unique, one-time link you can send via email or text to a recipient for fast and secure payouts. For card-based payouts, funds are typically available within minutes.

Payout Links can be used for various purposes, including insurance payments, sales commissions, and more. Each link can be customized to display your brand name and logo, providing a seamless experience for recipients.

Related Guides: Payout Links

Operations

Receipts

Operations

Subscriptions

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

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

Limitations:
- Supported countries: At this time, subscriptions are available in the United States.
- Supported payment methods: Subscriptions currently support recurring card payments and recurring bank account payments (ACH in the USA).
- Approved merchants: At this time, only approved merchants with one of the following processors can create subscriptions: DUMMY_V1 and FINIX_V1.

Related Guides: Creating Subscriptions, Creating Subscription Plans, Recurring Payments Guidelines

Operations

Subscription Plans

Operations

Transfer Attempts

A transfer_attempt is created when a buyer attempts to pay for a payment using a Payment Link or Checkout Form. 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.

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

Operations

Balances

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:

  • available_amount for immediate use or disbursement.
  • pending_amount due to processing times, holds, or other constraints.
  • posted_amount, which reflects the total sum (including both available and pending funds).
Operations

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

Application Profiles

The application_profile resource is used to configure the Application's Fee Profile. The Application's Fee Profile configures what Fee gets applied to transactions processed by the application_profile.

Related Guides: Onboarding Process, Collecting Fees

Operations

Applications

The Application resource represents your app. For example, an iOS app, website, online marketplace, SaaS platform, etc. – any web service that connects buyers (i.e. customers) and sellers (i.e. merchants). In other words, an Application is a resource that represents the program you're integrating with Finix and using to connect with customers (i.e. buyers).

Related Guides: Getting Started

Operations

Balance Transfers

Our Balance Transfers API provides platforms the option to create a money movement between their FBO (For the Benefit Of) Settlement account and their operating account. This is only available for Finix Core customers with Litle V12 credentials.

If you have any questions, please reach out to your Finix point of contact or contact the Finix Support team.

Operations

Merchant Profiles

A merchant_profile links a merchant to it's risk_profile and fee_profile. Each merchant has a merchant_profile.

When a merchant gets created, a merchant_profile also gets created. This new merchant_profile automatically receives a new risk_profile and fee_profile that are copies of the risk and fee profiles on the application_profile.

Related Guides: Collecting Fees

Operations

Payout Profiles

A Payout Profile configures how fees and payouts get calculated and processed.

Related Guides: Configuring Payouts

Operations

Review Queue Items

Funds are released to sub-merchants when a Settlement's corresponding Review Queue Item is marked as ACCEPTED by a user with the appropriate role permissions.

Related Guides: Roles & Permissions

Operations

Verifications

Verifications are used to verify Identities and Payment Instruments.

For Identities, a verification represents an attempt to onboard and underwrite an identity.

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: Onboarding with the API, Push to Card

Operations