docs
NAV
cURL

Topics

API Endpoints

Finix provides two distinct base URLs to make API requests, which are dependent on your needs. Each environment is completely separate and does not share information including API credentials.

For testing purposes, we recommend using the Sandbox API. Sandbox API: https://finix.sandbox-payments-api.com

For processing live transactions, we recommend using the Live API.

Authentication

# With CURL, just supply your username as basic auth (-u) in the header of each request as follows:

curl https://finix.sandbox-payments-api.com/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88

To communicate with the Finix API, you 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, you can test our APIs with the credentials below:

An Application is a resource that represents your web app, such as a web service that connects buyers (i.e. customers) and sellers (i.e. merchants).

Dashboard Overview

This section details common actions that a user can perform using the Dashboard.

Create an Identity for a Merchant

  1. Navigate to the PEOPLE header on the left navigation. Click on Applications.
  2. Select the Application. Click the IDENTITIES tab on the top navigation bar.
  3. Click the Create New Identity button. Complete the merchant underwriting form. Click the Submit button to submit the form.

Create a Bank Account for a Merchant

  1. Navigate to the PEOPLE header on the left navigation. Click on Merchants.
  2. Select the Merchant. This opens the merchant information screen.
  3. At the top of the Dashboard, click the ID breadcrumb link. This displays the Identities screen.
  4. Click the PAYMENT INSTRUMENTS tab on the top navigation bar. Click the Add Bank Account button. A pop-up modal appears. Add the bank information. Click the Submit button.

Onboard a New Merchant

  1. Navigate to the PEOPLE header on the left navigation. Click on Merchants.
  2. Select the Merchant.
  3. Click the Create Verification button. A pop-up modal appears. This screen confirms the merchant verification request. To confirm, click the Create button. To close and exit out of the modal, click the X at the top right of the modal.

View KYC Identity Verification

  1. Navigate to the PEOPLE header on the left navigation. Click on Merchants.
  2. Select the Merchant. This opens the merchant information screen. The KYC information is displayed in the Verifications container.

Approve and Reject a Merchant

  1. Navigate to the REVIEW header on the left navigation. Click on Merchants. This displays all the pending Merchants under your Application.
  2. Select the Merchant(s) by checking the box inline with the merchant name. You can select multiple Merchants.
  3. Click the Bulk Actions drop-down at the bottom of the page. On the drop-down you can approve or reject the selected Merchant(s).

Enable or Disable Payments Processing

  1. Navigate to the PEOPLE header on the left navigation. Click on Identities.
  2. Select the Identity. Click the PROCESSORS tab on the top navigation bar.
  3. Click the Merchant ID. Click the Edit button at the top right of the Dashboard.
  4. A pop-up modal appears. You can update merchant settings here. Toggle the Processing Enabled button. Click the Save button to save your changes. A success message appears to confirm your changes. To reenable payments, toggle the button and save the changes again.

Enable or Disable Settlement Functionality

  1. Navigate to the PEOPLE header on the left navigation. Click on Identites.
  2. Select the Identity. Click the PROCESSORS tab on the top navigation bar.
  3. Click the Merchant ID. Click the Edit button at the top right of the Dashboard.
  4. A pop-up modal appears. You can update merchant settings here. Toggle the Settlements Enabled button. Click the Save button to save your changes. A success message appears to confirm your changes. To reenable payments, toggle the button and save the changes again.

Update Fee Profile

  1. Navigate to the PEOPLE header. Click on Applications.
  2. Select the Application. Click the FEE AND RISK PROFILE tab on the top navigation bar.
  3. Click the Create Fee Profile button. Update your fee profile settings. Click Create Profile button to save your changes.

Update Risk Profile

  1. Navigate to the PEOPLE header. Click on Applications.
  2. Select the Application. Click the FEE AND RISK PROFILE tab on the top navigation bar.
  3. Scroll down to the Risk Profile container, click the Edit button. Toggle your selections. Click the Submit button to save your changes.

Approve a Settlement

  1. Navigate to the REVIEW header. Click on Settlements. This displays all the pending Settlements.
  2. Select the Settlement(s) by checking the box inline with the Settlement ID.
  3. Click the Bulk Actions drop-down at the bottom of the page. On the drop-down, select Approve to approve a Settlement(s).

Upload Dispute Evidence

  1. Navigate to the TRANSACTIONS header. Click on Disputes. This displays all Disputes.
  2. Select the Dispute. This opens the Dispute information screen. Scroll down to the Evidence container and click the Upload evidence file link and upload your evidence. Click the Upload button to save your Dispute evidence.

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.
SUSPECTED_FRAUD Please contact card issuer for more information.
EXCEEDS_APPROVAL_AMOUNT_LIMIT Transaction violates issuer amount limit. Please contact card issuer for more information or try with another card.
RESTRICTED_CARD 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.

Filters

Filters allow users to search for specific information using terms and values. Multiple filters can be applied to a search.

The tables below include examples of search filters. The examples include mock data.

Transfers and Authorizations Filters

Field Description Example
Amount = Filter Transactions that are equal to the amount in cents amount=100.00
Amount > Filter Transactions that have an amount greater than the given amount in cents gt=100.00
Amount >= Filter Transactions that have an amount greater than or equal to the given amount in cents gte=100.00
Amount < Filter Transactions that have an amount less than the given amount in cents lt=100.00
Amount <= Filter Transactions that have an amount less than or equal to the given amount in cents lte=100.00
Application ID Filter by Application ID application_id=AP6LPbgrQ2xeeadyAWN4Pp4e
Authorization ID Filter by Authorization ID id=AUtTjMjwh62oDxwEDi5o6Ktv
Bank Account Last 4 Filter Transactions by the last 4 digits of the bank account. The bank account last 4 are the last 4 digits of the masked number instrument_account_last4=9444
BIN Filter by Bank Identification Number (BIN). The BIN is the first 6 digits of the masked number instrument_bin=444444
Card Brand Filter by card brand. Available card brand types can be found in the drop-down instrument_brand_type=DISCOVER
Created At = Filter Transactions that are equal to the date and time given. Time to be entered in UTC format created_at.created_at.gte=2019-06-15&created_at.lte=2019-06-15
Created At >= Filter Transactions that are greater than or equal to the date and time given. Time to be entered in UTC format created_at.gte=2019-06-15
Created At <= Filter Transactions that are less than or equal to the date and time given. Time to be entered in UTC format created_at.lte=2019-06-15
Identity ID Filter by Identity ID merchant_identity_id=IDpcdriNfwBZwB5EMG52nMQV
Identity Name Filter Transactions by Identity name. The name is not case-sensitive merchant_identity_name=Finix
Instrument Name Filter Transactions by payment instrument name instrument_name=visa
Instrument Type Filter Transactions by payment instrument type. Available instrument types include: Bank Account or Payment Card instrument_type=PAYMENT_CARD
Merchant ID Filter by Merchant ID merchant_id=MU4zxKcvWB15paBe5SdYiFta
Merchant Ident String Filter by Merchant Identification Number (MID) merchant_mid=4445036913770
Payment Card Last 4 Filter by the payment card last 4 digits instrument_card_last4=9444
Processor ID Filter by Processor ID merchant_processor_id=PRfsrJgRawB64a6zz293Vmpy
State Filter by Transaction state. Available state filters include: All, Succeeded, Failed, Pending, or Canceled state=SUCCEEDED
Trace ID Filter Transactions by Trace ID trace_id=5a3f3db8-79c5-4202-9938-00fee9d7546a
Transfer ID Filter by Transfer ID id=TR9fk2U2ivhfeQM9sJgxZYnH
Type Filter by Transfer type. Available type filters include: All, Debits, Refunds, or Credits. Transfer values include: DEBIT, REVERSAL, CREDIT, or SETTLEMENT type=REVERSAL

Settlement Filters

Field Description Example
Amount = Filter Settlements that are equal to the amount in cents amount=100.00
Amount > Filter Settlements that have an amount greater than the given amount in cents gt=100.00
Amount >= Filter Settlements that have an amount greater than or equal to the given amount in cents gte=100.00
Amount < Filter Settlements that have an amount less than the given amount in cents lt=100.00
Amount <= Filter Settlements that have an amount less than or equal to the given amount in cents lte=100.00
Created At = Filter Settlements that are equal to the date and time given. Time to be entered in UTC format created_at.created_at.gte=2019-06-15&created_at.lte=2019-06-15
Created At >= Filter Settlements that are greater than or equal to the date and time given. Time to be entered in UTC format created_at.gte=2019-06-15
Created At <= Filter Settlements that are less than or equal to the date and time given. Time to be entered in UTC format created_at.lte=2019-06-15

Disputes and Merchants Filters

Field Description Example
Created At = Filter Disputes and Merchants that are equal to the date and time given. Time to be entered in UTC format created_at.gte=2019-06-15&created_at.lte=2019-06-15
Created At >= Filter Disputes and Merchants that are greater than or equal to the date and time given. Time to be entered in UTC format created_at.gte=2019-06-15
Created At <= Filter Disputes and Merchants that are less than or equal to the date and time given. Time to be entered in UTC format created_at.lte=2019-06-15
Dispute ID Filter by Dispute ID id=DIbYnUak9YkucZCFCNzUESX2
Merchant ID Filter by Merchant ID id=MU4zxKcvWB15paBe5SdYiFta

Identities Filters

Field Description Example
Business Name Filter Identities by full business name. An incomplete business name does not work business_name=ACME%20Anchors
Business Type Filter Identities by business type. An incomplete business type does not work business_type=LIMITED_LIABILITY_COMPANY
Created At = Filter Identities that are equal to the date and time given. Time to be entered in UTC format created_at.gte=2019-06-15&created_at.lte=2019-06-15
Created At >= Filter Identities that are greater than or equal to the date and time given. Time to be entered in UTC format created_at.gte=2019-06-15
Created At <= Filter Identities that are less than or equal to the date and time given. Time to be entered in UTC format created_at.lte=2019-06-15
Doing Business As Filter Identities by doing business as (DBA) name. An incomplete DBA name does not work doing_business_as=MTTM
Email Filter Identities by full email address or the email domain. An incomplete email address does not work email=user%40example.org
First Name Filter Identities by the first name of the person associated with the Identity first_name=Daphne
Identity ID Filter by Identity ID id=IDpcdriNfwBZwB5EMG52nMQV
Last Name Filter Identities by the last name of the person associated with the Identity last_name=kline
Title Filter Identities by title if available title=ceo

Applications Filters

Field Description Example
Application ID Filter by Application ID id=APiTHvXGuHvhVUYJtrBTjuD7

Payment Instruments Filters

Field Description Example
Account Last Four Filter Payment Instruments by the last 4 digits of the account if available account_last4=9444
Account Routing Number Filter Payment Instruments by the account routing number if available account_routing_number=9444
Application ID Filter by Application ID id=APiTHvXGuHvhVUYJtrBTjuD7
BIN Filter by Bank Identification Number (BIN). The BIN is the first 6 digits of the masked number bin=489514
Created At = Filter Payment Instruments that are equal to the date and time given. Time to be entered in UTC format created_at.gte=2019-06-15&created_at.lte=2019-06-15
Created At >= Filter Payment Instruments that are greater than or equal to the date and time given. Time to be entered in UTC format created_at.gte=2019-06-15
Created At <= Filter Payment Instruments that are less than or equal to the date and time given. Time to be entered in UTC format created_at.lte=2019-06-15
Expiration Month Filter Payment Instruments by the expiration month associated with the Payment Instruments if applicable. This filter only applies to payment cards expiration_month=1
Expiration Year Filter Payment Instruments by the 4 digit expiration year associated with the Payment Instruments if applicable. This filter only applies to payment cards expiration_year=2022
Last Four Filter Payment Instruments by the last 4 digits of the Payment Instrument card. This filter only applies to payment cards last_four=0454
Name Filter Payment Instruments by name. An incomplete entry does not work name=fran%20lemke
Owner Identity ID Filter Payment Instruments by owner identity ID owner_identity_id=IDcWwprrKrD6cSh225JWPri3
Payment Instrument ID Filter Payment Instruments by the Payment Instrument ID id=PInYuD7LM5Xdautqnm3yAN5f
Type Filter by Payment Instrument type. Available type filters include: All, Bank Account, or Payment Card type=BANK_ACCOUNT

Reports Filters

Field Description Example
End Date Filter reports that are equal to the end date given end_date=2019-06-15
Start Date Filter reports that are equal to the start date given start_date=2019-06-15

Review Queue Settlements Filters

Field Description Example
Created At = Filter Review Queue Setttlements that are equal to the date and time given. Time to be entered in UTC format created_at.gte=2019-06-15&created_at.erlte=2019-06-15
Created At >= Filter Review Queue Setttlements that are greater than or equal to the date and time given. Time to be entered in UTC format created_at.gte=2019-06-15
Created At <= Filter Review Queue Setttlements that are less than or equal to the date and time given. Time to be entered in UTC format created_at.lte=2019-06-15
Processor Filter Review Queue Setttlements by Processor type. Available processors include: LITLE_v1, VANTIV_V1, VISA_V1, or MICROBILT_V1 processor_type=VANTIV_V1

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.

Level 2 and Level 3 Processing

Credit card processing fits into three levels: Level 1, Level 2 and Level 3. Each level is defined by the amount of information that is required to complete a transaction.

For Level 2 and Level 3, only business to business merchants and the government can receive lower interchange fees. In addition, either corporate, business, or a purchase card is required to receive the lower interchange rate for Level 2 and Level 3. This feature is only supported on Visa and Mastercard branded cards. Because only business to business and government transactions qualify, you must first enable a Merchant for Level 2/3 processing.

Tags

All Finix resources (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 resource. A resource’s tags object, can have an unlimited number of tags. The information in the tags can also be updated as many times as needed.

For example, if creating a Payment Instrument, you can include additional data about the card by passing a custom key and value such, as “card-type”: “business card”.

Testing for specific responses and errors

Payment Facilitation Testing

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

Push-to-Card Testing

Cards for Testing a Push-to-Card Payout

Scenario number region country code
Successful push to a Visa (debit card) 4895142232120006 CA USA N/A
Successful push to a Visa (credit card) 4957030420210454 CA USA N/A
Successful push to a Mastercard (debit card) 5123280115058611 CA USA N/A
Invalid account number 4957030420210504 CA USA INVALID_INSTRUMENT
Exceeds approval amount limit 4957030420210488 CA USA EXCEEDS_ISSUER_AMOUNT_LIMIT
Exceeds withdrawal frequency limit 4957030420210496 CA USA EXCEEDS_ISSUER_COUNT_LIMIT
Refer to card issuer 4895070000007685 CA USA CALL_ISSUER
Do not honor 4895070000006687 CA USA DECLINE
Lost card, pick up (fraud account) 4895070000005671 CA USA LOST_OR_STOLEN_CARD
Suspected fraud 4895070000004674 CA USA SUSPECTED_FRAUD
Transaction does not fulfill AML requirement 4895070000003551 CA USA COMPLIANCE_VIOLATION

Cards for Testing a Verification

Scenario number fast_funds_indicator push_funds_block_indicator card_type_code card_issuer_country_code
Issuer does participate in fast funds for only domestic transactions 4815070000000018 D C D 840
Issuer does participate in fast funds for all transactions 4835070000000014 B C D 840
Issuer does not participate in fast funds 4855070000000035 N C D 840
Issuer does participate in fast funds and Push-to-Card 4895047700003297 B B C 840

Guides

Overview

We offer a number of guides that provide a collection of resources for utilizing the Finix API.

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

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

  3. Tokenization with Hosted Fields: This guide explains how to properly tokenize cards in live via hosted fields.

  4. Subscription Billing: Guide to create, apply, and repeat payments for subscription-based services.

  5. Managing Subscriptions: Guide to manage subscriptions.

  6. Push to Card: This guide walks through using the Visa Direct API to push payments to payment cards. With push-to-card funds are disbursed to a debit card within 30 minutes or less.

  7. Pull from Card: This guide walks through using the Visa Direct API to pull payments from payment cards.

  8. Mobile Tokenization: Mobile Tokenization: This guide explains how to tokenize cards via our mobile SDKs.

Getting Started

Step 1: Create an Identity for a Merchant

curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -d '
    {
        "additional_underwriting_data": {
            "merchant_agreement_accepted": true, 
            "merchant_agreement_ip_address": "42.1.1.113", 
            "volume_distribution_by_business_type": {
                "other_volume_percentage": 0, 
                "consumer_to_consumer_volume_percentage": 0, 
                "business_to_consumer_volume_percentage": 0, 
                "business_to_business_volume_percentage": 100, 
                "person_to_person_volume_percentage": 0
            }, 
            "average_ach_transfer_amount": 200000, 
            "annual_ach_volume": 200000, 
            "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)", 
            "refund_policy": "MERCHANDISE_EXCHANGE_ONLY", 
            "credit_check_timestamp": "2021-04-28T16:42:55Z", 
            "credit_check_allowed": true, 
            "merchant_agreement_timestamp": "2021-04-28T16:42:55Z", 
            "business_description": "SB3 vegan cafe", 
            "average_card_transfer_amount": 200000, 
            "credit_check_ip_address": "42.1.1.113", 
            "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)", 
            "card_volume_distribution": {
                "card_present_percentage": 30, 
                "mail_order_telephone_order_percentage": 10, 
                "ecommerce_percentage": 60
            }
        }, 
        "tags": {
            "Studio Rating": "4.7"
        }, 
        "entity": {
            "last_name": "Sunkhronos", 
            "max_transaction_amount": 12000000, 
            "has_accepted_credit_cards_previously": true, 
            "default_statement_descriptor": "Bobs Burgers", 
            "personal_address": {
                "city": "San Mateo", 
                "country": "USA", 
                "region": "CA", 
                "line2": "Apartment 7", 
                "line1": "741 Douglass St", 
                "postal_code": "94114"
            }, 
            "incorporation_date": {
                "year": 1978, 
                "day": 27, 
                "month": 6
            }, 
            "business_address": {
                "city": "San Mateo", 
                "country": "USA", 
                "region": "CA", 
                "line2": "Apartment 8", 
                "line1": "741 Douglass St", 
                "postal_code": "94114"
            }, 
            "ownership_type": "PRIVATE", 
            "first_name": "dwayne", 
            "title": "CEO", 
            "business_tax_id": "123456789", 
            "doing_business_as": "Bobs Burgers", 
            "principal_percentage_ownership": 50, 
            "email": "user@example.org", 
            "mcc": "0742", 
            "phone": "1234567890", 
            "business_name": "Bobs Burgers", 
            "tax_id": "123456789", 
            "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP", 
            "business_phone": "+1 (408) 756-4497", 
            "dob": {
                "year": 1978, 
                "day": 27, 
                "month": 6
            }, 
            "url": "www.BobsBurgers.com", 
            "annual_card_volume": 12000000
        }
    }'

Example Response:

{
  "id" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "entity" : {
    "title" : "CEO",
    "first_name" : "dwayne",
    "last_name" : "Sunkhronos",
    "email" : "user@example.org",
    "business_name" : "Bobs Burgers",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "Bobs Burgers",
    "phone" : "1234567890",
    "business_phone" : "+1 (408) 756-4497",
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 8",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "mcc" : "0742",
    "dob" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "max_transaction_amount" : 12000000,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : "www.BobsBurgers.com",
    "annual_card_volume" : 12000000,
    "has_accepted_credit_cards_previously" : true,
    "incorporation_date" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "principal_percentage_ownership" : 50,
    "short_business_name" : null,
    "ownership_type" : "PRIVATE",
    "tax_authority" : null,
    "tax_id_provided" : true,
    "business_tax_id_provided" : true,
    "default_statement_descriptor" : "Bobs Burgers"
  },
  "tags" : {
    "Studio Rating" : "4.7"
  },
  "created_at" : "2021-11-22T23:50:55.56Z",
  "updated_at" : "2021-11-22T23:50:55.56Z",
  "additional_underwriting_data" : {
    "annual_ach_volume" : 200000,
    "average_ach_transfer_amount" : 200000,
    "average_card_transfer_amount" : 200000,
    "business_description" : "SB3 vegan cafe",
    "card_volume_distribution" : {
      "card_present_percentage" : 30,
      "ecommerce_percentage" : 60,
      "mail_order_telephone_order_percentage" : 10
    },
    "credit_check_allowed" : true,
    "credit_check_ip_address" : "42.1.1.113",
    "credit_check_timestamp" : "2021-04-28T16:42:55Z",
    "credit_check_user_agent" : "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)",
    "merchant_agreement_accepted" : true,
    "merchant_agreement_ip_address" : "42.1.1.113",
    "merchant_agreement_timestamp" : "2021-04-28T16:42:55Z",
    "merchant_agreement_user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)",
    "refund_policy" : "MERCHANDISE_EXCHANGE_ONLY",
    "volume_distribution_by_business_type" : {
      "business_to_business_volume_percentage" : 100,
      "business_to_consumer_volume_percentage" : 0,
      "consumer_to_consumer_volume_percentage" : 0,
      "other_volume_percentage" : 0,
      "person_to_person_volume_percentage" : 0
    }
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    }
  }
}

Before we can begin charging cards we’ll need to provision a Merchant account for your seller. This requires 3-steps, which we’ll go into greater detail in the next few sections:

  1. First, create an Identity resource with the merchant’s underwriting and identity verification information

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

  2. Second, create a Payment Instrument representing the merchant’s bank account where processed funds will be settled (i.e. deposited)

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

  3. Finally, provision the Merchant account

    POST https://finix.sandbox-payments-api.com/identities/:IDENTITY_ID/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)
business_type string, required Please select one of the following values: INDIVIDUAL_SOLE_PROPRIETORSHIP, CORPORATION, LIMITED_LIABILITY_COMPANY, PARTNERSHIP, ASSOCIATION_ESTATE_TRUST, TAX_EXEMPT_ORGANIZATION, INTERNATIONAL_ORGANIZATION, GOVERNMENT_AGENCY
business_tax_id string, required 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)
business_address object, required Primary address for the legal entity (Full description of child attributes below)
ownership_type string, required Values can be either PUBLIC to indicate a publicly traded company or PRIVATE for privately held businesses
amex_mid integer, optional Assigned amexMid value. If provided must be 10 or 11 digits
discover_mid integer, optional Assigned discoverMid value

Principal-specific Request Arguments

(i.e. authorized representative or primary contact responsible for the account)

Field Type Description
first_name string, required Full legal first name of the merchant’s principal representative (max 20 characters)
last_name string, required Full legal last name of the merchant’s principal representative (max 20 characters)
title string, required Principal’s corporate title or role (i.e. Chief Executive Officer, CFO, etc.; max 60 characters)
principal_percentage_ownership integer, required Percentage of company owned by the principal (min 0; max 100)
tax_id string, required Nine digit Social Security Number (SSN) for the principal
dob object, required Principal’s date of birth (Full description of child attributes below)
phone string, required Principal’s phone number (max 10 characters)
email string, required Principal’s email address where they can be reached (max 100 characters)
personal_address object, required Principal’s personal home address. This field is used for identity verification purposes (Full description of child attributes below)

Processing-specific Request Arguments

Field Type Description
default_statement_descriptor string, required Billing descriptor displayed on the buyer’s bank or card statement (Length must be between 1 and 20 characters)
annual_card_volume integer, required Approximate annual credit card sales expected to be processed in cents by this merchant (max 23 characters)
max_transaction_amount integer, required Maximum amount that can be transacted for a single transaction in cents (max 12 characters)
mcc string, required Merchant Category Code (MCC) that this merchant will be classified under
has_accepted_credit_cards_previously boolean, optional Defaults to false if not passed

Address-object Request Arguments

Field Type Description
line1 string, required First line of the address (max 35 characters)
line2 string, optional Second line of the address (max 35 characters)
city string, required City (max 20 characters)
region string, required 2-letter State code
postal_code string, required Zip or Postal code (max 7 characters)
country string, required 3-Letter Country code

Incorporation Date-object Request Arguments

Field Type Description
day integer, required Day business was incorporated (between 1 and 31)
month integer, required Month business was incorporated (between 1 and 12)
year integer, required Year business was incorporated (4-digit)

DOB-object Request Arguments

Field Type Description
day integer, required Day of birth (between 1 and 31)
month integer, required Month of birth (between 1 and 12)
year integer, required Year of birth (4-digit)

Additional Underwriting Request Arguments

Field Type Description
annual _ach_volume integer, required Approximate annual ACH sales expected to be processed in cents by this merchant
average_ach_transfer_amount integer, required Approximate average ACH sale amount in cents for this merchant
average_card_transfer_amount integer, required Approximate average credit card sale amount in cents for this merchant
business_description string, required Description of this merchant’s business (max 200 characters)
card_volume_distribution object, required Merchant’s distribution of credit card volume (See below for a full list of the child attributes). Sum of card_volume_distribution must be 100.
credit_check_allowed boolean, required Sets whether this merchant has consented and accepted to a credit check
credit_check_ip_address string, required IP address of the merchant when this merchant consented to a credit check (e.g., 42.1.1.113 )
credit_check_timestamp string, required Timestamp of the merchant when this merchant consented to a credit check (e.g., 2021-04-28T16:42:55Z)
credit_check_user_agent string, required The user agent of the browser when this merchant consented to a credit check (e.g., Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6))
merchant_agreeement_accepted boolean, required Sets whether this merchant has accepted the terms and conditions of the merchant agreement
merchant_agreement_ip_address string, required IP address of the merchant when this merchant accepted the merchant agreement (e.g., 42.1.1.113 )
merchant_agreement_timestamp string, required Timestamp of the merchant when this merchant consented to a credit check (e.g., 2021-04-28T16:42:55Z)
merchant_agreement_user_agent string, required The user agent of the browser when this merchant accepted the merchant agreement (e.g., Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6))
refund_policy string, required Please select one of the following values: NO_REFUNDS, MERCHANDISE_EXCHANGE_ONLY, WITHIN_30_DAYS, OTHER
volume_distribution_by_business_type object, required Merchant’s distribution of credit card volume by business type (See below for a full list of the child attributes). Sum of volume_distribution_by_business_type must be 100.

Card Volume Distribution-object Request Arguments

Field Type Description
card_present_percentage integer, required Merchant’s percentage of business that is card present (between 0 and 100)
ecommerce_present_percentage integer, required Merchant’s percentage of business that is ecommerce (between 0 and 100)
mail_order_telephone_order_percentage integer, required Merchant’s percentage of business that is mail order or telephone order (between 0 and 100)

Volume Distribution by Business Type-object Request Arguments

Field Type Description
business_to_business_volume_percentage integer, required Merchant’s percentage of volume that is business to business (between 0 and 100)
business_to_consumer_volume_percentage integer, required Merchant’s percentage of volume that is business to consumer (between 0 and 100)
consumer_to_consumer_volume_percentage integer, required Merchant’s percentage of volume that is consumer to consumer (between 0 and 100)
person_to_person_volume_percentage integer, required Merchant’s percentage of volume that is person to person (between 0 and 100)
other_volume_percentage integer, required Merchant’s percentage of volume that is not represented by the previous fields (between 0 and 100)

Step 1.5: Add Additional Benefical Owners for a Merchant

curl https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/associated_identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -d '
    {
        "entity": {
            "first_name": "John", 
            "last_name": "Smith", 
            "title": "Founder", 
            "dob": {
                "month": 1, 
                "day": 1, 
                "year": 2013
            }, 
            "principal_percentage_ownership": 25, 
            "phone": "1234567890", 
            "personal_address": {
                "city": "San Francisco", 
                "region": "CA", 
                "postal_code": "90650", 
                "line1": "123 Main Street", 
                "country": "USA"
            }, 
            "email": "john.smith@company1.com", 
            "tax_id": "123456789"
        }
    }'

Example Response:

{
  "id" : "IDeCJ9SYhwMgwtHpAG7eo6sk",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "entity" : {
    "title" : "Founder",
    "first_name" : "John",
    "last_name" : "Smith",
    "email" : "john.smith@company1.com",
    "business_name" : null,
    "business_type" : null,
    "doing_business_as" : null,
    "phone" : "1234567890",
    "business_phone" : null,
    "personal_address" : {
      "line1" : "123 Main Street",
      "line2" : null,
      "city" : "San Francisco",
      "region" : "CA",
      "postal_code" : "90650",
      "country" : "USA"
    },
    "business_address" : null,
    "mcc" : null,
    "dob" : {
      "day" : 1,
      "month" : 1,
      "year" : 2013
    },
    "max_transaction_amount" : 0,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : null,
    "annual_card_volume" : 0,
    "has_accepted_credit_cards_previously" : false,
    "incorporation_date" : null,
    "principal_percentage_ownership" : 25,
    "short_business_name" : null,
    "ownership_type" : null,
    "tax_authority" : null,
    "tax_id_provided" : true,
    "business_tax_id_provided" : false,
    "default_statement_descriptor" : null
  },
  "tags" : { },
  "created_at" : "2021-11-22T23:51:05.59Z",
  "updated_at" : "2021-11-22T23:51:05.62Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    }
  }
}

If you have beneficial owners with greater than 25% ownership, each beneficial owners must be addded along with the primary prinicipal in step 1. This is a requirement from our financial partners and regulators.

HTTP Request

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

Principal-specific Request Arguments

(i.e. authorized representative or primary contact responsible for the account)

Field Type Description
dob object, required Principal’s date of birth (Full description of child attributes below)
email string, required Principal’s email address where they can be reached (max 100 characters)
first_name string, required Full legal first name of the merchant’s principal representative (max 20 characters)
last_name string, required Full legal last name of the merchant’s principal representative (max 20 characters)
personal_address object, required Principal’s personal home address. This field is used for Identity verification purposes (Full description of child attributes below)
phone string, required Principal’s phone number (max 10 characters)
principal_percentage_ownership integer, required Percentage of company owned by the principal (min 0; max 100)
tax_id string, required Nine digit Social Security Number (SSN) for the principal
title string, required Principal’s corporate title or role (i.e. Chief Executive Officer, CFO, etc.; max 60 characters)

Address-object Request Arguments

Field Type Description
city string, required City (max 20 characters)
country string, required 3-Letter Country code
line1 string, required First line of the address (max 35 characters)
line2 string, optional Second line of the address (max 35 characters)
postal_code string, required Zip or Postal code (max 7 characters)
region string, required 2-letter State code

DOB-object Request Arguments

Field Type Description
day integer, required Day of birth (between 1 and 31)
month integer, required Month of birth (between 1 and 12)
year integer, required Year of birth (4-digit)

Step 2: Tokenize a Bank Account for Funding your Merchant

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -d '
    {
        "account_type": "SAVINGS", 
        "name": "Alice", 
        "tags": {
            "Bank Account": "Company Account"
        }, 
        "country": "USA", 
        "bank_code": "123123123", 
        "account_number": "123123123", 
        "type": "BANK_ACCOUNT", 
        "identity": "IDnKHJ7wtcJDhK9RgSqFiYgr"
    }'

Example Response:

{
  "id" : "PI69e1uVuBM1sFijQUjCsdYA",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
  "tags" : {
    "Bank Account" : "Company Account"
  },
  "bank_code" : "123123123",
  "country" : "USA",
  "masked_account_number" : "XXXXX3123",
  "name" : "Alice",
  "account_type" : "SAVINGS",
  "created_at" : "2021-11-22T23:51:01.14Z",
  "updated_at" : "2021-11-22T23:51:01.14Z",
  "instrument_type" : "BANK_ACCOUNT",
  "type" : "BANK_ACCOUNT",
  "currency" : "USD",
  "identity" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI69e1uVuBM1sFijQUjCsdYA"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI69e1uVuBM1sFijQUjCsdYA/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI69e1uVuBM1sFijQUjCsdYA/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI69e1uVuBM1sFijQUjCsdYA/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
    }
  }
}

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.

HTTP Request

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

Request Arguments

Field Type Description
account_number string, required Bank account number
bank_code string, required Bank routing number
type string, required Type of Payment Instrument (for bank accounts use BANK_ACCOUNT)
identity string, required ID for the Identity resource which the account is associated
account_type string, required Either CHECKING or SAVINGS
name string, required Account owner’s full name (max 40 characters)

Step 3: Provision Merchant Account

curl https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -d '
    {
        "processor": null, 
        "tags": {
            "key_2": "value_2"
        }
    }'

Example Response:

{
  "id" : "MUwkMjGKSoqkjwg2s6Qe9GPx",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "identity" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
  "verification" : "VIiwqTD6WgoVE56heaL8DfvB",
  "merchant_profile" : "MPsZcjGQrrkMeV3bg1JrWbdt",
  "processor" : "DUMMY_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "card_expiration_date_required" : true,
  "card_cvv_required" : false,
  "tags" : {
    "key_2" : "value_2"
  },
  "mcc" : "0742",
  "mid" : "FNXiyZ8cZGmt2DJ6c21Ve4eT",
  "merchant_name" : "Bobs Burgers",
  "settlement_funding_identifier" : "UNSET",
  "ready_to_settle_upon" : null,
  "fee_ready_to_settle_upon" : "RECONCILIATION",
  "level_two_level_three_data_enabled" : false,
  "created_at" : "2021-11-22T23:51:01.91Z",
  "updated_at" : "2021-11-22T23:51:02.12Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : {
    "mid" : "FNXiyZ8cZGmt2DJ6c21Ve4eT",
    "api_key" : "secretValue"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUwkMjGKSoqkjwg2s6Qe9GPx"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUwkMjGKSoqkjwg2s6Qe9GPx/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPsZcjGQrrkMeV3bg1JrWbdt"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIiwqTD6WgoVE56heaL8DfvB"
    }
  }
}

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:

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

    • processing_enabled: False
    • settlement_enabled: False

  2. APPROVED: Merchant has been approved and can begin processing

    • processing_enabled: True
    • settlement_enabled: True

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

HTTP Request

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

URL Parameters

Parameter Description
:IDENTITY_ID ID of the Identity

Request Arguments

Field Type Description
processor string, required Name of the processor that you’re onboarding the Merchant with (a user can pass either null or DUMMY_V1 for sandbox)

Step 4: Create an Identity for a Buyer


curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -d '
    {
        "tags": {
            "key": "value"
        }, 
        "entity": {
            "phone": "7145677613", 
            "first_name": "Marcie", 
            "last_name": "Wade", 
            "email": "therock@gmail.com", 
            "personal_address": {
                "city": "San Mateo", 
                "country": "USA", 
                "region": "CA", 
                "line2": "Apartment 7", 
                "line1": "741 Douglass St", 
                "postal_code": "94114"
            }
        }
    }'

Example Response:

{
  "id" : "IDmULj61C8ke6Y7qQiKENJ7",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "entity" : {
    "title" : null,
    "first_name" : "Marcie",
    "last_name" : "Wade",
    "email" : "therock@gmail.com",
    "business_name" : null,
    "business_type" : null,
    "doing_business_as" : null,
    "phone" : "7145677613",
    "business_phone" : null,
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : null,
    "mcc" : null,
    "dob" : null,
    "max_transaction_amount" : 0,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : null,
    "annual_card_volume" : 0,
    "has_accepted_credit_cards_previously" : false,
    "incorporation_date" : null,
    "principal_percentage_ownership" : null,
    "short_business_name" : null,
    "ownership_type" : null,
    "tax_authority" : null,
    "tax_id_provided" : false,
    "business_tax_id_provided" : false,
    "default_statement_descriptor" : null
  },
  "tags" : {
    "key" : "value"
  },
  "created_at" : "2021-11-22T23:51:03.58Z",
  "updated_at" : "2021-11-22T23:51:03.58Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    }
  }
}

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.

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

HTTP Request

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

Request Arguments

Field Type Description
first_name string, optional First name
last_name string, optional Last name
email string, optional Email
phone string, optional Phone number
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)
personal_address object, optional Customers shipping address or billing address (Full description of child attributes below)

Address-object Request Arguments

Field Type Description
line1 string, required First line of the address (max 35 characters)
line2 string, optional Second line of the address (max 35 characters)
city string, required City (max 20 characters)
region string, required 2-letter State code
postal_code string, required Zip or Postal code (max 7 characters)
country string, required 3-Letter Country code

Step 5: Tokenize a Card



curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -d '
    {
        "name": "Walter Lopez", 
        "expiration_year": 2029, 
        "tags": {
            "card_name": "Business Card"
        }, 
        "number": "4895142232120006", 
        "expiration_month": 12, 
        "address": {
            "city": "San Francisco", 
            "region": "CA", 
            "postal_code": "94404", 
            "line1": "900 Metro Center Blv", 
            "country": "USA"
        }, 
        "security_code": "022", 
        "type": "PAYMENT_CARD", 
        "identity": "IDmULj61C8ke6Y7qQiKENJ7"
    }'

Example Response:

{
  "id" : "PIatE9xdPZTKdeeuyeLcB2Kj",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 12,
  "expiration_year" : 2029,
  "bin" : "489514",
  "last_four" : "0006",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Walter Lopez",
  "address" : {
    "line1" : "900 Metro Center Blv",
    "line2" : null,
    "city" : "San Francisco",
    "region" : "CA",
    "postal_code" : "94404",
    "country" : "USA"
  },
  "address_verification" : "UNKNOWN",
  "security_code_verification" : "UNKNOWN",
  "created_at" : "2021-11-22T23:51:04.31Z",
  "updated_at" : "2021-11-22T23:51:04.32Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDmULj61C8ke6Y7qQiKENJ7",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIatE9xdPZTKdeeuyeLcB2Kj"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIatE9xdPZTKdeeuyeLcB2Kj/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIatE9xdPZTKdeeuyeLcB2Kj/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIatE9xdPZTKdeeuyeLcB2Kj/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIatE9xdPZTKdeeuyeLcB2Kj/updates"
    }
  }
}

Now that we have an Identity resource representing our buyer, we’ll need to create a Payment Instrument which represents the credit card you’ll be debiting (i.e. charging).

You’ll also need to interpolate your own buyer’s Identity ID from the previous request to properly associate it.

Please review our guide on how to tokenize cards via the embedded tokenization form

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 Credit 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
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, required First line of the address (max 35 characters)
line2 string, optional Second line of the address (max 35 characters)
city string, required City (max 20 characters)
region string, required 2-letter State code
postal_code string, required Zip or Postal code (max 7 characters)
country string, required 3-Letter Country code

Step 6: Create Sale

curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -d '
    {
        "merchant": "MUfWNiRCntW1KCRVjH4jEoba", 
        "currency": "USD", 
        "amount": 742277, 
        "source": "PIatE9xdPZTKdeeuyeLcB2Kj", 
        "tags": {
            "test": "sale"
        }
    }'

Example Response:

{
  "id" : "TR3rU4ibFu8Dxi7oFbbn9QKX",
  "amount" : 742277,
  "tags" : {
    "test" : "sale"
  },
  "state" : "PENDING",
  "trace_id" : "e613b737-df7d-4fd4-af01-526731eb742d",
  "currency" : "USD",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "source" : "PIatE9xdPZTKdeeuyeLcB2Kj",
  "destination" : null,
  "ready_to_settle_at" : null,
  "externally_funded" : "UNKNOWN",
  "fee" : 0,
  "statement_descriptor" : "FIN*BOBS BURGERS",
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2021-11-22T23:51:14.32Z",
  "updated_at" : "2021-11-22T23:51:14.77Z",
  "idempotency_id" : null,
  "merchant_identity" : "ID2cAnM4kbLE4abQWj2fydHw",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR3rU4ibFu8Dxi7oFbbn9QKX"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR3rU4ibFu8Dxi7oFbbn9QKX/payment_instruments"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR3rU4ibFu8Dxi7oFbbn9QKX/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR3rU4ibFu8Dxi7oFbbn9QKX/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR3rU4ibFu8Dxi7oFbbn9QKX/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIatE9xdPZTKdeeuyeLcB2Kj"
    },
    "fee_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
    }
  }
}

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

Next you’ll need to create a Transfer. To generate a Transfer we’ll supply the buyer’s Payment Instrument ID as the source field and the seller’s Merchant ID in the merchant field. Note that the amount field is in cents. These specific Transfers are distinguished by their type which return DEBIT.

Alternatively, a user can create an Authorization and then proceed to capture the Authorization in two API calls. This is useful when you’re looking to capture a specific amount on a card at a later date. You can find more information on Authorization’s flow.

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

HTTP Request

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

Request Arguments

Field Type Description
source string, required ID of the Payment Instrument that will be debited
merchant string, required Merchant ID of the merchant whom you’re charging on behalf of
amount integer, required The total amount that will be debited in cents (e.g. 100 cents to debit $1.00)
fee integer, optional The amount of the Transfer you would like to collect as your fee in cents. Defaults to zero (Must be less than or equal to the amount)
currency string, required 3-letter ISO code designating the currency of the Transfers (e.g. USD)processor
idempotency_id string, optional A randomly generated value that you want associated with the request
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)

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

 <script type="text/javascript" src="https://forms.finixpymnts.com/finix.js"></script>

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



const paymentForm = 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, and CVV).

Step 3: Define input fields and configure styling

Now that we have a PaymentForm object we’ll want to style it

DefineField Arguments

Field Type Description
elementId string, required Name of HTML id
type string, required API attribute name that will be sent in the payload
placeholder string, required What the user will see in the input field
validations string, optional This allows customers to make a field required. The possible values are required, cardExpiry, cardNumber, and cardCVC. Each of the possible values returns a different error message when the required field is not present.
  • required returns ‘Value is required’.
  • cardExpiry returns 'Invalid expiration date’.
  • cardNumber returns 'Invalid card number’.
  • cardCVC returns 'Invalid CVV’.
autoComplete string, optional This allows the specified fields to auto-complete from saved card information. The possible values are: cc-number, cc-name, cc-exp, cc-csc, address-line1, address-line2, address-level1, postal-code, address-level2. 
function defineField(elementId, type, placeholder, validations, autoComplete) {
 // call field method with desired css styling
 const f = form.field(type, {
        validations,
        placeholder: { text: placeholder, hideOnFocus: true },
        autoComplete,
        styles: {
          default: {
            color: "black",
          },
          success: {
            color: '#5cb85c',
          },
          error: {
            color: '#d9534f',
          },
        }
      });
  // appends each field wrapper (that contains placeholder and styles) to the appropriate div
  document.getElementById(elementId).appendChild(f);
}

defineField("field-wrapper-number", "number", '4111 1111 1111 1111');
defineField("field-wrapper-name", "name", 'Bo Jackson');
defineField("field-wrapper-expiration_date", "expiration_date", '02/2020');
defineField("field-wrapper-security_code", "security_code", '411');

Step 4: Submit payload and handle response

Form#submit(environment, applicationID, callback)-> Form 


/*
Form#submit(environment, applicationID, callback)-> Form
*/

function submitForm() {
  // sandbox or production for environment
  form.submit('sandbox', APj9Gw6wRhpbaHJM1QtZakqH, function(err, res) {
    if (err) {
      console.log("There was an error");
    }
    // shows id of tokenized payment card
    document.getElementById('preview').innerHTML = JSON.stringify(res, null, '  ');
  })
}

document.getElementById('button').addEventListener('click', function (e){
  e.preventDefault();
  submitForm();
})

// if user types "enter" instead of clicking submit button
form.onSubmit(submitForm);

Example Response:

{
  "status": 201,
  "statusText": "Created",
  "data": {
    "id": "TKiu6N8r5wN38J1xXdeNjzZY",
    "fingerprint": "FPR-2083311660",
    "created_at": "2017-08-29T06:25:54.29Z",
    "updated_at": "2017-08-29T06:25:54.29Z",
    "instrument_type": "PAYMENT_CARD",
    "expires_at": "2017-08-30T06:25:54.29Z",
    "currency": "USD"
  }
}
{
  "cardBrand": "visa",
  "bin": "411111"
}

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.

Arguments

Field Type Description
environment string, required sandbox for testing and live for live
applicationId string, required Application id that the payment card will be scoped to
callback function, required Callback that will be executed when the HTTPRequest is finished.

Step 5: Associate to an Identity

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  USxpFPfqbFXM5jBZPmmCAwEm:e4359f08-b9e9-463f-b5f3-fcf8c65ec54e \
    -d '
    {
        "token": "TKcKzwmnNr4T1Hx2mCTKtKpg", 
        "type": "TOKEN", 
        "identity": "IDnKHJ7wtcJDhK9RgSqFiYgr"
    }'

Example Response:

{
  "id" : "PI56k5MG9pZKgDi6e1vSwGFj",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "fingerprint" : "FPRw9NoorETQgCjFgwKPvcGsV",
  "tags" : { },
  "expiration_month" : 12,
  "expiration_year" : 2029,
  "bin" : "495703",
  "last_four" : "0454",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : null,
  "address" : {
    "line1" : "741 Douglass St",
    "line2" : "Apartment 7",
    "city" : "San Mateo",
    "region" : "CA",
    "postal_code" : "94114",
    "country" : "USA"
  },
  "address_verification" : "UNKNOWN",
  "security_code_verification" : "UNKNOWN",
  "created_at" : "2021-11-22T23:51:33.48Z",
  "updated_at" : "2021-11-22T23:51:33.48Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI56k5MG9pZKgDi6e1vSwGFj"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI56k5MG9pZKgDi6e1vSwGFj/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI56k5MG9pZKgDi6e1vSwGFj/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI56k5MG9pZKgDi6e1vSwGFj/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI56k5MG9pZKgDi6e1vSwGFj/updates"
    }
  }
}

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.

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

Subscription Billing Guide

Finix’s Subscription Billing APIs provide Platforms the option to automatically charge their Merchants on a fixed billing plan. The Subscription Billing APIs can be used to charge a Fee to a Merchant for a service, equipment, or other use case. An example of a subscription Fee is charging a Merchant a one-time registration Fee or an annual software renewal Fee.

There are three steps to create and apply a Subscription to a Merchant.

Step 1: Create a Subscription Schedule

curl https://finix.sandbox-payments-api.com/subscription/subscription_schedules \
    -H "Content-Type: application/vnd.json+api" \
    -u  USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041 \
    -d '
    {
        "line_item_type": "FEE", 
        "nickname": "Fixed_Time_Subscription_Schedule", 
        "fixed_time_interval_offset": {
            "interval_count": 4, 
            "hourly_interval": 24
        }, 
        "subscription_type": "FIXED_TIME_INTERVAL"
    }'

Example Response:

{
  "id" : "SUBSCHEDULE_38qYndpNono28SXDwGP55F",
  "created_at" : "2021-11-22T23:58:19.50Z",
  "updated_at" : "2021-11-22T23:58:19.50Z",
  "created_by" : "USimz3zSq5R2PqiEBXY6rSiJ",
  "fixed_time_interval_offset" : {
    "hourly_interval" : 24,
    "interval_count" : 4
  },
  "line_item_type" : "FEE",
  "nickname" : "Fixed_Time_Subscription_Schedule",
  "period_offset" : null,
  "subscription_type" : "FIXED_TIME_INTERVAL",
  "tags" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_38qYndpNono28SXDwGP55F"
    },
    "amounts" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_38qYndpNono28SXDwGP55F/subscription_amounts"
    }
  }
}

The Subscription Schedule details when the Subscription Fee is charged to the Merchant. There are two available schedule types: FIXED_TIME_INTERVAL or PERIODIC. Each schedule type provides different functionality:

The fixed_interval uses hourly increments. For example, to charge a Fee every day for 4 days, pass 24 in the interval field and 4 in the interval_count field in the request. There is no limit to the number of interval_count or intervals you can pass.

A PERIODIC_YEARLY Subscription Schedule charges a Merchant a Fee once a year on a specific day and month. If you pass in a day that does not exist, such as 2/31 or 11/30 in the day field, the request will error out.

A PERIODIC_MONTHLY Subscription Schedule charges a Merchant a Fee once a month on a specific day. The month field should not be passed in the payload, or the request will throw an error. If you pass in 31 to represent the last day of a month, for every month that does not have 31 days, the Fee will be charged on the last day of the month. For example, Fees for February would be charged on the 28th, September on the 30th, and etc. This logic also applies to leap years.

HTTP Request

POST https://finix.sandbox-payments-api.com/subscription/subscription_schedules

Fixed-time Interval Offset Request Arguments

Field Type Description
hourly_interval integer, required Hourly increments between recurring charges
interval_count integer, required Number of recurring charges

Request Arguments

Field Type Description
line_item_type string, required Subscription Schedule type. For subscriptions, the type is FEE
nickname string, required Subscription Schedule name
subscription_type string, required Subscription Schedule type. Available types are: PERIODIC_MONTHLY, PERIODIC_YEARLY or FIXED_TIME_INTERVAL
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)

Response

Field Type Description
id string ID of the Subscription Schedule
created_at string Timestamp of when the Subscription Schedule was created
updated_at string Timestamp of when the Subscription Schedule was last updated
created_by string User ID
fixed_time_offset object Specifies when the Fee is charged
hourly_interval integer Hourly increments between recurring charges
interval_count integer Number of recurring charges
line_item_type string Subscription Schedule type. For subscriptions, the type is FEE
nickname string Subscription Schedule name
period_offset object Specifies when the Fee is charged. This field is null for FIXED_TIME_INTERVAL Subscription Schedules
subscription_type string Subscription Schedule type
tags object Key value pair for annotating custom meta data (e.g. order numbers)

Step 2: Create a Subscription Amount

curl https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_38qYndpNono28SXDwGP55F/subscription_amounts  \
    -H "Content-Type: application/vnd.json+api" \
    -u  USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041 \
    -d '
    {
        "amount_type": "FEE", 
        "fee_amount_data": {
            "currency": "USD", 
            "amount": 2500, 
            "label": "POS_INSTALLMENT_FEE"
        }, 
        "nickname": "POS_INSTALLMENT_FEE", 
        "tags": {
            "order_number": "124"
        }
    }'

Example Response:

{
  "id" : "SUBAMOUNT_3pZg2NscW2ctbmfdxXTpqy",
  "created_at" : "2021-11-22T23:58:23.37Z",
  "updated_at" : "2021-11-22T23:58:23.37Z",
  "amount_type" : "FEE",
  "created_by" : "USimz3zSq5R2PqiEBXY6rSiJ",
  "fee_amount_data" : {
    "amount" : 2500,
    "currency" : "USD",
    "label" : "POS_INSTALLMENT_FEE"
  },
  "nickname" : "POS_INSTALLMENT_FEE",
  "subscription_schedule" : "SUBSCHEDULE_38qYndpNono28SXDwGP55F",
  "tags" : {
    "order_number" : "124"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_38qYndpNono28SXDwGP55F/subscription_amounts/SUBAMOUNT_3pZg2NscW2ctbmfdxXTpqy"
    },
    "schedule" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_38qYndpNono28SXDwGP55F"
    }
  }
}

The next step is to create and associate a Subscription Amount to a Subscription Schedule. The Subscription Amount is the amount to be charged to a Merchant. To associate a Subscription Amount with a Subscription Schedule pass FEE in the amount_type field of the request. You can associate up to 25 amounts to a schedule. To add an additional Subscription Amount to a schedule, make a new Subscription Amount request with the Subscription Schedule ID.

If you add another Subscription Amount to a schedule, all Merchants enrolled in that schedule will be charged the additional amount when the enrollment is triggered. For example, if your schedule charges a monthly software license fee of $10, and you add another monthly $10 reporting fee, all Merchants enrolled in this schedule will be charged $20 per month once the enrollment is triggered.

HTTP Request

POST https://finix.sandbox-payments-api.com/subscription/subscription_schedules/:SUBSCRIPTION_SCHEDULE_ID/subscription_amounts

URL Parameters

Parameter Description
:SUBSCRIPTION_SCHEDULE_ID ID of the Subscription Schedule

Request Arguments

Field Type Description
amount_type string, required Subscription Amount type. For subscriptions, the type is FEE
fee_amount_data object, required Key value pair specifying amount and currency
nickname string, required Subscription Amount name
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)

Fee Amount Object Request Arguments

Field Type Description
amount integer, required A positive integer in cents representing how much to charge on a recurring basis
currency string, required Three-letter ISO currency code in uppercase
label string, optional The display name of the Settlement that can be used for filtering purposes

Response

Field Type Description
id string ID of the Subscription Amount
created_at string Timestamp of when the Subscription Amount was created
updated_at string Timestamp of when the Subscription Amount was last updated
amount_type string Subscription Amount type. For subscriptions, the type is FEE
created_by string User ID
fee_amount_data object Key value pair specifying amount and currency
amount integer A positive integer in cents representing how much to charge on a recurring basis
currency string Three-letter ISO currency code in uppercase
label string The display name of the Settlement that can be used for filtering purposes
nickname string Subscription Amount name
subscription_schedule string ID of the Subscription Schedule
tags object Key value pair for annotating custom meta data (e.g. order numbers)

Step 3: Create a Subscription Enrollment and Enroll the Merchant

curl https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_38qYndpNono28SXDwGP55F/subscription_enrollments \
    -H "Content-Type: application/vnd.json+api" \
    -u  USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041 \
    -d '
    {
        "merchant": "MUwkMjGKSoqkjwg2s6Qe9GPx", 
        "started_at": "2022-11-11T16:50:59.891Z", 
        "nickname": "Security Fee", 
        "tags": {
            "enrollment_info": "Security Fee Enrollment"
        }
    }'

Example Response:

{
  "id" : "SUBENROLLMENT_3uSdKZ4xSFKXKbNLJ5c6Pf",
  "created_at" : "2021-11-22T23:58:24.52Z",
  "updated_at" : "2021-11-22T23:58:24.52Z",
  "created_by" : "USimz3zSq5R2PqiEBXY6rSiJ",
  "ended_at" : null,
  "merchant" : "MUwkMjGKSoqkjwg2s6Qe9GPx",
  "nickname" : "Security Fee",
  "started_at" : "2022-11-11T16:50:59.89Z",
  "subscription_schedule" : "SUBSCHEDULE_38qYndpNono28SXDwGP55F",
  "tags" : {
    "enrollment_info" : "Security Fee Enrollment"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_enrollments/SUBENROLLMENT_3uSdKZ4xSFKXKbNLJ5c6Pf"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUwkMjGKSoqkjwg2s6Qe9GPx"
    },
    "schedule" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_38qYndpNono28SXDwGP55F"
    },
    "amounts" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_38qYndpNono28SXDwGP55F/subscription_amounts"
    }
  }
}

A Subscription Enrollment details which Merchant gets charged, to what schedule, and when the subscription will start. The Subscription Enrollment must be associated with a Subscription Schedule.

HTTP Request

POST https://finix.sandbox-payments-api.com/subscription/subscription_schedules/:SUBSCRIPTION_SCHEDULE_ID/subscription_enrollments

URL Parameters

Parameter Description
:SUBSCRIPTION_SCHEDULE_ID ID of the Subscription Schedule

Request Arguments

Field Type Description
ended_at string, optional When the subscription will end in DateTime format. This field can be null. If left null, the Fee will continue in perpetuity
merchant string, required ID of the Merchant
nickname string, required Subscription Enrollment name
started_at string, required When the subscription will begin in DateTime format. The start date must be a future date
tags object, optional Key value pair annotating custom meta data (e.g. order numbers)

Response

Field Type Description
id string Subscription Enrollment ID
created_at string Timestamp of when the Subscription Enrollment was created
updated_at string Timestamp of when the Subscription Enrollment was last updated
created_by string User ID
ended_at string When the subscription will end in DateTime format. If left blank, it will continue in perpetuity
merchant string ID of the Merchant
nickname string Name of the Subscription Enrollment
started_at string When the subscription will begin in DateTime format
subscription_schedule string ID of the Subscription Schedule
tags object Key value pair annotating custom meta data (e.g. order numbers)

Managing Subscriptions

Create Subscription Amount

curl https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_38qYndpNono28SXDwGP55F/subscription_amounts  \
    -H "Content-Type: application/vnd.json+api" \
    -u  USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041 \
    -d '
    {
        "amount_type": "FEE", 
        "fee_amount_data": {
            "currency": "USD", 
            "amount": 2500, 
            "label": "POS_INSTALLMENT_FEE"
        }, 
        "nickname": "POS_INSTALLMENT_FEE", 
        "tags": {
            "order_number": "124"
        }
    }'

Example Response:

{
  "id" : "SUBAMOUNT_3pZg2NscW2ctbmfdxXTpqy",
  "created_at" : "2021-11-22T23:58:23.37Z",
  "updated_at" : "2021-11-22T23:58:23.37Z",
  "amount_type" : "FEE",
  "created_by" : "USimz3zSq5R2PqiEBXY6rSiJ",
  "fee_amount_data" : {
    "amount" : 2500,
    "currency" : "USD",
    "label" : "POS_INSTALLMENT_FEE"
  },
  "nickname" : "POS_INSTALLMENT_FEE",
  "subscription_schedule" : "SUBSCHEDULE_38qYndpNono28SXDwGP55F",
  "tags" : {
    "order_number" : "124"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_38qYndpNono28SXDwGP55F/subscription_amounts/SUBAMOUNT_3pZg2NscW2ctbmfdxXTpqy"
    },
    "schedule" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_38qYndpNono28SXDwGP55F"
    }
  }
}

The Subscription Amount is the amount to be charged to a Merchant. The Subscription Amount must be associated to a Subscription Schedule.

HTTP Request

POST https://finix.sandbox-payments-api.com/subscription/subscription_schedules/:SUBSCRIPTION_SCHEDULE_ID/subscription_amounts

URL Parameters

Parameter Description
:SUBSCRIPTION_SCHEDULE_ID ID of the Subscription Schedule

Request Arguments

Field Type Description
amount_type string, required Subscription Amount type. For subscriptions, the type is FEE
fee_amount_data object, required Key value pair specifying amount and currency
nickname string, required Subscription Amount name
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)

Fee Amount Object Request Arguments

Field Type Description
amount integer, required A positive integer in cents representing how much to charge on a recurring basis
currency string, required Three-letter ISO currency code in uppercase
label string, optional The display name of the Settlement that can be used for filtering purposes

Response

Field Type Description
id string ID of the Subscription Amount
created_at string Timestamp of when the Subscription Amount was created
updated_at string Timestamp of when the Subscription Amount was last updated
amount_type string Subscription Amount type. For subscriptions, the type is FEE
created_by string User ID
fee_amount_data object Key value pair specifying amount and currency
amount integer A positive integer in cents representing how much to charge on a recurring basis
currency string Three-letter ISO currency code in uppercase
label string The display name of the Settlement that can be used for filtering purposes
nickname string Subscription Amount name
subscription_schedule string ID of the Subscription Schedule
tags object Key value pair for annotating custom meta data (e.g. order numbers)

Update Subscription Amount

curl https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_38qYndpNono28SXDwGP55F/subscription_amounts/SUBAMOUNT_3pZg2NscW2ctbmfdxXTpqy  \
    -H "Content-Type: application/vnd.json+api" \
    -u  USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041 \
    -X PATCH \
    -d '
    {
        "amount_type": "FEE", 
        "amount": 5000, 
        "nickname": "NEW_POS_INSTALLMENT_FEE"
    }'

Example Response:

{
  "id" : "SUBAMOUNT_3sGmdTfHBqcRpsixikZ2A5",
  "created_at" : "2021-11-22T23:58:24.01Z",
  "updated_at" : "2021-11-22T23:58:24.01Z",
  "amount_type" : "FEE",
  "created_by" : "USimz3zSq5R2PqiEBXY6rSiJ",
  "fee_amount_data" : {
    "amount" : 2500,
    "currency" : "USD",
    "label" : "POS_INSTALLMENT_FEE"
  },
  "nickname" : "NEW_POS_INSTALLMENT_FEE",
  "subscription_schedule" : "SUBSCHEDULE_38qYndpNono28SXDwGP55F",
  "tags" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_38qYndpNono28SXDwGP55F/subscription_amounts/SUBAMOUNT_3sGmdTfHBqcRpsixikZ2A5"
    },
    "schedule" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_38qYndpNono28SXDwGP55F"
    }
  }
}

Update a previously created Subscription Amount. This creates a new Subscription Amount resource.

HTTP Request

PATCH https://finix.sandbox-payments-api.com/subscription/subscription_schedules/:SUBSCRIPTION_SCHEDULE_ID/subscription_amounts/:SUBSCRIPTION_AMOUNT_ID

URL Parameters

Parameter Description
:SUBSCRIPTION_SCHEDULE_ID ID of the Subscription Schedule
:SUBSCRIPTION_AMOUNT_ID ID of the Subscription Amount

Request Arguments

Field Type Description
amount_type string, required Subscription Amount type. For subscriptions, the type is FEE
fee_amount_data object, required Key value pair specifying amount and currency
nickname string, required Subscription Amount name

Fee Amount Object Request Arguments

Field Type Description
amount integer, optional A positive integer in cents representing how much to charge on a recurring basis
currency string, optional Three-letter ISO currency code in uppercase
label string, optional The display name of the Settlement that can be used for filtering purposes

Response

Field Type Description
id string ID of the Subscription Amount
created_at string Timestamp of when the Subscription Amount was created
updated_at string Timestamp of when the Subscription Amount was last updated
amount_type string Subscription Amount type. For subscriptions, the type is FEE
created_by string User ID
fee_amount_data object Key value pair specifying amount and currency
amount integer A positive integer in cents representing how much to charge on a recurring basis
currency string Three-letter ISO currency code in uppercase
label string The display name of the Settlement that can be used for filtering purposes
nickname string Subscription Amount name
subscription_schedule string ID of the Subscription Schedule
tags object Key value pair for annotating custom meta data (e.g. order numbers)

Delete Subscription Amount


curl https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_38qYndpNono28SXDwGP55F/subscription_amounts/SUBAMOUNT_3pZg2NscW2ctbmfdxXTpqy  \
    -H "Content-Type: application/vnd.json+api" \
    -X DELETE \
    -u  USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041

Delete a previously created Subscription Amount.

HTTP Request

DELETE https://finix.sandbox-payments-api.com/subscription/subscription_schedules/:SUBSCRIPTION_SCHEDULE_ID/subscription_amounts/:SUBSCRIPTION_AMOUNT_ID

URL Parameters

Parameter Description
:SUBSCRIPTION_SCHEDULE_ID ID of the Subscription Schedule
:SUBSCRIPTION_AMOUNT_ID ID of the Subscription Amount

Delete Subscription Enrollment


curl https://finix.sandbox-payments-api.com/subscription/subscription_enrollments/SUBENROLLMENT_3uSdKZ4xSFKXKbNLJ5c6Pf  \
    -H "Content-Type: application/vnd.json+api" \
    -X DELETE \
    -u  USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041

Delete a previously created Subscription Enrollment.

HTTP Request

DELETE https://finix.sandbox-payments-api.com/subscription/subscription_enrollments/:SUBSCRIPTION_ENROLLMENT_ID

URL Parameters

Parameter Description
:SUBSCRIPTION_ENROLLMENT_ID ID of the Subscription Enrollment

Push-to-Card

Step 1: Create a Recipient Identity

curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u USxpFPfqbFXM5jBZPmmCAwEm:e4359f08-b9e9-463f-b5f3-fcf8c65ec54e \
    -d '
    {
        "tags": {
            "key": "value"
        }, 
        "entity": {
            "phone": "7145677612", 
            "first_name": "Walter", 
            "last_name": "Le", 
            "email": "Walter@gmail.com", 
            "personal_address": {
                "city": "San Mateo", 
                "country": "USA", 
                "region": "CA", 
                "line2": "Apartment 7", 
                "line1": "741 Douglass St", 
                "postal_code": "94114"
            }
        }
    }'

Example Response:

{
  "id" : "IDszD87NDFCEebMFuCeYewn6",
  "application" : "AP6rt8kfRVoi9Si1i3oJTkos",
  "entity" : {
    "title" : null,
    "first_name" : "Walter",
    "last_name" : "Le",
    "email" : "Walter@gmail.com",
    "business_name" : null,
    "business_type" : null,
    "doing_business_as" : null,
    "phone" : "7145677612",
    "business_phone" : null,
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : null,
    "mcc" : null,
    "dob" : null,
    "max_transaction_amount" : 0,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : null,
    "annual_card_volume" : 0,
    "has_accepted_credit_cards_previously" : false,
    "incorporation_date" : null,
    "principal_percentage_ownership" : null,
    "short_business_name" : null,
    "ownership_type" : null,
    "tax_authority" : null,
    "tax_id_provided" : false,
    "business_tax_id_provided" : false,
    "default_statement_descriptor" : null
  },
  "tags" : {
    "key" : "value"
  },
  "created_at" : "2021-11-22T23:50:43.13Z",
  "updated_at" : "2021-11-22T23:50:43.13Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDszD87NDFCEebMFuCeYewn6"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDszD87NDFCEebMFuCeYewn6/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDszD87NDFCEebMFuCeYewn6/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDszD87NDFCEebMFuCeYewn6/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDszD87NDFCEebMFuCeYewn6/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDszD87NDFCEebMFuCeYewn6/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDszD87NDFCEebMFuCeYewn6/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDszD87NDFCEebMFuCeYewn6/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDszD87NDFCEebMFuCeYewn6/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP6rt8kfRVoi9Si1i3oJTkos"
    }
  }
}

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.

HTTP Request

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

Request Arguments

Field Type Description
first_name string, optional First name
last_name string, optional Last name
email string, optional Email
phone string, optional Phone number
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)
personal_address object, optional Customers shipping address or billing address (Full description of child attributes below)

Address-object Request Arguments

Field Type Description
line1 string, optional First line of the address (max 35 characters)
line2 string, optional Second line of the address (max 35 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 2: Add a Payment Instrument for the Recipient

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u USxpFPfqbFXM5jBZPmmCAwEm:e4359f08-b9e9-463f-b5f3-fcf8c65ec54e \
    -d '
    {
        "name": "Ricardo Le", 
        "expiration_year": 2029, 
        "tags": {
            "card_name": "Business Card"
        }, 
        "number": "4895142232120006", 
        "expiration_month": 12, 
        "address": {
            "city": "San Francisco", 
            "region": "CA", 
            "postal_code": "94404", 
            "line1": "900 Metro Center Blv", 
            "country": "USA"
        }, 
        "security_code": "022", 
        "type": "PAYMENT_CARD", 
        "identity": "IDszD87NDFCEebMFuCeYewn6"
    }'

Example Response:

{
  "id" : "PIpRfLXq5ejK8ZefS3gxDNz7",
  "application" : "AP6rt8kfRVoi9Si1i3oJTkos",
  "fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 12,
  "expiration_year" : 2029,
  "bin" : "489514",
  "last_four" : "0006",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Ricardo Le",
  "address" : {
    "line1" : "900 Metro Center Blv",
    "line2" : null,
    "city" : "San Francisco",
    "region" : "CA",
    "postal_code" : "94404",
    "country" : "USA"
  },
  "address_verification" : "UNKNOWN",
  "security_code_verification" : "UNKNOWN",
  "created_at" : "2021-11-22T23:50:47.10Z",
  "updated_at" : "2021-11-22T23:50:47.10Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDszD87NDFCEebMFuCeYewn6",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIpRfLXq5ejK8ZefS3gxDNz7"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIpRfLXq5ejK8ZefS3gxDNz7/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIpRfLXq5ejK8ZefS3gxDNz7/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIpRfLXq5ejK8ZefS3gxDNz7/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP6rt8kfRVoi9Si1i3oJTkos"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDszD87NDFCEebMFuCeYewn6"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIpRfLXq5ejK8ZefS3gxDNz7/updates"
    }
  }
}

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 20 characters)
line2 string, optional Second line of the address (max 35 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.

curl https://finix.sandbox-payments-api.com/payment_instruments/PI2waD7kEq8by3vrB6bQBsGH/verifications \
    -H "Content-Type: application/vnd.json+api" \
    -u USxpFPfqbFXM5jBZPmmCAwEm:e4359f08-b9e9-463f-b5f3-fcf8c65ec54e \
    -d '
    {
        "processor": "VISA_V1"
    }'

Example Response:

{
  "id" : "VI8eTGSVVsbAh2RvsKvk7AAn",
  "application" : "AP6rt8kfRVoi9Si1i3oJTkos",
  "tags" : { },
  "messages" : [ ],
  "raw" : {
    "validation_details" : {
      "systems_trace_audit_number" : "132623207974",
      "error_result" : null,
      "transaction_identifier" : "549914509459124",
      "approval_code" : null,
      "action_code" : "25",
      "response_code" : "5",
      "address_verification_results" : "I",
      "cvv2_result_code" : "P"
    },
    "inquiry_details" : {
      "systems_trace_audit_number" : "132623207974",
      "error_result" : null,
      "visa_network_info" : [ {
        "card_type_code" : "D",
        "billing_currency_code" : 840,
        "billing_currency_minor_digits" : 2,
        "issuer_name" : "Visa Test Bank",
        "card_issuer_country_code" : 840,
        "fast_funds_indicator" : "D",
        "push_funds_block_indicator" : "C",
        "online_gambing_block_indicator" : "N"
      } ],
      "ppgs_network_info" : [ ]
    },
    "general_inquiry_details" : {
      "systems_trace_audit_number" : "132623207974",
      "error_result" : null,
      "card_product_id" : "B",
      "card_product_name" : "Visa Traditional Rewards",
      "card_product_subtype_code" : "",
      "card_product_subtype_description" : "",
      "card_type_code" : "C",
      "card_subtype_code" : "",
      "card_platform_code" : "CN",
      "issuer_name" : "BANCO AGROMERCANTIL DE GUATEMALA S.A.",
      "bin" : "481507",
      "country_code" : "320",
      "status" : {
        "status_code" : "CDI000",
        "status_description" : "Success"
      }
    }
  },
  "processor" : "VISA_V1",
  "state" : "SUCCEEDED",
  "created_at" : "2021-11-22T23:51:39.85Z",
  "updated_at" : "2021-11-22T23:51:42.68Z",
  "trace_id" : "132623207974",
  "payment_instrument" : "PI2waD7kEq8by3vrB6bQBsGH",
  "merchant" : null,
  "identity" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VI8eTGSVVsbAh2RvsKvk7AAn"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP6rt8kfRVoi9Si1i3oJTkos"
    },
    "payment_instrument" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2waD7kEq8by3vrB6bQBsGH"
    }
  }
}

HTTP Request

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

URL Parameters

Parameter Description
:PAYMENT_INSTRUMENT_ID ID of the Payment Instrument

Request Arguments

Field Type Description
processor string, required The name of the processor, which needs to be: VISA_V1
country string, optional 3-Letter Country code. This attribute is currently only applicable for our Latin America partners.

Address Verification Results (address_verification_results)

Letter Description
D, F, M, Y Address verified
A, B, C, G, I, N, P, R, S, U, W Address not verified
Z Postal/ZIP match, street addresses do not match or street address not included in request

Card Verification 2 Results (cvv2_result_code)

Letter Description
M CVV and expiration verified
N, P, S Either CVV or expiration date is incorrect
U Issuer does not participate in CVV2 service

Card Type (card_type_code)

This one-character code indicates whether the account is credit, debit, prepaid, deferred debit, or charge.

Letter Description
C Credit
D Debit
H Charge Card
P Prepaid
R Deferred Debit

Fasts Funds Indicator (fast_funds_indicator)

Indicates whether or not the card is Fast Funds eligible (i.e. if the funds will settle in 30 mins or less). If not eligible, typically funds will settle within 2 business days.

Letter Description
B Fast Funds eligible for all transactions
D Fast Funds eligible for only domestic transactions
N Not eligible for Fast Funds

Push Funds Indicator (push_funds_block_indicator)

This code indicates if the associated card can receive push-to-card disbursements.

Letter Description
A, B, C Accepts push-to-card payments
N Does not accept push-to-card payments

Online Gambling Block Indicator (online_gambing_block_indicator)

Indicates if the card can receive push-payments for online gambling payouts.

Letter Description
Y Blocked for online gambling payouts
N Not blocked for online gambling payouts

Card Product ID (card_product_id)

A combination of card brand, platform, class and scheme.

Letter Description
A Visa Traditional
AX American Express
B Visa Traditional Rewards
C Visa Signature
D Visa Signature Preferred
DI Discover
DN Diners
E Proprietary ATM
F Visa Classic
G Visa Business
G1 Visa Signature Business
G2 Visa Business Check Card
G3 Visa Business Enhanced
G4 Visa Infinite Business
G5 Visa Business Rewards
I Visa Infinite
I1 Visa Infinite Privilege
I2 Visa UHNW
J3 Visa Healthcare
JC JCB
K Visa Corporate T&E
K1 Visa Government Corporate T&E
L Visa Electron
M MasterCard
N Visa Platinum
N1 Visa Rewards
N2 Visa Select
P Visa Gold
Q Private Label
Q1 Private Label Prepaid
Q2 Private Label Basic
Q3 Private Label Standard
Q4 Private Label Enhanced
Q5 Private Label Specialized
Q6 Private Label Premium
R Proprietary
S Visa Purchasing
S1 Visa Purchasing with Fleet
S2 Visa Government Purchasing
S3 Visa Government Purchasing with Fleet
S4 Visa Commercial Agriculture
S5 Visa Commercial Transport
S6 Visa Commercial Marketplace
U Visa Travel Money
V Visa V PAY

Product Sub-Type (card_product_subtype)

Description of product subtype.

Letter Description
AC Agriculture Maintenance Account
AE Agriculture Debit Account/Electron
AG Agriculture
AI Agriculture Investment Loan
CG Brazil Cargo
CS Construction
DS Distribution
HC Healthcare
LP Visa Large Purchase Advantage
MA Visa Mobile Agent
MB Interoperable Mobile Branchless Banking
MG Visa Mobile General
VA Visa Vale - Supermarket
VF Visa Vale - Fuel
VR Visa Vale - Restaurant

Card Sub-Type (card_subtype_code)

The code for account funding source subtype, such as reloadable and non-reloadable.

Letter Description
N Non-Reloadable
R Reloadable

Step 4: Provision Recipient Account

curl https://finix.sandbox-payments-api.com/identities/IDszD87NDFCEebMFuCeYewn6/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u USxpFPfqbFXM5jBZPmmCAwEm:e4359f08-b9e9-463f-b5f3-fcf8c65ec54e \
    -d '
    {
        "processor": "VISA_V1"
    }'

Example Response:

{
  "id" : "MUtMjxRLLJzAmbD9Wkhw7dKn",
  "application" : "AP6rt8kfRVoi9Si1i3oJTkos",
  "identity" : "IDszD87NDFCEebMFuCeYewn6",
  "verification" : "VIpinEDxGHue5iR8E8urYoLp",
  "merchant_profile" : "MPrx78a3CAEvKqGPB5whV9XA",
  "processor" : "VISA_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "card_expiration_date_required" : true,
  "card_cvv_required" : false,
  "tags" : { },
  "mcc" : null,
  "mid" : null,
  "merchant_name" : "Walter Le",
  "settlement_funding_identifier" : "UNSET",
  "ready_to_settle_upon" : null,
  "fee_ready_to_settle_upon" : "RECONCILIATION",
  "level_two_level_three_data_enabled" : false,
  "created_at" : "2021-11-22T23:50:49.08Z",
  "updated_at" : "2021-11-22T23:50:49.37Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUtMjxRLLJzAmbD9Wkhw7dKn"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDszD87NDFCEebMFuCeYewn6"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUtMjxRLLJzAmbD9Wkhw7dKn/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPrx78a3CAEvKqGPB5whV9XA"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP6rt8kfRVoi9Si1i3oJTkos"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIpinEDxGHue5iR8E8urYoLp"
    }
  }
}

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.

HTTP Request

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

Request Arguments

Field Type Description
processor string, optional Name of Processor

Step 5: Send Payout

curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/vnd.json+api" \
    -u USxpFPfqbFXM5jBZPmmCAwEm:e4359f08-b9e9-463f-b5f3-fcf8c65ec54e \
    -d '
    {
        "currency": "USD", 
        "amount": 1510, 
        "destination": "PIpRfLXq5ejK8ZefS3gxDNz7", 
        "tags": {
            "order_number": "21DFASJSAKAS"
        }
    }'

Example Response:

{
  "id" : "TRHBiqwzjVhn3gu8oKWNVza",
  "amount" : 1510,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "trace_id" : "132623207971",
  "currency" : "USD",
  "application" : "AP6rt8kfRVoi9Si1i3oJTkos",
  "source" : null,
  "destination" : "PIpRfLXq5ejK8ZefS3gxDNz7",
  "ready_to_settle_at" : null,
  "externally_funded" : "UNKNOWN",
  "fee" : 0,
  "statement_descriptor" : null,
  "type" : "CREDIT",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2021-11-22T23:50:50.83Z",
  "updated_at" : "2021-11-22T23:50:51.87Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDszD87NDFCEebMFuCeYewn6",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP6rt8kfRVoi9Si1i3oJTkos"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRHBiqwzjVhn3gu8oKWNVza"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDszD87NDFCEebMFuCeYewn6"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRHBiqwzjVhn3gu8oKWNVza/payment_instruments"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRHBiqwzjVhn3gu8oKWNVza/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRHBiqwzjVhn3gu8oKWNVza/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRHBiqwzjVhn3gu8oKWNVza/disputes"
    },
    "destination" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIpRfLXq5ejK8ZefS3gxDNz7"
    },
    "fee_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
    }
  }
}

Now the final step - time to payout the recipient!

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 a Payout to a card.

To create a Transfer we’ll simply supply the Payment Instrument ID of the previously tokenized card as the destination field. Also, be sure to note that the amount field is in cents.

Simple enough, right? 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
destination string, required ID of the Payment Instrument where funds will be sent
amount integer, required The total amount that will be charged in cents (e.g. 100 cents to charge $1.00)
currency string, required 3-letter ISO code designating the currency of the Transfers (e.g. USD)
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)
country string, optional 3-Letter Country code. This attribute is currently only applicable for our Latin America partners.

Pull-from-Card

Step 1: Create a Sender Identity

curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u USxpFPfqbFXM5jBZPmmCAwEm:e4359f08-b9e9-463f-b5f3-fcf8c65ec54e \
    -d '
    {
        "tags": {
            "key": "value"
        }, 
        "entity": {
            "phone": "7145677612", 
            "first_name": "Alex", 
            "last_name": "White", 
            "email": "Alex@gmail.com", 
            "personal_address": {
                "city": "San Mateo", 
                "country": "USA", 
                "region": "CA", 
                "line2": "Apartment 7", 
                "line1": "741 Douglass St", 
                "postal_code": "94114"
            }
        }
    }'

Example Response:

{
  "id" : "IDdWXvfUtyqdA6kKFgEu8dkQ",
  "application" : "AP6rt8kfRVoi9Si1i3oJTkos",
  "entity" : {
    "title" : null,
    "first_name" : "Alex",
    "last_name" : "White",
    "email" : "Alex@gmail.com",
    "business_name" : null,
    "business_type" : null,
    "doing_business_as" : null,
    "phone" : "7145677612",
    "business_phone" : null,
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : null,
    "mcc" : null,
    "dob" : null,
    "max_transaction_amount" : 0,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : null,
    "annual_card_volume" : 0,
    "has_accepted_credit_cards_previously" : false,
    "incorporation_date" : null,
    "principal_percentage_ownership" : null,
    "short_business_name" : null,
    "ownership_type" : null,
    "tax_authority" : null,
    "tax_id_provided" : false,
    "business_tax_id_provided" : false,
    "default_statement_descriptor" : null
  },
  "tags" : {
    "key" : "value"
  },
  "created_at" : "2021-11-22T23:50:44.17Z",
  "updated_at" : "2021-11-22T23:50:44.17Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDdWXvfUtyqdA6kKFgEu8dkQ"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDdWXvfUtyqdA6kKFgEu8dkQ/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDdWXvfUtyqdA6kKFgEu8dkQ/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDdWXvfUtyqdA6kKFgEu8dkQ/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDdWXvfUtyqdA6kKFgEu8dkQ/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDdWXvfUtyqdA6kKFgEu8dkQ/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDdWXvfUtyqdA6kKFgEu8dkQ/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDdWXvfUtyqdA6kKFgEu8dkQ/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDdWXvfUtyqdA6kKFgEu8dkQ/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP6rt8kfRVoi9Si1i3oJTkos"
    }
  }
}

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.

HTTP Request

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

Request Arguments

Field Type Description
first_name string, optional First name
last_name string, optional Last name
email string, optional Email
phone string, optional Phone number
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)
personal_address object, optional Customers shipping address or billing address (Full description of child attributes below)

Address-object Request Arguments

Field Type Description
line1 string, optional First line of the address (max 35 characters)
line2 string, optional Second line of the address (max 35 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 2: Add a Payment Instrument for the Sender

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u USxpFPfqbFXM5jBZPmmCAwEm:e4359f08-b9e9-463f-b5f3-fcf8c65ec54e \
    -d '
    {
        "name": "Alex Wade", 
        "expiration_year": 2029, 
        "tags": {
            "card_name": "Business Card"
        }, 
        "number": "4895142232120006", 
        "expiration_month": 12, 
        "address": {
            "city": "San Francisco", 
            "region": "CA", 
            "postal_code": "94404", 
            "line1": "900 Metro Center Blv", 
            "country": "USA"
        }, 
        "security_code": "022", 
        "type": "PAYMENT_CARD", 
        "identity": "IDdWXvfUtyqdA6kKFgEu8dkQ"
    }'

Example Response:

{
  "id" : "PIvPgFf5Tx6tfCe6k7uKYnwi",
  "application" : "AP6rt8kfRVoi9Si1i3oJTkos",
  "fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 12,
  "expiration_year" : 2029,
  "bin" : "489514",
  "last_four" : "0006",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Alex Wade",
  "address" : {
    "line1" : "900 Metro Center Blv",
    "line2" : null,
    "city" : "San Francisco",
    "region" : "CA",
    "postal_code" : "94404",
    "country" : "USA"
  },
  "address_verification" : "UNKNOWN",
  "security_code_verification" : "UNKNOWN",
  "created_at" : "2021-11-22T23:50:47.87Z",
  "updated_at" : "2021-11-22T23:50:47.88Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDdWXvfUtyqdA6kKFgEu8dkQ",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvPgFf5Tx6tfCe6k7uKYnwi"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvPgFf5Tx6tfCe6k7uKYnwi/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvPgFf5Tx6tfCe6k7uKYnwi/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvPgFf5Tx6tfCe6k7uKYnwi/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP6rt8kfRVoi9Si1i3oJTkos"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDdWXvfUtyqdA6kKFgEu8dkQ"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvPgFf5Tx6tfCe6k7uKYnwi/updates"
    }
  }
}

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.

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
name string, optional Full name of the registered card holder
currency string, required 3-letter ISO code designating the currency of the Payment Instruments (e.g. USD, CAD)
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
line2 string, optional Second line of the address
city string, required City
region string, optional 2-letter State code
postal_code string, optional Zip or Postal code
country string, optional 3-Letter Country code

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.

curl https://finix.sandbox-payments-api.com/payment_instruments/PIpRfLXq5ejK8ZefS3gxDNz7/verifications \
    -H "Content-Type: application/vnd.json+api" \
    -u USxpFPfqbFXM5jBZPmmCAwEm:e4359f08-b9e9-463f-b5f3-fcf8c65ec54e \
    -d '
    {
        "processor": "VISA_V1"
    }'

Example Response:

{
  "id" : "VI8eTGSVVsbAh2RvsKvk7AAn",
  "application" : "AP6rt8kfRVoi9Si1i3oJTkos",
  "tags" : { },
  "messages" : [ ],
  "raw" : {
    "validation_details" : {
      "systems_trace_audit_number" : "132623207974",
      "error_result" : null,
      "transaction_identifier" : "549914509459124",
      "approval_code" : null,
      "action_code" : "25",
      "response_code" : "5",
      "address_verification_results" : "I",
      "cvv2_result_code" : "P"
    },
    "inquiry_details" : {
      "systems_trace_audit_number" : "132623207974",
      "error_result" : null,
      "visa_network_info" : [ {
        "card_type_code" : "D",
        "billing_currency_code" : 840,
        "billing_currency_minor_digits" : 2,
        "issuer_name" : "Visa Test Bank",
        "card_issuer_country_code" : 840,
        "fast_funds_indicator" : "D",
        "push_funds_block_indicator" : "C",
        "online_gambing_block_indicator" : "N"
      } ],
      "ppgs_network_info" : [ ]
    },
    "general_inquiry_details" : {
      "systems_trace_audit_number" : "132623207974",
      "error_result" : null,
      "card_product_id" : "B",
      "card_product_name" : "Visa Traditional Rewards",
      "card_product_subtype_code" : "",
      "card_product_subtype_description" : "",
      "card_type_code" : "C",
      "card_subtype_code" : "",
      "card_platform_code" : "CN",
      "issuer_name" : "BANCO AGROMERCANTIL DE GUATEMALA S.A.",
      "bin" : "481507",
      "country_code" : "320",
      "status" : {
        "status_code" : "CDI000",
        "status_description" : "Success"
      }
    }
  },
  "processor" : "VISA_V1",
  "state" : "SUCCEEDED",
  "created_at" : "2021-11-22T23:51:39.85Z",
  "updated_at" : "2021-11-22T23:51:42.68Z",
  "trace_id" : "132623207974",
  "payment_instrument" : "PI2waD7kEq8by3vrB6bQBsGH",
  "merchant" : null,
  "identity" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VI8eTGSVVsbAh2RvsKvk7AAn"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP6rt8kfRVoi9Si1i3oJTkos"
    },
    "payment_instrument" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2waD7kEq8by3vrB6bQBsGH"
    }
  }
}

HTTP Request

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

URL Parameters

Parameter Description
:PAYMENT_INSTRUMENT_ID ID of the Payment Instrument

Request Arguments

Field Type Description
processor string, required The name of the processor, which needs to be: VISA_V1
country string, optional 3-Letter Country code. This attribute is currently only applicable for our Latin America partners.

Address Verification Results (address_verification_results)

Letter Description
D, F, M, Y Address verified
A, B, C, G, I, N, P, R, S, U, W Address not verified
Z Postal/ZIP match, street addresses do not match or street address not included in request

Card Verification 2 Results (cvv2_result_code)

Letter Description
M CVV and expiration verified
N, P, S Either CVV or expiration date is incorrect
U Issuer does not participate in CVV2 service

Card Type (card_type_code)

This one-character code indicates whether the account is credit, debit, prepaid, deferred debit, or charge.

Letter Description
C Credit
D Debit
H Charge Card
P Prepaid
R Deferred Debit

Fasts Funds Indicator (fast_funds_indicator)

Indicates whether or not the card is Fast Funds eligible (i.e. if the funds will settle in 30 mins or less). If not eligible, typically funds will settle within 2 business days.

Letter Description
B Fast Funds eligible for all transactions
D Fast Funds eligible for only domestic transactions
N Not eligible for Fast Funds

Push Funds Indicator (push_funds_block_indicator)

This code indicates if the associated card can receive push-to-card disbursements.

Letter Description
A, B, C Accepts push-to-card payments
N Does not accept push-to-card payments

Online Gambling Block Indicator (online_gambing_block_indicator)

Indicates if the card can receive push-payments for online gambling payouts.

Letter Description
Y Blocked for online gambling payouts
N Not blocked for online gambling payouts

Card Product ID (card_product_id)

A combination of card brand, platform, class and scheme.

Letter Description
A Visa Traditional
AX American Express
B Visa Traditional Rewards
C Visa Signature
D Visa Signature Preferred
DI Discover
DN Diners
E Proprietary ATM
F Visa Classic
G Visa Business
G1 Visa Signature Business
G2 Visa Business Check Card
G3 Visa Business Enhanced
G4 Visa Infinite Business
G5 Visa Business Rewards
I Visa Infinite
I1 Visa Infinite Privilege
I2 Visa UHNW
J3 Visa Healthcare
JC JCB
K Visa Corporate T&E
K1 Visa Government Corporate T&E
L Visa Electron
M MasterCard
N Visa Platinum
N1 Visa Rewards
N2 Visa Select
P Visa Gold
Q Private Label
Q1 Private Label Prepaid
Q2 Private Label Basic
Q3 Private Label Standard
Q4 Private Label Enhanced
Q5 Private Label Specialized
Q6 Private Label Premium
R Proprietary
S Visa Purchasing
S1 Visa Purchasing with Fleet
S2 Visa Government Purchasing
S3 Visa Government Purchasing with Fleet
S4 Visa Commercial Agriculture
S5 Visa Commercial Transport
S6 Visa Commercial Marketplace
U Visa Travel Money
V Visa V PAY

Product Sub-Type (card_product_subtype)

Description of product subtype.

Letter Description
AC Agriculture Maintenance Account
AE Agriculture Debit Account/Electron
AG Agriculture
AI Agriculture Investment Loan
CG Brazil Cargo
CS Construction
DS Distribution
HC Healthcare
LP Visa Large Purchase Advantage
MA Visa Mobile Agent
MB Interoperable Mobile Branchless Banking
MG Visa Mobile General
VA Visa Vale - Supermarket
VF Visa Vale - Fuel
VR Visa Vale - Restaurant

Card Sub-Type (card_subtype_code)

The code for account funding source subtype, such as reloadable and non-reloadable.

Letter Description
N Non-Reloadable
R Reloadable

Step 4: Provision a Sender Account

curl https://finix.sandbox-payments-api.com/identities/IDszD87NDFCEebMFuCeYewn6/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u USxpFPfqbFXM5jBZPmmCAwEm:e4359f08-b9e9-463f-b5f3-fcf8c65ec54e \
    -d '
    {
        "processor": "VISA_V1"
    }'

Example Response:

{
  "id" : "MUtMjxRLLJzAmbD9Wkhw7dKn",
  "application" : "AP6rt8kfRVoi9Si1i3oJTkos",
  "identity" : "IDszD87NDFCEebMFuCeYewn6",
  "verification" : "VIpinEDxGHue5iR8E8urYoLp",
  "merchant_profile" : "MPrx78a3CAEvKqGPB5whV9XA",
  "processor" : "VISA_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "card_expiration_date_required" : true,
  "card_cvv_required" : false,
  "tags" : { },
  "mcc" : null,
  "mid" : null,
  "merchant_name" : "Walter Le",
  "settlement_funding_identifier" : "UNSET",
  "ready_to_settle_upon" : null,
  "fee_ready_to_settle_upon" : "RECONCILIATION",
  "level_two_level_three_data_enabled" : false,
  "created_at" : "2021-11-22T23:50:49.08Z",
  "updated_at" : "2021-11-22T23:50:49.37Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUtMjxRLLJzAmbD9Wkhw7dKn"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDszD87NDFCEebMFuCeYewn6"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUtMjxRLLJzAmbD9Wkhw7dKn/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPrx78a3CAEvKqGPB5whV9XA"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP6rt8kfRVoi9Si1i3oJTkos"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIpinEDxGHue5iR8E8urYoLp"
    }
  }
}

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.

HTTP Request

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

Request Arguments

Field Type Description
processor string, optional Name of Processor

Step 5: Pull Funds

curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/vnd.json+api" \
    -u USxpFPfqbFXM5jBZPmmCAwEm:e4359f08-b9e9-463f-b5f3-fcf8c65ec54e \
    -d '
    {
        "currency": "USD", 
        "amount": 20000, 
        "source": "PIvPgFf5Tx6tfCe6k7uKYnwi", 
        "operation_key": "PULL_FROM_CARD", 
        "tags": {
            "order_number": "21DFASJSAKAS"
        }
    }'

Example Response:

{
  "id" : "TRQYyLACCyHvwLBea77PX9t",
  "amount" : 20000,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "trace_id" : "132623207972",
  "currency" : "USD",
  "application" : "AP6rt8kfRVoi9Si1i3oJTkos",
  "source" : "PIvPgFf5Tx6tfCe6k7uKYnwi",
  "destination" : null,
  "ready_to_settle_at" : null,
  "externally_funded" : "UNKNOWN",
  "fee" : 0,
  "statement_descriptor" : null,
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2021-11-22T23:50:52.55Z",
  "updated_at" : "2021-11-22T23:50:53.74Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDckAWf8Ukc6CqNACwxZpNGU",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP6rt8kfRVoi9Si1i3oJTkos"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRQYyLACCyHvwLBea77PX9t"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDckAWf8Ukc6CqNACwxZpNGU"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRQYyLACCyHvwLBea77PX9t/payment_instruments"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRQYyLACCyHvwLBea77PX9t/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRQYyLACCyHvwLBea77PX9t/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRQYyLACCyHvwLBea77PX9t/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvPgFf5Tx6tfCe6k7uKYnwi"
    },
    "fee_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
    }
  }
}

Now it’s time to pull funds from the sender.

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)
currency string, required 3-letter ISO code designating the currency of the Transfers (e.g. USD, CAD)
operation_key string, required PULL_FROM_CARD
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)
country string, optional 3-Letter Country code. This attribute is currently only applicable for our Latin America partners.

Reverse a Pull-from-Card Transfer


curl https://finix.sandbox-payments-api.com/transfers/TRQYyLACCyHvwLBea77PX9t/reversals \
    -H "Content-Type: application/vnd.json+api" \
    -u  USxpFPfqbFXM5jBZPmmCAwEm:e4359f08-b9e9-463f-b5f3-fcf8c65ec54e \
    -d  '
                  {
                  "refund_amount" : 100
                  }
                '

Example Response:

{
  "id" : "TRfeZv9MNW31DdXDRFZRRyrb",
  "amount" : 100,
  "tags" : { },
  "state" : "SUCCEEDED",
  "trace_id" : "132623207973",
  "currency" : "USD",
  "application" : "AP6rt8kfRVoi9Si1i3oJTkos",
  "source" : null,
  "destination" : "PIvPgFf5Tx6tfCe6k7uKYnwi",
  "ready_to_settle_at" : null,
  "externally_funded" : "UNKNOWN",
  "fee" : 0,
  "statement_descriptor" : "FIN*FINIXPAYMENTS",
  "type" : "REVERSAL",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2021-11-22T23:51:23.37Z",
  "updated_at" : "2021-11-22T23:51:24.10Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDckAWf8Ukc6CqNACwxZpNGU",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP6rt8kfRVoi9Si1i3oJTkos"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRfeZv9MNW31DdXDRFZRRyrb"
    },
    "parent" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRQYyLACCyHvwLBea77PX9t"
    },
    "destination" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvPgFf5Tx6tfCe6k7uKYnwi"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDckAWf8Ukc6CqNACwxZpNGU"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRfeZv9MNW31DdXDRFZRRyrb/payment_instruments"
    },
    "fee_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
    }
  }
}

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.

A Reversal can have one subtype indicating how it was created:

HTTP Request

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

URL Parameters

Parameter Description
:TRANSFER_ID ID of the original Transfer

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)

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.

  1. Android SDK

  2. iOS SDK

Android SDK

Step 1: Installation

In the root module, make sure jcenter() is listed inside the repositories section. In the module, add this line to its build.gradle inside the dependencies section.

implementation 'com.payment.android:sdk:1.4'

Step 2: Instantiate Instrument Class

Create an Instrument and pass it the card number, expiration year, and expiration month.

 Instrument instrument = new Instrument(cardNumber, paymentType, expirationYear, expirationMonth);  

 Instrument instrument = new Instrument("4111111111111111", "PAYMENT_CARD", "2022", "12");
Arguments
Field Type Description
cardNumber string, required Payment card account number
paymentType string, required Use “Payment_CARD”
expirationYear integer, required 4-digit expiration year
expirationMonth integer, required Expiration month (e.g. 12 for December)

Step 3: Instantiate PaymentsSDK Class

Next, create a PaymentsSDK object and pass it either a sandbox or a live endpoint. In the second argument you will need to pass the Application ID.

PaymentsSDK paymentsSDK = new PaymentsSDK(apiEndpoint, applicationId);;  

PaymentsSDK paymentsSDK = new PaymentsSDK(https://finix.sandbox-payments-api.com, APj9Gw6wRhpbaHJM1QtZakqH);;
Arguments
Field Type Description
apiEndpoint string, required Sandbox or Live API endpoint (e.g. https://finix.sandbox-payments-api.com for Sandbox)
applicationId string, required ID of Application

Step 4: Tokenize Payment Card

Lastly, you will tokenize the payment card from that you received from step two by passing it to the Tokenize function.

Token token = paymentsSDK.Tokenize(instrument);

iOS SDK

Step 1: Import Payments SDK

Import the Payments SDK with with CocoaPods by adding pod 'PaymentsSDK', '~> 1.0.4' to the Podfile

Step 2: Import Library

Import PaymentsSDK by running import PaymentsSDK

 import PaymentsSDK

Step 3: Initialize Tokenizer Class

First, initiate Tokenizer class and pass it a sandbox or live endpoint. In addition to the endpoint, you need to pass the Application ID to the Tokenizer function.

let tokenizer = Tokenizer(
  host: apiEndpoint,
  applicationId: applicationId)

let tokenizer = Tokenizer(
  host: https://finix.sandbox-payments-api.com,
  applicationId: APj9Gw6wRhpbaHJM1QtZakqH)
Arguments
Field Type Description
apiEndpoint string, required Sandbox or Live API endpoint (e.g. https://finix.sandbox-payments-api.com for Sandbox)
applicationId string, required ID of Application

Step 4: Tokenize Payment Card

Lastly, pass the card number, payment type, expiration month and year to the createToken function.

tokenizer.createToken(
  cardNumber: cardNumber,
  paymentType: paymentType,
  expirationMonth: expirationMonth,
  expirationYear: expirationYear) { (token, error) in
       guard let token = token else {
           print(error!.localizedDescription)
           return
       }
       print(token.id)
       print(token.fingerprint)
}   

tokenizer.createToken(
  cardNumber: "4111111111111111",
  paymentType: "PAYMENT_CARD",
  expirationMonth: 12,
  expirationYear: 2021) { (token, error) in
       guard let token = token else {
           print(error!.localizedDescription)
           return
       }
       print(token.id)
       print(token.fingerprint)
}
Arguments
Field Type Description
cardNumber string, required Payment card account number
paymentType string, required Use “Payment_CARD”
expirationYear integer, required 4-digit expiration year
expirationMonth integer, required Expiration month (e.g. 12 for December)

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.

Step 1: Provision Merchant with triPOS

curl https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR/merchants \
        -H "Content-Type: application/vnd.json+api" \
        -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
        -d '
        {
            "processor": "VANTIV_V1",
            "gateway": "TRIPOS_CLOUD_V1"
        }'

HTTP Request

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

URL Parameters

Parameter Description
:IDENTITY_ID ID of the Identity

Request Arguments

Field Type Description
processor string, required Name of the processor
gateway string, required Name of the gateway
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers) 
{
  "id" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "verification" : "VIhjGSJCnvXLzFQZUsUaeHxb",
  "merchant_profile" : "MPgDcdhXsdcJ9MVeJrZRNp79",
  "processor" : "VANTIV_V1",
  "processing_enabled" : false,
  "settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "tags" : { },
  "created_at" : "2019-03-01T00:49:02.47Z",
  "updated_at" : "2019-03-01T00:49:02.47Z",
  "onboarding_state" : "PROVISIONING",
  "processor_details" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPgDcdhXsdcJ9MVeJrZRNp79"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIhjGSJCnvXLzFQZUsUaeHxb"
    }
  }
}

Step 2: Create Device

curl https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd/devices \
        -H "Content-Type: application/vnd.json+api" \
        -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
        -d '
      {
        "name": "Finix  triPOS #1",
        "model": "MX915",
        "description": "Mike Jones",
        "configuration": {
          "allow_debit": true,
          "prompt_signature": "NEVER"
        }
      }'

HTTP Request

POST https://finix.sandbox-payments-api.com/merchants/:MERCHANT_ID/devices

URL Parameters

Field Type Description
:MERCHANT_ID string, required ID of Device

Request Arguments

Field Type Description
model string, required 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

Field Type Description
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) 
{
  "id" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "name" : "Finix  triPOS #1",
  "model" : "MX915",
  "description" : "Mike Jones",
  "serial_number" : null,
  "idle_message" : null,
  "enabled" : false,
  "device_config_details" : {
    "allow_debit" : true,
    "check_for_duplicate_transactions" : true,
    "prompt_amount_confirmation" : true,
    "prompt_manual_entry" : false,
    "prompt_signature" : "NEVER",
    "signature_threshold_amount" : 0
  },
  "created_at" : "2019-03-01T01:07:17.015",
  "updated_at" : "2019-03-01T01:07:17.022",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "activations" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf/activations"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations"
    }
  }
}

Step 3: Activate Device

curl https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf \
  -H "Content-Type: application/vnd.json+api" \
  -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
  -X PUT \
  -d '
    {
      "activation_code": "C887298",
      "action": "ACTIVATE"
    }'

HTTP Request

PUT https://finix.sandbox-payments-api.com/devices/:DEVICE_ID

URL Parameters

Field Type Description
:DEVICE_ID string, required ID of Device

Request Arguments

Field Type Description
action string, required The action parameter must include ACTIVATE for to enable device
activation_code string, required Input the code that’s displayed on the device screen
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers) 
{
  "id" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "name" : "Finix Tripos #1",
  "model" : "MX915",
  "description" : "Mike Jones",
  "serial_number" : "262-410-025",
  "idle_message" : null,
  "enabled" : true,
  "tags" : { },
  "created_at" : "2019-03-01T02:27:20.366",
  "updated_at" : "2019-03-11T23:19:44.378",
  "configuration_details" : {
    "allow_debit" : true,
    "check_for_duplicate_transactions" : true,
    "prompt_amount_confirmation" : true,
    "prompt_manual_entry" : false,
    "prompt_signature" : "NEVER",
    "signature_threshold_amount" : 0
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations"
    }
  }
}

Step 4: Authorization with EMV card

curl https://finix.sandbox-payments-api.com/authorizations \
   -H "Content-Type: application/vnd.json+api" \
   -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
   -d '
   {
     "device": "DVf2H8sh4LZZC52GTUrwCPPf",
     "tags": {
       "order_number": "chris123transfer"
     },
     "currency": "USD",
     "amount": 150,
     "operation_key": "CARD_PRESENT_AUTHORIZATION"
   }'

HTTP Request

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

Request Arguments

Field Type Description
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)
device string, required The ID of the activated device
amount integer, required Amount of sale
currency string, required Currency of sale
operation_key string, required Describes the operation to be performed in the transaction

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)

{
  "id" : "TReEok8811pDqsR1BbxZLbw1",
  "amount" : 150,
  "tags" : {
    "order_number" : "chris123transfer"
  },
  "state" : "SUCCEEDED",
  "trace_id" : "FNXmEM7d6ns8LMMzt61AD8TrR",
  "currency" : "USD",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "source" : "PIcW77CfRyBUWJhA231TWXWf",
  "destination" : null,
  "ready_to_settle_at" : null,
  "fee" : 0,
  "statement_descriptor" : "FIN*GOLDS GYM",
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "card_present_details" : {
    "emv_data" : {
      "application_identifier" : "A0000000031010",
      "application_label" : "Visa Credit",
      "application_preferred_name" : null,
      "application_transaction_counter" : "004F",
      "cryptogram" : "TC F8C706E8A0368D15",
      "issuer_code_table_index" : null,
      "pin_verified" : false
    },
    "masked_account_number" : "************7564",
    "name" : "AARON/CHRISTOPHER W ",
    "brand" : "VISA",
    "entry_mode" : "CHIP_ENTRY",
    "payment_type" : "CREDIT",
    "approval_code" : "000036"
  },
  "created_at" : "2019-03-11T23:36:42.03Z",
  "updated_at" : "2019-03-11T23:36:57.09Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "device" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1/payment_instruments"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR"
    },
    "device" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIcW77CfRyBUWJhA231TWXWf"
    }
  }

Step 5: Capture Authorization

curl https://finix.sandbox-payments-api.com/authorizations/AUuCfRve8QG6G1wnPCReiLma \
   -H "Content-Type: application/vnd.json+api" \
   -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
   -X PUT \
   -d '
     {
         "capture_amount": 150
     }'

HTTP Request

PUT https://finix.sandbox-payments-api.com/authorizations/:AUTHORIZATION_ID

URL Parameters

Field Type Description
AUTHORIZATION_ID string, required ID of Device

Request Arguments

Field Type Description
capture_amount integer, required The amount of the Authorization you would like to capture in cents. 
{
  "id" : "AUuCfRve8QG6G1wnPCReiLma",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "amount" : 150,
  "tags" : {
    "order_number" : "chris123transfer"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : "TRjiUo5CXLmaJp4k9PL7iP8z",
  "messages" : [ ],
  "raw" : null,
  "card_present_details" : null,
  "created_at" : "2019-03-01T03:42:13.59Z",
  "updated_at" : "2019-03-01T03:49:28.67Z",
  "trace_id" : "957ce193-b4e4-4a39-88e2-d88a019982d2",
  "source" : "PIjnHHLBZvRu6GPEZdFt7E2q",
  "merchant_identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "device" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "is_void" : false,
  "expires_at" : "2019-03-08T03:42:13.59Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUuCfRve8QG6G1wnPCReiLma"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "transfer" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRjiUo5CXLmaJp4k9PL7iP8z"
    },
    "device" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR"
    }
  }
}

Authorizations

An Authorization (also known as a card hold) reserves a specific amount on a card to be captured (i.e. debited) at a later date, usually within seven days. When an Authorization is captured it produces a Transfer resource.

Create an Authorization

curl https://finix.sandbox-payments-api.com/authorizations \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -d '
    {
        "source": "PIatE9xdPZTKdeeuyeLcB2Kj", 
        "merchant_identity": "IDnKHJ7wtcJDhK9RgSqFiYgr", 
        "tags": {
            "order_number": "21DFASJSAKAS"
        }, 
        "currency": "USD", 
        "amount": 100, 
        "processor": "DUMMY_V1"
    }'

Example Response:

{
  "id" : "AU2BunwBkS6Er4LeY36P2TCJ",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2021-11-22T23:51:24.93Z",
  "updated_at" : "2021-11-22T23:51:25.18Z",
  "trace_id" : "b3276081-1cf0-4300-ab46-f727a6e2d3fe",
  "source" : "PIatE9xdPZTKdeeuyeLcB2Kj",
  "merchant_identity" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
  "3ds_redirect_url" : null,
  "is_void" : false,
  "void_state" : "UNATTEMPTED",
  "expires_at" : "2021-11-29T23:51:24.93Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AU2BunwBkS6Er4LeY36P2TCJ"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
    }
  }
}

Authorizations can 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.

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
amount integer, required The amount of the authorization in cents
currency string, required 3-letter ISO code designating the currency (e.g. USD)
processor string, optional If the Application has more than one processor association, it’s required to pass the processor (e.g. DUMMY_V1)
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)
idempotency_id string, optional A randomly generated value that you want associated with the request

Create an Authorization with 3D Secure

curl https://finix.sandbox-payments-api.com/authorizations \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -d '
    {
        "merchant": "MUfWNiRCntW1KCRVjH4jEoba", 
        "3d_secure_authentication": {
            "electronic_commerce_indicator": "AUTHENTICATED", 
            "cardholder_authentication": "BwABBJQ1AgAAAAAgJDUCAAAAAAA=", 
            "transaction_id": "EaOMucALHQqLAEGAgk"
        }, 
        "source": "PIatE9xdPZTKdeeuyeLcB2Kj", 
        "tags": {
            "order_number": "21DFASJSAKAS"
        }, 
        "currency": "USD", 
        "amount": 100
    }'

Example Response:

{
  "id" : "AUfgUSmTmLfuM5sSCLwB5VVs",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2021-11-22T23:51:25.92Z",
  "updated_at" : "2021-11-22T23:51:25.99Z",
  "trace_id" : "42905fcf-deef-4f20-8510-5c32cdb4d3d0",
  "source" : "PIatE9xdPZTKdeeuyeLcB2Kj",
  "merchant_identity" : "ID2cAnM4kbLE4abQWj2fydHw",
  "3ds_redirect_url" : null,
  "is_void" : false,
  "void_state" : "UNATTEMPTED",
  "expires_at" : "2021-11-29T23:51:25.92Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUfgUSmTmLfuM5sSCLwB5VVs"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw"
    }
  }
}

Authorizations can 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.

3D Secure 2.0 allows end-users to authenticate a transaction by having the cardholder authenticate with their issuing bank. By enabling 3D Secure on a transaction, you are shifting the liability of a chargeback from the merchant to the issuing bank. The integration requires a 3D Secure vendor to generate the values needed for 3d_secure_authentication.

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

HTTP Request

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

Request Arguments

Field Type Description
amount integer, required The total amount that will be debited in cents (e.g. 100 cents to debit $1.00)
currency string, required 3-letter ISO code designating the currency of the Transfers (e.g. USD)processor
fee integer, optional The amount of the Transfer you would like to collect as your fee in cents. Defaults to zero (Must be less than or equal to the amount)
idempotency_id string, optional A randomly generated value that you want associated with the request
merchant string, optional Merchant ID of the merchant whom you’re charging on behalf of
source string, required ID of the Payment Instrument that will be debited
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)

3d_secure_authentication-object Request Arguments

Field Type Description
cardholder_authentication string, required Provides evidence that the cardholder authentication occurred or that the merchant attempted authentication. This is unique for each authentication transaction.
cardholder_ip_address integer, optional Only required for American Express cards. Format is nnn.nnn.nnn.nnn
electronic_commerce_indicator string, required AUTHENTICATED: Approved by 3D Secure Vendor; ATTEMPTED: Issuer or cardholder does not support 3D Secure
transaction_id string, optional Only valid for Visa transactions

Create an Authorization with Level 2 Processing

curl https://finix.sandbox-payments-api.com/authorizations \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -d '
    {
        "merchant": "MUfWNiRCntW1KCRVjH4jEoba", 
        "source": "PIatE9xdPZTKdeeuyeLcB2Kj", 
        "additional_purchase_data": {
            "customer_reference_number": "321xyz", 
            "sales_tax": 200
        }, 
        "tags": {
            "order_number": "21DFASJSAKAS"
        }, 
        "currency": "USD", 
        "amount": 1000, 
        "processor": "DUMMY_V1"
    }'

Example Response:

{
  "id" : "AUmxvofebCU94QBYwnHV14Mb",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "amount" : 1000,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2021-11-22T23:51:26.70Z",
  "updated_at" : "2021-11-22T23:51:26.86Z",
  "trace_id" : "29791b12-b1fb-49e2-977a-531ca81bcdc3",
  "source" : "PIatE9xdPZTKdeeuyeLcB2Kj",
  "merchant_identity" : "ID2cAnM4kbLE4abQWj2fydHw",
  "3ds_redirect_url" : null,
  "is_void" : false,
  "void_state" : "UNATTEMPTED",
  "expires_at" : "2021-11-29T23:51:26.70Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUmxvofebCU94QBYwnHV14Mb"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw"
    }
  }
}

See request arguments table below for the fields that are required to meet Level 2 processing for an Authorization.

A Merchant first needs to be enabled for Level 2 and Level 3. Update Merchant to Enable Level 2/Level 3 Processing.

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
amount integer, required The amount of the authorization in cents
currency string, required 3-letter ISO code designating the currency (e.g. USD)
processor string, optional If the Application has more than one processor association, it’s required to pass the processor (e.g. DUMMY_V1)
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)
idempotency_id string, optional A randomly generated value that you want associated with the request

additional_purchase_data-object Request Arguments

Field Type Description
customer_reference_number string, required The customer reference for the purchase (max 17 characters)
customs_duty_amount integer, required The duty in cents on the total purchase amount for the order
destination_country_code string, optional The ISO country code of the order destination
destination_postal_code string, optional The postal code of the order destination (10 characters)
discount_amount integer, required The amount in cents of the discount for the order
invoice_reference_number string, optional The order’s invoice number (max 15 characters)
sales_tax integer, optional Total aggregate tax amount in cents for the entire purchase. Field is automatically calculated if you pass in the itemized tax amounts. For non-taxable transactions either set sales_tax to 0 or omit from payload and also set tax_exempt to True.
ship_from_postal_code string, optional The postal code from where order is shipped (10 characters)
shipping_amount integer, required The shipping cost in cents for the order
tax_exempt boolean, optional For tax exempt purchases set to True

order_date-object Request Arguments

Field Type Description
day integer, required Day of purchase (between 1 and 31)
month integer, required Month of purchase (between 1 and 12)
year integer, required Year of purchase (4-digit)

item_data-object Request Arguments

Field Type Description
amount_excluding_sales_tax integer, required Total cost in cents of the line item excluding tax
amount_including_sales_tax integer, required Total cost in cents of the line item including tax
commodity_code string, required A commodity code is a numeric code representing a particular product or service as defined by the National Institute of Governmental Purchasing. The code can be 3, 5, 7, or 11 digits in length. The longer the code the more granular the description of the product/service. (max 12 characters)
cost_per_unit integer, required The price in cents of one unit of the item purchased
item_description string, required Required when item_data is supplied (max 25 characters)
item_discount_amount integer, required Item discount amount in cents
merchant_product_code string, required Merchant defined product code (max 12 characters)
quantity integer, required The number of items purchased. Must be greater than 0.
unit_of_measure string, required The unit of measure of the purchased item (max 3 characters)

Create an Authorization with Level 3 Processing

curl https://finix.sandbox-payments-api.com/authorizations \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -d '
    {
        "merchant": "MUfWNiRCntW1KCRVjH4jEoba", 
        "source": "PIatE9xdPZTKdeeuyeLcB2Kj", 
        "additional_purchase_data": {
            "item_data": [
                {
                    "amount_including_sales_tax": 500, 
                    "unit_of_measure": "BX", 
                    "merchant_product_code": "1149611", 
                    "amount_excluding_sales_tax": 400, 
                    "cost_per_unit": 500, 
                    "commodity_code": "175-62-20", 
                    "item_discount_amount": 100, 
                    "item_description": "printing paper", 
                    "quantity": 1
                }, 
                {
                    "amount_including_sales_tax": 500, 
                    "unit_of_measure": "CTN", 
                    "merchant_product_code": "2149612", 
                    "amount_excluding_sales_tax": 400, 
                    "cost_per_unit": 500, 
                    "commodity_code": "207-72-54", 
                    "item_discount_amount": 0, 
                    "item_description": "printing ink", 
                    "quantity": 1
                }
            ], 
            "discount_amount": 100, 
            "customer_reference_number": "321xyz", 
            "shipping_amount": 100, 
            "customs_duty_amount": 10
        }, 
        "tags": {
            "order_number": "21DFASJSAKAS"
        }, 
        "currency": "USD", 
        "amount": 1000, 
        "processor": "DUMMY_V1"
    }'

Example Response:

{
  "id" : "AUmAwTs9CdEMnXCxWTJPLgeX",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "amount" : 1000,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2021-11-22T23:51:27.64Z",
  "updated_at" : "2021-11-22T23:51:27.74Z",
  "trace_id" : "25dee937-fb7a-4079-8ee2-01c4c64c0953",
  "source" : "PIatE9xdPZTKdeeuyeLcB2Kj",
  "merchant_identity" : "ID2cAnM4kbLE4abQWj2fydHw",
  "3ds_redirect_url" : null,
  "is_void" : false,
  "void_state" : "UNATTEMPTED",
  "expires_at" : "2021-11-29T23:51:27.64Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUmAwTs9CdEMnXCxWTJPLgeX"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw"
    }
  }
}

See request arguments table below for the fields that are required to meet Level 3 processing for an Authorization.

A Merchant first needs to be enabled for Level 2 and Level 3. Update Merchant to Enable Level 2/Level 3 Processing.

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
amount integer, required The amount of the authorization in cents
currency string, required 3-letter ISO code designating the currency (e.g. USD)
processor string, optional If the Application has more than one processor association, it’s required to pass the processor (e.g. DUMMY_V1)
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)
idempotency_id string, optional A randomly generated value that you want associated with the request

additional_purchase_data-object Request Arguments

Field Type Description
customer_reference_number string, required The customer reference for the purchase (max 17 characters)
customs_duty_amount integer, required The duty in cents on the total purchase amount for the order
destination_country_code string, optional The ISO country code of the order destination
destination_postal_code string, optional The postal code of the order destination (10 characters)
discount_amount integer, required The amount in cents of the discount for the order
invoice_reference_number string, optional The order’s invoice number (max 15 characters)
sales_tax integer, optional Total aggregate tax amount in cents for the entire purchase. Field is automatically calculated if you pass in the itemized tax amounts. For non-taxable transactions either set sales_tax to 0 or omit from payload and also set tax_exempt to True.
ship_from_postal_code string, optional The postal code from where order is shipped (10 characters)
shipping_amount integer, required The shipping cost in cents for the order
tax_exempt boolean, optional For tax exempt purchases set to True

order_date-object Request Arguments

Field Type Description
day integer, required Day of purchase (between 1 and 31)
month integer, required Month of purchase (between 1 and 12)
year integer, required Year of purchase (4-digit)

item_data-object Request Arguments

Field Type Description
amount_excluding_sales_tax integer, required Total cost in cents of the line item excluding tax
amount_including_sales_tax integer, required Total cost in cents of the line item including tax
commodity_code string, required A commodity code is a numeric code representing a particular product or service as defined by the National Institute of Governmental Purchasing. The code can be 3, 5, 7, or 11 digits in length. The longer the code the more granular the description of the product/service. (max 12 characters)
cost_per_unit integer, required The price in cents of one unit of the item purchased
item_description string, required Required when item_data is supplied (max 25 characters)
item_discount_amount integer, required Item discount amount in cents
merchant_product_code string, required Merchant defined product code (max 12 characters)
quantity integer, required The number of items purchased. Must be greater than 0.
unit_of_measure string, required The unit of measure of the purchased item (max 3 characters)

Capture an Authorization

curl https://finix.sandbox-payments-api.com/authorizations/AU2BunwBkS6Er4LeY36P2TCJ \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -X PUT \
    -d '
    {
        "fee": "10", 
        "capture_amount": 100
    }'

Example Response:

{
  "id" : "AU2BunwBkS6Er4LeY36P2TCJ",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : "TRdUn6SYuf4rEnv2a6Fkdf5a",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2021-11-22T23:51:24.93Z",
  "updated_at" : "2021-11-22T23:51:31.51Z",
  "trace_id" : "b3276081-1cf0-4300-ab46-f727a6e2d3fe",
  "source" : "PIatE9xdPZTKdeeuyeLcB2Kj",
  "merchant_identity" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
  "3ds_redirect_url" : null,
  "is_void" : false,
  "void_state" : "UNATTEMPTED",
  "expires_at" : "2021-11-29T23:51:24.93Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AU2BunwBkS6Er4LeY36P2TCJ"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "transfer" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRdUn6SYuf4rEnv2a6Fkdf5a"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
    }
  }
}

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

HTTP Request

PUT https://finix.sandbox-payments-api.com/authorizations/:AUTHORIZATION_ID

URL Parameters

Parameter Description
:AUTHORIZATION_ID ID of the Authorization

Request Arguments

Field Type Description
capture_amount integer, required The amount of the Authorization you would like to capture in cents. Must be less than or equal to the amount of the Authorization
fee integer, optional Amount of the captured Authorization you would like to collect as your fee. Must be less than or equal to the amount

Capture an Authorization with Level 2/Level 3 Processing

curl https://finix.sandbox-payments-api.com/authorizations/AUk8VUahZGVnLxswBGxuQpA1 \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -X PUT \
    -d '
    {
        "additional_purchase_data": {
            "item_data": [
                {
                    "amount_including_sales_tax": 500, 
                    "unit_of_measure": "BX", 
                    "merchant_product_code": "1149611", 
                    "amount_excluding_sales_tax": 400, 
                    "cost_per_unit": 500, 
                    "commodity_code": "175-62-20", 
                    "item_discount_amount": 100, 
                    "item_description": "printing paper", 
                    "quantity": 1
                }, 
                {
                    "amount_including_sales_tax": 500, 
                    "unit_of_measure": "CTN", 
                    "merchant_product_code": "2149612", 
                    "amount_excluding_sales_tax": 400, 
                    "cost_per_unit": 500, 
                    "commodity_code": "207-72-54", 
                    "item_discount_amount": 0, 
                    "item_description": "printing ink", 
                    "quantity": 1
                }
            ], 
            "discount_amount": 100, 
            "customer_reference_number": "321xyz", 
            "shipping_amount": 100, 
            "customs_duty_amount": 10
        }, 
        "fee": "10", 
        "capture_amount": 100
    }'

Example Response:

{
  "id" : "AUk8VUahZGVnLxswBGxuQpA1",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "amount" : 1000,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : "TRtTydMAg9rdmaCwDsPviQ9S",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2021-11-22T23:51:28.52Z",
  "updated_at" : "2021-11-22T23:51:29.55Z",
  "trace_id" : "dfc9c337-c871-417c-9f5b-a138fc0141d1",
  "source" : "PIatE9xdPZTKdeeuyeLcB2Kj",
  "merchant_identity" : "ID2cAnM4kbLE4abQWj2fydHw",
  "3ds_redirect_url" : null,
  "is_void" : false,
  "void_state" : "UNATTEMPTED",
  "expires_at" : "2021-11-29T23:51:28.52Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUk8VUahZGVnLxswBGxuQpA1"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "transfer" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRtTydMAg9rdmaCwDsPviQ9S"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw"
    }
  }
}

Unless the Level 2 and Level 3 data is different than the original Authorization, there’s no need to pass in the Level 2 and Level 3 data on the capture request. We will automatically pass in the Level 2 and Level 3 data on the capture.

HTTP Request

PUT https://finix.sandbox-payments-api.com/authorizations/:AUTHORIZATION_ID

URL Parameters

Parameter Description
:AUTHORIZATION_ID ID of the Authorization

Request Arguments

Field Type Description
capture_amount integer, required The amount of the Authorization you would like to capture in cents. Must be less than or equal to the amount of the Authorization
fee integer, optional Amount of the captured Authorization you would like to collect as your fee. Must be less than or equal to the amount

additional_purchase_data-object Request Arguments

Field Type Description
customer_reference_number string, optional The customer reference for the purchase (max 17 characters)
customs_duty_amount integer, optional The duty in cents on the total purchase amount for the order
destination_country_code string, optional The ISO country code of the order destination
destination_postal_code string, optional The postal code of the order destination
discount_amount integer, optional The amount in cents of the discount for the order
invoice_reference_number string, optional The order’s invoice number (max 15 characters)
sales_tax integer, optional Total aggregate tax amount in cents for the entire purchase. Field is automatically calculated if you pass in the itemized tax amounts. For non-taxable transactions either set sales_tax to 0 or omit from payload and also set tax_exempt to True.
ship_from_postal_code string, optional The postal code from where order is shipped
shipping_amount integer, optional The shipping cost in cents for the order
tax_exempt boolean, optional For tax exempt purchases set to True

order_date-object Request Arguments

Field Type Description
day integer, optional Day of purchase (between 1 and 31)
month integer, optional Month of purchase (between 1 and 12)
year integer, optional Year of purchase (4-digit)

item_data-object Request Arguments

Field Type Description
amount_excluding_sales_tax integer, optional Total cost in cents of the line item excluding tax
amount_including_sales_tax integer, optional Total cost in cents of the line item including tax
commodity_code string, optional A commodity code is a numeric code representing a particular product or service as defined by the National Institute of Governmental Purchasing. The code can be 3, 5, 7, or 11 digits in length. The longer the code the more granular the description of the product/service. (max 12 characters)
cost_per_unit integer, optional The price in cents of one unit of the item purchased
item_description string, optional Required when item_data is supplied (max 26 characters)
item_discount_amount integer, optional Item discount amount in cents
merchant_product_code string, optional Merchant defined product code (max 12 characters)
quantity integer, optional The number of items purchased. Must be greater than 0.
unit_of_measure string, optional The unit of measure of the purchased item (max 12 characters)

Void an Authorization


curl https://finix.sandbox-payments-api.com/authorizations/AUxNKMgymQLNvoqGf6pj1Jr \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -X PUT \
    -d '
    {
        "void_me": true
    }'

Example Response:

{
  "id" : "AUxNKMgymQLNvoqGf6pj1Jr",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2021-11-22T23:51:34.19Z",
  "updated_at" : "2021-11-22T23:51:35.23Z",
  "trace_id" : "753087cb-aaa5-4cae-ad34-294c68c5dc69",
  "source" : "PIatE9xdPZTKdeeuyeLcB2Kj",
  "merchant_identity" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
  "3ds_redirect_url" : null,
  "is_void" : true,
  "void_state" : "PENDING",
  "expires_at" : "2021-11-29T23:51:34.19Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUxNKMgymQLNvoqGf6pj1Jr"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
    }
  }
}

Cancels the Authorization, releasing the funds. If an Authorization is voided, it can no longer be captured.

HTTP Request

PUT https://finix.sandbox-payments-api.com/authorizations/:AUTHORIZATION_ID

URL Parameters

Parameter Description
:AUTHORIZATION_ID ID of the Authorization

Request Arguments

Field Type Description
void_me boolean, required Set to True to void the Authorization

[Card Present] Authorization with EMV card

curl https://finix.sandbox-payments-api.com/authorizations \
   -H "Content-Type: application/vnd.json+api" \
   -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
   -d '
   {
    "device": "DVf2H8sh4LZZC52GTUrwCPPf",
     "tags": {
       "order_number": "chris123transfer"
     },
     "currency": "USD",
     "amount": 150,
     "operation_key": "CARD_PRESENT_AUTHORIZATION"
   }'

HTTP Request

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

Request Arguments

Field Type Description
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)
device string, required The ID of the activated device
amount integer, required Amount of sale
currency string, required Currency of sale
operation_key string, required Describes the operation to be performed in the transaction
device_configuration#allow_debit boolean, optional 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) 
{
  "id" : "TReEok8811pDqsR1BbxZLbw1",
  "amount" : 150,
  "tags" : {
    "order_number" : "chris123transfer"
  },
  "state" : "SUCCEEDED",
  "trace_id" : "FNXmEM7d6ns8LMMzt61AD8TrR",
  "currency" : "USD",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "source" : "PIcW77CfRyBUWJhA231TWXWf",
  "destination" : null,
  "ready_to_settle_at" : null,
  "fee" : 0,
  "statement_descriptor" : "FIN*GOLDS GYM",
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "card_present_details" : {
    "emv_data" : {
      "application_identifier" : "A0000000031010",
      "application_label" : "Visa Credit",
      "application_preferred_name" : null,
      "application_transaction_counter" : "004F",
      "cryptogram" : "TC F8C706E8A0368D15",
      "issuer_code_table_index" : null,
      "pin_verified" : false
    },
    "masked_account_number" : "************7564",
    "name" : "AARON/CHRISTOPHER W ",
    "brand" : "VISA",
    "entry_mode" : "CHIP_ENTRY",
    "payment_type" : "CREDIT",
    "approval_code" : "000036"
  },
  "created_at" : "2019-03-11T23:36:42.03Z",
  "updated_at" : "2019-03-11T23:36:57.09Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "device" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1/payment_instruments"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR"
    },
    "device" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIcW77CfRyBUWJhA231TWXWf"
    }
  }

[Card Present] Authorization with non EMV card

curl https://finix.sandbox-payments-api.com/authorizations \
   -H "Content-Type: application/vnd.json+api" \
   -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
   -d '
   {
     "device": "DVf2H8sh4LZZC52GTUrwCPPf",
     "tags": {
       "order_number": "chris123transfer"
     },
     "currency": "USD",
     "amount": 150,
     "operation_key": "CARD_PRESENT_AUTHORIZATION"
   }'

HTTP Request

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

Request Arguments

Field Type Description
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)
device string, required The ID of the activated device
amount integer, required Amount of sale
currency string, required Currency of sale
operation_key string, required Describes the operation to be performed in the transaction
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#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) 
{
  "id" : "AUiJS1VhMy8zpACLoacPFG7m",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "amount" : 150,
  "tags" : {
    "order_number" : "chris123transfer"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "card_present_details" : {
    "emv_data" : null,
    "masked_account_number" : "************0011",
    "name" : "TEST/WORLDPAY",
    "brand" : "UNKNOWN",
    "entry_mode" : "SWIPED",
    "payment_type" : "CREDIT",
    "approval_code" : "000037"
  },
  "created_at" : "2019-03-01T03:37:10.10Z",
  "updated_at" : "2019-03-01T03:37:23.63Z",
  "trace_id" : "556185b9-ceaa-490b-bae2-a662757b42e0",
  "source" : "PIaqFoGabsBTTowVr5z7jiLv",
  "merchant_identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "device" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "is_void" : false,
  "expires_at" : "2019-03-08T03:37:10.10Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUiJS1VhMy8zpACLoacPFG7m"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "device" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR"
    }
  }
}

[Card Present] Capture Authorization

curl https://finix.sandbox-payments-api.com/authorizations/AUuCfRve8QG6G1wnPCReiLma \
   -H "Content-Type: application/vnd.json+api" \
   -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
   -X PUT \
   -d '
     {
         "capture_amount": 150
     }'

HTTP Request

PUT https://finix.sandbox-payments-api.com/authorizations/:AUTHORIZATION_ID

URL Parameters

Field Type Description
AUTHORIZATION_ID string, required ID of Authorization

Request Arguments

Field Type Description
capture_amount integer, required The amount of the Authorization you would like to capture in cents. 
{
  "id" : "AUuCfRve8QG6G1wnPCReiLma",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "amount" : 150,
  "tags" : {
    "order_number" : "chris123transfer"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : "TRjiUo5CXLmaJp4k9PL7iP8z",
  "messages" : [ ],
  "raw" : null,
  "card_present_details" : null,
  "created_at" : "2019-03-01T03:42:13.59Z",
  "updated_at" : "2019-03-01T03:49:28.67Z",
  "trace_id" : "957ce193-b4e4-4a39-88e2-d88a019982d2",
  "source" : "PIjnHHLBZvRu6GPEZdFt7E2q",
  "merchant_identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "device" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "is_void" : false,
  "expires_at" : "2019-03-08T03:42:13.59Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUuCfRve8QG6G1wnPCReiLma"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "transfer" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRjiUo5CXLmaJp4k9PL7iP8z"
    },
    "device" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR"
    }
  }
}

Fetch an Authorization


curl https://finix.sandbox-payments-api.com/authorizations/AU2BunwBkS6Er4LeY36P2TCJ \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88

Example Response:

{
  "id" : "AU2BunwBkS6Er4LeY36P2TCJ",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : "TRdUn6SYuf4rEnv2a6Fkdf5a",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2021-11-22T23:51:24.93Z",
  "updated_at" : "2021-11-22T23:51:31.51Z",
  "trace_id" : "b3276081-1cf0-4300-ab46-f727a6e2d3fe",
  "source" : "PIatE9xdPZTKdeeuyeLcB2Kj",
  "merchant_identity" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
  "3ds_redirect_url" : null,
  "is_void" : false,
  "void_state" : "UNATTEMPTED",
  "expires_at" : "2021-11-29T23:51:24.93Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AU2BunwBkS6Er4LeY36P2TCJ"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "transfer" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRdUn6SYuf4rEnv2a6Fkdf5a"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
    }
  }
}

Fetch a previously created Authorization.

HTTP Request

GET https://finix.sandbox-payments-api.com/authorizations/:AUTHORIZATION_ID

URL Parameters

Parameter Description
:AUTHORIZATION_ID ID of the Authorization

List All Authorizations

curl https://finix.sandbox-payments-api.com/authorizations/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88

Example Response:

{
  "_embedded" : {
    "authorizations" : [ {
      "id" : "AUxNKMgymQLNvoqGf6pj1Jr",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "amount" : 100,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : null,
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2021-11-22T23:51:34.19Z",
      "updated_at" : "2021-11-22T23:51:35.23Z",
      "trace_id" : "753087cb-aaa5-4cae-ad34-294c68c5dc69",
      "source" : "PIatE9xdPZTKdeeuyeLcB2Kj",
      "merchant_identity" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
      "3ds_redirect_url" : null,
      "is_void" : true,
      "void_state" : "PENDING",
      "expires_at" : "2021-11-29T23:51:34.19Z",
      "idempotency_id" : null,
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations/AUxNKMgymQLNvoqGf6pj1Jr"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
        }
      }
    }, {
      "id" : "AU4RjUjTyarGLmBDW99nUm5k",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "amount" : 100,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : null,
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2021-11-22T23:51:30.55Z",
      "updated_at" : "2021-11-22T23:51:30.64Z",
      "trace_id" : "03930aa1-cd9d-4bc1-91b5-f8acc45b4efa",
      "source" : "PIatE9xdPZTKdeeuyeLcB2Kj",
      "merchant_identity" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
      "3ds_redirect_url" : null,
      "is_void" : false,
      "void_state" : "UNATTEMPTED",
      "expires_at" : "2021-11-29T23:51:30.55Z",
      "idempotency_id" : "b9aa8af8c99049a79a7758048789b715",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations/AU4RjUjTyarGLmBDW99nUm5k"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
        }
      }
    }, {
      "id" : "AUk8VUahZGVnLxswBGxuQpA1",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "amount" : 1000,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : "TRtTydMAg9rdmaCwDsPviQ9S",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2021-11-22T23:51:28.52Z",
      "updated_at" : "2021-11-22T23:51:29.55Z",
      "trace_id" : "dfc9c337-c871-417c-9f5b-a138fc0141d1",
      "source" : "PIatE9xdPZTKdeeuyeLcB2Kj",
      "merchant_identity" : "ID2cAnM4kbLE4abQWj2fydHw",
      "3ds_redirect_url" : null,
      "is_void" : false,
      "void_state" : "UNATTEMPTED",
      "expires_at" : "2021-11-29T23:51:28.52Z",
      "idempotency_id" : null,
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations/AUk8VUahZGVnLxswBGxuQpA1"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        },
        "transfer" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRtTydMAg9rdmaCwDsPviQ9S"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw"
        }
      }
    }, {
      "id" : "AUmAwTs9CdEMnXCxWTJPLgeX",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "amount" : 1000,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : null,
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2021-11-22T23:51:27.64Z",
      "updated_at" : "2021-11-22T23:51:27.74Z",
      "trace_id" : "25dee937-fb7a-4079-8ee2-01c4c64c0953",
      "source" : "PIatE9xdPZTKdeeuyeLcB2Kj",
      "merchant_identity" : "ID2cAnM4kbLE4abQWj2fydHw",
      "3ds_redirect_url" : null,
      "is_void" : false,
      "void_state" : "UNATTEMPTED",
      "expires_at" : "2021-11-29T23:51:27.64Z",
      "idempotency_id" : null,
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations/AUmAwTs9CdEMnXCxWTJPLgeX"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw"
        }
      }
    }, {
      "id" : "AUmxvofebCU94QBYwnHV14Mb",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "amount" : 1000,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : null,
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2021-11-22T23:51:26.70Z",
      "updated_at" : "2021-11-22T23:51:26.86Z",
      "trace_id" : "29791b12-b1fb-49e2-977a-531ca81bcdc3",
      "source" : "PIatE9xdPZTKdeeuyeLcB2Kj",
      "merchant_identity" : "ID2cAnM4kbLE4abQWj2fydHw",
      "3ds_redirect_url" : null,
      "is_void" : false,
      "void_state" : "UNATTEMPTED",
      "expires_at" : "2021-11-29T23:51:26.70Z",
      "idempotency_id" : null,
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations/AUmxvofebCU94QBYwnHV14Mb"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw"
        }
      }
    }, {
      "id" : "AUfgUSmTmLfuM5sSCLwB5VVs",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "amount" : 100,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : null,
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2021-11-22T23:51:25.92Z",
      "updated_at" : "2021-11-22T23:51:25.99Z",
      "trace_id" : "42905fcf-deef-4f20-8510-5c32cdb4d3d0",
      "source" : "PIatE9xdPZTKdeeuyeLcB2Kj",
      "merchant_identity" : "ID2cAnM4kbLE4abQWj2fydHw",
      "3ds_redirect_url" : null,
      "is_void" : false,
      "void_state" : "UNATTEMPTED",
      "expires_at" : "2021-11-29T23:51:25.92Z",
      "idempotency_id" : null,
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations/AUfgUSmTmLfuM5sSCLwB5VVs"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw"
        }
      }
    }, {
      "id" : "AU2BunwBkS6Er4LeY36P2TCJ",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "amount" : 100,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : "TRdUn6SYuf4rEnv2a6Fkdf5a",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2021-11-22T23:51:24.93Z",
      "updated_at" : "2021-11-22T23:51:31.51Z",
      "trace_id" : "b3276081-1cf0-4300-ab46-f727a6e2d3fe",
      "source" : "PIatE9xdPZTKdeeuyeLcB2Kj",
      "merchant_identity" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
      "3ds_redirect_url" : null,
      "is_void" : false,
      "void_state" : "UNATTEMPTED",
      "expires_at" : "2021-11-29T23:51:24.93Z",
      "idempotency_id" : null,
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations/AU2BunwBkS6Er4LeY36P2TCJ"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        },
        "transfer" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRdUn6SYuf4rEnv2a6Fkdf5a"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
        }
      }
    }, {
      "id" : "AUxrdWEzot6LBKZ4KZVcjNEg",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "amount" : 739615,
      "tags" : {
        "test" : "sale"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : null,
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2021-11-22T23:51:15.61Z",
      "updated_at" : "2021-11-22T23:51:15.77Z",
      "trace_id" : "c5d1caae-b1d9-49e4-8793-718f37fd1de1",
      "source" : "PIatE9xdPZTKdeeuyeLcB2Kj",
      "merchant_identity" : "ID2cAnM4kbLE4abQWj2fydHw",
      "3ds_redirect_url" : null,
      "is_void" : false,
      "void_state" : "UNATTEMPTED",
      "expires_at" : "2021-11-29T23:51:15.61Z",
      "idempotency_id" : null,
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations/AUxrdWEzot6LBKZ4KZVcjNEg"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 8
  }
}

List all Authorizations.

HTTP Request

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

Devices

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

Create Device

curl https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd/devices \
        -H "Content-Type: application/vnd.json+api" \
        -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
        -d '
      {
        "name": "Finix  triPOS #1",
        "model": "MX915",
        "description": "Mike Jones",
        "configuration": {
          "allow_debit": true,
          "prompt_signature": "NEVER"
        }
      }'

HTTP Request

POST https://finix.sandbox-payments-api.com/merchants/:MERCHANT_ID/devices

URL Parameters

Field Type Description
:MERCHANT_ID string, required ID of Merchant

Request Arguments

Field Type Description
model string, required Please select one of the following values which will let Finix know the type of device being used: BBPOS, MX915, MX925, IPP320, IPP350, ISC250, ISC480, ISMP4, LANE_3000, and ANDROID
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

Field Type Description
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) 
{
  "id" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "name" : "Finix  triPOS #1",
  "model" : "MX915",
  "description" : "Mike Jones",
  "serial_number" : null,
  "idle_message" : null,
  "enabled" : false,
  "device_config_details" : {
    "allow_debit" : true,
    "check_for_duplicate_transactions" : true,
    "prompt_amount_confirmation" : true,
    "prompt_manual_entry" : false,
    "prompt_signature" : "NEVER",
    "signature_threshold_amount" : 0
  },
  "created_at" : "2019-03-01T01:07:17.015",
  "updated_at" : "2019-03-01T01:07:17.022",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "activations" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf/activations"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations"
    }
  }
}

Activate Device

curl https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf \
  -H "Content-Type: application/vnd.json+api" \
  -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
  -X PUT \
  -d '
    {
      "activation_code": "C887298",
      "action": "ACTIVATE"
    }'

HTTP Request

PUT https://finix.sandbox-payments-api.com/devices/:DEVICE_ID

URL Parameters

Field Type Description
:DEVICE_ID string, required ID of Device

Request Arguments

Field Type Description
activation_code string, required Input the code thats show up on the device screen
action string, required The action parameter must include ACTIVATE for to enable device
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers) 
{
  "id" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "name" : "Finix Tripos #1",
  "model" : "MX915",
  "description" : "Mike Jones",
  "serial_number" : "262-410-025",
  "idle_message" : null,
  "enabled" : true,
  "tags" : { },
  "created_at" : "2019-03-01T02:27:20.366",
  "updated_at" : "2019-03-11T23:19:44.378",
  "configuration_details" : {
    "allow_debit" : true,
    "check_for_duplicate_transactions" : true,
    "prompt_amount_confirmation" : true,
    "prompt_manual_entry" : false,
    "prompt_signature" : "NEVER",
    "signature_threshold_amount" : 0
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations"
    }
  }
}

Fetch Device

curl https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf \
           -H "Content-Type: application/vnd.json+api" \
           -u   USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3

HTTP Request

GET https://finix.sandbox-payments-api.com/devices/:DEVICE_ID

URL Parameters

Field Type Description
:DEVICE_ID string, required ID of Device 
  {
  "id" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "name" : "Finix Tripos #1",
  "model" : "MX915",
  "description" : "Mike Jones",
  "serial_number" : "262-410-025",
  "idle_message" : null,
  "enabled" : true,
  "tags" : { },
  "created_at" : "2019-03-01T02:27:20.366",
  "updated_at" : "2019-03-11T23:35:55.633",
  "configuration_details" : {
    "allow_debit" : true,
    "check_for_duplicate_transactions" : true,
    "prompt_amount_confirmation" : true,
    "prompt_manual_entry" : false,
    "prompt_signature" : "NEVER",
    "signature_threshold_amount" : 0
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations"
    }
  }
}

Reboot Device

curl https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf \
   -H "Content-Type: application/vnd.json+api" \
   -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
   -X PUT \
   -d '
   {
       "action": "REBOOT"
   }'

HTTP Request

PUT https://finix.sandbox-payments-api.com/devices/:DEVICE_ID

URL Parameters

Field Type Description
:DEVICE_ID string, required ID of Device

Request Arguments

Field Type Description
action string, required The action parameter must include REBOOT to reboot the device 
{
  "id" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "name" : "Finix Tripos #1",
  "model" : "MX915",
  "description" : "Mike Jones",
  "serial_number" : "262-410-025",
  "idle_message" : null,
  "enabled" : true,
  "tags" : { },
  "created_at" : "2019-03-01T02:27:20.366",
  "updated_at" : "2019-03-11T23:22:39.690",
  "configuration_details" : {
    "allow_debit" : true,
    "check_for_duplicate_transactions" : true,
    "prompt_amount_confirmation" : true,
    "prompt_manual_entry" : false,
    "prompt_signature" : "NEVER",
    "signature_threshold_amount" : 0
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations"
    }
  }

Set Idle Message on Device

curl https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf \
-H "Content-Type: application/vnd.json+api" \
-u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
-X PUT \
-d '
  {
    "idle_message": "Michaels Juice Shop",
    "action": "CREATE_IDLE_MESSAGE"
  }'

HTTP Request

PUT https://finix.sandbox-payments-api.com/devices/:DEVICE_ID

URL Parameters

Field Type Description
:DEVICE_ID string, required ID of Device

Request Arguments

Field Type Description
idle_message string, required ID of Device
action string, required The action parameter must include CREATE_IDLE_MESSAGE to create an idle message 
{
  "id" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "name" : "Finix Tripos #1",
  "model" : "MX915",
  "description" : "Mike Jones",
  "serial_number" : "262-410-025",
  "idle_message" : "Michaels Juice Shop",
  "enabled" : true,
  "tags" : { },
  "created_at" : "2019-03-01T02:27:20.366",
  "updated_at" : "2019-03-11T23:19:44.399",
  "configuration_details" : {
    "allow_debit" : true,
    "check_for_duplicate_transactions" : true,
    "prompt_amount_confirmation" : true,
    "prompt_manual_entry" : false,
    "prompt_signature" : "NEVER",
    "signature_threshold_amount" : 0
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations"
    }
  }
}

Check Connectivity of Device

curl https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf?include_connection\=true \
   -H "Content-Type: application/vnd.json+api" \
   -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3

HTTP Request

GET https://finix.sandbox-payments-api.com/devices/:DEVICE_ID

URL Parameters

Field Type Description
DEVICE_ID string, required ID of Device 
  {
  "id" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "name" : "Finix Tripos #1",
  "model" : "MX915",
  "description" : "Mike Jones",
  "serial_number" : "262-410-025",
  "idle_message" : null,
  "connection" : "Open",
  "enabled" : true,
  "tags" : { },
  "created_at" : "2019-03-01T02:27:20.366",
  "updated_at" : "2019-03-11T23:35:55.633",
  "configuration_details" : {
    "allow_debit" : true,
    "check_for_duplicate_transactions" : true,
    "prompt_amount_confirmation" : true,
    "prompt_manual_entry" : false,
    "prompt_signature" : "NEVER",
    "signature_threshold_amount" : 0
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations"
    }
  }
}

Deactivate Device

curl https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf \
     -H "Content-Type: application/vnd.json+api" \
     -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
     -X PUT \
     -d '
       {
           "action": "DEACTIVATE"
       }'

HTTP Request

PUT https://finix.sandbox-payments-api.com/devices/:DEVICE_ID

URL Parameters

Field Type Description
:DEVICE_ID string, required ID of Device

Request Arguments

Field Type Description
action string, required The action parameter must include DEACTIVATE to deactivate the device 
    {
      "id" : "DVf2H8sh4LZZC52GTUrwCPPf",
      "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
      "name" : "Finix Tripos #1",
      "model" : "MX915",
      "description" : "Mike Jones",
      "serial_number" : null,
      "idle_message" : null,
      "enabled" : false,
      "tags" : { },
      "created_at" : "2019-03-01T02:27:20.366",
      "updated_at" : "2019-03-11T23:30:05.816",
      "configuration_details" : null,
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
        },
        "merchant" : {
          "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations"
        }
      }
    }

Disputes

Disputes, also known as chargebacks, represent any customer-disputed charge. The respond_by field id set by the upstream Processor and is the date the Merchant needs to submit evidence that supports their claim.

Upload Dispute Evidence

curl https://finix.sandbox-payments-api.com/disputes/DIdneCGbDtF6XYUS2TwZCNrn/evidence \
    -H "Content-Type: multipart/form-data" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -F 'file=@path/to/local/file'

Example Response:


    {
        "tags": {
            "content-type": "application/pdf", 
            "file-extension": ".pdf", 
            "file-name": "testfile.pdf"
        }, 
        "created_at": "2021-11-22T23:58:06.84Z", 
        "updated_at": "2021-11-22T23:58:06.84Z", 
        "state": "PENDING", 
        "_links": {
            "self": {
                "href": "https://finix.sandbox-payments-api.com/disputes/DIdneCGbDtF6XYUS2TwZCNrn/evidence/DFtYGtq3hC3gFS3CQT5b5Tpt"
            }
        }, 
        "id": "DFtYGtq3hC3gFS3CQT5b5Tpt", 
        "dispute": "DIdneCGbDtF6XYUS2TwZCNrn"
    }

A core part of the dispute lifecycle is the ability for a Merchant to upload Dispute evidence that supports their side of the Dispute. It is recommended you provide as much supporting evidence as possible.

There are four available values that indicate the state of the evidence upload:

HTTP Request

POST https://finix.sandbox-payments-api.com/disputes/:DISPUTE_ID/evidence

Fetch a Dispute


curl https://finix.sandbox-payments-api.com/disputes/DIdneCGbDtF6XYUS2TwZCNrn \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88

Example Response:

{
  "id" : "DIdneCGbDtF6XYUS2TwZCNrn",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "amount" : 888888,
  "state" : "PENDING",
  "transfer" : "TRtNH4ZXp223f3QE12EcBjqf",
  "reason" : "FRAUD",
  "message" : null,
  "action" : null,
  "identity" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
  "created_at" : "2021-11-22T23:57:07.57Z",
  "updated_at" : "2021-11-22T23:57:07.17Z",
  "occurred_at" : "2021-11-22T23:56:58.86Z",
  "respond_by" : "2021-11-29T23:57:07.56Z",
  "dispute_details" : {
    "arn" : "123"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes/DIdneCGbDtF6XYUS2TwZCNrn"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "transfer" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRtNH4ZXp223f3QE12EcBjqf"
    },
    "evidence" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes/DIdneCGbDtF6XYUS2TwZCNrn/evidence"
    },
    "adjustment_transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes/DIdneCGbDtF6XYUS2TwZCNrn/adjustment_transfers"
    }
  }
}

Fetch a previously created Dispute.

HTTP Request

GET https://finix.sandbox-payments-api.com/disputes/:DISPUTE_ID

URL Parameters

Parameter Description
:DISPUTE_ID ID of the Dispute

Response

Field Type Description
state integer The current state of the Dispute. It is one of the following values: INQUIRY, PENDING, WON, or LOST
reason integer The system defined reason for the Dispute. It is one of the following values: INQUIRY, QUALITY, CLERICAL, FRAUD, or TECHNICAL

List All Disputes

curl https://finix.sandbox-payments-api.com/disputes/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88

Example Response:

{
  "_embedded" : {
    "disputes" : [ {
      "id" : "DIdneCGbDtF6XYUS2TwZCNrn",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "amount" : 888888,
      "state" : "PENDING",
      "transfer" : "TRtNH4ZXp223f3QE12EcBjqf",
      "reason" : "FRAUD",
      "message" : null,
      "action" : null,
      "identity" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
      "created_at" : "2021-11-22T23:57:07.57Z",
      "updated_at" : "2021-11-22T23:57:07.17Z",
      "occurred_at" : "2021-11-22T23:56:58.86Z",
      "respond_by" : "2021-11-29T23:57:07.56Z",
      "dispute_details" : {
        "arn" : "123"
      },
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/disputes/DIdneCGbDtF6XYUS2TwZCNrn"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        },
        "transfer" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRtNH4ZXp223f3QE12EcBjqf"
        },
        "evidence" : {
          "href" : "https://finix.sandbox-payments-api.com/disputes/DIdneCGbDtF6XYUS2TwZCNrn/evidence"
        },
        "adjustment_transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/disputes/DIdneCGbDtF6XYUS2TwZCNrn/adjustment_transfers"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 1
  }
}

List all Disputes.

HTTP Request

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

Response

Field Type Description
state integer The current state of the Dispute. It is one of the following values: INQUIRY, PENDING, WON, or LOST
reason integer The system defined reason for the Dispute. It is one of the following values: INQUIRY, QUALITY, CLERICAL, FRAUD, or TECHNICAL

Fetch Dispute Adjustment Transfers


curl https://finix.sandbox-payments-api.com/disputes/DIdneCGbDtF6XYUS2TwZCNrn/adjustment_transfers \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88

Example Response:

{
  "_embedded" : {
    "transfers" : [ {
      "id" : "TRbFtU2x3Ud6kGp7EwjnDYq2",
      "amount" : 888888,
      "tags" : { },
      "state" : "SUCCEEDED",
      "trace_id" : "aa881999-b5da-4f53-84be-a9e3f9e2b5bd",
      "currency" : "USD",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "source" : null,
      "destination" : null,
      "ready_to_settle_at" : "2021-11-22T23:57:07.84Z",
      "externally_funded" : "FALSE",
      "fee" : 0,
      "statement_descriptor" : null,
      "type" : "DISPUTE",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2021-11-22T23:57:07.87Z",
      "updated_at" : "2021-11-22T23:57:07.17Z",
      "idempotency_id" : null,
      "merchant_identity" : "ID8bW3W9DmKEgFYF4GfDJ8or",
      "subtype" : "PLATFORM_CREDIT",
      "_links" : {
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        },
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRbFtU2x3Ud6kGp7EwjnDYq2"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID8bW3W9DmKEgFYF4GfDJ8or"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRbFtU2x3Ud6kGp7EwjnDYq2/payment_instruments"
        },
        "disputed_transfer" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRbFtU2x3Ud6kGp7EwjnDYq2/disputed_transfer"
        },
        "fee_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPcMBbo5zF1ZTs7usEpi6UxS"
        }
      }
    }, {
      "id" : "TRrSbUqa4Spct1fN6RV91UGj",
      "amount" : 888888,
      "tags" : { },
      "state" : "SUCCEEDED",
      "trace_id" : "5a19aefa-58a3-4e2d-b9d1-23015b0378f2",
      "currency" : "USD",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "source" : null,
      "destination" : "PIatE9xdPZTKdeeuyeLcB2Kj",
      "ready_to_settle_at" : "2021-11-22T23:57:07.60Z",
      "externally_funded" : "FALSE",
      "fee" : 0,
      "statement_descriptor" : null,
      "type" : "DISPUTE",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2021-11-22T23:57:07.62Z",
      "updated_at" : "2021-11-22T23:57:07.17Z",
      "idempotency_id" : null,
      "merchant_identity" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
      "subtype" : "MERCHANT_DEBIT",
      "_links" : {
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        },
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRrSbUqa4Spct1fN6RV91UGj"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRrSbUqa4Spct1fN6RV91UGj/payment_instruments"
        },
        "disputed_transfer" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRrSbUqa4Spct1fN6RV91UGj/disputed_transfer"
        },
        "destination" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIatE9xdPZTKdeeuyeLcB2Kj"
        },
        "fee_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPLzfegpFFm2ux5Ckiqev17"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes/DIdneCGbDtF6XYUS2TwZCNrn/adjustment_transfers?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 2
  }
}

List the adjustment Transfers for a Dispute. Depending on the stage of the Dispute, different adjustment Transfer subtypes can be applied. There are four available subtypes: PLATFORM_CREDIT, MERCHANT_DEBIT, MERCHANT_CREDIT, and PLATFORM_DEBIT.

HTTP Request

GET https://finix.sandbox-payments-api.com/disputes/:DISPUTE_ID/adjustment_transfers

URL Parameters

Parameter Description
:DISPUTE_ID ID of the Dispute

Response

Field Type Description
id string ID of the Transfer
amount integer The total amount to be adjusted in cents
application string ID of the Application
currency string 3-letter ISO code designating the currency of the adjustment
destination string ID of the Payment Instrument where funds are deposited
fee integer The amount of the adjustment you would like to collect as your Fee in cents. Defaults to zero (must be less than or equal to the amount)
idempotency_id string A randomly generated value that you want associated with the request
merchant_identity string The ID of the Identity for the Merchant that you are transacting or charging on behalf of
messages string Message field that provides additional details. This field is typically null
raw string Raw card data. This field is typically null
ready_to_settle_at string Timestamp of when the Transfer is ready to be settled
source string ID of the Payment Instrument where funds are debited
state string The state of the Transfer. There are four available values: PENDING, SUCCEEDED, CANCELED, or FAILED
statement_descriptor string Billing descriptor displayed on the buyer’s bank or card statement (Length must be between 1 and 20 characters)
subtype string Specifies money movement to and from the Merchant. There are four available subtypes: PLATFORM_CREDIT, MERCHANT_DEBIT, MERCHANT_CREDIT, and PLATFORM_DEBIT
tags object Key value pair for annotating custom meta data
trace_id string Trace ID
type string Type of adjustment. There is one available value: DISPUTE
created_at string Timestamp of when the adjustment was created
updated_at string Timestamp of when the adjustment was updated

Fetch a Dispute Evidence File


curl https://finix.sandbox-payments-api.com/disputes/DIdneCGbDtF6XYUS2TwZCNrn/evidence/DFtYGtq3hC3gFS3CQT5b5Tpt \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88

Example Response:

{
  "id" : "DFtYGtq3hC3gFS3CQT5b5Tpt",
  "tags" : {
    "file-extension" : ".pdf",
    "content-type" : "application/pdf",
    "file-name" : "testfile.pdf"
  },
  "dispute" : "DIdneCGbDtF6XYUS2TwZCNrn",
  "state" : "PENDING",
  "created_at" : "2021-11-22T23:58:06.84Z",
  "updated_at" : "2021-11-22T23:58:06.58Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes/DIdneCGbDtF6XYUS2TwZCNrn/evidence/DFtYGtq3hC3gFS3CQT5b5Tpt"
    }
  }
}

Fetch a previously uploaded Dispute evidence file. Users can view the status of their evidence upload to check if the file was successfully sent to the processor if they do not have access to the Dashboard.

HTTP Request

GET https://finix.sandbox-payments-api.com/disputes/:DISPUTE_ID/evidence/:EVIDENCE_ID

URL Parameters

Parameter Description
:DISPUTE_ID ID of the Dispute
:EVIDENCE_ID ID of the Dispute evidence file

Response

Field Type Description
id string ID of the Dispute evidence file
content_type string Specifies the data being sent to and from the client
dispute string ID of the Dispute
file_extension string File format type
file_name string Dispute file name
state string The state of the evidence upload. There are four available values: PENDING, SUCCEEDED, CANCELED, or FAILED
tags object Key value pair for annotating custom meta data
created_at string Timestamp of when the Dispute evidence file was created
updated_at string Timestamp of when the Dispute evidence file was updated

List Dispute Evidence Files


curl https://finix.sandbox-payments-api.com/disputes/DIdneCGbDtF6XYUS2TwZCNrn/evidence \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88

Example Response:

{
  "_embedded" : {
    "evidences" : [ {
      "id" : "DFtYGtq3hC3gFS3CQT5b5Tpt",
      "tags" : {
        "file-extension" : ".pdf",
        "content-type" : "application/pdf",
        "file-name" : "testfile.pdf"
      },
      "dispute" : "DIdneCGbDtF6XYUS2TwZCNrn",
      "state" : "PENDING",
      "created_at" : "2021-11-22T23:58:06.84Z",
      "updated_at" : "2021-11-22T23:58:06.58Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/disputes/DIdneCGbDtF6XYUS2TwZCNrn/evidence/DFtYGtq3hC3gFS3CQT5b5Tpt"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes/DIdneCGbDtF6XYUS2TwZCNrn/evidence?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 1
  }
}

List all uploaded Dispute evidence files.

HTTP Request

GET https://finix.sandbox-payments-api.com/disputes/:DISPUTE_ID/evidence

URL Parameters

Parameter Description
:DISPUTE_ID ID of the Dispute

Response

Field Type Description
id string ID of the Dispute evidence file
content_type string Specifies the data being sent to and from the client
dispute string ID of the Dispute
file_extension string File format type
file_name string Dispute file name
state string The state of the evidence upload. There are four available values: PENDING, SUCCEEDED, CANCELED, or FAILED
tags object Key value pair for annotating custom meta data
created_at string Timestamp of when the Dispute evidence file was created
updated_at string Timestamp of when the Dispute evidence file was updated

Identities

An Identity resource represents either a buyer or a Merchant and is in many ways the centerpiece of our 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 associated banks accounts, transaction history, and payouts.

Create an Identity for a Buyer



curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -d '
    {
        "tags": {
            "key": "value"
        }, 
        "entity": {
            "phone": "7145677613", 
            "first_name": "Marcie", 
            "last_name": "Wade", 
            "email": "therock@gmail.com", 
            "personal_address": {
                "city": "San Mateo", 
                "country": "USA", 
                "region": "CA", 
                "line2": "Apartment 7", 
                "line1": "741 Douglass St", 
                "postal_code": "94114"
            }
        }
    }'

Example Response:

{
  "id" : "IDmULj61C8ke6Y7qQiKENJ7",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "entity" : {
    "title" : null,
    "first_name" : "Marcie",
    "last_name" : "Wade",
    "email" : "therock@gmail.com",
    "business_name" : null,
    "business_type" : null,
    "doing_business_as" : null,
    "phone" : "7145677613",
    "business_phone" : null,
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : null,
    "mcc" : null,
    "dob" : null,
    "max_transaction_amount" : 0,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : null,
    "annual_card_volume" : 0,
    "has_accepted_credit_cards_previously" : false,
    "incorporation_date" : null,
    "principal_percentage_ownership" : null,
    "short_business_name" : null,
    "ownership_type" : null,
    "tax_authority" : null,
    "tax_id_provided" : false,
    "business_tax_id_provided" : false,
    "default_statement_descriptor" : null
  },
  "tags" : {
    "key" : "value"
  },
  "created_at" : "2021-11-22T23:51:03.58Z",
  "updated_at" : "2021-11-22T23:51:03.58Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    }
  }
}

All fields for a buyer’s Identity are optional. Do not pass the business_type field as that indicates that the Identity should be treated as a Merchant.

HTTP Request

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

Request Arguments

Field Type Description
city string, optional City (max 20 characters)
country string, optional 3-Letter Country code
email string, optional Email address
first_name string, optional First name
last_name string, optional Last name
line1 string, optional First line of the address (max 35 characters)
line2 string, optional Second line of the address (max 35 characters)
phone string, optional Phone number
postal_code string, optional Zip or Postal code (max 7 characters)
region string, optional 2-letter State code
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)

Create an Identity for a Merchant

curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -d '
    {
        "additional_underwriting_data": {
            "merchant_agreement_accepted": true, 
            "merchant_agreement_ip_address": "42.1.1.113", 
            "volume_distribution_by_business_type": {
                "other_volume_percentage": 0, 
                "consumer_to_consumer_volume_percentage": 0, 
                "business_to_consumer_volume_percentage": 0, 
                "business_to_business_volume_percentage": 100, 
                "person_to_person_volume_percentage": 0
            }, 
            "average_ach_transfer_amount": 200000, 
            "annual_ach_volume": 200000, 
            "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)", 
            "refund_policy": "MERCHANDISE_EXCHANGE_ONLY", 
            "credit_check_timestamp": "2021-04-28T16:42:55Z", 
            "credit_check_allowed": true, 
            "merchant_agreement_timestamp": "2021-04-28T16:42:55Z", 
            "business_description": "SB3 vegan cafe", 
            "average_card_transfer_amount": 200000, 
            "credit_check_ip_address": "42.1.1.113", 
            "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)", 
            "card_volume_distribution": {
                "card_present_percentage": 30, 
                "mail_order_telephone_order_percentage": 10, 
                "ecommerce_percentage": 60
            }
        }, 
        "tags": {
            "Studio Rating": "4.7"
        }, 
        "entity": {
            "last_name": "Sunkhronos", 
            "max_transaction_amount": 12000000, 
            "has_accepted_credit_cards_previously": true, 
            "default_statement_descriptor": "Bobs Burgers", 
            "personal_address": {
                "city": "San Mateo", 
                "country": "USA", 
                "region": "CA", 
                "line2": "Apartment 7", 
                "line1": "741 Douglass St", 
                "postal_code": "94114"
            }, 
            "incorporation_date": {
                "year": 1978, 
                "day": 27, 
                "month": 6
            }, 
            "business_address": {
                "city": "San Mateo", 
                "country": "USA", 
                "region": "CA", 
                "line2": "Apartment 8", 
                "line1": "741 Douglass St", 
                "postal_code": "94114"
            }, 
            "ownership_type": "PRIVATE", 
            "first_name": "dwayne", 
            "title": "CEO", 
            "business_tax_id": "123456789", 
            "doing_business_as": "Bobs Burgers", 
            "principal_percentage_ownership": 50, 
            "email": "user@example.org", 
            "mcc": "0742", 
            "phone": "1234567890", 
            "business_name": "Bobs Burgers", 
            "tax_id": "123456789", 
            "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP", 
            "business_phone": "+1 (408) 756-4497", 
            "dob": {
                "year": 1978, 
                "day": 27, 
                "month": 6
            }, 
            "url": "www.BobsBurgers.com", 
            "annual_card_volume": 12000000
        }
    }'

Example Response:

{
  "id" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "entity" : {
    "title" : "CEO",
    "first_name" : "dwayne",
    "last_name" : "Sunkhronos",
    "email" : "user@example.org",
    "business_name" : "Bobs Burgers",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "Bobs Burgers",
    "phone" : "1234567890",
    "business_phone" : "+1 (408) 756-4497",
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 8",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "mcc" : "0742",
    "dob" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "max_transaction_amount" : 12000000,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : "www.BobsBurgers.com",
    "annual_card_volume" : 12000000,
    "has_accepted_credit_cards_previously" : true,
    "incorporation_date" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "principal_percentage_ownership" : 50,
    "short_business_name" : null,
    "ownership_type" : "PRIVATE",
    "tax_authority" : null,
    "tax_id_provided" : true,
    "business_tax_id_provided" : true,
    "default_statement_descriptor" : "Bobs Burgers"
  },
  "tags" : {
    "Studio Rating" : "4.7"
  },
  "created_at" : "2021-11-22T23:50:55.56Z",
  "updated_at" : "2021-11-22T23:50:55.56Z",
  "additional_underwriting_data" : {
    "annual_ach_volume" : 200000,
    "average_ach_transfer_amount" : 200000,
    "average_card_transfer_amount" : 200000,
    "business_description" : "SB3 vegan cafe",
    "card_volume_distribution" : {
      "card_present_percentage" : 30,
      "ecommerce_percentage" : 60,
      "mail_order_telephone_order_percentage" : 10
    },
    "credit_check_allowed" : true,
    "credit_check_ip_address" : "42.1.1.113",
    "credit_check_timestamp" : "2021-04-28T16:42:55Z",
    "credit_check_user_agent" : "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)",
    "merchant_agreement_accepted" : true,
    "merchant_agreement_ip_address" : "42.1.1.113",
    "merchant_agreement_timestamp" : "2021-04-28T16:42:55Z",
    "merchant_agreement_user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)",
    "refund_policy" : "MERCHANDISE_EXCHANGE_ONLY",
    "volume_distribution_by_business_type" : {
      "business_to_business_volume_percentage" : 100,
      "business_to_consumer_volume_percentage" : 0,
      "consumer_to_consumer_volume_percentage" : 0,
      "other_volume_percentage" : 0,
      "person_to_person_volume_percentage" : 0
    }
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    }
  }
}

Before we can begin charging cards we’ll need to provision a Merchant account for your seller. This requires 3-steps, which we’ll go into greater detail in the next few sections:

  1. First, create an Identity resource with the merchant’s underwriting and identity verification information

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

  2. Second, create a Payment Instrument representing the merchant’s bank account where processed funds will be settled (i.e. deposited)

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

  3. Finally, provision the Merchant account

    POST https://finix.sandbox-payments-api.com/identities/:IDENTITY_ID/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.

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)
business_type string, required Please select one of the following values: INDIVIDUAL_SOLE_PROPRIETORSHIP, CORPORATION, LIMITED_LIABILITY_COMPANY, PARTNERSHIP, ASSOCIATION_ESTATE_TRUST, TAX_EXEMPT_ORGANIZATION, INTERNATIONAL_ORGANIZATION, GOVERNMENT_AGENCY.
business_tax_id string, required 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)
business_address object, required Primary address for the legal entity (Full description of child attributes below)
ownership_type string, required Values can be either PUBLIC to indicate a publicly traded company or PRIVATE for privately held businesses. For business_type GOVERNMENT_AGENCY and TAX_EXEMPT_ORGANIZATION the ownership_type should be set to PUBLIC. For business_type INDIVIDUAL_SOLE_PROPRIETORSHIP, the ownership_type should be set to PRIVATE.
amex_mid integer, optional Assigned amexMid value. If provided must be 10 or 11 digits
discover_mid integer, optional Assigned discoverMid value

Principal-specific Request Arguments

(i.e. authorized representative or primary contact responsible for the account). All representatives with 25% or more ownership of the business must be added as principal owners on the Identity.

Field Type Description
first_name string, required Full legal first name of the merchant’s principal representative (max 20 characters)
last_name string, required Full legal last name of the merchant’s principal representative (max 20 characters)
title string, required Principal’s corporate title or role (i.e. Chief Executive Officer, CFO, etc.; max 60 characters)
principal_percentage_ownership integer, required Percentage of company owned by the principal (min 0; max 100)
tax_id string, required Nine digit Social Security Number (SSN) for the principal
dob object, required Principal’s date of birth (Full description of child attributes below)
phone string, required Principal’s phone number (max 10 characters)
email string, required Principal’s email address where they can be reached (max 100 characters)
personal_address object, required Principal’s personal home address. This field is used for identity verification purposes (Full description of child attributes below)

Processing-specific Request Arguments

Field Type Description
default_statement_descriptor string, required Billing descriptor displayed on the buyer’s bank or card statement (Length must be between 1 and 20 characters)
annual_card_volume integer, required Approximate annual credit card sales expected to be processed in cents by this merchant (max 23 characters)
max_transaction_amount integer, required Maximum amount that can be transacted for a single transaction in cents (max 12 characters)
mcc string, required Merchant Category Code (MCC) that this merchant will be classified under
has_accepted_credit_cards_previously boolean, optional Defaults to false if not passed

Address-object Request Arguments

Field Type Description
line1 string, required First line of the address (max 35 characters)
line2 string, optional Second line of the address (max 35 characters)
city string, required City (max 20 characters)
region string, required 2-letter State code
postal_code string, required Zip or Postal code (max 7 characters)
country string, required 3-Letter Country code

Incorporation Date-object Request Arguments

Field Type Description
day integer, required Day business was incorporated (between 1 and 31)
month integer, required Month business was incorporated (between 1 and 12)
year integer, required Year business was incorporated (4-digit)

DOB-object Request Arguments

Field Type Description
day integer, required Day of birth (between 1 and 31)
month integer, required Month of birth (between 1 and 12)
year integer, required Year of birth (4-digit). Year must be greater than 1900.

Additional Underwriting Request Arguments

Field Type Description
annual _ach_volume integer, required Approximate annual ACH sales expected to be processed in cents by this merchant
average_ach_transfer_amount integer, required Approximate average ACH sale amount in cents for this merchant
average_card_transfer_amount integer, required Approximate average credit card sale amount in cents for this merchant
business_description string, required Description of this merchant’s business (max 200 characters)
card_volume_distribution object, required Merchant’s distribution of credit card volume (See below for a full list of the child attributes). Sum of card_volume_distribution must be 100.
credit_check_allowed boolean, required Sets whether this merchant has consented and accepted to a credit check
credit_check_ip_address string, required IP address of the merchant when this merchant consented to a credit check (e.g., 42.1.1.113 )
credit_check_timestamp string, required Timestamp of the merchant when this merchant consented to a credit check (e.g., 2021-04-28T16:42:55Z)
credit_check_user_agent string, required The user agent of the browser when this merchant consented to a credit check (e.g., Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6))
merchant_agreeement_accepted boolean, required Sets whether this merchant has accepted the terms and conditions of the merchant agreement
merchant_agreement_ip_address string, required IP address of the merchant when this merchant accepted the merchant agreement (e.g., 42.1.1.113 )
merchant_agreement_timestamp string, required Timestamp of the merchant when this merchant consented to a credit check (e.g., 2021-04-28T16:42:55Z)
merchant_agreement_user_agent string, required The user agent of the browser when this merchant accepted the merchant agreement (e.g., Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6))
refund_policy string, required Please select one of the following values: NO_REFUNDS, MERCHANDISE_EXCHANGE_ONLY, WITHIN_30_DAYS, OTHER
volume_distribution_by_business_type object, required Merchant’s distribution of credit card volume by business type (See below for a full list of the child attributes). Sum of volume_distribution_by_business_type must be 100.

Card Volume Distribution-object Request Arguments

Field Type Description
card_present_percentage integer, required Merchant’s percentage of business that is card present (between 0 and 100)
ecommerce_present_percentage integer, required Merchant’s percentage of business that is ecommerce (between 0 and 100)
mail_order_telephone_order_percentage integer, required Merchant’s percentage of business that is mail order or telephone order (between 0 and 100)

Volume Distribution by Business Type-object Request Arguments

Field Type Description
business_to_business_volume_percentage integer, required Merchant’s percentage of volume that is business to business (between 0 and 100)
business_to_consumer_volume_percentage integer, required Merchant’s percentage of volume that is business to consumer (between 0 and 100)
consumer_to_consumer_volume_percentage integer, required Merchant’s percentage of volume that is consumer to consumer (between 0 and 100)
person_to_person_volume_percentage integer, required Merchant’s percentage of volume that is person to person (between 0 and 100)
other_volume_percentage integer, required Merchant’s percentage of volume that is not represented by the previous fields (between 0 and 100)

Fetch an Identity


curl https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88

Example Response:

{
  "id" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "entity" : {
    "title" : "CEO",
    "first_name" : "dwayne",
    "last_name" : "Sunkhronos",
    "email" : "user@example.org",
    "business_name" : "Bobs Burgers",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "Bobs Burgers",
    "phone" : "1234567890",
    "business_phone" : "+1 (408) 756-4497",
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 8",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "mcc" : "0742",
    "dob" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "max_transaction_amount" : 12000000,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : "www.BobsBurgers.com",
    "annual_card_volume" : 12000000,
    "has_accepted_credit_cards_previously" : true,
    "incorporation_date" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "principal_percentage_ownership" : 50,
    "short_business_name" : null,
    "ownership_type" : "PRIVATE",
    "tax_authority" : null,
    "tax_id_provided" : true,
    "business_tax_id_provided" : true,
    "default_statement_descriptor" : "Bobs Burgers"
  },
  "tags" : {
    "Studio Rating" : "4.7"
  },
  "created_at" : "2021-11-22T23:50:55.56Z",
  "updated_at" : "2021-11-22T23:50:55.47Z",
  "additional_underwriting_data" : {
    "annual_ach_volume" : 200000,
    "average_ach_transfer_amount" : 200000,
    "average_card_transfer_amount" : 200000,
    "business_description" : "SB3 vegan cafe",
    "card_volume_distribution" : {
      "card_present_percentage" : 30,
      "ecommerce_percentage" : 60,
      "mail_order_telephone_order_percentage" : 10
    },
    "credit_check_allowed" : true,
    "credit_check_ip_address" : "42.1.1.113",
    "credit_check_timestamp" : "2021-04-28T16:42:55Z",
    "credit_check_user_agent" : "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)",
    "merchant_agreement_accepted" : true,
    "merchant_agreement_ip_address" : "42.1.1.113",
    "merchant_agreement_timestamp" : "2021-04-28T16:42:55Z",
    "merchant_agreement_user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)",
    "refund_policy" : "MERCHANDISE_EXCHANGE_ONLY",
    "volume_distribution_by_business_type" : {
      "business_to_business_volume_percentage" : 100,
      "business_to_consumer_volume_percentage" : 0,
      "consumer_to_consumer_volume_percentage" : 0,
      "other_volume_percentage" : 0,
      "person_to_person_volume_percentage" : 0
    }
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    }
  }
}

Fetch a previously created Identity.

HTTP Request

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

URL Parameters

Parameter Description
:IDENTITY_ID ID of the Identity

List All Identities

curl https://finix.sandbox-payments-api.com/identities/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88

Example Response:

{
  "_embedded" : {
    "identities" : [ {
      "id" : "ID2cAnM4kbLE4abQWj2fydHw",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Bobs Burgers",
        "business_type" : "CORPORATION",
        "doing_business_as" : "Bobs Burgers",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.BobsBurgers.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Bobs Burgers"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2021-11-22T23:51:06.81Z",
      "updated_at" : "2021-11-22T23:51:06.67Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        }
      }
    }, {
      "id" : "IDeCJ9SYhwMgwtHpAG7eo6sk",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "entity" : {
        "title" : "Founder",
        "first_name" : "John",
        "last_name" : "Smith",
        "email" : "john.smith@company1.com",
        "business_name" : null,
        "business_type" : null,
        "doing_business_as" : null,
        "phone" : "1234567890",
        "business_phone" : null,
        "personal_address" : {
          "line1" : "123 Main Street",
          "line2" : null,
          "city" : "San Francisco",
          "region" : "CA",
          "postal_code" : "90650",
          "country" : "USA"
        },
        "business_address" : null,
        "mcc" : null,
        "dob" : {
          "day" : 1,
          "month" : 1,
          "year" : 2013
        },
        "max_transaction_amount" : 0,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : null,
        "annual_card_volume" : 0,
        "has_accepted_credit_cards_previously" : false,
        "incorporation_date" : null,
        "principal_percentage_ownership" : 25,
        "short_business_name" : null,
        "ownership_type" : null,
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : false,
        "default_statement_descriptor" : null
      },
      "tags" : { },
      "created_at" : "2021-11-22T23:51:05.59Z",
      "updated_at" : "2021-11-22T23:51:05.62Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDeCJ9SYhwMgwtHpAG7eo6sk/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        }
      }
    }, {
      "id" : "IDmULj61C8ke6Y7qQiKENJ7",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "entity" : {
        "title" : null,
        "first_name" : "Marcie",
        "last_name" : "Wade",
        "email" : "therock@gmail.com",
        "business_name" : null,
        "business_type" : null,
        "doing_business_as" : null,
        "phone" : "7145677613",
        "business_phone" : null,
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : null,
        "mcc" : null,
        "dob" : null,
        "max_transaction_amount" : 0,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : null,
        "annual_card_volume" : 0,
        "has_accepted_credit_cards_previously" : false,
        "incorporation_date" : null,
        "principal_percentage_ownership" : null,
        "short_business_name" : null,
        "ownership_type" : null,
        "tax_authority" : null,
        "tax_id_provided" : false,
        "business_tax_id_provided" : false,
        "default_statement_descriptor" : null
      },
      "tags" : {
        "key" : "value"
      },
      "created_at" : "2021-11-22T23:51:03.58Z",
      "updated_at" : "2021-11-22T23:51:03.50Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmULj61C8ke6Y7qQiKENJ7/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        }
      }
    }, {
      "id" : "IDdtU9QzAKm58LV9iq3EmTcc",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Petes Coffee",
        "business_type" : "GOVERNMENT_AGENCY",
        "doing_business_as" : "Petes Coffee",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.PetesCoffee.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PUBLIC",
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Petes Coffee"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2021-11-22T23:50:59.81Z",
      "updated_at" : "2021-11-22T23:50:59.69Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdtU9QzAKm58LV9iq3EmTcc"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdtU9QzAKm58LV9iq3EmTcc/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdtU9QzAKm58LV9iq3EmTcc/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdtU9QzAKm58LV9iq3EmTcc/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdtU9QzAKm58LV9iq3EmTcc/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdtU9QzAKm58LV9iq3EmTcc/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdtU9QzAKm58LV9iq3EmTcc/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdtU9QzAKm58LV9iq3EmTcc/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdtU9QzAKm58LV9iq3EmTcc/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        }
      }
    }, {
      "id" : "IDo7hkkceNZUVTaj7FmPf8aJ",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Bobs Burgers",
        "business_type" : "INTERNATIONAL_ORGANIZATION",
        "doing_business_as" : "Bobs Burgers",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.BobsBurgers.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Bobs Burgers"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2021-11-22T23:50:59.04Z",
      "updated_at" : "2021-11-22T23:50:58.91Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo7hkkceNZUVTaj7FmPf8aJ"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo7hkkceNZUVTaj7FmPf8aJ/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo7hkkceNZUVTaj7FmPf8aJ/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo7hkkceNZUVTaj7FmPf8aJ/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo7hkkceNZUVTaj7FmPf8aJ/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo7hkkceNZUVTaj7FmPf8aJ/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo7hkkceNZUVTaj7FmPf8aJ/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo7hkkceNZUVTaj7FmPf8aJ/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo7hkkceNZUVTaj7FmPf8aJ/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        }
      }
    }, {
      "id" : "IDs23XFFXAAZwXb9p684rDFk",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Pollos Hermanos",
        "business_type" : "TAX_EXEMPT_ORGANIZATION",
        "doing_business_as" : "Pollos Hermanos",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.PollosHermanos.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PUBLIC",
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Pollos Hermanos"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2021-11-22T23:50:58.25Z",
      "updated_at" : "2021-11-22T23:50:58.15Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDs23XFFXAAZwXb9p684rDFk"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDs23XFFXAAZwXb9p684rDFk/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDs23XFFXAAZwXb9p684rDFk/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDs23XFFXAAZwXb9p684rDFk/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDs23XFFXAAZwXb9p684rDFk/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDs23XFFXAAZwXb9p684rDFk/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDs23XFFXAAZwXb9p684rDFk/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDs23XFFXAAZwXb9p684rDFk/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDs23XFFXAAZwXb9p684rDFk/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        }
      }
    }, {
      "id" : "ID7vm9mhMbQm62oWQFzoxwwd",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Pawny City Hall",
        "business_type" : "ASSOCIATION_ESTATE_TRUST",
        "doing_business_as" : "Pawny City Hall",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.PawnyCityHall.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Pawny City Hall"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2021-11-22T23:50:57.60Z",
      "updated_at" : "2021-11-22T23:50:57.51Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7vm9mhMbQm62oWQFzoxwwd"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7vm9mhMbQm62oWQFzoxwwd/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7vm9mhMbQm62oWQFzoxwwd/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7vm9mhMbQm62oWQFzoxwwd/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7vm9mhMbQm62oWQFzoxwwd/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7vm9mhMbQm62oWQFzoxwwd/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7vm9mhMbQm62oWQFzoxwwd/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7vm9mhMbQm62oWQFzoxwwd/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7vm9mhMbQm62oWQFzoxwwd/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        }
      }
    }, {
      "id" : "IDfTuCK1xsknmnb5P6SLWwqq",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Pollos Hermanos",
        "business_type" : "PARTNERSHIP",
        "doing_business_as" : "Pollos Hermanos",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.PollosHermanos.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Pollos Hermanos"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2021-11-22T23:50:56.93Z",
      "updated_at" : "2021-11-22T23:50:56.82Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDfTuCK1xsknmnb5P6SLWwqq"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDfTuCK1xsknmnb5P6SLWwqq/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDfTuCK1xsknmnb5P6SLWwqq/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDfTuCK1xsknmnb5P6SLWwqq/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDfTuCK1xsknmnb5P6SLWwqq/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDfTuCK1xsknmnb5P6SLWwqq/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDfTuCK1xsknmnb5P6SLWwqq/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDfTuCK1xsknmnb5P6SLWwqq/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDfTuCK1xsknmnb5P6SLWwqq/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        }
      }
    }, {
      "id" : "IDuAyKsfHE21iv5YFziF4fAC",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Lees Sandwiches",
        "business_type" : "LIMITED_LIABILITY_COMPANY",
        "doing_business_as" : "Lees Sandwiches",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.LeesSandwiches.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Lees Sandwiches"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2021-11-22T23:50:56.19Z",
      "updated_at" : "2021-11-22T23:50:56.10Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDuAyKsfHE21iv5YFziF4fAC"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDuAyKsfHE21iv5YFziF4fAC/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDuAyKsfHE21iv5YFziF4fAC/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDuAyKsfHE21iv5YFziF4fAC/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDuAyKsfHE21iv5YFziF4fAC/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDuAyKsfHE21iv5YFziF4fAC/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDuAyKsfHE21iv5YFziF4fAC/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDuAyKsfHE21iv5YFziF4fAC/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDuAyKsfHE21iv5YFziF4fAC/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        }
      }
    }, {
      "id" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Bobs Burgers",
        "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
        "doing_business_as" : "Bobs Burgers",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.BobsBurgers.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Bobs Burgers"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2021-11-22T23:50:55.56Z",
      "updated_at" : "2021-11-22T23:50:55.47Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        }
      }
    }, {
      "id" : "IDsLPyMpP14Aiw1FxRyZP2Fd",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "entity" : {
        "title" : null,
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "BrainTree",
        "business_type" : "LIMITED_LIABILITY_COMPANY",
        "doing_business_as" : "BrainTree",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : null,
        "dob" : {
          "day" : 27,
          "month" : 5,
          "year" : 1978
        },
        "max_transaction_amount" : 1200000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : null,
        "annual_card_volume" : 0,
        "has_accepted_credit_cards_previously" : false,
        "incorporation_date" : null,
        "principal_percentage_ownership" : null,
        "short_business_name" : null,
        "ownership_type" : null,
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : null
      },
      "tags" : {
        "application_name" : "BrainTree"
      },
      "created_at" : "2021-11-22T23:50:32.42Z",
      "updated_at" : "2021-11-22T23:50:32.51Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDsLPyMpP14Aiw1FxRyZP2Fd"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDsLPyMpP14Aiw1FxRyZP2Fd/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDsLPyMpP14Aiw1FxRyZP2Fd/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDsLPyMpP14Aiw1FxRyZP2Fd/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDsLPyMpP14Aiw1FxRyZP2Fd/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDsLPyMpP14Aiw1FxRyZP2Fd/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDsLPyMpP14Aiw1FxRyZP2Fd/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDsLPyMpP14Aiw1FxRyZP2Fd/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDsLPyMpP14Aiw1FxRyZP2Fd/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 11
  }
}

List all Identities.

HTTP Request

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

Update an Identity

curl https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -X PUT \
    -d '
    {
        "tags": {
            "key": "value_2"
        }, 
        "entity": {
            "business_phone": "+1 (408) 756-4497", 
            "first_name": "Bernard", 
            "last_name": "Diaz", 
            "title": "CTO", 
            "dob": {
                "year": 1988, 
                "day": 2, 
                "month": 5
            }, 
            "ownership_type": "PRIVATE", 
            "has_accepted_credit_cards_previously": true, 
            "mcc": "0742", 
            "phone": "7144177878", 
            "business_tax_id": "123456789", 
            "max_transaction_amount": 1200000, 
            "principal_percentage_ownership": 50, 
            "doing_business_as": "Pawny City Hall", 
            "annual_card_volume": 12000000, 
            "default_statement_descriptor": "Pawny City Hall", 
            "url": "www.PawnyCityHall.com", 
            "business_name": "Pawny City Hall", 
            "personal_address": {
                "city": "San Diego", 
                "country": "USA", 
                "region": "CA", 
                "line2": "Apartment 2", 
                "line1": "712 Douglass St", 
                "postal_code": "94194"
            }, 
            "email": "user@example.org", 
            "tax_id": "999999999"
        }
    }'

Example Response:

{
  "id" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "entity" : {
    "title" : "CTO",
    "first_name" : "Bernard",
    "last_name" : "Diaz",
    "email" : "user@example.org",
    "business_name" : "Pawny City Hall",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "Pawny City Hall",
    "phone" : "7144177878",
    "business_phone" : "+1 (408) 756-4497",
    "personal_address" : {
      "line1" : "712 Douglass St",
      "line2" : "Apartment 2",
      "city" : "San Diego",
      "region" : "CA",
      "postal_code" : "94194",
      "country" : "USA"
    },
    "business_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 8",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "mcc" : "0742",
    "dob" : {
      "day" : 2,
      "month" : 5,
      "year" : 1988
    },
    "max_transaction_amount" : 1200000,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : "www.PawnyCityHall.com",
    "annual_card_volume" : 12000000,
    "has_accepted_credit_cards_previously" : true,
    "incorporation_date" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "principal_percentage_ownership" : 50,
    "short_business_name" : null,
    "ownership_type" : "PRIVATE",
    "tax_authority" : null,
    "tax_id_provided" : true,
    "business_tax_id_provided" : true,
    "default_statement_descriptor" : "Pawny City Hall"
  },
  "tags" : {
    "key" : "value_2"
  },
  "created_at" : "2021-11-22T23:50:55.56Z",
  "updated_at" : "2021-11-22T23:56:56.18Z",
  "additional_underwriting_data" : {
    "annual_ach_volume" : 200000,
    "average_ach_transfer_amount" : 200000,
    "average_card_transfer_amount" : 200000,
    "business_description" : "SB3 vegan cafe",
    "card_volume_distribution" : {
      "card_present_percentage" : 30,
      "ecommerce_percentage" : 60,
      "mail_order_telephone_order_percentage" : 10
    },
    "credit_check_allowed" : true,
    "credit_check_ip_address" : "42.1.1.113",
    "credit_check_timestamp" : "2021-04-28T16:42:55Z",
    "credit_check_user_agent" : "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)",
    "merchant_agreement_accepted" : true,
    "merchant_agreement_ip_address" : "42.1.1.113",
    "merchant_agreement_timestamp" : "2021-04-28T16:42:55Z",
    "merchant_agreement_user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)",
    "refund_policy" : "MERCHANDISE_EXCHANGE_ONLY",
    "volume_distribution_by_business_type" : {
      "business_to_business_volume_percentage" : 100,
      "business_to_consumer_volume_percentage" : 0,
      "consumer_to_consumer_volume_percentage" : 0,
      "other_volume_percentage" : 0,
      "person_to_person_volume_percentage" : 0
    }
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    }
  }
}

Update the information of a previously created Identity. In the case of Merchant accounts, this API request 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_address object, required Primary address for the legal entity (Full description of child attributes below)
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)
business_phone string, required Customer service phone number where the merchant can be reached (max 10 characters)
business_tax_id string, required 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)
business_type string, required Please select one of the following values: INDIVIDUAL_SOLE_PROPRIETORSHIP, CORPORATION, LIMITED_LIABILITY_COMPANY, PARTNERSHIP, ASSOCIATION_ESTATE_TRUST, TAX_EXEMPT_ORGANIZATION, INTERNATIONAL_ORGANIZATION, GOVERNMENT_AGENCY
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)
incorporation_date object, required Date company was founded (See below for a full list of the child attributes)
ownership_type string, required Values can be either PUBLIC to indicate a publicly traded company or PRIVATE for privately held businesses
url string, required Merchant’s publicly available website (max 100 characters)

Principal-specific Request Arguments

(i.e. authorized representative or primary contact responsible for the account)

Field Type Description
dob object, required Principal’s date of birth (Full description of child attributes below)
email string, required Principal’s email address where they can be reached (max 100 characters)
first_name string, required Full legal first name of the merchant’s principal representative (max 20 characters)
last_name string, required Full legal last name of the merchant’s principal representative (max 20 characters)
personal_address object, required Principal’s personal home address. This field is used for identity verification purposes (Full description of child attributes below)
phone string, required Principal’s phone number (max 10 characters)
principal_percentage_ownership integer, required Percentage of company owned by the principal (min 0; max 100)
tax_id string, required Nine digit Social Security Number (SSN) for the principal
title string, required Principal’s corporate title or role (i.e. Chief Executive Officer, CFO, etc.; max 60 characters)

Processing-specific Request Arguments

Field Type Description
annual_card_volume integer, required Approximate annual credit card sales expected to be processed in cents by this merchant (max 23 characters)
default_statement_descriptor string, required Billing descriptor displayed on the buyer’s bank or card statement (Length must be between 1 and 20 characters)
has_accepted_credit_cards_previously boolean, optional Defaults to false if not passed
max_transaction_amount integer, required Maximum amount that can be transacted for a single transaction in cents (max 12 characters)
mcc string, required Merchant Category Code (MCC) that this merchant will be classified under

Address-object Request Arguments

Field Type Description
city string, required City (max 20 characters)
country string, optional 3-Letter Country code
line1 string, optional First line of the address (max 35 characters)
line2 string, optional Second line of the address (max 35 characters)
postal_code string, optional Zip or Postal code (max 7 characters)
region string, optional 2-letter State code

Incorporation Date-object Request Arguments

Field Type Description
day integer, required Day business was incorporated (between 1 and 31)
month integer, required Month business was incorporated (between 1 and 12)
year integer, required Year business was incorporated (4-digit)

DOB-object Request Arguments

Field Type Description
day integer, required Day of birth (between 1 and 31)
month integer, required Month of birth (between 1 and 12)
year integer, required Year of birth (4-digit)

Provision a Merchant

curl https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -d '
    {
        "processor": null, 
        "tags": {
            "key_2": "value_2"
        }
    }'

Example Response:

{
  "id" : "MUwkMjGKSoqkjwg2s6Qe9GPx",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "identity" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
  "verification" : "VIiwqTD6WgoVE56heaL8DfvB",
  "merchant_profile" : "MPsZcjGQrrkMeV3bg1JrWbdt",
  "processor" : "DUMMY_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "card_expiration_date_required" : true,
  "card_cvv_required" : false,
  "tags" : {
    "key_2" : "value_2"
  },
  "mcc" : "0742",
  "mid" : "FNXiyZ8cZGmt2DJ6c21Ve4eT",
  "merchant_name" : "Bobs Burgers",
  "settlement_funding_identifier" : "UNSET",
  "ready_to_settle_upon" : null,
  "fee_ready_to_settle_upon" : "RECONCILIATION",
  "level_two_level_three_data_enabled" : false,
  "created_at" : "2021-11-22T23:51:01.91Z",
  "updated_at" : "2021-11-22T23:51:02.12Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : {
    "mid" : "FNXiyZ8cZGmt2DJ6c21Ve4eT",
    "api_key" : "secretValue"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUwkMjGKSoqkjwg2s6Qe9GPx"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUwkMjGKSoqkjwg2s6Qe9GPx/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPsZcjGQrrkMeV3bg1JrWbdt"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIiwqTD6WgoVE56heaL8DfvB"
    }
  }
}

To gateway transactions, provision the Merchant using the previously created Identity.

Merchant resources can have three possible onboarding_states:

  1. PROVISIONING: The request is pending (the state may change after two minutes)

    • processing_enabled: False
    • settlement_enabled: False

  2. APPROVED: The Merchant has been approved and can begin processing payments

    • processing_enabled: True
    • settlement_enabled: True

  3. REJECTED: The Merchant was rejected by the processor because of
    invalid information or it failed a regulatory and/or compliance check (e.g. KYC, OFAC, or MATCH)

    • processing_enabled: False
    • settlement_enabled: False

HTTP Request

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

URL Parameters

Parameter Description
:IDENTITY_ID ID of the Identity

Request Arguments

Field Type Description
processor string, required Name of the processor that you’re onboarding the Merchant with (a user can pass either null or DUMMY_V1 for sandbox)

Merchants

A Merchant resource represents a business’s merchant account on a processor, such as a web service that connects buyers (i.e. customers) and sellers (i.e. merchants).

Provision a Merchant

curl https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -d '
    {
        "processor": null, 
        "tags": {
            "key_2": "value_2"
        }
    }'

Example Response:

{
  "id" : "MUwkMjGKSoqkjwg2s6Qe9GPx",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "identity" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
  "verification" : "VIiwqTD6WgoVE56heaL8DfvB",
  "merchant_profile" : "MPsZcjGQrrkMeV3bg1JrWbdt",
  "processor" : "DUMMY_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "card_expiration_date_required" : true,
  "card_cvv_required" : false,
  "tags" : {
    "key_2" : "value_2"
  },
  "mcc" : "0742",
  "mid" : "FNXiyZ8cZGmt2DJ6c21Ve4eT",
  "merchant_name" : "Bobs Burgers",
  "settlement_funding_identifier" : "UNSET",
  "ready_to_settle_upon" : null,
  "fee_ready_to_settle_upon" : "RECONCILIATION",
  "level_two_level_three_data_enabled" : false,
  "created_at" : "2021-11-22T23:51:01.91Z",
  "updated_at" : "2021-11-22T23:51:02.12Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : {
    "mid" : "FNXiyZ8cZGmt2DJ6c21Ve4eT",
    "api_key" : "secretValue"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUwkMjGKSoqkjwg2s6Qe9GPx"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUwkMjGKSoqkjwg2s6Qe9GPx/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPsZcjGQrrkMeV3bg1JrWbdt"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIiwqTD6WgoVE56heaL8DfvB"
    }
  }
}

To gateway transactions, provision the Merchant using the previously created Identity.

Merchant resources can have three possible onboarding_states:

  1. PROVISIONING: The request is pending (the state may change after two minutes)

    • processing_enabled: False
    • settlement_enabled: False

  2. APPROVED: The Merchant has been approved and can begin processing payments

    • processing_enabled: True
    • settlement_enabled: True

  3. REJECTED: The Merchant was rejected by the processor because of
    invalid information or it failed a regulatory and/or compliance check (e.g. KYC, OFAC, or MATCH)

    • processing_enabled: False
    • settlement_enabled: False

HTTP Request

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

URL Parameters

Parameter Description
:IDENTITY_ID ID of the Identity

Request Arguments

Field Type Description
processor string, required Name of the processor that you’re onboarding the Merchant with (a user can pass either null or DUMMY_V1 for sandbox)
level_two_level_three_data_enabled boolean, optional Set to True to enable Merchant for Level 2 and Level 3 processing. Default value is false.

Fetch a Merchant

curl https://finix.sandbox-payments-api.com/merchants/MUwkMjGKSoqkjwg2s6Qe9GPx \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88

Example Response:

{
  "id" : "MUwkMjGKSoqkjwg2s6Qe9GPx",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "identity" : "IDnKHJ7wtcJDhK9RgSqFiYgr",
  "verification" : "VIiwqTD6WgoVE56heaL8DfvB",
  "merchant_profile" : "MPsZcjGQrrkMeV3bg1JrWbdt",
  "processor" : "DUMMY_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "card_expiration_date_required" : true,
  "card_cvv_required" : false,
  "tags" : {
    "key_2" : "value_2"
  },
  "mcc" : "0742",
  "mid" : "FNXiyZ8cZGmt2DJ6c21Ve4eT",
  "merchant_name" : "Bobs Burgers",
  "settlement_funding_identifier" : "UNSET",
  "ready_to_settle_upon" : "RECONCILIATION",
  "fee_ready_to_settle_upon" : "RECONCILIATION",
  "level_two_level_three_data_enabled" : false,
  "created_at" : "2021-11-22T23:51:01.91Z",
  "updated_at" : "2021-11-22T23:51:02.12Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : {
    "mid" : "FNXiyZ8cZGmt2DJ6c21Ve4eT",
    "api_key" : "secretValue"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUwkMjGKSoqkjwg2s6Qe9GPx"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnKHJ7wtcJDhK9RgSqFiYgr"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUwkMjGKSoqkjwg2s6Qe9GPx/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPsZcjGQrrkMeV3bg1JrWbdt"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIiwqTD6WgoVE56heaL8DfvB"
    }
  }
}

Fetch a previously created Merchant.

HTTP Request

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

URL Parameters

Parameter Description
:MERCHANT_ID ID of the Merchant

Reattempt Merchant Provisioning

curl https://finix.sandbox-payments-api.com/merchants/MUwkMjGKSoqkjwg2s6Qe9GPx/verifications \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -d '{}'

Example Response:

{
  "id" : "VI38Ehos1Q114eGKUV2GSfFy",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "tags" : { },
  "messages" : [ ],
  "raw" : null,
  "processor" : "DUMMY_V1",
  "state" : "PENDING",
  "created_at" : "2021-11-22T23:56:58.31Z",
  "updated_at" : "2021-11-22T23:56:58.36Z",
  "trace_id" : "e6b678e9-c365-4346-a0e9-d0c694f6eeea",
  "payment_instrument" : null,
  "merchant" : "MUwkMjGKSoqkjwg2s6Qe9GPx",
  "identity" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VI38Ehos1Q114eGKUV2GSfFy"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUwkMjGKSoqkjwg2s6Qe9GPx"
    }
  }
}

If the previous Merchant provisioning attempt returned a FAILED onboarding_state, then re-attempt provisioning on the processor.

HTTP Request

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

URL Parameters

Parameter Description
:MERCHANT_ID ID of the Merchant

[Card Present] Provision Merchant

curl https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR/merchants \
        -H "Content-Type: application/vnd.json+api" \
        -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
        -d '
        {
            "processor": "VANTIV_V1",
            "gateway": "TRIPOS_CLOUD_V1"
        }'

HTTP Request

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

URL Parameters

Parameter Description
:IDENTITY_ID ID of the Identity

Request Arguments

Field Type Description
processor string, required Name of the processor
gateway string, required Name of the gateway
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers) 
{
  "id" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "verification" : "VIhjGSJCnvXLzFQZUsUaeHxb",
  "merchant_profile" : "MPgDcdhXsdcJ9MVeJrZRNp79",
  "processor" : "VANTIV_V1",
  "processing_enabled" : false,
  "settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "tags" : { },
  "created_at" : "2019-03-01T00:49:02.47Z",
  "updated_at" : "2019-03-01T00:49:02.47Z",
  "onboarding_state" : "PROVISIONING",
  "processor_details" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPgDcdhXsdcJ9MVeJrZRNp79"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIhjGSJCnvXLzFQZUsUaeHxb"
    }
  }
}

Update Info on Processor

curl https://finix.sandbox-payments-api.com/merchants/MUwkMjGKSoqkjwg2s6Qe9GPx/verifications \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \
    -d '{}'

Example Response:

{
  "id" : "VI38Ehos1Q114eGKUV2GSfFy",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "tags" : { },
  "messages" : [ ],
  "raw" : null,
  "processor" : "DUMMY_V1",
  "state" : "PENDING",
  "created_at" : "2021-11-22T23:56:58.31Z",
  "updated_at" : "2021-11-22T23:56:58.36Z",
  "trace_id" : "e6b678e9-c365-4346-a0e9-d0c694f6eeea",
  "payment_instrument" : null,
  "merchant" : "MUwkMjGKSoqkjwg2s6Qe9GPx",
  "identity" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VI38Ehos1Q114eGKUV2GSfFy"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUwkMjGKSoqkjwg2s6Qe9GPx"
    }
  }
}

Update Identity information (e.g. default_statement_descriptor, KYC info, etc.) on the underlying processor.

HTTP Request

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

URL Parameters

Parameter Description
:MERCHANT_ID ID of the Merchant

Update Merchant to Enable Level 2/Level 3 Processing 

curl https://finix.sandbox-payments-api.com/merchants/MUfWNiRCntW1KCRVjH4jEoba \
    -H "Content-Type: application/vnd.json+api" \
    -u  USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041 \
    -X PUT \
    -d '
    {
        "level_two_level_three_data_enabled": true
    }'

Example Response:

{
  "id" : "MUfWNiRCntW1KCRVjH4jEoba",
  "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
  "identity" : "ID2cAnM4kbLE4abQWj2fydHw",
  "verification" : "VI3CgdWq8PEnsWEY8SsQDK9N",
  "merchant_profile" : "MPwwzqTtGtXHG77Kwt8KsbQH",
  "processor" : "DUMMY_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "card_expiration_date_required" : false,
  "card_cvv_required" : false,
  "tags" : {
    "key_2" : "value_2"
  },
  "mcc" : "0742",
  "mid" : "FNXjNwryzN6E6uKfKaf6Yu1w9",
  "merchant_name" : "Bobs Burgers",
  "settlement_funding_identifier" : "UNSET",
  "ready_to_settle_upon" : null,
  "fee_ready_to_settle_upon" : "RECONCILIATION",
  "level_two_level_three_data_enabled" : true,
  "created_at" : "2021-11-22T23:51:08.21Z",
  "updated_at" : "2021-11-22T23:51:09.84Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : {
    "mid" : "FNXjNwryzN6E6uKfKaf6Yu1w9",
    "api_key" : "secretValue"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUfWNiRCntW1KCRVjH4jEoba"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID2cAnM4kbLE4abQWj2fydHw"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUfWNiRCntW1KCRVjH4jEoba/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPwwzqTtGtXHG77Kwt8KsbQH"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APj9Gw6wRhpbaHJM1QtZakqH"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VI3CgdWq8PEnsWEY8SsQDK9N"
    }
  }
}

Enabling this flag will allow a Merchant to engage in Level 2/3 processing.

HTTP Request

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

URL Parameters

Parameter Description
:MERCHANT_ID ID of the Identity

Request Arguments

Field Type Description
level_two_level_three_data_enabled boolean, optional Set to True to enable Merchant for Level 2 and Level 3 processing. Default value is false.

List All Merchants

curl https://finix.sandbox-payments-api.com/merchants/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88

Example Response:

{
  "_embedded" : {
    "merchants" : [ {
      "id" : "MUfWNiRCntW1KCRVjH4jEoba",
      "application" : "APj9Gw6wRhpbaHJM1QtZakqH",
      "identity" : "ID2cAnM4kbLE4abQWj2fydHw",
      "verification" : "VI3CgdWq8PEnsWEY8SsQDK9N",
      "merchant_profile" : "MPwwzqTtGtXHG77Kwt8KsbQH",
      "processor" : "DUMMY_V1",
      "processing_enabled" : true,
      "settlement_enabled" : true,
      "gross_settlement_enabled" : false,
      "creating_transfer_from_report_enabled" : false,
      "card_expiration_date_required" : true,