Topics

API Endpoints

We provide two distinct base urls for making API requests depending on
whether you would like to utilize the sandbox or live environments. These
two environments are completely separate and share no information, including
API credentials. For testing please use the Sandbox API and when you are ready to
process live transactions use the Live endpoint.

To communicate with the Finix API you’ll need to authenticate your requests
via http basic access authentication with a username and password, which you
can locate in your dashboard. If you do not have a dashboard feel free to test
the API with the credentials below:

Username: USeQYcTy9SmUEwEY57DAipW7

Password: 022b0789-66a0-487a-b60c-5a628ab45c51

Application ID: APwuf1TPsGvw3tBbz9vwnxsM

Your Application is a resource that represents your web app. In other words,
any web service that connects buyers (i.e. customers) and sellers
(i.e. merchants).

Dashboard Overview

Below are videos of some of the common actions that you will be performing when using the dashboard.

Sign Up

If you haven’t signed up yet, please create a user account.

Create Live Account

Once you’ve played with a sandbox account, you’re ready to create a live Application.

Create an Identity for a Merchant

Simply select Identity on the sidebar, click “Create new identity”, and fill out the form with the Merchant's underwriting information.

Create a Bank Account for a Merchant

First, select Merchant on the sidebar, then click the “Payment instruments” tab. Next, click “Add bank account”, and fill out the form with the Merchant's bank account information.

Onboarding a New Merchant

View KYC Identity Verification

You are able to view important KYC information for Merchants by first selecting Merchants, then clicking your desired Merchant. This will take you the summary view of the Merchant you selected. Now just click the Processor tab and scroll down to the Verification container.

Approve Merchant

Want to approve a Merchant? Under review queues in the sidebar, you’ll see Merchants- a list of all pending Merchants under your Application. You have the ability to approve one by one, or approve an entire page.

Enable or Disable Processing Functionality

Enable or disable Merchant's ability to create new Transfers and Authorizations by navigating to Merchants on the sidebar. Then select your desired Merchant and click the Processors tab. Finally, click the edit button and configure a Merchant's processing ability to your liking.

Enable or Disable Settlement Functionality

Disable or disable Merchant's ability to create new Settlementsby navigating to Merchants on the sidebar. Then select your desired Merchant and click the Processors tab. Finally, click the edit button and configure a Merchant's settlement ability to your liking.

Edit Fees & Interchange Plus

Want to edit an Application's fixed fee, basis points, ACH fee, or toggle interchange plus? First, click Application on the sidebar and then click the Processors tab. Once you pick which processor you want to configure, you’ll be presented with a modal allowing you edit fees and interchange plus.

Enable CVV & AVS

Finix offers you the ability to configure Address Verification System (AVS) and CVV rules as part of our fraud risk system, to help you ensure that transactions are being made by only authorized users. How? Simply click Application on the sidebar, then click the Processors tab. Select the desired processor, and then click edit on the Security configuration.

Approve a Settlement

Want to approve a Settlement? Under review queues in the sidebar, you’ll see Settlements- a list of all pending Settlements under your Application. You have the ability to approve one by one, or approve an entire page.

Upload Dispute Evidence

Have evidence for your dispute? Click Disputes, select the desired dispute, then scroll down to the Evidence container, and click Upload File.

Errors

HTTP Code

Meaning

400

Bad Request – You’ve attemped an invalid request

401

Unauthorized – You have used the incorrect API key

402

Upstream Processor Error – Errors caused by 3rd party service

404

Not Found – The specified resource could not be found

422

Unprocessable Entity – The parameters were valid but the request failed. The error is usually some misunderstanding of various steps that have to be executed in order (e.g. attempting to initiate a transfer on behalf of a merchant that has not yet been approved)

500

Internal Server Error – We had a problem with our server. Try again later.

Below are the different error values that the messages attribute will return for Push to Card.

Error Code

Messages

REFER_TO_CARD_ISSUER

Please contact card issuer for more information.

INVALID_MERCHANT

Merchant not permitted for this transaction type

PICK_UP_CARD_NO_FRAUD

Please contact card issuer for more information.

DO_NOT_HONOR

Please contact card issuer for more information.

ERROR

Please attempt transaction again but if it still cannot be processed try again at a later time

PICK_UP_CARD_FRAUD_ACCOUNT

Please contact card issuer for more information.

INVALID_TRANSACTION

Issuing bank does not support this transaction type on this card. Please contact card issuer for more information.

INVALID_AMOUNT_OR_CURRENCY

Transaction violates network amount limit.

INVALID_ACCOUNT_NUMBER

The account number does not exist. Please make sure the account number is correct or contact your issuer.

NO_SUCH_ISSUER

The issuer can not be found. Please check card number to ensure it is valid.

RE_ENTER_TRANSACTION

Please attempt transaction again and contact card issuer if it still cannot be processed.

NO_ACTION_TAKEN

Please contact card issuer for more information.

UNABLE_TO_LOCATE_RECORD

The account number does not exist. Please make sure the account number is correct or contact your issuer.

FILE_TEMPORARILY_NOT_AVAILABLE

Please contact card issuer for more information.

NO_CREDIT_ACCOUNT

Issuer has declined the transaction because the card is not a credit account. Please try another card.

LOST_CARD_PICK_UP_FRAUD_ACCOUNT

Please contact card issuer for more information.

STOLEN_CARD_PICK_UP_FRAUD_ACCOUNT

Please contact card issuer for more information.

NOT_SUFFICIENT_FUNDS

Card issuer has declined the transaction as it does not have sufficient funds.

NO_CHECKING_ACCOUNT

The card is not tied to a checking account and thus cannot be processed. Please try another card.

NO_SAVINGS_ACCOUNT

The card is not tied to a savings account and thus cannot be processed. Please try another card.

EXPIRED_CARD

The expiration date is expired or missing. Please correct and try again.

INCORRECT_PIN

The PIN is invalid or missing. Please try again with the correct PIN.

TRANSACTION_NOT_PERMITTED

Transaction not permitted to cardholder. Please contact card issuer for more information.

Card not supported in this region or country. Please contact card issuer for more information.

TRANSACTION_DOES_NOT_FULFILL_AML_REQUIREMENT

This transaction does not fulfill compliance requirements and cannot be processed.

EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT

Please attempt with another card or contact card issuer for more information.

ALLOWABLE_NUMBER_OF_PIN_ENTRY_TRIES_EXCEEDED

The maximum permitted number of PIN entry attempts has been exceeded. Please use another payment method.

CRYPTOGRAPHIC_ERROR_FOUND_IN_PIN

The supplied PIN is invalid.

NEGATIVE_RESULTS

Invalid security code.

CANNOT_VERIFY_PIN

The PIN is invalid or missing. Please try again with the correct PIN.

ISSUER_INOPERATIVE

Please attempt transaction again and contact card issuer if it still cannot be processed.

FINANCIAL_INSTITUTION_NOT_FOUND

The issuer can not be found. Please check card number to ensure it is valid.

TRANSACTION_NOT_COMPLETED_LAW_VIOLATION

The transaction cannot be completed because it violates a law.

SURCHARGE_AMOUNT_NOT_SUPPORTED

The supplied surcharge amount is not supported by the issuer.

TRANSACTION_AMOUNT_EXCEEDS_PREAUTHORIZED_APPROVAL_AMOUNT

Transaction violates amount limit.

CARD_AUTHENTICATION_FAILED

Please contact card issuer for more information.

STOP_PAYMENT_ORDER

Please contact card issuer for more information.

Idempotency Requests

You’ll notice the authorization and transfer object have a field named idempotency_id which ensures the API request is only performed once. Why is this important? We’ve all experienced a hanging request while on a checkout page and feared that if we refresh or submit the payment again we’ll be charged twice. With Finix, we remove the ambiguity by having the user generate a unique idempotency_id and sending it with the normal payload. If the user attempts a request with the same idempotency_id, the response will raise an exception. Now you can rest assured that when you create an authorization or debit a bank account that the user will be protected from potential network issues by simply passing idempotency_id in body of the request.

Tags

All Finix objects (i.e. Authorization, Application, Identity, Merchant, Payment Instrument, Settlement, Transfer) include a tags attribute that allows the user to include key-value metadata to their object. For example, when creating a Payment Instrument, you may want to include more data about the card. Simply pass a custom key and value, such as “card-type”: “business card”. Or when creating an Authorization, you may want to include specific information about the transaction, such as a unique ID or additional information about the transaction.

Testing for specific responses and errors

Before taking your integration to live, use the information below to test it thoroughly. Please note, once a Payment Instrument has been flagged with AVS or CVC, it will continue to throw the respective error.

Amount

Description

100

Success amount

102

Failed amount

888888

Disputed amount

193

Insufficient funds amount

194

Invalid card number amount

889986

AVS total failure amount

889987

CVC failure amount

Card

Description

4000000000000036

Payment card AVS total failure

4000000000000127

Payment card CVC failure

Below are the different scenarios that we have available for the sandbox environment.

Cards for Testing a Push to Card Payout

Scenario

number

security_code

address.line1

postal_code

region

city

country

address_verification_results

cvv2_result_code

Successful push to card payout (credit card)

4957030420210454

999

801 Metro Center Blv

94404

CA

San Francisco

USA

Y

M

Successful push to card payout (debit card)

4895142232120006

022

900 Metro Center Blv

94404

CA

San Francisco

USA

M

M

Invalid account number

4957040000000001

999

801 Metro Center Blv

94404

CA

San Francisco

USA

I

P

Invalid Zip Code and CVV2 values

4957030420210488

227

900 Metro Center Blv

94402

CA

San Francisco

USA

A

N

Invalid CVV2 value

4957030420210496

664

900 Metro Center Blv

94404

CA

San Francisco

USA

Y

N

Invalid Address, Zip code and CVV2 values

4957030420210504

322

901 Metro Center Blv

94404

CA

San Francisco

USA

Z

N

Cards for Testing a Verification

Scenario

number

fast_funds_indicator

push_funds_block_indicator

card_type_code

card_issuer_country_code

Issuer does Participates in Fast Funds

4815070000000018

D

C

D

840

Issuer does Not Participates in Fast Funds

4855070000000035

N

C

D

840

Issuer does Not Participates in Fast Funds or Push to Card

4895047700003297

N

N

C

840

Guides

Overview

These guides provide a collection of resources for utilizing the Finix
API and its client libraries. We offer a number of client libraries for
interfacing with the API, and you can view example code snippets for each in
the dark area to the right.

Authentication: Learn how to properly
authenticate and interface with the API.

Getting Started: A step-by-step guide demonstrating the basic workflow
of charging a card. This guide will walk you through provisioning merchant
accounts, tokenizing cards, charging those cards, and finally settling (i.e.
payout) those funds out to your merchants.

Let’s start with the first step by creating an Identity resource. Each Identity represents either a person or a business. We use this resource to associate cards and payouts. This structure makes it simple to manage and reconcile payment instruments and payout history. Accounting of funds is done using the Identity so it’s recommended to have an Identity per recipient of funds. Additionally, the Identity resource is optionally used to collect KYC information.

You’ll want to store the ID of the newly created Identity resource for
reference later.

HTTP Request

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

Business-specific Request Arguments

Field

Type

Description

business_name

string, required

Merchant’s full legal business name (If INDIVIDUAL_SOLE_PROPRIETORSHIP, please input first name, Full legal last name and middle initial; max 120 characters)

doing_business_as

string, required

Alternate name of the business. If no other name is used please use the same value for business_name (max 60 characters)

Nine digit Tax Identification Number (TIN), Employer Identification Number (EIN) or if the business_type is INDIVIDUAL_SOLE_PROPRIETORSHIP and a Tax ID is not available, the principal’s Social Security Number (SSN)

url

string, required

Merchant’s publicly available website (max 100 characters)

business_phone

string, required

Customer service phone number where the merchant can be reached (max 10 characters)

incorporation_date

object, required

Date company was founded (See below for a full list of the child attributes)

Now that we’ve created an Identity for our merchant, we’ll need to add a bank
account where funds will be disbursed (i.e. their funding
account).

In the API, bank accounts – as well as credit cards – are represented by the
Payment Instrument resource.

To classify the Payment Instrument as a bank account you’ll need to pass
BANK_ACCOUNT in the type field of your request, and you’ll also want to pass
the ID of the Identity that you created in the last step via the identity
field to properly associate it with your merchant.

Now that we’ve associated a Payment Instrument with our seller’s Identity
we’re ready to provision a Merchant account. This is the last step before you
can begin processing on their behalf. Luckily you’ve already done most of the
heavy lifting. Just make one final POST request, and you’ll be returned a
Merchant resource. Take a second to inspect this newly created resource,
particularly the onboarding_state, which can have 3 potential states that
indicate its ability to process and settle funds:

PROVISIONING: Request is pending (state will typically change after two minutes)

processing_enabled: False

settlement_enabled: False

APPROVED: Merchant has been approved and can begin processing

processing_enabled: True

settlement_enabled: True

REJECTED: Merchant was rejected by the processor either because the information collected was invalid or it failed one of a number of regulatory and/or
compliance checks (e.g. KYC, OFAC or MATCH)

processing_enabled: False

settlement_enabled: False

Provisioning a Merchant account is an asynchronous request. We recommend creating
a Webhook to listen for the state change.

Now that we have successfully provisioned a Merchant we’ll need to create an
Identity that represents your buyer. Don’t worry though you won’t need to capture
the same amount of information from your buyer. So long as you
don’t pass a business_type field all the fields are optional.

Passing a business_type will introduce the underwriting form validators.

Typically, we suggest at least collecting the buyer’s name and email to help
with accounting, reconciliation, and chargebacks.

At this point we’ve created resources representing the merchant, the buyer, and
the buyer’s card.

Next you’ll need to create an Authorization. What’s a Authorization? Glad
you asked! An Authorization (also known as a card hold) reserves a specific
amount on a card to be captured (i.e. debited) at a later point, usually within
7 days. When an Authorization is captured it produces a Transfer resource.

To create an Authorization we’ll supply the buyer’s Payment Instrument ID
as the source field and the seller’s Identity ID in the merchant_identity field.
Note that the amount field is in cents.

Simple enough, right? You’ll also want to store the ID from that Authorization
for your records so that we can capture those funds in the next step.

Authorizations have two possible states SUCCEEDED and FAILED. If the Authorization
has succeeded, it must be captured before the expires_at or the funds will
be released.

Authorizations on debit cards actually place a hold on funds in the cardholder’s
bank account and may lead to lower than expected balances and/or insufficient
funds issues.
If the transfer field of an Authorization is null it has not yet been captured.

HTTP Request

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

Request Arguments

Field

Type

Description

source

string, required

The buyer’s Payment Instrument ID that you will be performing the authorization

merchant_identity

string, required

The ID of the Identity for the merchant that you are transacting on behalf of

Now that we have the funds held on a card, we’ll need to capture them. Failing to
do so will result in the funds being released (i.e. returned) to the buyer.

Note you can capture any amount less than or equal to the amount of the original
Authorization. You will also want to pass a fee. The fee field is the amount
in cents you would like to keep before settling out to the merchant. For example,
if you’re charging the buyer $100 on behalf of your merchant, and you’re taking
a 10% service fee you’ll want to pass 1000 as the fee. This way when the
funds are eventually settled out only $90 will be disbursed to your merchant.

Once successfully captured the transfer field of the Authorization will
contain the ID for the corresponding Transfer resource. By default, Transfers
will be in a PENDING state. PENDING means that the system hasn’t submitted the
capture request as they are submitted via batch request. Once submited
the state of the Transfer will update to SUCCEEDED.

Next we’re going to show you how to settle out the funds to your merchant.

Let’s start with the first step by creating an Identity resource. Each Identity represents either a person or a business. We use this resource to associate cards and payouts. This structure makes it simple to manage and reconcile payment instruments and payout history. Accounting of funds is done using the Identity so it’s recommended to have an Identity per recipient of funds. Additionally, the Identity resource is optionally used to collect KYC information.

Please note that creating cards directly via the API should only be done for
testing purposes. You must use the Tokenization iframe or javascript client
to remain out of PCI scope.

Now that we’ve created an Identity for our recipient, we’ll need to tokenize a payment card where funds will be disbursed.

In the API, payment cards are represented by the Payment Instrument resource.

To classify the Payment Instrument as a payment card you’ll need to pass PAYMENT_CARD in the type field of your request, and you’ll also want to pass the ID of the Identity that you created in the last step via the identity field to properly associate it with your recipient.

HTTP Request

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

Request Arguments

Field

Type

Description

identity

string, required

ID of the Identity that the card should be associated

type

string, required

Type of Payment Instrument (for cards input PAYMENT_CARD)

number

string, required

Primary card account number

security_code

string, optional

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

expiration_month

integer, required

Expiration month (e.g. 12 for December)

expiration_year

integer, required

4-digit expiration year

currency

string, required

Currency that should be associated with card

name

string, optional

Full name of the registered card holder

address

object, optional

Billing address (Full description of child attributes below)

Address-object Request Arguments

Field

Type

Description

line1

string, optional

First line of the address (max 60 characters)

line2

string, optional

Second line of the address (max 60 characters)

city

string, optional

City (max 20 characters)

region

string, optional

2-letter State code

postal_code

string, optional

Zip or Postal code (max 7 characters)

country

string, optional

3-Letter Country code

Step 3: Verify card is eligible to receive push-to-card disbursements

Now that we’ve associated a payment instrument to a recipient, we’ll need to verify whether or not the card is eligible to receive push-to-card disbursements. How? By making a request to the Verifications endpoint. The returned Verification resource returns a set of general attributes and details about the card in question (e.g. card type, issuer information). For example, the inquiry_details object will contain a push_funds_block_indicator attribute that indicates if it is eligible for push-to-card disbursements. Below you’ll see a number of fields and the potential responses.

Now that we’ve associated a Payment Instrument with our recipient’s Identity we’re ready to provision a Recipient account. This is the last step before you can begin paying out an Identity. Luckily you’ve already done most of the heavy lifting. Just make one final POST request, and you’ll be returned a Merchant resource.

Let’s start with the first step by creating an Identity resource. Each Identity represents either a person or a business. We use this resource to associate cards and payouts. This structure makes it simple to manage and reconcile payment instruments and payout history. Accounting of funds is done using the Identity so it’s recommended to have an Identity per recipient of funds. Additionally, the Identity resource is optionally used to collect KYC information.

Please note that creating cards directly via the API should only be done for
testing purposes. You must use the Tokenization iframe or javascript client
to remain out of PCI scope.

Now that we’ve created an Identity for our sender, we’ll need to tokenize a payment card where funds will be pulled from.

In the API, payment cards are represented by the Payment Instrument resource.

To classify the Payment Instrument as a payment card you’ll need to pass PAYMENT_CARD in the type field of your request, and you’ll also want to pass the ID of the Identity that you created in the last step via the identity field to properly associate it with your sender.

Step 3: Verify Address Verification System (AVS) and CVV

Now that we’ve associated a payment instrument to a sender, we have the ability to verify whether or not the card has passed AVS and CVV checks. How? By making a request to the Verifications endpoint. The returned Verification resource returns a set of general attributes and details about the card in question (e.g. card type, issuer information). Below you’ll see a number of fields and the potential responses.

Now that we’ve associated a Payment Instrument with the sender’s Identity we’re ready to provision a Sender account. This is the last step before you can begin pulling from an Identity. Luckily you’ve already done most of the heavy lifting. Just make one final POST request, and you’ll be returned a Merchant resource.

Next you’ll need to create a Transfer. What’s a Transfer? Glad you asked! A Transfer represents any flow of funds either to or from a Payment Instrument. In this case we are pulling from a card.

To create a Transfer we’ll simply supply the Payment Instrument ID of the previously tokenized card as the source field. In addition, you’ll pass the an operational key which describes the action that you’re taking.

You’ll also want to store the ID from that Transfer for your records. Transfers can have two possible states SUCCEEDED and FAILED.

HTTP Request

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

Request Arguments

Field

Type

Description

source

string, required

ID of the Payment Instrument where funds will be pulled from

amount

integer, required

The total amount that will be charged in cents (e.g. 100 cents to charge $1.00)

A Transfer representing the refund (i.e. reversal) of a previously created
Transfer (type DEBIT). The refunded amount may be any value up to the amount
of the original Transfer. These specific Transfers are distinguished by
their type which return REVERSAL.

HTTP Request

URL Parameters

Request Arguments

Field

Type

Description

refund_amount

integer, required

The amount of the refund in cents (Must be equal to or less than the amount of the original Transfer)

Tokenization with Hosted Fields

Library summary

The PaymentForm library is a javascript library that allows you secure your sensitive credit and debit card data. By having the end-user input their data into an iFrame, it prevents third-parties from accessing the information.

Once the fields are initialized the library communicates the state of the fields
through a JavaScript callback. The state object includes information about the
validity, focused value and if the user has entered information in the field.

For a complete example of how to use the library please refer to this
jsFiddle example.

Step 1: Include library and desired HTML elements

First we’ll need to include the library on the webpage where you’re hosting your
form. Please include the script as demonstrated to the right.

Step 2: Initialize the payment form

window.PaymentForm.card(function(state, binInformation)-> PaymentForm

constpaymentForm=window.PaymentForm.card(function(state,binInformation){// Logic for interacting with form's potential states (see jsFiddle for example)});

The next step is to configure the library. This “card” method is the single entry point into the library. It initializes and returns a PaymentForm object that contains fields(i.e. name, number, expiration date, & CVV).

Finally we will need to register a click event that fires when our users submit
the form and define a callback for handling the response.

Next, configure the library to your specific Application where all of the form
fields will be submitted during the executed POST request. We’ll also want to
register a click event that fires when our users submit the form and define a
callback for handling the response.

Once you’ve handled the response you will want to store that ID to utilize
the token in the future. To do this you will need to send the ID from your
front-end client to your back-end server.

Before you can use the newly tokenized card or bank account you will need to
associate it with an Identity. To do this you must make an authenticated
POST request to the /payment_instruments endpoint with the relevant token
and Identity information.

Tokens should be associated right away. Tokens not associated within 30 mins
of creation will be invalidated.

HTTP Request

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

Request Arguments

Field

Type

Description

token

string, required

ID for the Token that was returned via the tokenization client

type

string, required

Must pass TOKEN as the value

identity

string, required

ID for the Identity resource which the account is to be associated

Mobile Tokenization

Our mobile SDKs for tokenization make it simple to accept payments inside any iOS or Android app. With these two libraries, we take on the responsibility of PCI compliance by removing the need to send sensitive payment card data to your servers. Simply use the tools to tokenize payment cards and we’ll store the payment card number in our secure vault. Next, we’ll return a token that you can use to associate to an Application. Once associated with an Application you can use it to process payments.

Card Present Integration

The card present integration allows you to gateway card present transactions. With a quick and easy setup process, you’ll be able to use point of sale devices to accept in-person payments. The card present integration also gives you the ability to unify in-person and online transactions on a single platform. To learn more about the card present integration and to be given access please contact bd@finixpayments.com.

URL Parameters

Request Arguments

Please select one of the following values which will let Finix know the type of device being used: MX915

name

string, required

Name of device

tags

object, optional

Key value pair for annotating custom meta data (e.g. order numbers)

description

string, optional

Additional information about device (e.g. self serving terminal)

Configuration Arguments

allow_debit | boolean, optional | Sets whether device will allow debit by default or not (defaults to true)
prompt_signature | string, optional | Sets whether device will prompt the card holder for a signature by default or not, AMOUNT is used in conjuction with signature_threshold_amount so that when the threshold is reached the signature form appears on device screen (defaults to always). Options are: ALWAYS, NEVER, AMOUNT
check_for_duplicate_transactions | boolean, optional | Sets whether the device will check for duplicate transactions
prompt_amount_confirmation | boolean, optional | Sets whether or not to make card holder confirm the amount they will pay (defaults is true)
signature_threshold_amount | integer, optional | Threshold set for when to prompt a signature if configuration#prompt_signature is set to AMOUNT (defaults to 0)
prompt_manual_entry | boolean, optional | Sets whether or not the default card input method will be keyed in manual entry or not (defaults to false)

Configuration Arguments

allow_debit | boolean, optional | Sets whether device will allow debit by default or not (defaults to true)
prompt_signature | string, optional | Sets whether device will prompt the card holder for a signature by default or not, AMOUNT is used in conjuction with signature_threshold_amount so that when the threshold is reached the signature form appears on device screen (defaults to always). Options are: ALWAYS, NEVER, AMOUNT
check_for_duplicate_transactions | boolean, optional | Sets whether the device will check for duplicate transactions
signature_threshold_amount | integer, optional | Threshold set for when to prompt a signature if device_configuration#prompt_signature is set to AMOUNT (defaults to 0)
prompt_manual_entry | boolean, optional | Sets whether or not the default card input method will be keyed in manual entry or not (defaults to false)

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 7 days.
When an Authorization is captured it produces a Transfer resource.

Authorizations have two possible states SUCCEEDED and FAILED. If the Authorization
has succeeded, it must be captured before the expires_at or the funds will
be released.

Learn how to prevent duplicate authorizations by passing an idempotency ID in the payload.

Authorizations on debit cards actually place a hold on funds in the cardholder’s
bank account and may lead to lower than expected balances and/or insufficient
funds issues.
If the transfer field of an Authorization is null it has not yet been captured.

HTTP Request

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

Request Arguments

Field

Type

Description

source

string, required

The Payment Instrument that you will be performing the authorization

merchant_identity

string, required

The ID of the Identity for the merchant that you are transacting on behalf of

Once successfully captured the transfer field of the Authorization will
contain the ID for the corresponding Transfer resource. By default, Transfers
will be in a PENDING state. PENDING means that the system hasn’t submitted the
capture request as they are submitted via batch request. Once submited
the state of the Transfer will update to SUCCEEDED.

Sets whether device will allow debit by default or not (defaults to true)

device_configuration#prompt_signature

string, optional

Sets whether device will prompt the card holder for a signature by default or not, AMOUNT is used in conjuction with device_configuration#signature_threshold_amount so that when the threshold is reached the signature form appears on device screen (defaults to always). Options are: ALWAYS, NEVER, AMOUNT

device_configuration#check_for_duplicate_transactions

boolean, optional

Sets whether the device will check for duplicate transactions

device_configuration#signature_threshold_amount

integer, optional

Threshold set for when to prompt a signature if device_configuration#prompt_signature is set to AMOUNT (defaults to 0)

device_configuration#prompt_manual_entry

boolean, optional

Sets whether or not the default card input method will be keyed in manual entry or not (defaults to false)

Sets whether device will prompt the card holder for a signature by default or not, AMOUNT is used in conjuction with device_configuration#signature_threshold_amount so that when the threshold is reached the signature form appears on device screen (defaults to always). Options are: ALWAYS, NEVER, AMOUNT

device_configuration#signature_threshold_amount

integer, optional

Threshold set for when to prompt a signature if device_configuration#prompt_signature is set to AMOUNT (defaults to 0)

device_configuration#prompt_manual_entry

boolean, optional

Sets whether or not the default card input method will be keyed in manual entry or not (defaults to false)

URL Parameters

Request Arguments

Please select one of the following values which will let Finix know the type of device being used: MX915

name

string, required

Name of device

tags

object, optional

Key value pair for annotating custom meta data (e.g. order numbers)

description

string, optional

Additional information about device (e.g. self serving terminal)

Configuration Arguments

allow_debit | boolean, optional | Sets whether device will allow debit by default or not (defaults to true)
prompt_signature | string, optional | Sets whether device will prompt the card holder for a signature by default or not, AMOUNT is used in conjuction with signature_threshold_amount so that when the threshold is reached the signature form appears on device screen (defaults to always). Options are: ALWAYS, NEVER, AMOUNT
check_for_duplicate_transactions | boolean, optional | Sets whether the device will check for duplicate transactions
prompt_amount_confirmation | boolean, optional | Sets whether or not to make card holder confirm the amount they will pay (defaults is true)
signature_threshold_amount | integer, optional | Threshold set for when to prompt a signature prompt_signature is set to AMOUNT (defaults to 0)
prompt_manual_entry | boolean, optional | Sets whether or not the default card input method will be keyed in manual entry or not (defaults to false)

Identities

An Identity resource represents either a buyer or a merchant and is in a many ways the
centerpiece of the payment API’s architecture. Transfers and Payment Instruments must
be associated with an Identity. For both buyers and merchants this structure makes it easy
to manage and reconcile their associated banks accounts, transaction history, and payouts.

Nine digit Tax Identification Number (TIN), Employer Identification Number (EIN) or if the business_type is INDIVIDUAL_SOLE_PROPRIETORSHIP and a Tax ID is not available, the principal’s Social Security Number (SSN)

url

string, required

Merchant’s publicly available website (max 100 characters)

business_phone

string, required

Customer service phone number where the merchant can be reached (max 10 characters)

incorporation_date

object, required

Date company was founded (See below for a full list of the child attributes)

tax_id and business_tax_id are not updatable. If either field was input incorrectly,
please create a new Identity resource.

Update the information of a previously created Identity. Please note that in
the case of merchant accounts this API request alone does not update this
information on the underlying processor. To update the merchant’s information
on the underlying processor you must update the merchant on the
processor.

HTTP Request

PUT https://finix.sandbox-payments-api.com/identities/:IDENTITY_ID

Business-specific Request Arguments

Field

Type

Description

business_name

string, required

Merchant’s full legal business name (If INDIVIDUAL_SOLE_PROPRIETORSHIP, please input first name, Full legal last name and middle initial; max 120 characters)

doing_business_as

string, required

Alternate name of the business. If no other name is used please use the same value for business_name (max 60 characters)

Nine digit Tax Identification Number (TIN), Employer Identification Number (EIN) or if the business_type is INDIVIDUAL_SOLE_PROPRIETORSHIP and a Tax ID is not available, the principal’s Social Security Number (SSN)

url

string, required

Merchant’s publicly available website (max 100 characters)

business_phone

string, required

Customer service phone number where the merchant can be reached (max 10 characters)

incorporation_date

object, required

Date company was founded (See below for a full list of the child attributes)

Provision a Merchant for a previously created Identity resource to begin
transacting on their behalf.

Please make sure that a bank account has been created and associated to the
previously created Identity before attempting to provision a Merchant account.

Merchant resources can have 3 potential states:

PROVISIONING: Request is pending (state will typically change after two minutes)

APPROVED: Merchant has been approved and can begin processing

REJECTED: Merchant was rejected by the processor either because the underwriting information collected was invalid or it failed one a number of regulatory and compliance checks (e.g. KYC, OFAC or MATCH)

Provisioning a `Merchant` account is an asynchronous request. We recommend creating a Webhook to listen for the state change.

Retrieve all attempts to onboard (i.e. provision) a merchant onto a processor.

HTTP Request

GET https://finix.sandbox-payments-api.com/merchants/:MERCHANT_ID/verifications

URL Parameters

Parameter

Description

:MERCHANT_ID

ID of the Merchant

Payment Instruments

A Payment Instrument resource represents either a credit card or bank account.
A Payment Instrument may be tokenized multiple times and each tokenization produces
a unique ID. Each ID may only be associated one time and to only one Identity.
Once associated, a Payment Instrument may not be disassociated from an
Identity.