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.

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

Request Format

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

Environments

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

A Sandbox environment for developing and testing your integration.
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 of this, requests to the Finix API have a maximum timeout of 5 minutes.

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

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

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

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

Servers

Sandbox server

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

Production server

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

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.

Related Guides: Auth and Captures, Level 2 and 3 Processing, POS Integration, Buyer Charges

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

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

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

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

Related Guides: File Uploads, Update Requests

Operations

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.

Related Guides: Getting Started, Onboarding Sellers, Push to Card

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

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

Create a Payment Instrument

Request

Create a Payment Instrument resource using a card or bank account.

The creation of Payment Instruments directly via Finix's API should only be done for testing purposes. You must use our hosted fields or the javascript client to remain out of PCI scope.

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

Any of:

addressobject

The address of the card owner.

Note: Including a postal or zip code when creating a Payment Instrument can lower the interchange on credit card transactions.

expiration_monthintegerrequired

The expiration month of the card (e.g. 12 for December).

expiration_yearintegerrequired

The 4-digit expiration year of the card.

identitystringrequired

The ID of the Identity used to create the Payment Instrument resource.

namestringrequired

The name of the bank account or card owner. This value can get truncated to comply with processor requirements.

numberstringrequired

The card or bank account number (no dashes in between numbers).

security_codestringrequired

The 3-4 digit security code of the card (i.e. CVV code).

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)

typestringrequired

Type of Payment Instrument.

Value"PAYMENT_CARD"

third_party_tokenstring

Stringified token provided by Apple or Google. Required if using Apple or Google Pay.

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/payment_instruments \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "address": {
      "city": "San Francisco",
      "country": "USA",
      "line1": "900 Metro Center Blv",
      "postal_code": "94404",
      "region": "CA"
    },
    "expiration_month": 12,
    "expiration_year": 2029,
    "identity": "IDmj1yA97RS4rMjiQgvK3Vio",
    "name": "John Smith",
    "number": "5200828282828210",
    "security_code": "022",
    "type": "PAYMENT_CARD"
  }'

Responses

Single Payment Instrument 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

Any of:

idstring

The ID of the Payment Instrument.

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.

account_updater_enabledboolean(EnableAccountUpdaterCardLevel)

When enabled at the Payment Instrument-level, Finix automatically checks for updates with card networks. This Account Updater functionality:

Automatically updates card details (e.g., number or expiration date) to maintain continuity of charges, increasing authorization rates.
Saves the cardholder the hassle of updating card details across Merchants for each of their Subscriptions.

If set at the Application level, this Payment Instrument-level setting will override the Application-level configuration. If not configured at the Application-level, the card defaults to false, requiring explicit opt-in.

Note: Cards created before the feature is enabled are unaffected by default. To include these cards, you can manually enable the Account Updater functionality for each card individually using a PUT request. Once enabled, you can link the card to this API call to trigger updates with card networks.

Default false

addressobject or null(Address)

Address of the account owner.

address_verificationstring

Details the results of verifying address with the issuing bank.
Set to UNKNOWN when address gets updated.

Enum"POSTAL_CODE_AND_STREET_MATCH""STREET_MATCH""POSTAL_CODE_MATCH""NO_ADDRESS""NO_MATCH""NOT_SUPPORTED""UNKNOWN"

applicationstring

The ID of the Application resource the Payment Instrument was created under.

binstring

Bank Identification number for the Payment Instrument.

brandstring

The brand of the card saved in the Payment Instrument.

Enum"UNKNOWN""DINERS_CLUB_INTERNATIONAL""DANKORT""MIR""TROY""UATP""CHINA_T_UNION""CHINA_UNION_PAY""AMERICAN_EXPRESS""VERVE"

card_namestring or null

A custom name you can include to identify the card being used (e.g. Business Card).

card_typestring

The type of payment card saved in the Payment Instrument.

Enum"CREDIT""DEBIT""HSA_FSA""NON_RELOADABLE_PREPAID""RELOADABLE_PREPAID""UNKNOWN"

currencystring(Currency)

ISO 4217 3 letter currency code.

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

enabledboolean

Details if the Payment Instrument resource is enabled. Default value is true; set to false to disable the Payment Instrument.

expiration_monthinteger[ 1 .. 12 ]

Expiration month (e.g. 12 for December).

expiration_yearinteger>= 1

4-digit expiration year.

fast_funds_indicatorstring

Details if Fast Funds is enabled for the card.

fingerprintstring

Unique ID that represents the tokenized card data.

Example: "FPRxxxxxxxxxxxxxxxxx"

identitystring

The ID of the Identity used to create the Payment Instrument resource.

instrument_typestring

The type of Payment Instrument.

Value"PAYMENT_CARD"

issuer_countrystring(IssuerCountry)

The Alpha-3 Code of the country the card was issued in.

In addition, the following values are possible:

NON_USA - The card was issued outside of the United States.
UNKNOWN - The processor did not return an issuer country for this particular BIN.

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

last_fourstring

Last four digits of the card or bank account number.

namestring or null

The name of the bank account or card owner.

network_token_enabledboolean(EnableNetworkTokensCardLevel)

When enabled at the Payment Instrument level, a "network token" replaces raw card details (e.g., the 16-digit PAN and expiration date) for transactions. Network tokens have several benefits:

The token offers increased authorization rates, even for lost or stolen cards, as it remains valid while the physical card is replaced.
Visa reduces interchange fees when using network tokens.
Tokens enhance security by replacing card details with a non-sensitive string that is usable only within the Finix system.

If set at the Application level, this Payment Instrument level setting will override the application level configuration. If not configured at the application level, the card defaults to false, requiring explicit opt-in.

Note: Cards created before the feature is enabled are unaffected. To include them, update an individual Payment Instrument. Then, you can insert the hyperlink on the "update".

Default false

network_token_statestring

The state of the network token. The possible enum values are as follows:

NOT_ENABLED: The network_token_state is NOT_ENABLED when the value of network_token_enabled on the Payment Instrument is false.
PENDING: Immediately after Finix enables network tokens for a specific card, network_token_state is initially set to PENDING.
ACTIVE: After Finix receives the network token successfully from the card network, network_token_state updates to ACTIVE.
FAILED: In the event that there is an issue with the card network such as service becomes unavailable, FAILED is returned.
SUSPENDED: When the issuing bank does not allow the network token to be used in transactions, SUSPENDED is returned.
CLOSED: In the event that the issuing bank has closed the card permanently, CLOSED is returned.

Enum"ACTIVE""CLOSED""FAILED""NOT_ENABLED""SUSPENDED""PENDING"

online_gambling_block_indicatorstring

Details if the card is enabled to receive push-payments for online gambling payouts.

payload_typestring

Enum"SOURCE""DESTINATION"

push_funds_block_indicatorstring

Details if the card is enabled to receive push-to-card disbursements.

security_code_verificationstring

Details the results of the Card Verification Code check.

Enum"MATCHED""UNKNOWN""UNMATCHED"

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)

third-partystring or null

This field is not applicable to payment cards.

third_party_tokenstring or null

This field is not applicanle to payment cards.

typestring

Type of Payment Instrument.

Value"PAYMENT_CARD"

_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": "PI6F5kkcCB3dtGhFy1t8Aua5",
  "created_at": "2024-11-15T09:42:33.42Z",
  "updated_at": "2024-11-15T09:42:33.42Z",
  "account_updater_enabled": false,
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "created_via": "API",
  "currency": "USD",
  "disabled_code": null,
  "disabled_message": null,
  "enabled": true,
  "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY",
  "identity": "IDgWxBhfGYLLdkhxx2ddYf9K",
  "instrument_type": "PAYMENT_CARD",
  "address": {
    "line1": "900 Metro Center Blv",
    "line2": null,
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94404",
    "country": "USA"
  },
  "address_verification": "UNKNOWN",
  "bin": "520082",
  "brand": "MASTERCARD",
  "card_type": "DEBIT",
  "expiration_month": 12,
  "expiration_year": 2029,
  "issuer_country": "NON_USA",
  "last_four": "8210",
  "name": "John Smith",
  "network_token_enabled": false,
  "network_token_state": "NOT_ENABLED",
  "security_code_verification": "UNKNOWN",
  "tags": {},
  "third_party": null,
  "third_party_token": null,
  "type": "PAYMENT_CARD",
  "_links": {
    "self": { … },
    "authorizations": { … },
    "transfers": { … },
    "verifications": { … },
    "application": { … },
    "identity": { … },
    "updates": { … }
  }
}

List Payment Instruments

Request

Retrieve a list of Payment Instruments.

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

Query

account_last4string

Filter by the last 4 digits of the account if available.

Example: account_last4=4242

account_routing_numberstring

Filter by the account routing number if available.

Example: account_routing_number=9444

after_cursorstring

Return every resource created after the cursor value.

Example: after_cursor=TRnasXQ5AmjsLnPMwnme7TL4

applicationstring

Filter by Application ID.

Example: application=APgPDQrLD52TYvqazjHJJchM

before_cursorstring

Return every resource created before the cursor value.

Example: before_cursor=TRnasXQ5AmjsLnPMwnme7TL4

binstring

Filter by Bank Identification Number (BIN). The BIN is the first 6 digits of the masked number.

Example: bin=411111

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

expiration_monthstring

Filter by the expiration month associated with the Payment Instrument if applicable. This filter only applies to payment cards.

Example: expiration_month=9

expiration_yearstring

Filter by the 4 digit expiration year associated with the Payment Instrument if applicable. This filter only applies to payment cards.

Example: expiration_year=2029

last4string

Filter by the last 4 digits of the Payment Instrument card. This filter only applies to payment cards.

Example: last4=0454

limitinteger

The numbers of items to return.

Example: limit=10

namestring

Filter by the name.

Example: name=john%%20smith

owner_identity_idstring

Filter by the owner id of the associated Identity.

Example: owner_identity_id=IDcWwprrKrD6cSh225JWPri3

typestring

Filter by the Payment Instrument type.

Enum"ALL""BANK_ACCOUNT""PAYMENT_CARD"

Example: type=BANK_ACCOUNT

tags.keystring

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

Example: tags.key=card_type

tags.valuestring

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

Example: tags.value=business_card

Headers

Acceptstring

Body Header

Default application/hal+json

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

Responses

List of Payment Instrument 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 Payment Instrument 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": {
    "payment_instruments": [ … ]
  },
  "_links": {
    "self": { … },
    "next": { … },
    "last": { … }
  },
  "page": {
    "offset": 0,
    "limit": 20,
    "count": 14679
  }
}

Fetch a Payment Instrument

Request

Retrieve the details of a Payment Instrument.

Path

payment_instrument_idstringrequired

ID of object

Example: PI4Ppf8rxWYapuEqQr3u6efi

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

Responses

Response schema and example when fetching a Payment Instrument.

Bodyapplication/json

Any of:

idstring

The ID of the Payment Instrument.

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.

account_updater_enabledboolean(EnableAccountUpdaterCardLevel)

When enabled at the Payment Instrument-level, Finix automatically checks for updates with card networks. This Account Updater functionality:

Automatically updates card details (e.g., number or expiration date) to maintain continuity of charges, increasing authorization rates.
Saves the cardholder the hassle of updating card details across Merchants for each of their Subscriptions.

Default false

addressobject or null(Address)

Address of the account owner.

address_verificationstring

Details the results of verifying address with the issuing bank.
Set to UNKNOWN when address gets updated.

Enum"POSTAL_CODE_AND_STREET_MATCH""STREET_MATCH""POSTAL_CODE_MATCH""NO_ADDRESS""NO_MATCH""NOT_SUPPORTED""UNKNOWN"

applicationstring

The ID of the Application resource the Payment Instrument was created under.

binstring

Bank Identification number for the Payment Instrument.

brandstring

The brand of the card saved in the Payment Instrument.

Enum"UNKNOWN""DINERS_CLUB_INTERNATIONAL""DANKORT""MIR""TROY""UATP""CHINA_T_UNION""CHINA_UNION_PAY""AMERICAN_EXPRESS""VERVE"

card_namestring or null

A custom name you can include to identify the card being used (e.g. Business Card).

card_typestring

The type of payment card saved in the Payment Instrument.

Enum"CREDIT""DEBIT""HSA_FSA""NON_RELOADABLE_PREPAID""RELOADABLE_PREPAID""UNKNOWN"

currencystring(Currency)

ISO 4217 3 letter currency code.

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

enabledboolean

Details if the Payment Instrument resource is enabled. Default value is true; set to false to disable the Payment Instrument.

expiration_monthinteger[ 1 .. 12 ]

Expiration month (e.g. 12 for December).

expiration_yearinteger>= 1

4-digit expiration year.

fast_funds_indicatorstring

Details if Fast Funds is enabled for the card.

fingerprintstring

Unique ID that represents the tokenized card data.

Example: "FPRxxxxxxxxxxxxxxxxx"

identitystring

The ID of the Identity used to create the Payment Instrument resource.

instrument_typestring

The type of Payment Instrument.

Value"PAYMENT_CARD"

issuer_countrystring(IssuerCountry)

The Alpha-3 Code of the country the card was issued in.

In addition, the following values are possible:

NON_USA - The card was issued outside of the United States.
UNKNOWN - The processor did not return an issuer country for this particular BIN.

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

last_fourstring

Last four digits of the card or bank account number.

namestring or null

The name of the bank account or card owner.

network_token_enabledboolean(EnableNetworkTokensCardLevel)

When enabled at the Payment Instrument level, a "network token" replaces raw card details (e.g., the 16-digit PAN and expiration date) for transactions. Network tokens have several benefits:

The token offers increased authorization rates, even for lost or stolen cards, as it remains valid while the physical card is replaced.
Visa reduces interchange fees when using network tokens.
Tokens enhance security by replacing card details with a non-sensitive string that is usable only within the Finix system.

Note: Cards created before the feature is enabled are unaffected. To include them, update an individual Payment Instrument. Then, you can insert the hyperlink on the "update".

Default false

network_token_statestring

The state of the network token. The possible enum values are as follows:

NOT_ENABLED: The network_token_state is NOT_ENABLED when the value of network_token_enabled on the Payment Instrument is false.
PENDING: Immediately after Finix enables network tokens for a specific card, network_token_state is initially set to PENDING.
ACTIVE: After Finix receives the network token successfully from the card network, network_token_state updates to ACTIVE.
FAILED: In the event that there is an issue with the card network such as service becomes unavailable, FAILED is returned.
SUSPENDED: When the issuing bank does not allow the network token to be used in transactions, SUSPENDED is returned.
CLOSED: In the event that the issuing bank has closed the card permanently, CLOSED is returned.

Enum"ACTIVE""CLOSED""FAILED""NOT_ENABLED""SUSPENDED""PENDING"

online_gambling_block_indicatorstring

Details if the card is enabled to receive push-payments for online gambling payouts.

payload_typestring

Enum"SOURCE""DESTINATION"

push_funds_block_indicatorstring

Details if the card is enabled to receive push-to-card disbursements.

security_code_verificationstring

Details the results of the Card Verification Code check.

Enum"MATCHED""UNKNOWN""UNMATCHED"

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)

third-partystring or null

This field is not applicable to payment cards.

third_party_tokenstring or null

This field is not applicanle to payment cards.

typestring

Type of Payment Instrument.

Value"PAYMENT_CARD"

_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": "PI8uU6wfi6hqBoWmzm9L4F2b",
  "created_at": "2022-10-11T01:42:22.32Z",
  "updated_at": "2022-10-11T01:42:22.32Z",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "created_via": "API",
  "currency": "USD",
  "disabled_code": null,
  "disabled_message": null,
  "enabled": true,
  "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY",
  "identity": "IDgWxBhfGYLLdkhxx2ddYf9K",
  "instrument_type": "PAYMENT_CARD",
  "address": {
    "line1": "900 Metro Center Blv",
    "line2": null,
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94404",
    "country": "USA"
  },
  "address_verification": "UNKNOWN",
  "bin": "520082",
  "brand": "MASTERCARD",
  "card_type": "DEBIT",
  "expiration_month": 12,
  "expiration_year": 2029,
  "issuer_country": "NON_USA",
  "last_four": "8210",
  "name": "John Smith",
  "security_code_verification": "UNKNOWN",
  "tags": {
    "card_name": "Business Card"
  },
  "type": "PAYMENT_CARD",
  "_links": {
    "self": { … },
    "authorizations": { … },
    "transfers": { … },
    "verifications": { … },
    "application": { … },
    "identity": { … },
    "updates": { … }
  }
}

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

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

Related Guides: Online Payments Quickstart, Level 2 and 3 Processing, POS Integration, Buyer Charges, ACH (eCheck) Direct Debit

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

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

Related Guides: Receipts for Online Payments

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

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

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

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

Finix API

Authentication

Environments

HTTP Codes and Errors

Idempotent Requests

Query Parameters

Tags

Versioning

Authorizations

Compliance Forms

Devices

Disputes

Fees

Fee Profiles

Files

Identities

Instrument Updates

Merchants

Onboarding Forms

Payment Instruments

Create a Payment Instrument

Request

Responses

Was this helpful?

List Payment Instruments

Request

Responses

Was this helpful?

Fetch a Payment Instrument

Request

Responses

Was this helpful?

Settlements

Settlement Queue Entries

Split Transfers

Transfers

Users

Webhooks

Checkout Forms

Payment Links

Payout Links

Receipts

Subscriptions

Subscription Plans

Transfer Attempts

Balances

Balance Adjustments

Application Profiles

Applications

Balance Transfers

Merchant Profiles

Payout Profiles

Review Queue Items

Verifications