docs
NAV
cURL Java PHP Python Ruby

Topics

API Endpoints

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

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  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed


/*
Add the following to your pom.xml (Maven file):

<dependency>
  <groupId>io.finix.payments.processing.client</groupId>
  <artifactId>finix</artifactId>
  <version>1.0.0</version>
</dependency>

...

<repositories>
  <repository>
      <id>ossrh</id>
      <url>https://oss.sonatype.org/content/repositories/</url>
      <snapshots>
          <enabled>true</enabled>
      </snapshots>
  </repository>
</repositories>

*/

import io.finix.payments.ApiClient;
import io.finix.payments.views.*;
import io.finix.payments.forms.*;

//...

public static void main(String[] args) {

  ApiClient api = ApiClient.builder()
                  .url("https://finix.sandbox-payments-api.com")
                  .user("US9B3AqAqaf6Jab9bzgBhaBU")
                  .password("4f81ec6a-0dff-4b06-a262-a34f757ad6ed")
                  .build();
//...


<?php
// Download the PHP Client here: https://github.com/finix-payments/processing-php-client

require_once('vendor/autoload.php');
require(__DIR__ . '/src/Finix/Settings.php');

Finix\Settings::configure([
    "root_url" => 'https://finix.sandbox-payments-api.com',
    "username" => 'US9B3AqAqaf6Jab9bzgBhaBU',
    "password" => '4f81ec6a-0dff-4b06-a262-a34f757ad6ed']
    );

require(__DIR__ . '/src/Finix/Bootstrap.php');
Finix\Bootstrap::init();




# To install the python client run the command below from your terminal:
# pip install finix

import finix

from finix.config import configure
configure(root_url="https://finix.sandbox-payments-api.com", auth=("US9B3AqAqaf6Jab9bzgBhaBU", "4f81ec6a-0dff-4b06-a262-a34f757ad6ed"))


# To download the Ruby gem:
# gem install finix

require 'finix'

Finix.configure(
    :root_url => 'https://finix.sandbox-payments-api.com',
    :user=>'US9B3AqAqaf6Jab9bzgBhaBU',
    :password => '4f81ec6a-0dff-4b06-a262-a34f757ad6ed'
)

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

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

Dashboard Overview

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

Sign Up

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

Create Live Account

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

Create an Identity for a Merchant

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

Create a Bank Account for a Merchant

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

Onboarding a New Merchant

To begin, select Merchant on the sidebar, then select your desired merchant. Next, click the “Processors” tab and click “Create verification”. Lastly, click “Create” to onboard the merchant.

View KYC Identity Verification

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

Approve Merchant

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

Enable or Disable Processing Functionality

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

Enable or Disable Settlement Functionality

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

Edit Fees & Interchange Plus

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

Enable CVV & AVS

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

Approve a Settlement

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

Upload Dispute Evidence

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

Errors

HTTP Code Meaning
400 Bad Request – You’ve attemped an invalid request
401 Unauthorized – You have used the incorrect API key
402 Upstream Processor Error – Errors caused by 3rd party service
404 Not Found – The specified resource could not be found
422 Unprocessable Entity – The parameters were valid but the request failed. The error is usually some misunderstanding of various steps that have to be executed in order (e.g. attempting to initiate a transfer on behalf of a merchant that has not yet been approved)
500 Internal Server Error – We had a problem with our server. Try again later.

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

Error Code Messages
REFER_TO_CARD_ISSUER Please contact card issuer for more information.
INVALID_MERCHANT Merchant not permitted for this transaction type
PICK_UP_CARD_NO_FRAUD Please contact card issuer for more information.
DO_NOT_HONOR Please contact card issuer for more information.
ERROR Please attempt transaction again but if it still cannot be processed try again at a later time
PICK_UP_CARD_FRAUD_ACCOUNT Please contact card issuer for more information.
INVALID_TRANSACTION Issuing bank does not support this transaction type on this card. Please contact card issuer for more information.
INVALID_AMOUNT_OR_CURRENCY Transaction violates network amount limit.
INVALID_ACCOUNT_NUMBER The account number does not exist. Please make sure the account number is correct or contact your issuer.
NO_SUCH_ISSUER The issuer can not be found. Please check card number to ensure it is valid.
RE_ENTER_TRANSACTION Please attempt transaction again and contact card issuer if it still cannot be processed.
NO_ACTION_TAKEN Please contact card issuer for more information.
UNABLE_TO_LOCATE_RECORD The account number does not exist. Please make sure the account number is correct or contact your issuer.
FILE_TEMPORARILY_NOT_AVAILABLE Please contact card issuer for more information.
NO_CREDIT_ACCOUNT Issuer has declined the transaction because the card is not a credit account. Please try another card.
LOST_CARD_PICK_UP_FRAUD_ACCOUNT Please contact card issuer for more information.
STOLEN_CARD_PICK_UP_FRAUD_ACCOUNT Please contact card issuer for more information.
NOT_SUFFICIENT_FUNDS Card issuer has declined the transaction as it does not have sufficient funds.
NO_CHECKING_ACCOUNT The card is not tied to a checking account and thus cannot be processed. Please try another card.
NO_SAVINGS_ACCOUNT The card is not tied to a savings account and thus cannot be processed. Please try another card.
EXPIRED_CARD The expiration date is expired or missing. Please correct and try again.
INCORRECT_PIN The PIN is invalid or missing. Please try again with the correct PIN.
TRANSACTION_NOT_PERMITTED Transaction not permitted to cardholder. Please contact card issuer for more information.
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.

Idempotency Requests

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

Tags

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

Testing for specific responses and errors

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

Amount Description
100 Success amount
102 Failed amount
888888 Disputed amount
193 Insufficient funds amount
194 Invalid card number amount
889986 AVS total failure amount
889987 CVC failure amount
Card Description
4000000000000036 Payment card AVS total failure
4000000000000127 Payment card CVC failure

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

Cards for Testing a Push to Card Payout

Scenario number security_code address.line1 postal_code region city country address_verification_results cvv2_result_code
Successful push to card payout (credit card) 4957030420210454 999 801 Metro Center Blv 94404 CA San Francisco USA Y M
Successful push to card payout (debit card) 4895142232120006 022 900 Metro Center Blv 94404 CA San Francisco USA M M
Invalid account number 4957040000000001 999 801 Metro Center Blv 94404 CA San Francisco USA I P
Invalid Zip Code and CVV2 values 4957030420210488 227 900 Metro Center Blv 94402 CA San Francisco USA A N
Invalid CVV2 value 4957030420210496 664 900 Metro Center Blv 94404 CA San Francisco USA Y N
Invalid Address, Zip code and CVV2 values 4957030420210504 322 901 Metro Center Blv 94404 CA San Francisco USA Z N

Cards for Testing a Verification

Scenario number fast_funds_indicator push_funds_block_indicator card_type_code card_issuer_country_code
Issuer does Participates in Fast Funds 4815070000000018 D C D 840
Issuer does Not Participates in Fast Funds 4855070000000035 N C D 840
Issuer does Not Participates in Fast Funds or Push to Card 4895047700003297 N N C 840

Guides

Overview

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

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

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

  6. 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  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '
    {
        "tags": {
            "Studio Rating": "4.7"
        },
        "entity": {
            "last_name": "Sunkhronos",
            "max_transaction_amount": 12000000,
            "has_accepted_credit_cards_previously": true,
            "default_statement_descriptor": "Pawny City Hall",
            "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": "Pawny City Hall",
            "principal_percentage_ownership": 50,
            "email": "user@example.org",
            "mcc": "0742",
            "phone": "1234567890",
            "business_name": "Pawny City Hall",
            "tax_id": "123456789",
            "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone": "+1 (408) 756-4497",
            "dob": {
                "year": 1978,
                "day": 27,
                "month": 6
            },
            "url": "www.PawnyCityHall.com",
            "annual_card_volume": 12000000
        }
    }'


import io.finix.payments.ApiClient;
import io.finix.payments.enums.BusinessType;
import io.finix.payments.forms.Address;
import io.finix.payments.forms.Date;
import io.finix.payments.forms.IdentityEntityForm;
import io.finix.payments.forms.IdentityForm;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.views.Identity;


IdentityForm form = IdentityForm.builder()
  .entity(IdentityEntityForm.builder()
  .firstName("dwayne")
  .lastName("Sunkhronos")
  .email("user@example.org")
  .businessName("business inc")
  .businessType(BusinessType.LIMITED_LIABILITY_COMPANY)
  .doingBusinessAs("doingBusinessAs")
  .phone("1234567890")
  .businessPhone("+1 (408) 756-4497")
  .taxId("123456789")
  .businessTaxId("123456789")
  .personalAddress(Address.builder()
  .line1("741 Douglass St")
  .line2("Apartment 7")
  .city("San Mateo")
  .region("CA")
  .postalCode("94114")
  .country("USA")
  .build())
  .businessAddress(Address.builder()
  .line1("741 Douglass St")
  .line2("Apartment 7")
  .city("San Mateo")
  .region("CA")
  .postalCode("94114")
  .country("USA")
  .build())
  .dob(Date.builder().day(Integer.valueOf(27)).month(Integer.valueOf(5)).year(Integer.valueOf(1978)).build())
  .maxTransactionAmount(Long.valueOf(1000L))
  .mcc("7399").url("http://sample-entity.com")
  .annualCardVolume(Long.valueOf(100L))
  .defaultStatementDescriptor("Business Inc")
  .incorporationDate(Date.builder().day(Integer.valueOf(1)).month(Integer.valueOf(12)).year(Integer.valueOf(2012)).build())
  .principalPercentageOwnership(Integer.valueOf(51)).build()).build();

Maybe<Identity> response = api.identities.post(form);
if(! response.succeeded().booleanValue()) {
    ApiError error = response.error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to create Identity");
}
    Identity identity = (Identity)response.view();
    identity.getId();


<?php
use Finix\Resources\Identity;

$identity = new Identity(
    array(
        "tags"=> array(
            "Studio Rating"=> "4.7"
        ),
        "entity"=> array(
            "last_name"=> "Sunkhronos",
            "max_transaction_amount"=> 12000000,
            "has_accepted_credit_cards_previously"=> true,
            "default_statement_descriptor"=> "Pawny City Hall",
            "personal_address"=> array(
                "city"=> "San Mateo",
                "country"=> "USA",
                "region"=> "CA",
                "line2"=> "Apartment 7",
                "line1"=> "741 Douglass St",
                "postal_code"=> "94114"
            ),
            "incorporation_date"=> array(
                "year"=> 1978,
                "day"=> 27,
                "month"=> 6
            ),
            "business_address"=> array(
                "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"=> "Pawny City Hall",
            "principal_percentage_ownership"=> 50,
            "email"=> "user@example.org",
            "mcc"=> "0742",
            "phone"=> "1234567890",
            "business_name"=> "Pawny City Hall",
            "tax_id"=> "123456789",
            "business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone"=> "+1 (408) 756-4497",
            "dob"=> array(
                "year"=> 1978,
                "day"=> 27,
                "month"=> 6
            ),
            "url"=> "www.PawnyCityHall.com",
            "annual_card_volume"=> 12000000
        )
    )
);
$identity = $identity->save();




from finix.resources import Identity

identity = Identity(**
    {
        "tags": {
            "Studio Rating": "4.7"
        },
        "entity": {
            "last_name": "Sunkhronos",
            "max_transaction_amount": 12000000,
            "has_accepted_credit_cards_previously": True,
            "default_statement_descriptor": "Pawny City Hall",
            "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": "Pawny City Hall",
            "principal_percentage_ownership": 50,
            "email": "user@example.org",
            "mcc": "0742",
            "phone": "1234567890",
            "business_name": "Pawny City Hall",
            "tax_id": "123456789",
            "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone": "+1 (408) 756-4497",
            "dob": {
                "year": 1978,
                "day": 27,
                "month": 6
            },
            "url": "www.PawnyCityHall.com",
            "annual_card_volume": 12000000
        }
    }).save()


identity = Finix::Identity.new(
    {
        "tags"=> {
            "Studio Rating"=> "4.7"
        },
        "entity"=> {
            "last_name"=> "Sunkhronos",
            "max_transaction_amount"=> 12000000,
            "has_accepted_credit_cards_previously"=> true,
            "default_statement_descriptor"=> "Pawny City Hall",
            "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"=> "Pawny City Hall",
            "principal_percentage_ownership"=> 50,
            "email"=> "user@example.org",
            "mcc"=> "0742",
            "phone"=> "1234567890",
            "business_name"=> "Pawny City Hall",
            "tax_id"=> "123456789",
            "business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone"=> "+1 (408) 756-4497",
            "dob"=> {
                "year"=> 1978,
                "day"=> 27,
                "month"=> 6
            },
            "url"=> "www.PawnyCityHall.com",
            "annual_card_volume"=> 12000000
        }
    }).save

Example Response:

{
  "id" : "IDtYboiBEsqMo9WqqCeswAXL",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "entity" : {
    "title" : "CEO",
    "first_name" : "dwayne",
    "last_name" : "Sunkhronos",
    "email" : "user@example.org",
    "business_name" : "Pawny City Hall",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "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_id_provided" : true,
    "business_tax_id_provided" : true,
    "default_statement_descriptor" : "Pawny City Hall"
  },
  "tags" : {
    "Studio Rating" : "4.7"
  },
  "created_at" : "2019-03-13T22:08:55.92Z",
  "updated_at" : "2019-03-13T22:08:55.92Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    }
  }
}

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

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

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  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '
    {
        "account_type": "SAVINGS",
        "name": "Fran Lemke",
        "tags": {
            "Bank Account": "Company Account"
        },
        "country": "USA",
        "bank_code": "123123123",
        "account_number": "123123123",
        "type": "BANK_ACCOUNT",
        "identity": "IDtYboiBEsqMo9WqqCeswAXL"
    }'



import io.finix.payments.ApiClient;
import io.finix.payments.enums.BankAccountType;
import io.finix.payments.forms.BankAccountForm;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.views.BankAccount;
import io.finix.payments.views.Identity;
import java.util.Currency;

BankAccountForm form = BankAccountForm.builder()
        .name("Joe Doe")
        .identity("IDtYboiBEsqMo9WqqCeswAXL")
        .accountNumber("84012312415")
        .bankCode("840123124")
        .accountType(BankAccountType.SAVINGS)
        .companyName("company name")
        .country("USA")
        .currency(Currency.getInstance("USD"))
        .build();

Maybe<BankAccount> request = api.instruments.post(form);

if (! request.succeeded()) {
    ApiError error = request.error();
    System.out.println(error);
    throw new RuntimeException("API error attempting to create bank account");
}
BankAccount bankAccount = request.view();


<?php
use Finix\Resources\Identity;
use Finix\Resources\BankAccount;

$identity = Identity::retrieve('IDtYboiBEsqMo9WqqCeswAXL');
$bank_account = new BankAccount(
    array(
        "account_type"=> "SAVINGS",
        "name"=> "Fran Lemke",
        "tags"=> array(
            "Bank Account"=> "Company Account"
        ),
        "country"=> "USA",
        "bank_code"=> "123123123",
        "account_number"=> "123123123",
        "type"=> "BANK_ACCOUNT",
        "identity"=> "IDtYboiBEsqMo9WqqCeswAXL"
    ));
$bank_account = $identity->createBankAccount($bank_account);



from finix.resources import BankAccount

bank_account = BankAccount(**
    {
        "account_type": "SAVINGS",
        "name": "Fran Lemke",
        "tags": {
            "Bank Account": "Company Account"
        },
        "country": "USA",
        "bank_code": "123123123",
        "account_number": "123123123",
        "type": "BANK_ACCOUNT",
        "identity": "IDtYboiBEsqMo9WqqCeswAXL"
    }).save()


bank_account = Finix::BankAccount.new(
    {
        "account_type"=> "SAVINGS",
        "name"=> "Fran Lemke",
        "tags"=> {
            "Bank Account"=> "Company Account"
        },
        "country"=> "USA",
        "bank_code"=> "123123123",
        "account_number"=> "123123123",
        "type"=> "BANK_ACCOUNT",
        "identity"=> "IDtYboiBEsqMo9WqqCeswAXL"
    }).save

Example Response:

{
  "id" : "PIdyidW1HNq47hDSrRjFckqn",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
  "tags" : {
    "Bank Account" : "Company Account"
  },
  "bank_code" : "123123123",
  "country" : "USA",
  "masked_account_number" : "XXXXX3123",
  "name" : "Fran Lemke",
  "account_type" : "SAVINGS",
  "created_at" : "2019-03-13T22:09:01.72Z",
  "updated_at" : "2019-03-13T22:09:01.72Z",
  "instrument_type" : "BANK_ACCOUNT",
  "type" : "BANK_ACCOUNT",
  "currency" : "USD",
  "identity" : "IDtYboiBEsqMo9WqqCeswAXL",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdyidW1HNq47hDSrRjFckqn"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdyidW1HNq47hDSrRjFckqn/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdyidW1HNq47hDSrRjFckqn/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdyidW1HNq47hDSrRjFckqn/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    }
  }
}

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/IDtYboiBEsqMo9WqqCeswAXL/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '
    {
        "processor": null,
        "tags": {
            "key_2": "value_2"
        }
    }'

import io.finix.payments.processing.client.model.Merchant;

Merchant merchant = identity.provisionMerchantOn(Merchant.builder().build());


<?php
use Finix\Resources\Identity;
use Finix\Resources\Merchant;

$identity = Identity::retrieve('IDtYboiBEsqMo9WqqCeswAXL');
$merchant = $identity->provisionMerchantOn(new Merchant());



from finix.resources import Identity
from finix.resources import Merchant

identity = Identity.get(id="IDtYboiBEsqMo9WqqCeswAXL")
merchant = identity.provision_merchant_on(Merchant())

identity = Finix::Identity.retrieve(:id=>"IDtYboiBEsqMo9WqqCeswAXL")

merchant = identity.provision_merchant

Example Response:

{
  "id" : "MU283Zr8JgEeVzvg8sUSGiU2",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "identity" : "IDtYboiBEsqMo9WqqCeswAXL",
  "verification" : "VI3L9XzyskUEzYPAku37BswX",
  "merchant_profile" : "MPad2wRbceApbBwtZ9TbpP62",
  "processor" : "DUMMY_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "creating_transfer_from_report_enabled" : false,
  "tags" : {
    "key_2" : "value_2"
  },
  "created_at" : "2019-03-13T22:09:03.67Z",
  "updated_at" : "2019-03-13T22:09:03.86Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : {
    "api_key" : "secretValue"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU283Zr8JgEeVzvg8sUSGiU2"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU283Zr8JgEeVzvg8sUSGiU2/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPad2wRbceApbBwtZ9TbpP62"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VI3L9XzyskUEzYPAku37BswX"
    }
  }
}

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

Step 4: Create an Identity for a Buyer


curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '
    {
        "tags": {
            "key": "value"
        },
        "entity": {
            "phone": "7145677613",
            "first_name": "Michael",
            "last_name": "Lopez",
            "email": "therock@gmail.com",
            "personal_address": {
                "city": "San Mateo",
                "country": "USA",
                "region": "CA",
                "line2": "Apartment 7",
                "line1": "741 Douglass St",
                "postal_code": "94114"
            }
        }
    }'


import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.forms.Address;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.forms.Date;


IdentityForm form = IdentityForm.builder()
    .entity(
    IdentityEntityForm.builder()
        .firstName("dwayne")
        .lastName("Sunkhronos")
        .email("user@example.org")
        .personalAddress(
            Address.builder()
                .line1("741 Douglass St")
                .line2("Apartment 7")
                .city("San Mateo")
                .region("CA")
                .postalCode("94114")
                .country("USA")
                .build()
        )
        .build())
      .build();

Maybe<Identity> response = api.identities.post(form);

if (! response.succeeded()) {
    ApiError error = response.error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to create Identity");
}

Identity identity = response.view();


<?php
use Finix\Resources\Identity;

$identity = new Identity(
    array(
        "tags"=> array(
            "key"=> "value"
        ),
        "entity"=> array(
            "phone"=> "7145677613",
            "first_name"=> "Michael",
            "last_name"=> "Lopez",
            "email"=> "therock@gmail.com",
            "personal_address"=> array(
                "city"=> "San Mateo",
                "country"=> "USA",
                "region"=> "CA",
                "line2"=> "Apartment 7",
                "line1"=> "741 Douglass St",
                "postal_code"=> "94114"
            )
        )
    ));
$identity = $identity->save();




from finix.resources import Identity

identity = Identity(**
    {
        "tags": {
            "key": "value"
        },
        "entity": {
            "phone": "7145677613",
            "first_name": "Michael",
            "last_name": "Lopez",
            "email": "therock@gmail.com",
            "personal_address": {
                "city": "San Mateo",
                "country": "USA",
                "region": "CA",
                "line2": "Apartment 7",
                "line1": "741 Douglass St",
                "postal_code": "94114"
            }
        }
    }).save()


identity = Finix::Identity.new(
    {
        "tags"=> {
            "key"=> "value"
        },
        "entity"=> {
            "phone"=> "7145677613",
            "first_name"=> "Michael",
            "last_name"=> "Lopez",
            "email"=> "therock@gmail.com",
            "personal_address"=> {
                "city"=> "San Mateo",
                "country"=> "USA",
                "region"=> "CA",
                "line2"=> "Apartment 7",
                "line1"=> "741 Douglass St",
                "postal_code"=> "94114"
            }
        }
    }).save

Example Response:

{
  "id" : "IDbUcrKrk2ksC2oiirfLF17t",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "entity" : {
    "title" : null,
    "first_name" : "Michael",
    "last_name" : "Lopez",
    "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_id_provided" : false,
    "business_tax_id_provided" : false,
    "default_statement_descriptor" : null
  },
  "tags" : {
    "key" : "value"
  },
  "created_at" : "2019-03-13T22:09:04.95Z",
  "updated_at" : "2019-03-13T22:09:04.95Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    }
  }
}

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 60 characters)
line2 string, optional Second line of the address (max 60 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  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '
    {
        "name": "Laura Jones",
        "expiration_year": 2020,
        "tags": {
            "card_name": "Business Card"
        },
        "number": "4895142232120006",
        "expiration_month": 3,
        "address": {
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "94404",
            "line1": "900 Metro Center Blv",
            "country": "USA"
        },
        "security_code": "022",
        "type": "PAYMENT_CARD",
        "identity": "IDbUcrKrk2ksC2oiirfLF17t"
    }'



import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.forms.Address;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import com.google.common.collect.ImmutableMap;

PaymentCardForm form = PaymentCardForm.builder()
        .name("Joe Doe")
        .number("4957030420210454")
        .securityCode("112")
        .expirationYear(2020)
        .identity("IDtYboiBEsqMo9WqqCeswAXL")
        .expirationMonth(12)
        .address(
                Address.builder()
                        .city("San Mateo")
                        .country("USA")
                        .region("CA")
                        .line1("123 Fake St")
                        .line2("#7")
                        .postalCode("90210")
                        .build()
        )
        .tags(ImmutableMap.of("card_name", "Business Card"))
        .build();

Maybe<PaymentCard> response = api.instruments.post(form);
        if (! response.succeeded()) {
            ApiError error = response .error();
            System.out.println(error.getCode());
            throw new RuntimeException("API error attempting to create Payment Card");
        }
PaymentCard card = response.view();


<?php
use Finix\Resources\PaymentCard;
use Finix\Resources\Identity;

$identity = Identity::retrieve('IDtYboiBEsqMo9WqqCeswAXL');
$card = new PaymentCard(
    array(
        "name"=> "Laura Jones",
        "expiration_year"=> 2020,
        "tags"=> array(
            "card_name"=> "Business Card"
        ),
        "number"=> "4895142232120006",
        "expiration_month"=> 3,
        "address"=> array(
            "city"=> "San Francisco",
            "region"=> "CA",
            "postal_code"=> "94404",
            "line1"=> "900 Metro Center Blv",
            "country"=> "USA"
        ),
        "security_code"=> "022",
        "type"=> "PAYMENT_CARD",
        "identity"=> "IDbUcrKrk2ksC2oiirfLF17t"
    ));
$card = $identity->createPaymentCard($card);




from finix.resources import PaymentCard

card = PaymentCard(**
    {
        "name": "Laura Jones",
        "expiration_year": 2020,
        "tags": {
            "card_name": "Business Card"
        },
        "number": "4895142232120006",
        "expiration_month": 3,
        "address": {
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "94404",
            "line1": "900 Metro Center Blv",
            "country": "USA"
        },
        "security_code": "022",
        "type": "PAYMENT_CARD",
        "identity": "IDbUcrKrk2ksC2oiirfLF17t"
    }).save()

card = Finix::PaymentCard.new(
    {
        "name"=> "Laura Jones",
        "expiration_year"=> 2020,
        "tags"=> {
            "card_name"=> "Business Card"
        },
        "number"=> "4895142232120006",
        "expiration_month"=> 3,
        "address"=> {
            "city"=> "San Francisco",
            "region"=> "CA",
            "postal_code"=> "94404",
            "line1"=> "900 Metro Center Blv",
            "country"=> "USA"
        },
        "security_code"=> "022",
        "type"=> "PAYMENT_CARD",
        "identity"=> "IDbUcrKrk2ksC2oiirfLF17t"
    }).save

Example Response:

{
  "id" : "PIgM3PiQZsPUyhds2hZRgUGe",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 3,
  "expiration_year" : 2020,
  "bin" : "489514",
  "last_four" : "0006",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Laura Jones",
  "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" : "2019-03-13T22:09:05.85Z",
  "updated_at" : "2019-03-13T22:09:05.85Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDbUcrKrk2ksC2oiirfLF17t",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe/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 60 characters)
line2 string, optional Second line of the address (max 60 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 an Authorization

curl https://finix.sandbox-payments-api.com/authorizations \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '
    {
        "merchant_identity": "IDtYboiBEsqMo9WqqCeswAXL",
        "currency": "USD",
        "amount": 100,
        "source": "PIgM3PiQZsPUyhds2hZRgUGe",
        "tags": {
            "order_number": "21DFASJSAKAS"
        }
    }'


import io.finix.payments.ApiClient;
import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;

AuthorizationCreateForm formCreateAuthorization = AuthorizationCreateForm.builder()
    .amount(10000L)
    .merchantIdentity("IDtYboiBEsqMo9WqqCeswAXL")
    .source("PIgM3PiQZsPUyhds2hZRgUGe")
    .build();

Maybe<Authorization> response = api.authorizations.post(formCreateAuthorization);

if (! response.succeeded()) {
  ApiError error = response.error();
  System.out.println(error.getMessage());
  throw new RuntimeException("API error attempting to creating Authorization");
}

Authorization authorization = response.view();


<?php
use Finix\Resources\Authorization;

$authorization = new Authorization(
    array(
        "merchant_identity"=> "IDtYboiBEsqMo9WqqCeswAXL",
        "currency"=> "USD",
        "amount"=> 100,
        "source"=> "PIgM3PiQZsPUyhds2hZRgUGe",
        "tags"=> array(
            "order_number"=> "21DFASJSAKAS"
        )
    ));
$authorization = $authorization->save();




from finix.resources import Authorization
authorization = Authorization(**
    {
        "merchant_identity": "IDtYboiBEsqMo9WqqCeswAXL",
        "currency": "USD",
        "amount": 100,
        "source": "PIgM3PiQZsPUyhds2hZRgUGe",
        "tags": {
            "order_number": "21DFASJSAKAS"
        }
    }).save()


authorization = Finix::Authorization.new(
    {
        "merchant_identity"=> "IDtYboiBEsqMo9WqqCeswAXL",
        "currency"=> "USD",
        "amount"=> 100,
        "source"=> "PIgM3PiQZsPUyhds2hZRgUGe",
        "tags"=> {
            "order_number"=> "21DFASJSAKAS"
        }
    }).save

Example Response:

{
  "id" : "AUvGP4ivrCY3oaxFQrPtB9Ne",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2019-03-13T22:09:31.96Z",
  "updated_at" : "2019-03-13T22:09:32.01Z",
  "trace_id" : "630b209a-14e9-4edd-84c6-b03ebfa3beb3",
  "source" : "PIgM3PiQZsPUyhds2hZRgUGe",
  "merchant_identity" : "IDtYboiBEsqMo9WqqCeswAXL",
  "is_void" : false,
  "expires_at" : "2019-03-20T22:09:31.96Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUvGP4ivrCY3oaxFQrPtB9Ne"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    }
  }
}

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

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

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

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

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

HTTP Request

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

Request Arguments

Field Type Description
source string, required The buyer’s Payment Instrument ID that you will be performing the authorization
merchant_identity string, required The ID of the Identity for the merchant that you are transacting on behalf of
amount integer, required The amount of the authorization in cents
currency string, required 3-letter ISO code designating the currency (e.g. USD)
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)

Step 7: Capture the Authorization

curl https://finix.sandbox-payments-api.com/authorizations/AUvGP4ivrCY3oaxFQrPtB9Ne \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -X PUT \
    -d '
    {
        "fee": "10",
        "capture_amount": 100
    }'

import io.finix.payments.ApiClient;
import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;

AuthorizationUpdateForm form = AuthorizationUpdateForm.builder()
    .captureAmount(100L)
    .fee(10L)
    .statementDescriptor("Order 123")
    .build();

Maybe<Authorization> response = api.authorizations.id("AUvGP4ivrCY3oaxFQrPtB9Ne").put(form);

if (! response.succeeded()) {
    ApiError error = response.error();
    System.out.println(error.getMessage());
    throw new RuntimeException("API error attempting to capture authorization");
}
Authorization capturedAuthorization = response.view();


<?php
use Finix\Resources\Authorization;

$authorization = Authorization::retrieve('AUvGP4ivrCY3oaxFQrPtB9Ne');
$authorization = $authorization->capture(50, 10);




from finix.resources import Authorization

authorization = Authorization.get(id="AUvGP4ivrCY3oaxFQrPtB9Ne")
authorization.capture(**
    {
        "fee": "10",
        "capture_amount": 100
    })


authorization = Finix::Authorization.retrieve(:id=>"AUvGP4ivrCY3oaxFQrPtB9Ne")
authorization = authorization.capture(
    {
        "fee"=> "10",
        "capture_amount"=> 100
    })

Example Response:

{
  "id" : "AUvGP4ivrCY3oaxFQrPtB9Ne",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : "TR3spQQCm7ZpyWnV7mP47fxV",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2019-03-13T22:09:31.96Z",
  "updated_at" : "2019-03-13T22:09:33.44Z",
  "trace_id" : "630b209a-14e9-4edd-84c6-b03ebfa3beb3",
  "source" : "PIgM3PiQZsPUyhds2hZRgUGe",
  "merchant_identity" : "IDtYboiBEsqMo9WqqCeswAXL",
  "is_void" : false,
  "expires_at" : "2019-03-20T22:09:31.96Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUvGP4ivrCY3oaxFQrPtB9Ne"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "transfer" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR3spQQCm7ZpyWnV7mP47fxV"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    }
  }
}

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

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

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

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

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

Step 8: Create a Batch Settlement

curl https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/settlements \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '
    {
        "currency": "USD",
        "tags": {
            "Internal Daily Settlement ID": "21DFASJSAKAS"
        }
    }'


import io.finix.payments.ApiClient;
import io.finix.payments.forms.SettlementForm;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.views.*;
import java.util.Currency;


Settlement settlement = identity.createSettlement(
  Settlement.builder()
    .currency("USD")
    .build()
);

SettlementForm formSettlement = SettlementForm.builder()
    .currency(Currency.getInstance("USD"))
    .build();

Transfer transfer = api.transfers.id("AUvGP4ivrCY3oaxFQrPtB9Ne").get().view();

Maybe<Settlement> response = api.identities.id("IDtYboiBEsqMo9WqqCeswAXL").settlements.post(formSettlement);

if (! response.succeeded()) {
    throw new RuntimeException("API error attempting to create batch settlement");
}

Settlement settlementBatch = response.view();


<?php
use Finix\Resources\Identity;
use Finix\Resources\Settlement;

$identity = Identity::retrieve('IDtYboiBEsqMo9WqqCeswAXL');
$settlement = new Settlement(
    array(
        "currency"=> "USD",
        "tags"=> array(
            "Internal Daily Settlement ID"=> "21DFASJSAKAS"
        )
    ));
$settlement = $identity->createSettlement($settlement);




from finix.resources import Identity
from finix.resources import Settlement

identity = Identity.get(id="IDtYboiBEsqMo9WqqCeswAXL")
settlement = Settlement(**
    {
        "currency": "USD",
        "tags": {
            "Internal Daily Settlement ID": "21DFASJSAKAS"
        }
    })
identity.create_settlement(settlement)

identity = Finix::Identity.retrieve(:id=>"IDtYboiBEsqMo9WqqCeswAXL")
settlement = identity.create_settlement(
    {
        "currency"=> "USD",
        "tags"=> {
            "Internal Daily Settlement ID"=> "21DFASJSAKAS"
        }
    })

Example Response:

{
  "id" : "STxeDWk3gyCi3vLHZeveRYwo",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "tags" : {
    "Internal Daily Settlement ID" : "21DFASJSAKAS"
  },
  "identity" : "IDtYboiBEsqMo9WqqCeswAXL",
  "currency" : "USD",
  "created_at" : "2019-03-13T23:41:46.73Z",
  "updated_at" : "2019-03-13T23:41:46.79Z",
  "processor" : "DUMMY_V1",
  "type" : "MERCHANT",
  "total_amount" : 1717782,
  "total_fees" : 171870,
  "total_fee" : 171870,
  "net_amount" : 1545912,
  "destination" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/settlements/STxeDWk3gyCi3vLHZeveRYwo"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    },
    "funding_transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/settlements/STxeDWk3gyCi3vLHZeveRYwo/funding_transfers"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/settlements/STxeDWk3gyCi3vLHZeveRYwo/transfers"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/settlements/STxeDWk3gyCi3vLHZeveRYwo/transfers?type=fee"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/settlements/STxeDWk3gyCi3vLHZeveRYwo/transfers?type=reverse"
    },
    "credits" : {
      "href" : "https://finix.sandbox-payments-api.com/settlements/STxeDWk3gyCi3vLHZeveRYwo/transfers?type=credit"
    },
    "debits" : {
      "href" : "https://finix.sandbox-payments-api.com/settlements/STxeDWk3gyCi3vLHZeveRYwo/transfers?type=debit"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/settlements/STxeDWk3gyCi3vLHZeveRYwo/transfers?type=dispute"
    }
  }
}

Awesome! Now you know how to charge a card. Next you need to settle out the funds to your merchant’s bank account (i.e. issue an ACH Credit). To do so you will create a Settlement resource. A Settlement is a logical construct representing a collection (i.e. batch) of Transfers that are intended to be paid out to a specific Merchant.

Each settlement is comprised of all the Transfers that have a SUCCEEDED state and that have not yet been previously settled out. In other words, if a merchant has a Transfer in the PENDING state it will not be included in the batch settlement. In addition, Settlements will include any refunded Transfers as a deduction. The total_amount minus the total_fee equals the net_amount (the amount in cents that will be deposited into your merchant’s bank account).

Note that for reconciliation purposes each Settlement contains a transfers link which returns a list of all the Transfers that comprise the batch.

HTTP Request

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

Request Arguments

Field Type Description
currency integer, required 3-letter currency code that the funds should be deposited (e.g. USD)
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)

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 USbY54Hx2XhU93GPpqT64Yhw:64f5b2a4-f6ca-49f3-bc74-6ac135e1392b \
    -d '
    {
        "tags": {
            "key": "value"
        },
        "entity": {
            "phone": "7145677612",
            "first_name": "Daphne",
            "last_name": "Le",
            "email": "Daphne@gmail.com",
            "personal_address": {
                "city": "San Mateo",
                "country": "USA",
                "region": "CA",
                "line2": "Apartment 7",
                "line1": "741 Douglass St",
                "postal_code": "94114"
            }
        }
    }'


import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.forms.Address;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.forms.Date;


IdentityForm form = IdentityForm.builder()
    .entity(
    IdentityEntityForm.builder()
        .firstName("dwayne")
        .lastName("Sunkhronos")
        .email("user@example.org")
        .personalAddress(
            Address.builder()
                .line1("741 Douglass St")
                .line2("Apartment 7")
                .city("San Mateo")
                .region("CA")
                .postalCode("94114")
                .country("USA")
                .build()
        )
        .build())
      .build();

Maybe<Identity> response = api.identities.post(form);

if (! response.succeeded()) {
    ApiError error = response.error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to create Identity");
}

Identity identity = response.view();


<?php
use Finix\Resources\Identity;

$identity = new Identity(IDjZ476ZjPfnAKcB3PLZjLcn);
$identity = $identity->save();






from finix.resources import Identity

identity = Identity(**
    {
        "tags": {
            "key": "value"
        },
        "entity": {
            "phone": "7145677612",
            "first_name": "Daphne",
            "last_name": "Le",
            "email": "Daphne@gmail.com",
            "personal_address": {
                "city": "San Mateo",
                "country": "USA",
                "region": "CA",
                "line2": "Apartment 7",
                "line1": "741 Douglass St",
                "postal_code": "94114"
            }
        }
    }).save()

identity = Finix::Identity.new(
    {
        "tags"=> {
            "key"=> "value"
        },
        "entity"=> {
            "phone"=> "7145677612",
            "first_name"=> "Daphne",
            "last_name"=> "Le",
            "email"=> "Daphne@gmail.com",
            "personal_address"=> {
                "city"=> "San Mateo",
                "country"=> "USA",
                "region"=> "CA",
                "line2"=> "Apartment 7",
                "line1"=> "741 Douglass St",
                "postal_code"=> "94114"
            }
        }
    }).save

Example Response:

{
  "id" : "IDjZ476ZjPfnAKcB3PLZjLcn",
  "application" : "APtTJn7ToSrAXGG5jfdncRAJ",
  "entity" : {
    "title" : null,
    "first_name" : "Daphne",
    "last_name" : "Le",
    "email" : "Daphne@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_id_provided" : false,
    "business_tax_id_provided" : false,
    "default_statement_descriptor" : null
  },
  "tags" : {
    "key" : "value"
  },
  "created_at" : "2019-03-13T22:08:45.12Z",
  "updated_at" : "2019-03-13T22:08:45.12Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjZ476ZjPfnAKcB3PLZjLcn"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjZ476ZjPfnAKcB3PLZjLcn/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjZ476ZjPfnAKcB3PLZjLcn/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjZ476ZjPfnAKcB3PLZjLcn/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjZ476ZjPfnAKcB3PLZjLcn/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjZ476ZjPfnAKcB3PLZjLcn/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjZ476ZjPfnAKcB3PLZjLcn/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjZ476ZjPfnAKcB3PLZjLcn/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjZ476ZjPfnAKcB3PLZjLcn/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APtTJn7ToSrAXGG5jfdncRAJ"
    }
  }
}

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, required First line of the address (max 60 characters)
line2 string, optional Second line of the address (max 60 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 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 USbY54Hx2XhU93GPpqT64Yhw:64f5b2a4-f6ca-49f3-bc74-6ac135e1392b \
    -d '
    {
        "name": "Ayisha Diaz",
        "expiration_year": 2020,
        "tags": {
            "card_name": "Business Card"
        },
        "number": "4895142232120006",
        "expiration_month": 3,
        "address": {
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "94404",
            "line1": "900 Metro Center Blv",
            "country": "USA"
        },
        "security_code": "022",
        "type": "PAYMENT_CARD",
        "identity": "IDjZ476ZjPfnAKcB3PLZjLcn"
    }'


import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.forms.Address;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import com.google.common.collect.ImmutableMap;

PaymentCardForm form = PaymentCardForm.builder()
        .name("Joe Doe")
        .number("4957030420210454")
        .securityCode("112")
        .expirationYear(2020)
        .identity("IDtYboiBEsqMo9WqqCeswAXL")
        .expirationMonth(12)
        .address(
                Address.builder()
                        .city("San Mateo")
                        .country("USA")
                        .region("CA")
                        .line1("123 Fake St")
                        .line2("#7")
                        .postalCode("90210")
                        .build()
        )
        .tags(ImmutableMap.of("card_name", "Business Card"))
        .build();

Maybe<PaymentCard> response = api.instruments.post(form);
if (! response.succeeded()) {
    ApiError error = response .error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to create Payment Card");
}
PaymentCard card = response.view();


<?php
use Finix\Resources\PaymentCard;
use Finix\Resources\Identity;

$card = new PaymentCard(
    array(
        "name"=> "Ayisha Diaz",
        "expiration_year"=> 2020,
        "tags"=> array(
            "card_name"=> "Business Card"
        ),
        "number"=> "4895142232120006",
        "expiration_month"=> 3,
        "address"=> array(
            "city"=> "San Francisco",
            "region"=> "CA",
            "postal_code"=> "94404",
            "line1"=> "900 Metro Center Blv",
            "country"=> "USA"
        ),
        "security_code"=> "022",
        "type"=> "PAYMENT_CARD",
        "identity"=> "IDjZ476ZjPfnAKcB3PLZjLcn"
    ));
$card = $identity->createPaymentCard($card);




from finix.resources import PaymentCard

card = PaymentCard(**
    {
        "name": "Laura Jones",
        "expiration_year": 2020,
        "tags": {
            "card_name": "Business Card"
        },
        "number": "4895142232120006",
        "expiration_month": 3,
        "address": {
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "94404",
            "line1": "900 Metro Center Blv",
            "country": "USA"
        },
        "security_code": "022",
        "type": "PAYMENT_CARD",
        "identity": "IDbUcrKrk2ksC2oiirfLF17t"
    }).save()


card = Finix::PaymentCard.new(
    {
        "name"=> "Ayisha Diaz",
        "expiration_year"=> 2020,
        "tags"=> {
            "card_name"=> "Business Card"
        },
        "number"=> "4895142232120006",
        "expiration_month"=> 3,
        "address"=> {
            "city"=> "San Francisco",
            "region"=> "CA",
            "postal_code"=> "94404",
            "line1"=> "900 Metro Center Blv",
            "country"=> "USA"
        },
        "security_code"=> "022",
        "type"=> "PAYMENT_CARD",
        "identity"=> "IDjZ476ZjPfnAKcB3PLZjLcn"
    }).save

Example Response:

{
  "id" : "PIuSBLWPtGVHooetRVqKxHQ7",
  "application" : "APtTJn7ToSrAXGG5jfdncRAJ",
  "fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 3,
  "expiration_year" : 2020,
  "bin" : "489514",
  "last_four" : "0006",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Ayisha Diaz",
  "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" : "2019-03-13T22:08:47.44Z",
  "updated_at" : "2019-03-13T22:08:47.44Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDjZ476ZjPfnAKcB3PLZjLcn",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIuSBLWPtGVHooetRVqKxHQ7"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIuSBLWPtGVHooetRVqKxHQ7/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIuSBLWPtGVHooetRVqKxHQ7/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIuSBLWPtGVHooetRVqKxHQ7/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APtTJn7ToSrAXGG5jfdncRAJ"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjZ476ZjPfnAKcB3PLZjLcn"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIuSBLWPtGVHooetRVqKxHQ7/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, required First line of the address (max 60 characters)
line2 string, optional Second line of the address (max 60 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 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/PIfCzV6dsNE5k1pWnmxQAvob/verifications \
    -H "Content-Type: application/vnd.json+api" \
    -u USbY54Hx2XhU93GPpqT64Yhw:64f5b2a4-f6ca-49f3-bc74-6ac135e1392b \
    -d '
    {
        "processor": "VISA_V1"
    }'


import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;


 VerificationForm verificationForm = VerificationForm.builder()
    .processor("VISA_V1")
    .build();

Maybe<Verification> verificationResponse = api.instruments.id("PIfCzV6dsNE5k1pWnmxQAvob").verifications.post(verificationForm);
if (! verificationResponse.succeeded()) {
    ApiError error = verificationResponse.error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to create a Verification");
}
Verification verification = verificationResponse.view();


<?php




from finix.resources import PaymentInstrument
from finix.resources import Verification


payment_card = PaymentInstrument.get(id="PIfCzV6dsNE5k1pWnmxQAvob")

verify = payment_card.verify_on(Verification(**
    {
        "processor": "VISA_V1"
    }))

Example Response:

{
  "id" : "VI7D5yztsPwS6ga9DEAZt1us",
  "application" : "APtTJn7ToSrAXGG5jfdncRAJ",
  "tags" : { },
  "messages" : [ ],
  "raw" : {
    "validation_details" : {
      "systems_trace_audit_number" : "907222194161",
      "transaction_identifier" : "139586622247853",
      "action_code" : "25",
      "response_code" : "5",
      "address_verification_results" : "I",
      "cvv2_result_code" : "P"
    },
    "inquiry_details" : {
      "systems_trace_audit_number" : "907222194161",
      "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" : "907222194161",
      "card_product_id" : "F",
      "card_product_name" : "Visa Classic",
      "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" : "2019-03-13T22:09:42.90Z",
  "updated_at" : "2019-03-13T22:09:44.48Z",
  "trace_id" : "907222194161",
  "payment_instrument" : "PIfCzV6dsNE5k1pWnmxQAvob",
  "merchant" : null,
  "identity" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VI7D5yztsPwS6ga9DEAZt1us"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APtTJn7ToSrAXGG5jfdncRAJ"
    },
    "payment_instrument" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIfCzV6dsNE5k1pWnmxQAvob"
    }
  }
}

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

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, D Fast Funds eligible
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/IDjZ476ZjPfnAKcB3PLZjLcn/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u USbY54Hx2XhU93GPpqT64Yhw:64f5b2a4-f6ca-49f3-bc74-6ac135e1392b \
    -d '
    {
        "processor": "VISA_V1"
    }'


import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import com.google.common.collect.ImmutableMap;

Maybe<Identity> response = api.identities.id("IDjZ476ZjPfnAKcB3PLZjLcn").get();
if (! response.succeeded()) {
    ApiError error = response.error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to fetch Identity");
}
Identity identity = response.view();

MerchantUnderwritingForm form = MerchantUnderwritingForm.builder()
    .tags(ImmutableMap.of("key", "value"))
    .build();

Maybe<Merchant> merchantResponse = api.identities.id(identity.id).merchants.post(form);

if (! merchantResponse.succeeded()) {
            ApiError error = merchantResponse.error();
            System.out.println(error.getCode());
            throw new RuntimeException("API error attempting to provision Merchant");
        }
Merchant merchant = merchantResponse.view();

<?php
use Finix\Resources\Identity;
use Finix\Resources\Merchant;

$identity = Identity::retrieve('IDjZ476ZjPfnAKcB3PLZjLcn');

$merchant = $identity->provisionMerchantOn(new Merchant());




from finix.resources import Identity
from finix.resources import Merchant

identity = Identity.get(id="PIuSBLWPtGVHooetRVqKxHQ7")
merchant = identity.provision_merchant_on(Merchant())


identity = Finix::Identity.retrieve(:id=>"IDjZ476ZjPfnAKcB3PLZjLcn")

merchant = identity.provision_merchant

Example Response:

{
  "id" : "MUgaGy3ckJZhgwZVrX98VZ9G",
  "application" : "APtTJn7ToSrAXGG5jfdncRAJ",
  "identity" : "IDjZ476ZjPfnAKcB3PLZjLcn",
  "verification" : "VI2bA6k2gJKYLT1EEvjHadiZ",
  "merchant_profile" : "MPkhFj8RapDArBgG4327jjGh",
  "processor" : "VISA_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "creating_transfer_from_report_enabled" : false,
  "tags" : { },
  "created_at" : "2019-03-13T22:08:49.48Z",
  "updated_at" : "2019-03-13T22:08:49.64Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUgaGy3ckJZhgwZVrX98VZ9G"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjZ476ZjPfnAKcB3PLZjLcn"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUgaGy3ckJZhgwZVrX98VZ9G/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPkhFj8RapDArBgG4327jjGh"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APtTJn7ToSrAXGG5jfdncRAJ"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VI2bA6k2gJKYLT1EEvjHadiZ"
    }
  }
}

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 USbY54Hx2XhU93GPpqT64Yhw:64f5b2a4-f6ca-49f3-bc74-6ac135e1392b \
    -d '
    {
        "currency": "USD",
        "amount": 1510,
        "destination": "PIuSBLWPtGVHooetRVqKxHQ7",
        "tags": {
            "order_number": "21DFASJSAKAS"
        }
    }'


import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import com.google.common.collect.ImmutableMap;
import java.util.Currency;

TransferForm form = TransferForm.builder()
        .amount(100L)
        .currency(Currency.getInstance("USD"))
        .idempotencyId("Idsfk23jnasdfkjf")
        .destination("PIuSBLWPtGVHooetRVqKxHQ7")
        .tags(ImmutableMap.of("order_number", "21DFASJSAKAS"))
        .build();

Maybe<Transfer> response = api.transfers.post(form);
if (! response.succeeded()) {
    ApiError error = response.error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to create Transfer");
}
Transfer transfer = response.view();


<?php
use Finix\Resources\Transfer;

$transfer = new Transfer(
    array(
        "currency"=> "USD",
        "amount"=> 1510,
        "destination"=> "PIuSBLWPtGVHooetRVqKxHQ7",
        "tags"=> array(
            "order_number"=> "21DFASJSAKAS"
        )
    ));
$transfer = $transfer->save();



from finix.resources import Transfer

payout = Transfer(**
    {
        "name": "Ayisha Diaz",
        "expiration_year": 2020,
        "tags": {
            "card_name": "Business Card"
        },
        "number": "4895142232120006",
        "expiration_month": 3,
        "address": {
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "94404",
            "line1": "900 Metro Center Blv",
            "country": "USA"
        },
        "security_code": "022",
        "type": "PAYMENT_CARD",
        "identity": "IDjZ476ZjPfnAKcB3PLZjLcn"
    }).save()


transfer = Finix::Transfer.new(
    {
        "currency"=> "USD",
        "amount"=> 1510,
        "destination"=> "PIuSBLWPtGVHooetRVqKxHQ7",
        "tags"=> {
            "order_number"=> "21DFASJSAKAS"
        }
    }).save

Example Response:

{
  "id" : "TRi4SUeUqUs6GaiUoXSopaKi",
  "amount" : 1510,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "trace_id" : "907222194158",
  "currency" : "USD",
  "application" : "APtTJn7ToSrAXGG5jfdncRAJ",
  "source" : null,
  "destination" : "PIuSBLWPtGVHooetRVqKxHQ7",
  "ready_to_settle_at" : null,
  "fee" : 0,
  "statement_descriptor" : "FIN*FINIXPAYMENTS",
  "type" : "CREDIT",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2019-03-13T22:08:51.29Z",
  "updated_at" : "2019-03-13T22:08:52.97Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDjZ476ZjPfnAKcB3PLZjLcn",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APtTJn7ToSrAXGG5jfdncRAJ"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRi4SUeUqUs6GaiUoXSopaKi"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRi4SUeUqUs6GaiUoXSopaKi/payment_instruments"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjZ476ZjPfnAKcB3PLZjLcn"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRi4SUeUqUs6GaiUoXSopaKi/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRi4SUeUqUs6GaiUoXSopaKi/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRi4SUeUqUs6GaiUoXSopaKi/disputes"
    },
    "destination" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIuSBLWPtGVHooetRVqKxHQ7"
    }
  }
}

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)

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 USbY54Hx2XhU93GPpqT64Yhw:64f5b2a4-f6ca-49f3-bc74-6ac135e1392b \
    -d '
    {
        "tags": {
            "key": "value"
        },
        "entity": {
            "phone": "7145677612",
            "first_name": "Collen",
            "last_name": "Wade",
            "email": "Collen@gmail.com",
            "personal_address": {
                "city": "San Mateo",
                "country": "USA",
                "region": "CA",
                "line2": "Apartment 7",
                "line1": "741 Douglass St",
                "postal_code": "94114"
            }
        }
    }'


import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.forms.Address;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.forms.Date;


IdentityForm form = IdentityForm.builder()
    .entity(
    IdentityEntityForm.builder()
        .firstName("dwayne")
        .lastName("Sunkhronos")
        .email("user@example.org")
        .personalAddress(
            Address.builder()
                .line1("741 Douglass St")
                .line2("Apartment 7")
                .city("San Mateo")
                .region("CA")
                .postalCode("94114")
                .country("USA")
                .build()
        )
        .build())
      .build();

Maybe<Identity> response = api.identities.post(form);

if (! response.succeeded()) {
    ApiError error = response.error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to create Identity");
}

Identity identity = response.view();


<?php
use Finix\Resources\Identity;

$identity = new Identity(ID5PRU1UkEBbxvMEmm9rKqaK);
$identity = $identity->save();




from finix.resources import Identity

identity = Identity(**
    {
        "tags": {
            "key": "value"
        },
        "entity": {
            "phone": "7145677612",
            "first_name": "Collen",
            "last_name": "Wade",
            "email": "Collen@gmail.com",
            "personal_address": {
                "city": "San Mateo",
                "country": "USA",
                "region": "CA",
                "line2": "Apartment 7",
                "line1": "741 Douglass St",
                "postal_code": "94114"
            }
        }
    }).save()


identity = Finix::Identity.new(
    {
        "tags"=> {
            "key"=> "value"
        },
        "entity"=> {
            "phone"=> "7145677612",
            "first_name"=> "Collen",
            "last_name"=> "Wade",
            "email"=> "Collen@gmail.com",
            "personal_address"=> {
                "city"=> "San Mateo",
                "country"=> "USA",
                "region"=> "CA",
                "line2"=> "Apartment 7",
                "line1"=> "741 Douglass St",
                "postal_code"=> "94114"
            }
        }
    }).save

Example Response:

{
  "id" : "ID5PRU1UkEBbxvMEmm9rKqaK",
  "application" : "APtTJn7ToSrAXGG5jfdncRAJ",
  "entity" : {
    "title" : null,
    "first_name" : "Collen",
    "last_name" : "Wade",
    "email" : "Collen@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_id_provided" : false,
    "business_tax_id_provided" : false,
    "default_statement_descriptor" : null
  },
  "tags" : {
    "key" : "value"
  },
  "created_at" : "2019-03-13T22:08:45.67Z",
  "updated_at" : "2019-03-13T22:08:45.67Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID5PRU1UkEBbxvMEmm9rKqaK"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID5PRU1UkEBbxvMEmm9rKqaK/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID5PRU1UkEBbxvMEmm9rKqaK/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID5PRU1UkEBbxvMEmm9rKqaK/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID5PRU1UkEBbxvMEmm9rKqaK/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID5PRU1UkEBbxvMEmm9rKqaK/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID5PRU1UkEBbxvMEmm9rKqaK/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID5PRU1UkEBbxvMEmm9rKqaK/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID5PRU1UkEBbxvMEmm9rKqaK/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APtTJn7ToSrAXGG5jfdncRAJ"
    }
  }
}

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, required First line of the address (max 60 characters)
line2 string, optional Second line of the address (max 60 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 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 USbY54Hx2XhU93GPpqT64Yhw:64f5b2a4-f6ca-49f3-bc74-6ac135e1392b \
    -d '
    {
        "name": "Michael Green",
        "expiration_year": 2020,
        "tags": {
            "card_name": "Business Card"
        },
        "number": "4895142232120006",
        "expiration_month": 3,
        "address": {
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "94404",
            "line1": "900 Metro Center Blv",
            "country": "USA"
        },
        "security_code": "022",
        "type": "PAYMENT_CARD",
        "identity": "ID5PRU1UkEBbxvMEmm9rKqaK"
    }'


import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.forms.Address;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import com.google.common.collect.ImmutableMap;

PaymentCardForm form = PaymentCardForm.builder()
        .name("Joe Doe")
        .number("4957030420210454")
        .securityCode("112")
        .expirationYear(2020)
        .identity("IDtYboiBEsqMo9WqqCeswAXL")
        .expirationMonth(12)
        .address(
                Address.builder()
                        .city("San Mateo")
                        .country("USA")
                        .region("CA")
                        .line1("123 Fake St")
                        .line2("#7")
                        .postalCode("90210")
                        .build()
        )
        .tags(ImmutableMap.of("card_name", "Business Card"))
        .build();

Maybe<PaymentCard> response = api.instruments.post(form);
if (! response.succeeded()) {
    ApiError error = response .error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to create Payment Card");
}
PaymentCard card = response.view();


<?php
use Finix\Resources\PaymentCard;
use Finix\Resources\Identity;

$card = new PaymentCard(
    array(
        "name"=> "Michael Green",
        "expiration_year"=> 2020,
        "tags"=> array(
            "card_name"=> "Business Card"
        ),
        "number"=> "4895142232120006",
        "expiration_month"=> 3,
        "address"=> array(
            "city"=> "San Francisco",
            "region"=> "CA",
            "postal_code"=> "94404",
            "line1"=> "900 Metro Center Blv",
            "country"=> "USA"
        ),
        "security_code"=> "022",
        "type"=> "PAYMENT_CARD",
        "identity"=> "ID5PRU1UkEBbxvMEmm9rKqaK"
    ));
$card = $identity->createPaymentCard($card);




from finix.resources import PaymentCard

card = PaymentCard(**
    {
        "name": "Michael Green",
        "expiration_year": 2020,
        "tags": {
            "card_name": "Business Card"
        },
        "number": "4895142232120006",
        "expiration_month": 3,
        "address": {
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "94404",
            "line1": "900 Metro Center Blv",
            "country": "USA"
        },
        "security_code": "022",
        "type": "PAYMENT_CARD",
        "identity": "ID5PRU1UkEBbxvMEmm9rKqaK"
    }).save()


card = Finix::PaymentCard.new(
    {
        "name"=> "Michael Green",
        "expiration_year"=> 2020,
        "tags"=> {
            "card_name"=> "Business Card"
        },
        "number"=> "4895142232120006",
        "expiration_month"=> 3,
        "address"=> {
            "city"=> "San Francisco",
            "region"=> "CA",
            "postal_code"=> "94404",
            "line1"=> "900 Metro Center Blv",
            "country"=> "USA"
        },
        "security_code"=> "022",
        "type"=> "PAYMENT_CARD",
        "identity"=> "ID5PRU1UkEBbxvMEmm9rKqaK"
    }).save

Example Response:

{
  "id" : "PIopFg1n5oi5shC73zhxZR8M",
  "application" : "APtTJn7ToSrAXGG5jfdncRAJ",
  "fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 3,
  "expiration_year" : 2020,
  "bin" : "489514",
  "last_four" : "0006",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Michael Green",
  "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" : "2019-03-13T22:08:48.17Z",
  "updated_at" : "2019-03-13T22:08:48.17Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "ID5PRU1UkEBbxvMEmm9rKqaK",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIopFg1n5oi5shC73zhxZR8M"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIopFg1n5oi5shC73zhxZR8M/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIopFg1n5oi5shC73zhxZR8M/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIopFg1n5oi5shC73zhxZR8M/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APtTJn7ToSrAXGG5jfdncRAJ"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID5PRU1UkEBbxvMEmm9rKqaK"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIopFg1n5oi5shC73zhxZR8M/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, required First line of the address (max 60 characters)
line2 string, optional Second line of the address (max 60 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 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/PIuSBLWPtGVHooetRVqKxHQ7/verifications \
    -H "Content-Type: application/vnd.json+api" \
    -u USbY54Hx2XhU93GPpqT64Yhw:64f5b2a4-f6ca-49f3-bc74-6ac135e1392b \
    -d '
    {
        "processor": "VISA_V1"
    }'


import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;


 VerificationForm verificationForm = VerificationForm.builder()
    .processor("VISA_V1")
    .build();

Maybe<Verification> verificationResponse = api.instruments.id("PIuSBLWPtGVHooetRVqKxHQ7").verifications.post(verificationForm);
if (! verificationResponse.succeeded()) {
    ApiError error = verificationResponse.error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to create a Verification");
}
Verification verification = verificationResponse.view();


<?php




from finix.resources import PaymentInstrument
from finix.resources import Verification


payment_card = PaymentInstrument.get(id="PIgM3PiQZsPUyhds2hZRgUGe")

verify = payment_card.verify_on(Verification(**
    {
        "processor": "VISA_V1"
    }))

Example Response:

{
  "id" : "VI7D5yztsPwS6ga9DEAZt1us",
  "application" : "APtTJn7ToSrAXGG5jfdncRAJ",
  "tags" : { },
  "messages" : [ ],
  "raw" : {
    "validation_details" : {
      "systems_trace_audit_number" : "907222194161",
      "transaction_identifier" : "139586622247853",
      "action_code" : "25",
      "response_code" : "5",
      "address_verification_results" : "I",
      "cvv2_result_code" : "P"
    },
    "inquiry_details" : {
      "systems_trace_audit_number" : "907222194161",
      "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" : "907222194161",
      "card_product_id" : "F",
      "card_product_name" : "Visa Classic",
      "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" : "2019-03-13T22:09:42.90Z",
  "updated_at" : "2019-03-13T22:09:44.48Z",
  "trace_id" : "907222194161",
  "payment_instrument" : "PIfCzV6dsNE5k1pWnmxQAvob",
  "merchant" : null,
  "identity" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VI7D5yztsPwS6ga9DEAZt1us"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APtTJn7ToSrAXGG5jfdncRAJ"
    },
    "payment_instrument" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIfCzV6dsNE5k1pWnmxQAvob"
    }
  }
}

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

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, D Fast Funds eligible
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/IDjZ476ZjPfnAKcB3PLZjLcn/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u USbY54Hx2XhU93GPpqT64Yhw:64f5b2a4-f6ca-49f3-bc74-6ac135e1392b \
    -d '
    {
        "processor": "VISA_V1"
    }'


import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import com.google.common.collect.ImmutableMap;

Maybe<Identity> response = api.identities.id("ID5PRU1UkEBbxvMEmm9rKqaK").get();
if (! response.succeeded()) {
    ApiError error = response.error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to fetch Identity");
}
Identity identity = response.view();

MerchantUnderwritingForm form = MerchantUnderwritingForm.builder()
    .tags(ImmutableMap.of("key", "value"))
    .build();

Maybe<Merchant> merchantResponse = api.identities.id(identity.id).merchants.post(form);

if (! merchantResponse.succeeded()) {
            ApiError error = merchantResponse.error();
            System.out.println(error.getCode());
            throw new RuntimeException("API error attempting to provision Merchant");
        }
Merchant merchant = merchantResponse.view();


<?php
use Finix\Resources\Identity;
use Finix\Resources\Merchant;

$identity = Identity::retrieve('ID5PRU1UkEBbxvMEmm9rKqaK');

$merchant = $identity->provisionMerchantOn(new Merchant());




from finix.resources import Identity
from finix.resources import Merchant

identity = Identity.get(id="PIopFg1n5oi5shC73zhxZR8M")
merchant = identity.provision_merchant_on(Merchant())


identity = Finix::Identity.retrieve(:id=>"ID5PRU1UkEBbxvMEmm9rKqaK")

merchant = identity.provision_merchant

Example Response:

{
  "id" : "MUgaGy3ckJZhgwZVrX98VZ9G",
  "application" : "APtTJn7ToSrAXGG5jfdncRAJ",
  "identity" : "IDjZ476ZjPfnAKcB3PLZjLcn",
  "verification" : "VI2bA6k2gJKYLT1EEvjHadiZ",
  "merchant_profile" : "MPkhFj8RapDArBgG4327jjGh",
  "processor" : "VISA_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "creating_transfer_from_report_enabled" : false,
  "tags" : { },
  "created_at" : "2019-03-13T22:08:49.48Z",
  "updated_at" : "2019-03-13T22:08:49.64Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUgaGy3ckJZhgwZVrX98VZ9G"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDjZ476ZjPfnAKcB3PLZjLcn"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUgaGy3ckJZhgwZVrX98VZ9G/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPkhFj8RapDArBgG4327jjGh"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APtTJn7ToSrAXGG5jfdncRAJ"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VI2bA6k2gJKYLT1EEvjHadiZ"
    }
  }
}

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 USbY54Hx2XhU93GPpqT64Yhw:64f5b2a4-f6ca-49f3-bc74-6ac135e1392b \
    -d '
    {
        "currency": "USD",
        "amount": 20000,
        "source": "PIopFg1n5oi5shC73zhxZR8M",
        "operation_key": "PULL_FROM_CARD",
        "tags": {
            "order_number": "21DFASJSAKAS"
        }
    }'


import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import com.google.common.collect.ImmutableMap;
import java.util.Currency;

TransferForm form = TransferForm.builder()
        .amount(100L)
        .currency(Currency.getInstance("USD"))
        .idempotencyId("Idsfk23jnasdfkjf")
        .destination("PIuSBLWPtGVHooetRVqKxHQ7")
        .tags(ImmutableMap.of("order_number", "21DFASJSAKAS"))
        .build();

Maybe<Transfer> response = api.transfers.post(form);
if (! response.succeeded()) {
    ApiError error = response.error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to create Transfer");
}
Transfer transfer = response.view();


<?php
use Finix\Resources\Transfer;

$transfer = new Transfer(
    array(
        "currency"=> "USD",
        "amount"=> 20000,
        "source"=> "PIopFg1n5oi5shC73zhxZR8M",
        "operation_key"=> "PULL_FROM_CARD",
        "tags"=> array(
            "order_number"=> "21DFASJSAKAS"
        )
    ));
$transfer = $transfer->save();




from finix.resources import Transfer

payout = Transfer(**
    {
        "currency": "USD",
        "amount": 20000,
        "source": "PIopFg1n5oi5shC73zhxZR8M",
        "operation_key": "PULL_FROM_CARD",
        "tags": {
            "order_number": "21DFASJSAKAS"
        }
    }).save()


transfer = Finix::Transfer.new(
    {
        "currency"=> "USD",
        "amount"=> 20000,
        "source"=> "PIopFg1n5oi5shC73zhxZR8M",
        "operation_key"=> "PULL_FROM_CARD",
        "tags"=> {
            "order_number"=> "21DFASJSAKAS"
        }
    }).save

Example Response:

{
  "id" : "TRkiQeawzdNq78LitRrcYDgS",
  "amount" : 20000,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "trace_id" : "907222194159",
  "currency" : "USD",
  "application" : "APtTJn7ToSrAXGG5jfdncRAJ",
  "source" : "PIopFg1n5oi5shC73zhxZR8M",
  "destination" : null,
  "ready_to_settle_at" : null,
  "fee" : 0,
  "statement_descriptor" : "FIN*FINIXPAYMENTS",
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2019-03-13T22:08:53.70Z",
  "updated_at" : "2019-03-13T22:08:54.33Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDuSXm5YKLNHAUBiFu1wJRwA",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APtTJn7ToSrAXGG5jfdncRAJ"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRkiQeawzdNq78LitRrcYDgS"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRkiQeawzdNq78LitRrcYDgS/payment_instruments"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDuSXm5YKLNHAUBiFu1wJRwA"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRkiQeawzdNq78LitRrcYDgS/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRkiQeawzdNq78LitRrcYDgS/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRkiQeawzdNq78LitRrcYDgS/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIopFg1n5oi5shC73zhxZR8M"
    }
  }
}

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)

Reverse a Pull-from-Card Transfer


curl https://finix.sandbox-payments-api.com/transfers/TRkiQeawzdNq78LitRrcYDgS/reversals \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d  '
                  {
                  "refund_amount" : 100
                  }
                '



import io.finix.payments.processing.client.model.Refund;

Refund refund = transfer.reverse(100L);


<?php
use Finix\Resources\Transfer;

$debit = Transfer::retrieve('TR53uWoFSm4EU9LASQEFFh6d');
$refund = $debit->reverse(11);




from finix.resources import Transfer

transfer = Transfer.get(id="TRkiQeawzdNq78LitRrcYDgS")
transfer.reverse(**
                  {
                  "refund_amount" : 100
                  }
                )


transfer = Finix::Transfer.retrieve(:id=> "TRkiQeawzdNq78LitRrcYDgS")

refund = transfer.reverse(100)

Example Response:

{
  "id" : "TRjTfXPeMPTKyMEXNnsS1u17",
  "amount" : 100,
  "tags" : { },
  "state" : "SUCCEEDED",
  "trace_id" : "907222194160",
  "currency" : "USD",
  "application" : "APtTJn7ToSrAXGG5jfdncRAJ",
  "source" : null,
  "destination" : "PIopFg1n5oi5shC73zhxZR8M",
  "ready_to_settle_at" : null,
  "fee" : 0,
  "statement_descriptor" : "FIN*FINIXPAYMENTS",
  "type" : "REVERSAL",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2019-03-13T22:09:30.50Z",
  "updated_at" : "2019-03-13T22:09:31.20Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDuSXm5YKLNHAUBiFu1wJRwA",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APtTJn7ToSrAXGG5jfdncRAJ"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRjTfXPeMPTKyMEXNnsS1u17"
    },
    "parent" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRkiQeawzdNq78LitRrcYDgS"
    },
    "destination" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIopFg1n5oi5shC73zhxZR8M"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDuSXm5YKLNHAUBiFu1wJRwA"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRjTfXPeMPTKyMEXNnsS1u17/payment_instruments"
    }
  }
}

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 two subtypes indicating how they were 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)

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, & 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
placholder string, required What the user will see in the input field 
function defineField(elementId, type, placeholder) {
  // call field method with desired css styling
  const f = form.field(type, {
    placeholder,
    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', APmqHR9e843RMFye7WmAj5pB, 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  USbY54Hx2XhU93GPpqT64Yhw:64f5b2a4-f6ca-49f3-bc74-6ac135e1392b \
    -d '
    {
        "token": "TK4TT5vFtN4BM87ac3MX3dXH",
        "type": "TOKEN",
        "identity": "IDtYboiBEsqMo9WqqCeswAXL"
    }'


import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;

TokenAssociationForm tokenForm =  TokenAssociationForm.builder()
    .token("TK4TT5vFtN4BM87ac3MX3dXH")
    .identity("IDtYboiBEsqMo9WqqCeswAXL")
    .build();

Maybe<PaymentCard> cardResponse = api.instruments.post(tokenForm);
if (! cardResponse.succeeded()) {
    ApiError error = cardResponse.error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to create Payment Card");
}
PaymentCard paymentCard = cardResponse.view();


<?php
use Finix\Resources\PaymentInstrument;

$card = new PaymentInstrument(
    array(
        "token"=> "TK4TT5vFtN4BM87ac3MX3dXH",
        "type"=> "TOKEN",
        "identity"=> "IDtYboiBEsqMo9WqqCeswAXL"
    ));
$card = $card->save();




from finix.resources import PaymentInstrument

payment_instrument = PaymentInstrument(**
    {
        "token": "TK4TT5vFtN4BM87ac3MX3dXH",
        "type": "TOKEN",
        "identity": "IDtYboiBEsqMo9WqqCeswAXL"
    }).save()


card = Finix::PaymentInstrument.new(
    {
        "token"=> "TK4TT5vFtN4BM87ac3MX3dXH",
        "type"=> "TOKEN",
        "identity"=> "IDtYboiBEsqMo9WqqCeswAXL"
    }).save

Example Response:

{
  "id" : "PI4TT5vFtN4BM87ac3MX3dXH",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "fingerprint" : "FPRw9NoorETQgCjFgwKPvcGsV",
  "tags" : { },
  "expiration_month" : 12,
  "expiration_year" : 2020,
  "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" : "2019-03-13T22:09:35.79Z",
  "updated_at" : "2019-03-13T22:09:35.79Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDtYboiBEsqMo9WqqCeswAXL",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI4TT5vFtN4BM87ac3MX3dXH"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI4TT5vFtN4BM87ac3MX3dXH/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI4TT5vFtN4BM87ac3MX3dXH/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI4TT5vFtN4BM87ac3MX3dXH/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI4TT5vFtN4BM87ac3MX3dXH/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

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, APmqHR9e843RMFye7WmAj5pB);;
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);






<?php

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: APmqHR9e843RMFye7WmAj5pB)
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) 




<?php

Authorizations

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

Create an Authorization

curl https://finix.sandbox-payments-api.com/authorizations \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '
    {
        "merchant_identity": "IDtYboiBEsqMo9WqqCeswAXL",
        "currency": "USD",
        "amount": 100,
        "source": "PIgM3PiQZsPUyhds2hZRgUGe",
        "tags": {
            "order_number": "21DFASJSAKAS"
        }
    }'


import io.finix.payments.ApiClient;
import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;

AuthorizationCreateForm formCreateAuthorization = AuthorizationCreateForm.builder()
                .amount(10000L)
                .merchantIdentity("IDtYboiBEsqMo9WqqCeswAXL")
                .source("PIgM3PiQZsPUyhds2hZRgUGe")
                .build();

Maybe<Authorization> response = api.authorizations.post(formCreateAuthorization);

if (! response.succeeded()) {
  ApiError error = response.error();
  System.out.println(error.getMessage());
  throw new RuntimeException("API error attempting to creating Authorization");
}

Authorization authorization = response.view();


<?php
use Finix\Resources\Authorization;

$authorization = new Authorization(
    array(
        "merchant_identity"=> "IDtYboiBEsqMo9WqqCeswAXL",
        "currency"=> "USD",
        "amount"=> 100,
        "source"=> "PIgM3PiQZsPUyhds2hZRgUGe",
        "tags"=> array(
            "order_number"=> "21DFASJSAKAS"
        )
    ));
$authorization = $authorization->save();





from finix.resources import Authorization

authorization = Authorization(**
    {
        "merchant_identity": "IDtYboiBEsqMo9WqqCeswAXL",
        "currency": "USD",
        "amount": 100,
        "source": "PIgM3PiQZsPUyhds2hZRgUGe",
        "tags": {
            "order_number": "21DFASJSAKAS"
        }
    }).save()

authorization = Finix::Authorization.new(
    {
        "merchant_identity"=> "IDtYboiBEsqMo9WqqCeswAXL",
        "currency"=> "USD",
        "amount"=> 100,
        "source"=> "PIgM3PiQZsPUyhds2hZRgUGe",
        "tags"=> {
            "order_number"=> "21DFASJSAKAS"
        }
    }).save

Example Response:

{
  "id" : "AUvGP4ivrCY3oaxFQrPtB9Ne",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2019-03-13T22:09:31.96Z",
  "updated_at" : "2019-03-13T22:09:32.01Z",
  "trace_id" : "630b209a-14e9-4edd-84c6-b03ebfa3beb3",
  "source" : "PIgM3PiQZsPUyhds2hZRgUGe",
  "merchant_identity" : "IDtYboiBEsqMo9WqqCeswAXL",
  "is_void" : false,
  "expires_at" : "2019-03-20T22:09:31.96Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUvGP4ivrCY3oaxFQrPtB9Ne"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    }
  }
}

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

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

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

Capture an Authorization

curl https://finix.sandbox-payments-api.com/authorizations/AUvGP4ivrCY3oaxFQrPtB9Ne \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -X PUT \
    -d '
    {
        "fee": "10",
        "capture_amount": 100
    }'


import io.finix.payments.ApiClient;
import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;

AuthorizationUpdateForm form = AuthorizationUpdateForm.builder()
        .captureAmount(100L)
        .fee(10L)
        .statementDescriptor("Order 123")
        .build();

Maybe<Authorization> responseAuthorization = api.authorizations.id("AUvGP4ivrCY3oaxFQrPtB9Ne").put(form);

if (! responseAuthorization.succeeded()) {
    ApiError error = responseAuthorization.error();
    System.out.println(error.getMessage());
    throw new RuntimeException("API error attempting to capture authorization");
}
Authorization capturedAuth = responseAuthorization.view();


<?php
use Finix\Resources\Authorization;

$authorization = Authorization::retrieve('AUvGP4ivrCY3oaxFQrPtB9Ne');
$authorization = $authorization->capture([
                    "capture_amount"=> 50,
                    "fee"=> 10
                ]);




from finix.resources import Authorization

authorization = Authorization.get(id="AUvGP4ivrCY3oaxFQrPtB9Ne")
authorization.capture(**
    {
        "fee": "10",
        "capture_amount": 100
    })


authorization = Finix::Authorization.retrieve(:id=>"AUvGP4ivrCY3oaxFQrPtB9Ne")
authorization = authorization.capture(
    {
        "fee"=> "10",
        "capture_amount"=> 100
    })

Example Response:

{
  "id" : "AUvGP4ivrCY3oaxFQrPtB9Ne",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : "TR3spQQCm7ZpyWnV7mP47fxV",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2019-03-13T22:09:31.96Z",
  "updated_at" : "2019-03-13T22:09:33.44Z",
  "trace_id" : "630b209a-14e9-4edd-84c6-b03ebfa3beb3",
  "source" : "PIgM3PiQZsPUyhds2hZRgUGe",
  "merchant_identity" : "IDtYboiBEsqMo9WqqCeswAXL",
  "is_void" : false,
  "expires_at" : "2019-03-20T22:09:31.96Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUvGP4ivrCY3oaxFQrPtB9Ne"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "transfer" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR3spQQCm7ZpyWnV7mP47fxV"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    }
  }
}

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

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

Void an Authorization


curl https://finix.sandbox-payments-api.com/authorizations/AUgYp46xTSGLjZv68nSteMkq \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -X PUT \
    -d '
    {
        "void_me": true
    }'


import io.finix.payments.ApiClient;
import io.finix.payments.forms.AuthorizationUpdateForm;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.views.*;

AuthorizationUpdateForm formVoid = AuthorizationUpdateForm.builder()
        .voidMe(true)
        .build();

Maybe<Authorization> response = api.authorizations.id("AUvGP4ivrCY3oaxFQrPtB9Ne").put(formVoid);

if (! response.succeeded()) {
    System.out.println(response.error());
    throw new RuntimeException("API error attempting to void authorization");
}
Authorization voidAuthorization = response.view();


<?php
use Finix\Resources\Authorization;

$authorization = Authorization::retrieve('AUvGP4ivrCY3oaxFQrPtB9Ne');
$authorization->void(true);
$authorization = $authorization->save();





from finix.resources import Authorization

authorization = Authorization.get(id="AUvGP4ivrCY3oaxFQrPtB9Ne")
authorization.void()


authorization = Finix::Authorization.retrieve(:id=>"AUvGP4ivrCY3oaxFQrPtB9Ne")
authorization = authorization.void

Example Response:

{
  "id" : "AUgYp46xTSGLjZv68nSteMkq",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2019-03-13T22:09:36.60Z",
  "updated_at" : "2019-03-13T22:09:37.28Z",
  "trace_id" : "d3a96d33-54bf-4e99-85a5-a9ee356386cc",
  "source" : "PIgM3PiQZsPUyhds2hZRgUGe",
  "merchant_identity" : "IDtYboiBEsqMo9WqqCeswAXL",
  "is_void" : true,
  "expires_at" : "2019-03-20T22:09:36.60Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUgYp46xTSGLjZv68nSteMkq"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    }
  }
}

Cancels the Authorization thereby releasing the funds. After voiding an Authorization 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

Fetch an Authorization


curl https://finix.sandbox-payments-api.com/authorizations/AUvGP4ivrCY3oaxFQrPtB9Ne \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed


import io.finix.ApiClient;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.views.Authorization;

Maybe <Authorization> response =  api.authorizations
    .id("AUvGP4ivrCY3oaxFQrPtB9Ne")
    .get();

if(! response.succeeded()){
    System.out.println(response.error());
    throw new RuntimeException("API error in attempting to fetch Authorization");
}

Authorization authorization = response.view();


<?php
use Finix\Resources\Authorization;

$authorization = Authorization::retrieve('AUvGP4ivrCY3oaxFQrPtB9Ne');




from finix.resources import Authorization

authorization = Authorization.get(id="AUvGP4ivrCY3oaxFQrPtB9Ne")

authorization = Finix::Authorization.retrieve(:id=>"AUvGP4ivrCY3oaxFQrPtB9Ne")

Example Response:

{
  "id" : "AUvGP4ivrCY3oaxFQrPtB9Ne",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : "TR3spQQCm7ZpyWnV7mP47fxV",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2019-03-13T22:09:31.96Z",
  "updated_at" : "2019-03-13T22:09:33.44Z",
  "trace_id" : "630b209a-14e9-4edd-84c6-b03ebfa3beb3",
  "source" : "PIgM3PiQZsPUyhds2hZRgUGe",
  "merchant_identity" : "IDtYboiBEsqMo9WqqCeswAXL",
  "is_void" : false,
  "expires_at" : "2019-03-20T22:09:31.96Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUvGP4ivrCY3oaxFQrPtB9Ne"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "transfer" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR3spQQCm7ZpyWnV7mP47fxV"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    }
  }
}

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  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed


import io.finix.payments.ApiClient;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.lib.Page;
import io.finix.payments.views.*;

Maybe<Page<Authorization>> response = api.authorizations.get();

if (! response.succeeded()) {
   ApiError error = response.error();
   System.out.println(error.getCode());
   System.out.println(error.getMessage());
   System.out.println(error.getDetails());
   throw new RuntimeException("API error attempting to list all Authorizations");
}

 Page<Authorization> page = response.view();
 Page<Authorization> page2 = page.getNext();


<?php
use Finix\Resources\Authorization;

$authorizations = Authorization::getPagination("/authorizations");





from finix.resources import Authorization

authorization = Authorization.get()

authorizations = Finix::Authorization.retrieve

Example Response:

{
  "_embedded" : {
    "authorizations" : [ {
      "id" : "AUgYp46xTSGLjZv68nSteMkq",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "amount" : 100,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : null,
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2019-03-13T22:09:36.60Z",
      "updated_at" : "2019-03-13T22:09:37.28Z",
      "trace_id" : "d3a96d33-54bf-4e99-85a5-a9ee356386cc",
      "source" : "PIgM3PiQZsPUyhds2hZRgUGe",
      "merchant_identity" : "IDtYboiBEsqMo9WqqCeswAXL",
      "is_void" : true,
      "expires_at" : "2019-03-20T22:09:36.60Z",
      "idempotency_id" : null,
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations/AUgYp46xTSGLjZv68nSteMkq"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
        }
      }
    }, {
      "id" : "AUkrGY2cFfZuQsgK75QFaYLx",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "amount" : 100,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : null,
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2019-03-13T22:09:32.78Z",
      "updated_at" : "2019-03-13T22:09:32.82Z",
      "trace_id" : "5dd23652-c491-4611-9f4f-bff00ed31de0",
      "source" : "PIgM3PiQZsPUyhds2hZRgUGe",
      "merchant_identity" : "IDtYboiBEsqMo9WqqCeswAXL",
      "is_void" : false,
      "expires_at" : "2019-03-20T22:09:32.78Z",
      "idempotency_id" : "08cea0c7ee864295a9ad89f1b3f46767",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations/AUkrGY2cFfZuQsgK75QFaYLx"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
        }
      }
    }, {
      "id" : "AUvGP4ivrCY3oaxFQrPtB9Ne",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "amount" : 100,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : "TR3spQQCm7ZpyWnV7mP47fxV",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2019-03-13T22:09:31.96Z",
      "updated_at" : "2019-03-13T22:09:33.44Z",
      "trace_id" : "630b209a-14e9-4edd-84c6-b03ebfa3beb3",
      "source" : "PIgM3PiQZsPUyhds2hZRgUGe",
      "merchant_identity" : "IDtYboiBEsqMo9WqqCeswAXL",
      "is_void" : false,
      "expires_at" : "2019-03-20T22:09:31.96Z",
      "idempotency_id" : null,
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations/AUvGP4ivrCY3oaxFQrPtB9Ne"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        },
        "transfer" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR3spQQCm7ZpyWnV7mP47fxV"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
        }
      }
    } ]
  },
  "_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" : 3
  }
}

HTTP Request

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

Identities

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

Create an Identity for a Buyer



curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '
    {
        "tags": {
            "key": "value"
        },
        "entity": {
            "phone": "7145677613",
            "first_name": "Michael",
            "last_name": "Lopez",
            "email": "therock@gmail.com",
            "personal_address": {
                "city": "San Mateo",
                "country": "USA",
                "region": "CA",
                "line2": "Apartment 7",
                "line1": "741 Douglass St",
                "postal_code": "94114"
            }
        }
    }'


import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.forms.Address;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.forms.Date;


IdentityForm form = IdentityForm.builder()
    .entity(
    IdentityEntityForm.builder()
        .firstName("dwayne")
        .lastName("Sunkhronos")
        .email("user@example.org")
        .personalAddress(
            Address.builder()
                .line1("741 Douglass St")
                .line2("Apartment 7")
                .city("San Mateo")
                .region("CA")
                .postalCode("94114")
                .country("USA")
                .build()
        )
        .build())
    .build();

Maybe<Identity> response = api.identities.post(form);

if (! response.succeeded()) {
    ApiError error = response.error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to create Identity");
}

Identity identity = response.view();

<?php
use Finix\Resources\Identity;

$identity = new Identity(
    array(
        "tags"=> array(
            "key"=> "value"
        ),
        "entity"=> array(
            "phone"=> "7145677613",
            "first_name"=> "Michael",
            "last_name"=> "Lopez",
            "email"=> "therock@gmail.com",
            "personal_address"=> array(
                "city"=> "San Mateo",
                "country"=> "USA",
                "region"=> "CA",
                "line2"=> "Apartment 7",
                "line1"=> "741 Douglass St",
                "postal_code"=> "94114"
            )
        )
    ));
$identity = $identity->save();




from finix.resources import Identity

identity = Identity(**
    {
        "tags": {
            "key": "value"
        },
        "entity": {
            "phone": "7145677613",
            "first_name": "Michael",
            "last_name": "Lopez",
            "email": "therock@gmail.com",
            "personal_address": {
                "city": "San Mateo",
                "country": "USA",
                "region": "CA",
                "line2": "Apartment 7",
                "line1": "741 Douglass St",
                "postal_code": "94114"
            }
        }
    }).save()

identity = Finix::Identity.new(
    {
        "tags"=> {
            "key"=> "value"
        },
        "entity"=> {
            "phone"=> "7145677613",
            "first_name"=> "Michael",
            "last_name"=> "Lopez",
            "email"=> "therock@gmail.com",
            "personal_address"=> {
                "city"=> "San Mateo",
                "country"=> "USA",
                "region"=> "CA",
                "line2"=> "Apartment 7",
                "line1"=> "741 Douglass St",
                "postal_code"=> "94114"
            }
        }
    }).save

Example Response:

{
  "id" : "IDbUcrKrk2ksC2oiirfLF17t",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "entity" : {
    "title" : null,
    "first_name" : "Michael",
    "last_name" : "Lopez",
    "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_id_provided" : false,
    "business_tax_id_provided" : false,
    "default_statement_descriptor" : null
  },
  "tags" : {
    "key" : "value"
  },
  "created_at" : "2019-03-13T22:09:04.95Z",
  "updated_at" : "2019-03-13T22:09:04.95Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    }
  }
}

All fields for a buyer’s Identity are optional. However, a business_type field should not be passed. Passing a business_type 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
first_name string, optional First name
last_name string, optional Last name
phone string, optional Phone number
email string, optional Email address
line1 string, optional First line of the address (max 60 characters)
line2 string, optional Second line of the address (max 60 characters)
city string, optional City (max 20 characters)
region string, optional 2-letter State code
postal_code string, optional Zip or Postal code (max 7 characters)
country string, optional 3-Letter Country code
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  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '
    {
        "tags": {
            "Studio Rating": "4.7"
        },
        "entity": {
            "last_name": "Sunkhronos",
            "max_transaction_amount": 12000000,
            "has_accepted_credit_cards_previously": true,
            "default_statement_descriptor": "Pawny City Hall",
            "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": "Pawny City Hall",
            "principal_percentage_ownership": 50,
            "email": "user@example.org",
            "mcc": "0742",
            "phone": "1234567890",
            "business_name": "Pawny City Hall",
            "tax_id": "123456789",
            "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone": "+1 (408) 756-4497",
            "dob": {
                "year": 1978,
                "day": 27,
                "month": 6
            },
            "url": "www.PawnyCityHall.com",
            "annual_card_volume": 12000000
        }
    }'


import io.finix.payments.ApiClient;
import io.finix.payments.enums.BusinessType;
import io.finix.payments.forms.Address;
import io.finix.payments.forms.Date;
import io.finix.payments.forms.IdentityEntityForm;
import io.finix.payments.forms.IdentityForm;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.views.Identity;


IdentityForm form = IdentityForm.builder()
  .entity(IdentityEntityForm.builder()
  .firstName("dwayne")
  .lastName("Sunkhronos")
  .email("user@example.org")
  .businessName("business inc")
  .businessType(BusinessType.LIMITED_LIABILITY_COMPANY)
  .doingBusinessAs("doingBusinessAs")
  .phone("1234567890")
  .businessPhone("+1 (408) 756-4497")
  .taxId("123456789")
  .businessTaxId("123456789")
  .personalAddress(Address.builder()
  .line1("741 Douglass St")
  .line2("Apartment 7")
  .city("San Mateo")
  .region("CA")
  .postalCode("94114")
  .country("USA")
  .build())
  .businessAddress(Address.builder()
  .line1("741 Douglass St")
  .line2("Apartment 7")
  .city("San Mateo")
  .region("CA")
  .postalCode("94114")
  .country("USA")
  .build())
  .dob(Date.builder().day(Integer.valueOf(27)).month(Integer.valueOf(5)).year(Integer.valueOf(1978)).build())
  .maxTransactionAmount(Long.valueOf(1000L))
  .mcc("7399").url("http://sample-entity.com")
  .annualCardVolume(Long.valueOf(100L))
  .defaultStatementDescriptor("Business Inc")
  .incorporationDate(Date.builder().day(Integer.valueOf(1)).month(Integer.valueOf(12)).year(Integer.valueOf(2012)).build())
  .principalPercentageOwnership(Integer.valueOf(51)).build()).build();

Maybe<Identity> response = api.identities.post(form);
if(! response.succeeded().booleanValue()) {
    ApiError error = response.error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to create Identity");
}
    Identity identity = (Identity)response.view();



<?php
use Finix\Resources\Identity;

$identity = new Identity(
    array(
        "tags"=> array(
            "Studio Rating"=> "4.7"
        ),
        "entity"=> array(
            "last_name"=> "Sunkhronos",
            "max_transaction_amount"=> 12000000,
            "has_accepted_credit_cards_previously"=> true,
            "default_statement_descriptor"=> "Pawny City Hall",
            "personal_address"=> array(
                "city"=> "San Mateo",
                "country"=> "USA",
                "region"=> "CA",
                "line2"=> "Apartment 7",
                "line1"=> "741 Douglass St",
                "postal_code"=> "94114"
            ),
            "incorporation_date"=> array(
                "year"=> 1978,
                "day"=> 27,
                "month"=> 6
            ),
            "business_address"=> array(
                "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"=> "Pawny City Hall",
            "principal_percentage_ownership"=> 50,
            "email"=> "user@example.org",
            "mcc"=> "0742",
            "phone"=> "1234567890",
            "business_name"=> "Pawny City Hall",
            "tax_id"=> "123456789",
            "business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone"=> "+1 (408) 756-4497",
            "dob"=> array(
                "year"=> 1978,
                "day"=> 27,
                "month"=> 6
            ),
            "url"=> "www.PawnyCityHall.com",
            "annual_card_volume"=> 12000000
        )
    )
);
$identity = $identity->save();




from finix.resources import Identity

identity = Identity(**
    {
        "tags": {
            "Studio Rating": "4.7"
        },
        "entity": {
            "last_name": "Sunkhronos",
            "max_transaction_amount": 12000000,
            "has_accepted_credit_cards_previously": True,
            "default_statement_descriptor": "Pawny City Hall",
            "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": "Pawny City Hall",
            "principal_percentage_ownership": 50,
            "email": "user@example.org",
            "mcc": "0742",
            "phone": "1234567890",
            "business_name": "Pawny City Hall",
            "tax_id": "123456789",
            "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone": "+1 (408) 756-4497",
            "dob": {
                "year": 1978,
                "day": 27,
                "month": 6
            },
            "url": "www.PawnyCityHall.com",
            "annual_card_volume": 12000000
        }
    }).save()

identity = Finix::Identity.new(
    {
        "tags"=> {
            "Studio Rating"=> "4.7"
        },
        "entity"=> {
            "last_name"=> "Sunkhronos",
            "max_transaction_amount"=> 12000000,
            "has_accepted_credit_cards_previously"=> true,
            "default_statement_descriptor"=> "Pawny City Hall",
            "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"=> "Pawny City Hall",
            "principal_percentage_ownership"=> 50,
            "email"=> "user@example.org",
            "mcc"=> "0742",
            "phone"=> "1234567890",
            "business_name"=> "Pawny City Hall",
            "tax_id"=> "123456789",
            "business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone"=> "+1 (408) 756-4497",
            "dob"=> {
                "year"=> 1978,
                "day"=> 27,
                "month"=> 6
            },
            "url"=> "www.PawnyCityHall.com",
            "annual_card_volume"=> 12000000
        }
    }).save

Example Response:

{
  "id" : "IDtYboiBEsqMo9WqqCeswAXL",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "entity" : {
    "title" : "CEO",
    "first_name" : "dwayne",
    "last_name" : "Sunkhronos",
    "email" : "user@example.org",
    "business_name" : "Pawny City Hall",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "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_id_provided" : true,
    "business_tax_id_provided" : true,
    "default_statement_descriptor" : "Pawny City Hall"
  },
  "tags" : {
    "Studio Rating" : "4.7"
  },
  "created_at" : "2019-03-13T22:08:55.92Z",
  "updated_at" : "2019-03-13T22:08:55.92Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    }
  }
}

Create an Identity resource with the merchant’s underwriting information.

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

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

Fetch a Identity


curl https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed


import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import com.google.common.collect.ImmutableMap;

Maybe<Identity> response = api.identities.id("IDtYboiBEsqMo9WqqCeswAXL").get();
if (! response.succeeded()) {
    ApiError error = response.error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to fetch Identity");
}
Identity identity = response.view();


<?php
use Finix\Resources\Identity;

$identity = Identity::retrieve('IDtYboiBEsqMo9WqqCeswAXL');



from finix.resources import Identity
identity = Identity.get(id="IDtYboiBEsqMo9WqqCeswAXL")


identity = Finix::Identity.retrieve(:id=>"IDtYboiBEsqMo9WqqCeswAXL")

Example Response:

{
  "id" : "IDtYboiBEsqMo9WqqCeswAXL",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "entity" : {
    "title" : "CEO",
    "first_name" : "dwayne",
    "last_name" : "Sunkhronos",
    "email" : "user@example.org",
    "business_name" : "Pawny City Hall",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "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_id_provided" : true,
    "business_tax_id_provided" : true,
    "default_statement_descriptor" : "Pawny City Hall"
  },
  "tags" : {
    "Studio Rating" : "4.7"
  },
  "created_at" : "2019-03-13T22:08:55.92Z",
  "updated_at" : "2019-03-13T22:09:01.72Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    }
  }
}

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  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed



import io.finix.payments.ApiClient;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.lib.Page;

Maybe<Page<Identity>> response = api.identities.get();

if (! response.succeeded()) {
    ApiError error = response.error();
    System.out.println(error.getCode());
    System.out.println(error.getMessage());
    System.out.println(error.getDetails());
    throw new RuntimeException("API error attempting to list all Identities");
}

Page<Identity> page = response.view();


<?php
use Finix\Resources\Identity;

$identities= Identity::getPagination("/identities");





from finix.resources import Identity
identity = Identity.get()


identities = Finix::Identity.retrieve

Example Response:

{
  "_embedded" : {
    "identities" : [ {
      "id" : "IDbUcrKrk2ksC2oiirfLF17t",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "entity" : {
        "title" : null,
        "first_name" : "Michael",
        "last_name" : "Lopez",
        "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_id_provided" : false,
        "business_tax_id_provided" : false,
        "default_statement_descriptor" : null
      },
      "tags" : {
        "key" : "value"
      },
      "created_at" : "2019-03-13T22:09:04.95Z",
      "updated_at" : "2019-03-13T22:09:05.85Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        }
      }
    }, {
      "id" : "IDaDgH5n8Ghqn4v7x3xzXhCf",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Prestige World Wide",
        "business_type" : "GOVERNMENT_AGENCY",
        "doing_business_as" : "Prestige World Wide",
        "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.PrestigeWorldWide.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_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Prestige World Wide"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2019-03-13T22:08:59.97Z",
      "updated_at" : "2019-03-13T22:08:59.96Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDaDgH5n8Ghqn4v7x3xzXhCf"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDaDgH5n8Ghqn4v7x3xzXhCf/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDaDgH5n8Ghqn4v7x3xzXhCf/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDaDgH5n8Ghqn4v7x3xzXhCf/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDaDgH5n8Ghqn4v7x3xzXhCf/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDaDgH5n8Ghqn4v7x3xzXhCf/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDaDgH5n8Ghqn4v7x3xzXhCf/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDaDgH5n8Ghqn4v7x3xzXhCf/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDaDgH5n8Ghqn4v7x3xzXhCf/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        }
      }
    }, {
      "id" : "IDu4sjcsCmhGxaEeb9pu4CXu",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Golds Gym",
        "business_type" : "INTERNATIONAL_ORGANIZATION",
        "doing_business_as" : "Golds Gym",
        "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.GoldsGym.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_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Golds Gym"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2019-03-13T22:08:59.42Z",
      "updated_at" : "2019-03-13T22:08:59.40Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu4sjcsCmhGxaEeb9pu4CXu"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu4sjcsCmhGxaEeb9pu4CXu/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu4sjcsCmhGxaEeb9pu4CXu/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu4sjcsCmhGxaEeb9pu4CXu/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu4sjcsCmhGxaEeb9pu4CXu/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu4sjcsCmhGxaEeb9pu4CXu/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu4sjcsCmhGxaEeb9pu4CXu/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu4sjcsCmhGxaEeb9pu4CXu/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu4sjcsCmhGxaEeb9pu4CXu/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        }
      }
    }, {
      "id" : "IDu9rqTFSQjCaAmoJPpLpkjH",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Dunder Mifflin",
        "business_type" : "TAX_EXEMPT_ORGANIZATION",
        "doing_business_as" : "Dunder Mifflin",
        "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.DunderMifflin.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_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Dunder Mifflin"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2019-03-13T22:08:58.86Z",
      "updated_at" : "2019-03-13T22:08:58.85Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu9rqTFSQjCaAmoJPpLpkjH"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu9rqTFSQjCaAmoJPpLpkjH/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu9rqTFSQjCaAmoJPpLpkjH/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu9rqTFSQjCaAmoJPpLpkjH/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu9rqTFSQjCaAmoJPpLpkjH/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu9rqTFSQjCaAmoJPpLpkjH/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu9rqTFSQjCaAmoJPpLpkjH/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu9rqTFSQjCaAmoJPpLpkjH/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDu9rqTFSQjCaAmoJPpLpkjH/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        }
      }
    }, {
      "id" : "IDrKGVzn1NKK98WseC1wz8uE",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Bobs Burgers",
        "business_type" : "ASSOCIATION_ESTATE_TRUST",
        "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_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Bobs Burgers"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2019-03-13T22:08:58.28Z",
      "updated_at" : "2019-03-13T22:08:58.27Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDrKGVzn1NKK98WseC1wz8uE"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDrKGVzn1NKK98WseC1wz8uE/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDrKGVzn1NKK98WseC1wz8uE/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDrKGVzn1NKK98WseC1wz8uE/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDrKGVzn1NKK98WseC1wz8uE/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDrKGVzn1NKK98WseC1wz8uE/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDrKGVzn1NKK98WseC1wz8uE/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDrKGVzn1NKK98WseC1wz8uE/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDrKGVzn1NKK98WseC1wz8uE/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        }
      }
    }, {
      "id" : "IDxhQyQjHLaXjktd6vskqFXd",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Golds Gym",
        "business_type" : "PARTNERSHIP",
        "doing_business_as" : "Golds Gym",
        "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.GoldsGym.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_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Golds Gym"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2019-03-13T22:08:57.73Z",
      "updated_at" : "2019-03-13T22:08:57.71Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDxhQyQjHLaXjktd6vskqFXd"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDxhQyQjHLaXjktd6vskqFXd/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDxhQyQjHLaXjktd6vskqFXd/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDxhQyQjHLaXjktd6vskqFXd/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDxhQyQjHLaXjktd6vskqFXd/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDxhQyQjHLaXjktd6vskqFXd/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDxhQyQjHLaXjktd6vskqFXd/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDxhQyQjHLaXjktd6vskqFXd/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDxhQyQjHLaXjktd6vskqFXd/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        }
      }
    }, {
      "id" : "ID2ed2omDWxRcYrjU7cHUqBJ",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "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_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Lees Sandwiches"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2019-03-13T22:08:57.14Z",
      "updated_at" : "2019-03-13T22:08:57.12Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2ed2omDWxRcYrjU7cHUqBJ"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2ed2omDWxRcYrjU7cHUqBJ/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2ed2omDWxRcYrjU7cHUqBJ/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2ed2omDWxRcYrjU7cHUqBJ/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2ed2omDWxRcYrjU7cHUqBJ/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2ed2omDWxRcYrjU7cHUqBJ/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2ed2omDWxRcYrjU7cHUqBJ/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2ed2omDWxRcYrjU7cHUqBJ/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID2ed2omDWxRcYrjU7cHUqBJ/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        }
      }
    }, {
      "id" : "IDgATKPEqcEwmyCLXj3yQDt3",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Golds Gym",
        "business_type" : "CORPORATION",
        "doing_business_as" : "Golds Gym",
        "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.GoldsGym.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_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Golds Gym"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2019-03-13T22:08:56.55Z",
      "updated_at" : "2019-03-13T22:08:56.54Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgATKPEqcEwmyCLXj3yQDt3"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgATKPEqcEwmyCLXj3yQDt3/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgATKPEqcEwmyCLXj3yQDt3/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgATKPEqcEwmyCLXj3yQDt3/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgATKPEqcEwmyCLXj3yQDt3/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgATKPEqcEwmyCLXj3yQDt3/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgATKPEqcEwmyCLXj3yQDt3/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgATKPEqcEwmyCLXj3yQDt3/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgATKPEqcEwmyCLXj3yQDt3/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        }
      }
    }, {
      "id" : "IDtYboiBEsqMo9WqqCeswAXL",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Pawny City Hall",
        "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
        "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_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Pawny City Hall"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2019-03-13T22:08:55.92Z",
      "updated_at" : "2019-03-13T22:09:01.72Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        }
      }
    }, {
      "id" : "IDgcSyU8YQAT4au9JhenCQf8",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "entity" : {
        "title" : null,
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Paypal",
        "business_type" : "LIMITED_LIABILITY_COMPANY",
        "doing_business_as" : "Paypal",
        "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_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : null
      },
      "tags" : {
        "application_name" : "Paypal"
      },
      "created_at" : "2019-03-13T22:08:38.32Z",
      "updated_at" : "2019-03-13T22:08:38.35Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgcSyU8YQAT4au9JhenCQf8"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgcSyU8YQAT4au9JhenCQf8/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgcSyU8YQAT4au9JhenCQf8/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgcSyU8YQAT4au9JhenCQf8/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgcSyU8YQAT4au9JhenCQf8/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgcSyU8YQAT4au9JhenCQf8/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgcSyU8YQAT4au9JhenCQf8/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgcSyU8YQAT4au9JhenCQf8/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgcSyU8YQAT4au9JhenCQf8/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        }
      }
    } ]
  },
  "_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" : 10
  }
}

HTTP Request

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

Update an Identity

curl https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -X PUT \
    -d '
    {
        "tags": {
            "key": "value_2"
        },
        "entity": {
            "business_phone": "+1 (408) 756-4497",
            "first_name": "Bernard",
            "last_name": "Jones",
            "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": "Dunder Mifflin",
            "annual_card_volume": 12000000,
            "default_statement_descriptor": "Dunder Mifflin",
            "url": "www.DunderMifflin.com",
            "business_name": "Dunder Mifflin",
            "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"
        }
    }'


import io.finix.payments.ApiClient;
import io.finix.payments.enums.BusinessType;
import io.finix.payments.forms.*;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.views.Identity;

IdentityForm form = IdentityForm.builder()
                .entity(
                  IdentityEntityForm.builder()
                      .firstName("dwayne")
                      .email("self@newdomain.com")
                      .businessPhone("+1 (408) 756-4497")
                      .build())
                .build();

Maybe<Identity> response = api.identities.id("IDtYboiBEsqMo9WqqCeswAXL").put(form);

if (! response.succeeded()) {
    System.out.println(response.error());
    throw new RuntimeException("API error attempting to update identity");
}

Identity updatedIdentity = response.view();


<?php




from finix.resources import Identity

identity = Identity.get(id="IDtYboiBEsqMo9WqqCeswAXL")
identity.entity["first_name"] = "Bernard"
identity.save()


identity = Finix::Identity.retrieve(:id=>"IDtYboiBEsqMo9WqqCeswAXL")

identity.entity["first_name"] = "Bernard"
identity.save

Example Response:

{
  "id" : "IDtYboiBEsqMo9WqqCeswAXL",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "entity" : {
    "title" : "CTO",
    "first_name" : "Bernard",
    "last_name" : "Jones",
    "email" : "user@example.org",
    "business_name" : "Dunder Mifflin",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "Dunder Mifflin",
    "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.DunderMifflin.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_id_provided" : true,
    "business_tax_id_provided" : true,
    "default_statement_descriptor" : "Dunder Mifflin"
  },
  "tags" : {
    "key" : "value_2"
  },
  "created_at" : "2019-03-13T22:08:55.92Z",
  "updated_at" : "2019-03-13T22:09:56.55Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    }
  }
}

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

HTTP Request

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

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, optional First line of the address (max 60 characters)
line2 string, optional Second line of the address (max 60 characters)
city string, required 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

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/IDtYboiBEsqMo9WqqCeswAXL/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '
    {
        "processor": null,
        "tags": {
            "key_2": "value_2"
        }
    }'



import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import com.google.common.collect.ImmutableMap;

Maybe<Identity> response = api.identities.id("IDtYboiBEsqMo9WqqCeswAXL").get();
if (! response.succeeded()) {
    ApiError error = response.error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to fetch Identity");
}
Identity identity = response.view();

MerchantUnderwritingForm form = MerchantUnderwritingForm.builder()
    .tags(ImmutableMap.of("key", "value"))
    .build();

Maybe<Merchant> merchantResponse = api.identities.id(identity.id).merchants.post(form);

if (! merchantResponse.succeeded()) {
            ApiError error = merchantResponse.error();
            System.out.println(error.getCode());
            throw new RuntimeException("API error attempting to provision Merchant");
        }
Merchant merchant = merchantResponse.view();


<?php
use Finix\Resources\Identity;
use Finix\Resources\Merchant;

$identity = Identity::retrieve('IDtYboiBEsqMo9WqqCeswAXL');

$merchant = $identity->provisionMerchantOn(new Merchant());




from finix.resources import Identity
from finix.resources import Merchant

identity = Identity.get(id="IDtYboiBEsqMo9WqqCeswAXL")
merchant = identity.provision_merchant_on(Merchant())


identity = Finix::Identity.retrieve(:id=>"IDtYboiBEsqMo9WqqCeswAXL")

merchant = identity.provision_merchant

Example Response:

{
  "id" : "MU283Zr8JgEeVzvg8sUSGiU2",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "identity" : "IDtYboiBEsqMo9WqqCeswAXL",
  "verification" : "VI3L9XzyskUEzYPAku37BswX",
  "merchant_profile" : "MPad2wRbceApbBwtZ9TbpP62",
  "processor" : "DUMMY_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "creating_transfer_from_report_enabled" : false,
  "tags" : {
    "key_2" : "value_2"
  },
  "created_at" : "2019-03-13T22:09:03.67Z",
  "updated_at" : "2019-03-13T22:09:03.86Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : {
    "api_key" : "secretValue"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU283Zr8JgEeVzvg8sUSGiU2"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU283Zr8JgEeVzvg8sUSGiU2/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPad2wRbceApbBwtZ9TbpP62"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VI3L9XzyskUEzYPAku37BswX"
    }
  }
}

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

Merchant resources can have 3 potential states:

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

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

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

HTTP Request

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

URL Parameters

Parameter Description
identity_id ID of the Identity

Merchants

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

Provision a Merchant

curl https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '
    {
        "processor": null,
        "tags": {
            "key_2": "value_2"
        }
    }'


import io.finix.payments.interfaces.Maybe;
import io.finix.payments.views.*;
import io.finix.payments.forms.*;

MerchantUnderwritingForm form = MerchantUnderwritingForm.builder()
    .processor(null)
    .tags(ImmutableMap.of("key", "value"))
    .build();

Maybe<Merchant> underwriteMerchant = api.identities.id("IDtYboiBEsqMo9WqqCeswAXL").merchants.post(form);

if(! underwriteMerchant.succeeded()){
   System.out.println(underwriteMerchant.error());
}

Merchant provisionMerchant = underwriteMerchant.view();


<?php
use Finix\Resources\Identity;
use Finix\Resources\Merchant;

$identity = Identity::retrieve('IDtYboiBEsqMo9WqqCeswAXL');

$merchant = $identity->provisionMerchantOn(new Merchant());




from finix.resources import Identity
from finix.resources import Merchant

identity = Identity.get(id="IDtYboiBEsqMo9WqqCeswAXL")
merchant = identity.provision_merchant_on(Merchant())


identity = Finix::Identity.retrieve(:id => "MU283Zr8JgEeVzvg8sUSGiU2")

merchant = identity.provision_merchant

Example Response:

{
  "id" : "MU283Zr8JgEeVzvg8sUSGiU2",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "identity" : "IDtYboiBEsqMo9WqqCeswAXL",
  "verification" : "VI3L9XzyskUEzYPAku37BswX",
  "merchant_profile" : "MPad2wRbceApbBwtZ9TbpP62",
  "processor" : "DUMMY_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "creating_transfer_from_report_enabled" : false,
  "tags" : {
    "key_2" : "value_2"
  },
  "created_at" : "2019-03-13T22:09:03.67Z",
  "updated_at" : "2019-03-13T22:09:03.86Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : {
    "api_key" : "secretValue"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU283Zr8JgEeVzvg8sUSGiU2"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU283Zr8JgEeVzvg8sUSGiU2/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPad2wRbceApbBwtZ9TbpP62"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VI3L9XzyskUEzYPAku37BswX"
    }
  }
}

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

Merchant resources can have 3 potential onboarding_states:

  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

Fetch a Merchant

curl https://finix.sandbox-payments-api.com/merchants/MU283Zr8JgEeVzvg8sUSGiU2 \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed


import io.finix.payments.ApiClient;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.views.Merchant;

Maybe<Merchant> response = api.merchants
    .id(merchant.id)
    .get();

if(! response.succeeded()){
    System.out.println(response.error());
    System.out.println(response.error().getDetails());
    throw new RuntimeException("API error attempting to fetch Merchant");
}

Merchant merchantView = response.view();


<?php
use Finix\Resources\Merchant;

$merchant = Merchant::retrieve('MU283Zr8JgEeVzvg8sUSGiU2');




from finix.resources import Merchant
merchant = Merchant.get(id="MU283Zr8JgEeVzvg8sUSGiU2")


merchant = Finix::Merchant.retrieve(:id => "MU283Zr8JgEeVzvg8sUSGiU2")

Example Response:

{
  "id" : "MU283Zr8JgEeVzvg8sUSGiU2",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "identity" : "IDtYboiBEsqMo9WqqCeswAXL",
  "verification" : null,
  "merchant_profile" : "MPad2wRbceApbBwtZ9TbpP62",
  "processor" : "DUMMY_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "creating_transfer_from_report_enabled" : false,
  "tags" : {
    "key_2" : "value_2"
  },
  "created_at" : "2019-03-13T22:09:03.67Z",
  "updated_at" : "2019-03-13T22:09:03.86Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : {
    "api_key" : "secretValue"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU283Zr8JgEeVzvg8sUSGiU2"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU283Zr8JgEeVzvg8sUSGiU2/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPad2wRbceApbBwtZ9TbpP62"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    }
  }
}

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/MU283Zr8JgEeVzvg8sUSGiU2/verifications \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '{}'

Merchant merchant = client.merchantsClient().fetch("MU283Zr8JgEeVzvg8sUSGiU2");
Verification verification = merchant.verify(
  Verification.builder().build()
);

<?php
use Finix\Resources\Merchant;
use Finix\Resources\Verification;

$merchant = Merchant::retrieve('MU283Zr8JgEeVzvg8sUSGiU2');
$verification = new Verification();
$verification = $merchant->verifyOn($verification);



from finix.resources import Merchant
from finix.resources import Verification

merchant = Merchant.get(id="MU283Zr8JgEeVzvg8sUSGiU2")

verification = merchant.verify_on(Verification())


merchant = Finix::Merchant.retrieve(:id => "MU283Zr8JgEeVzvg8sUSGiU2")

verification = merchant.verify

Example Response:

{
  "id" : "VIjVforZpozFyCVoVLgftFbk",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "tags" : { },
  "messages" : [ ],
  "raw" : null,
  "processor" : "DUMMY_V1",
  "state" : "PENDING",
  "created_at" : "2019-03-13T22:09:58.13Z",
  "updated_at" : "2019-03-13T22:09:58.16Z",
  "trace_id" : "c071bfe6-b8e0-489b-beb4-0dfd56a1c10f",
  "payment_instrument" : null,
  "merchant" : "MU283Zr8JgEeVzvg8sUSGiU2",
  "identity" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIjVforZpozFyCVoVLgftFbk"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU283Zr8JgEeVzvg8sUSGiU2"
    }
  }
}

Re-attempt provisioning a Merchant account on a processor if the previous attempt returned a FAILED onboarding_state.

HTTP Request

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

URL Parameters

Parameter Description
:MERCHANT_ID ID of the Merchant

Update Info on Processor

curl https://finix.sandbox-payments-api.com/merchants/MU283Zr8JgEeVzvg8sUSGiU2/verifications \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '{}'




<?php
use Finix\Resources\Merchant;
use Finix\Resources\Verification;

$merchant = Merchant::retrieve('MU283Zr8JgEeVzvg8sUSGiU2');
$verification = new Verification();
$verification = $merchant->verifyOn($verification);



from finix.resources import Merchant
merchant = Merchant.get(id="MU283Zr8JgEeVzvg8sUSGiU2")

merchant.entity["first_name"] = "Michael"
merchant.save()


merchant = Finix::Merchant.retrieve(:id => "MU283Zr8JgEeVzvg8sUSGiU2")

verification = merchant.entity["default_statement_descriptor"] = "Prestige World Wide"

Example Response:

{
  "id" : "VIjVforZpozFyCVoVLgftFbk",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "tags" : { },
  "messages" : [ ],
  "raw" : null,
  "processor" : "DUMMY_V1",
  "state" : "PENDING",
  "created_at" : "2019-03-13T22:09:58.13Z",
  "updated_at" : "2019-03-13T22:09:58.16Z",
  "trace_id" : "c071bfe6-b8e0-489b-beb4-0dfd56a1c10f",
  "payment_instrument" : null,
  "merchant" : "MU283Zr8JgEeVzvg8sUSGiU2",
  "identity" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIjVforZpozFyCVoVLgftFbk"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU283Zr8JgEeVzvg8sUSGiU2"
    }
  }
}

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

List all Merchants

curl https://finix.sandbox-payments-api.com/merchants/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed


import io.finix.payments.ApiClient;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.lib.Page;
import io.finix.payments.views.Merchant;

Maybe<Page<Merchant>> response = api.merchants.get();

if (! response.succeeded()) {
  ApiError error = response.error();
  System.out.println(error.getCode());
  System.out.println(error.getMessage());
  System.out.println(error.getDetails());
  throw new RuntimeException("API error attempting to list all Merchants");
}

Page<Merchant> page = response.view();


<?php
use Finix\Resources\Merchant;

$merchants = Merchant::getPagination("/merchants");





from finix.resources import Merchant
merchant = Merchant.get()


merchants = Finix::Merchant.retrieve

Example Response:

{
  "_embedded" : {
    "merchants" : [ {
      "id" : "MU283Zr8JgEeVzvg8sUSGiU2",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "identity" : "IDtYboiBEsqMo9WqqCeswAXL",
      "verification" : null,
      "merchant_profile" : "MPad2wRbceApbBwtZ9TbpP62",
      "processor" : "DUMMY_V1",
      "processing_enabled" : true,
      "settlement_enabled" : true,
      "creating_transfer_from_report_enabled" : false,
      "tags" : {
        "key_2" : "value_2"
      },
      "created_at" : "2019-03-13T22:09:03.67Z",
      "updated_at" : "2019-03-13T22:09:03.86Z",
      "onboarding_state" : "APPROVED",
      "processor_details" : {
        "api_key" : "secretValue"
      },
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/merchants/MU283Zr8JgEeVzvg8sUSGiU2"
        },
        "identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/merchants/MU283Zr8JgEeVzvg8sUSGiU2/verifications"
        },
        "merchant_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPad2wRbceApbBwtZ9TbpP62"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 1
  }
}

HTTP Request

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

List Merchant Verifications

curl https://finix.sandbox-payments-api.com/merchants/MU283Zr8JgEeVzvg8sUSGiU2/verifications \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed




<?php
use Finix\Resources\Merchant;
use Finix\Resources\Verification;

$merchant = Merchant::retrieve('MU283Zr8JgEeVzvg8sUSGiU2');
$verifications = Verification::getPagination($merchant->getHref("verifications"));





from finix.resources import Merchant
merchant = Merchant.get(id="MU283Zr8JgEeVzvg8sUSGiU2")
verifications = merchant.verifications


merchant = Finix::Merchant.retrieve(:id => "MU283Zr8JgEeVzvg8sUSGiU2")
verifications = merchant.verifications

Example Response:

{
  "_embedded" : {
    "verifications" : [ {
      "id" : "VI3L9XzyskUEzYPAku37BswX",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "tags" : {
        "key_2" : "value_2"
      },
      "messages" : [ ],
      "raw" : "RawDummyMerchantUnderwriteResult",
      "processor" : "DUMMY_V1",
      "state" : "SUCCEEDED",
      "created_at" : "2019-03-13T22:09:03.68Z",
      "updated_at" : "2019-03-13T22:09:03.94Z",
      "trace_id" : "0a661390-cc5f-4c93-9c0e-de659cbed68d",
      "payment_instrument" : null,
      "merchant" : "MU283Zr8JgEeVzvg8sUSGiU2",
      "identity" : null,
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/verifications/VI3L9XzyskUEzYPAku37BswX"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        },
        "merchant" : {
          "href" : "https://finix.sandbox-payments-api.com/merchants/MU283Zr8JgEeVzvg8sUSGiU2"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU283Zr8JgEeVzvg8sUSGiU2/verifications?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 1
  }
}

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

HTTP Request

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

URL Parameters

Parameter Description
:MERCHANT_ID ID of the Merchant

Payment Instruments

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

Create a Payment Card



curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '
    {
        "name": "Laura Jones",
        "expiration_year": 2020,
        "tags": {
            "card_name": "Business Card"
        },
        "number": "4895142232120006",
        "expiration_month": 3,
        "address": {
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "94404",
            "line1": "900 Metro Center Blv",
            "country": "USA"
        },
        "security_code": "022",
        "type": "PAYMENT_CARD",
        "identity": "IDbUcrKrk2ksC2oiirfLF17t"
    }'



import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.forms.Address;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import com.google.common.collect.ImmutableMap;

PaymentCardForm form = PaymentCardForm.builder()
        .name("Joe Doe")
        .number("4957030420210454")
        .securityCode("112")
        .expirationYear(2020)
        .identity("IDtYboiBEsqMo9WqqCeswAXL")
        .expirationMonth(12)
        .address(
                Address.builder()
                        .city("San Mateo")
                        .country("USA")
                        .region("CA")
                        .line1("123 Fake St")
                        .line2("#7")
                        .postalCode("90210")
                        .build()
        )
        .tags(ImmutableMap.of("card_name", "Business Card"))
        .build();

Maybe<PaymentCard> response = api.instruments.post(form);
        if (! response.succeeded()) {
            ApiError error = response .error();
            System.out.println(error.getCode());
            throw new RuntimeException("API error attempting to create Payment Card");
        }
PaymentCard card = response.view();


<?php
use Finix\Resources\PaymentCard;
use Finix\Resources\Identity;

$identity = Identity::retrieve('IDtYboiBEsqMo9WqqCeswAXL');
$card = new PaymentCard(
    array(
        "name"=> "Laura Jones",
        "expiration_year"=> 2020,
        "tags"=> array(
            "card_name"=> "Business Card"
        ),
        "number"=> "4895142232120006",
        "expiration_month"=> 3,
        "address"=> array(
            "city"=> "San Francisco",
            "region"=> "CA",
            "postal_code"=> "94404",
            "line1"=> "900 Metro Center Blv",
            "country"=> "USA"
        ),
        "security_code"=> "022",
        "type"=> "PAYMENT_CARD",
        "identity"=> "IDbUcrKrk2ksC2oiirfLF17t"
    ));
$card = $identity->createPaymentCard($card);




from finix.resources import PaymentCard

card = PaymentCard(**
    {
        "name": "Laura Jones",
        "expiration_year": 2020,
        "tags": {
            "card_name": "Business Card"
        },
        "number": "4895142232120006",
        "expiration_month": 3,
        "address": {
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "94404",
            "line1": "900 Metro Center Blv",
            "country": "USA"
        },
        "security_code": "022",
        "type": "PAYMENT_CARD",
        "identity": "IDbUcrKrk2ksC2oiirfLF17t"
    }).save()

card = Finix::PaymentCard.new(
    {
        "name"=> "Laura Jones",
        "expiration_year"=> 2020,
        "tags"=> {
            "card_name"=> "Business Card"
        },
        "number"=> "4895142232120006",
        "expiration_month"=> 3,
        "address"=> {
            "city"=> "San Francisco",
            "region"=> "CA",
            "postal_code"=> "94404",
            "line1"=> "900 Metro Center Blv",
            "country"=> "USA"
        },
        "security_code"=> "022",
        "type"=> "PAYMENT_CARD",
        "identity"=> "IDbUcrKrk2ksC2oiirfLF17t"
    }).save

Example Response:

{
  "id" : "PIgM3PiQZsPUyhds2hZRgUGe",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 3,
  "expiration_year" : 2020,
  "bin" : "489514",
  "last_four" : "0006",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Laura Jones",
  "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" : "2019-03-13T22:09:05.85Z",
  "updated_at" : "2019-03-13T22:09:05.85Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDbUcrKrk2ksC2oiirfLF17t",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe/updates"
    }
  }
}

Please review our guide on how to tokenize cards via the tokenization with hosted fields 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 Primary 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, optional First line of the address (max 60 characters)
line2 string, optional Second line of the address (max 60 characters)
city string, optional City (max 20 characters)
region string, optional 2-letter State code
postal_code string, optional Zip or Postal code (max 7 characters)
country string, optional 3-Letter Country code

Create a Bank Account


curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '
    {
        "account_type": "SAVINGS",
        "name": "Fran Lemke",
        "tags": {
            "Bank Account": "Company Account"
        },
        "country": "USA",
        "bank_code": "123123123",
        "account_number": "123123123",
        "type": "BANK_ACCOUNT",
        "identity": "IDtYboiBEsqMo9WqqCeswAXL"
    }'



import io.finix.payments.ApiClient;
import io.finix.payments.enums.BankAccountType;
import io.finix.payments.forms.BankAccountForm;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.views.BankAccount;
import io.finix.payments.views.Identity;
import java.util.Currency;

BankAccountForm form = BankAccountForm.builder()
        .name("Joe Doe")
        .identity("IDtYboiBEsqMo9WqqCeswAXL")
        .accountNumber("84012312415")
        .bankCode("840123124")
        .accountType(BankAccountType.SAVINGS)
        .companyName("company name")
        .country("USA")
        .currency(Currency.getInstance("USD"))
        .build();

Maybe<BankAccount> request = api.instruments.post(form);

if (! request.succeeded()) {
    ApiError error = request.error();
    System.out.println(error);
    throw new RuntimeException("API error attempting to create bank account");
}
BankAccount bankAccount = request.view();


<?php
use Finix\Resources\Identity;
use Finix\Resources\BankAccount;

$identity = Identity::retrieve('IDtYboiBEsqMo9WqqCeswAXL');
$bank_account = new BankAccount(
    array(
        "account_type"=> "SAVINGS",
        "name"=> "Fran Lemke",
        "tags"=> array(
            "Bank Account"=> "Company Account"
        ),
        "country"=> "USA",
        "bank_code"=> "123123123",
        "account_number"=> "123123123",
        "type"=> "BANK_ACCOUNT",
        "identity"=> "IDtYboiBEsqMo9WqqCeswAXL"
    ));
$bank_account = $identity->createBankAccount($bank_account);



from finix.resources import BankAccount

bank_account = BankAccount(**
    {
        "account_type": "SAVINGS",
        "name": "Fran Lemke",
        "tags": {
            "Bank Account": "Company Account"
        },
        "country": "USA",
        "bank_code": "123123123",
        "account_number": "123123123",
        "type": "BANK_ACCOUNT",
        "identity": "IDtYboiBEsqMo9WqqCeswAXL"
    }).save()

bank_account = Finix::BankAccount.new(
    {
        "account_type"=> "SAVINGS",
        "name"=> "Fran Lemke",
        "tags"=> {
            "Bank Account"=> "Company Account"
        },
        "country"=> "USA",
        "bank_code"=> "123123123",
        "account_number"=> "123123123",
        "type"=> "BANK_ACCOUNT",
        "identity"=> "IDtYboiBEsqMo9WqqCeswAXL"
    }).save

Example Response:

{
  "id" : "PIdyidW1HNq47hDSrRjFckqn",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
  "tags" : {
    "Bank Account" : "Company Account"
  },
  "bank_code" : "123123123",
  "country" : "USA",
  "masked_account_number" : "XXXXX3123",
  "name" : "Fran Lemke",
  "account_type" : "SAVINGS",
  "created_at" : "2019-03-13T22:09:01.72Z",
  "updated_at" : "2019-03-13T22:09:01.72Z",
  "instrument_type" : "BANK_ACCOUNT",
  "type" : "BANK_ACCOUNT",
  "currency" : "USD",
  "identity" : "IDtYboiBEsqMo9WqqCeswAXL",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdyidW1HNq47hDSrRjFckqn"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdyidW1HNq47hDSrRjFckqn/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdyidW1HNq47hDSrRjFckqn/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdyidW1HNq47hDSrRjFckqn/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    }
  }
}

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)

Associate a Token

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '
    {
        "token": "TK4TT5vFtN4BM87ac3MX3dXH",
        "type": "TOKEN",
        "identity": "IDtYboiBEsqMo9WqqCeswAXL"
    }'



import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;

TokenAssociationForm tokenForm =  TokenAssociationForm.builder()
    .token("TK4TT5vFtN4BM87ac3MX3dXH")
    .identity("IDtYboiBEsqMo9WqqCeswAXL")
    .build();

Maybe<PaymentCard> cardResponse = api.instruments.post(tokenForm);
if (! cardResponse.succeeded()) {
    ApiError error = cardResponse.error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to create Payment Card");
}
PaymentCard paymentCard = cardResponse.view();


<?php
use Finix\Resources\PaymentInstrument;

$card = new PaymentInstrument(
    array(
        "token"=> "TK4TT5vFtN4BM87ac3MX3dXH",
        "type"=> "TOKEN",
        "identity"=> "IDtYboiBEsqMo9WqqCeswAXL"
    ));
$card = $card->save();




from finix.resources import PaymentInstrument

payment_instrument = PaymentInstrument(**
    {
        "token": "TK4TT5vFtN4BM87ac3MX3dXH",
        "type": "TOKEN",
        "identity": "IDtYboiBEsqMo9WqqCeswAXL"
    }).save()

card = Finix::PaymentInstrument.new(
    {
        "token"=> "TK4TT5vFtN4BM87ac3MX3dXH",
        "type"=> "TOKEN",
        "identity"=> "IDtYboiBEsqMo9WqqCeswAXL"
    }).save

Example Response:

{
  "id" : "PI4TT5vFtN4BM87ac3MX3dXH",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "fingerprint" : "FPRw9NoorETQgCjFgwKPvcGsV",
  "tags" : { },
  "expiration_month" : 12,
  "expiration_year" : 2020,
  "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" : "2019-03-13T22:09:35.79Z",
  "updated_at" : "2019-03-13T22:09:35.79Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDtYboiBEsqMo9WqqCeswAXL",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI4TT5vFtN4BM87ac3MX3dXH"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI4TT5vFtN4BM87ac3MX3dXH/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI4TT5vFtN4BM87ac3MX3dXH/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI4TT5vFtN4BM87ac3MX3dXH/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI4TT5vFtN4BM87ac3MX3dXH/updates"
    }
  }
}

Associate the newly tokenized card or bank with the instrument owner’s Identity.

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 or hosted iframe
type string, required Must pass TOKEN as the value
identity string, required ID for the Identity resource which the account is to be associated

Fetch a Bank Account

curl https://finix.sandbox-payments-api.com/payment_instruments/PIdyidW1HNq47hDSrRjFckqn \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \


import io.finix.payments.ApiClient;
import io.finix.payments.views.Instrument;
import io.finix.payments.interfaces.Maybe;

Maybe<Instrument> response = api.paymentInstruments
    .id("PIdyidW1HNq47hDSrRjFckqn")
    .get();

if(! response.succeeded()){
    System.out.println(response.error());
    System.out.println(response.error().getDetails());
    throw new RuntimeException("API error attempting to fetch Bank Account");
}

Instrument bankAccountView = response.view();


<?php
use Finix\Resources\PaymentInstrument;

$bank_account = PaymentInstrument::retrieve('PIdyidW1HNq47hDSrRjFckqn');




from finix.resources import PaymentInstrument
bank_account = PaymentInstrument.get(id="PIdyidW1HNq47hDSrRjFckqn")


bank_account = Finix::BankAccount.retrieve(:id=> "PIdyidW1HNq47hDSrRjFckqn")

Example Response:

{
  "id" : "PIdyidW1HNq47hDSrRjFckqn",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
  "tags" : {
    "Display Name" : "Updated Field"
  },
  "bank_code" : "123123123",
  "country" : "USA",
  "masked_account_number" : "XXXXX3123",
  "name" : "Fran Lemke",
  "account_type" : "SAVINGS",
  "created_at" : "2019-03-13T22:09:01.72Z",
  "updated_at" : "2019-03-13T22:09:02.94Z",
  "instrument_type" : "BANK_ACCOUNT",
  "type" : "BANK_ACCOUNT",
  "currency" : "USD",
  "identity" : "IDtYboiBEsqMo9WqqCeswAXL",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdyidW1HNq47hDSrRjFckqn"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdyidW1HNq47hDSrRjFckqn/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdyidW1HNq47hDSrRjFckqn/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdyidW1HNq47hDSrRjFckqn/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
    }
  }
}

Fetch a previously created Payment Instrument that is of type BANK_ACCOUNT

HTTP Request

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

URL Parameters

Parameter Description
:PAYMENT_INSTRUMENT_ID ID of the Payment Instrument

Fetch a Payment Card

curl https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \


import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;

Maybe<PaymentCard> response = api.instruments
  .id("PIgM3PiQZsPUyhds2hZRgUGe")
  .get();

if (! response.succeeded()) {
    ApiError error = response.error();
    System.out.println(error.getCode());
    throw new RuntimeException("API error attempting to fetch Payment Card");
}
PaymentCard card = response.view();


<?php
use Finix\Resources\PaymentInstrument;

$card = PaymentInstrument::retrieve('PIgM3PiQZsPUyhds2hZRgUGe');




from finix.resources import PaymentInstrument
credit_card = PaymentInstrument.get(id="PIgM3PiQZsPUyhds2hZRgUGe")


card = Finix::PaymentCard.retrieve(:id=> "PIgM3PiQZsPUyhds2hZRgUGe")

Example Response:

{
  "id" : "PIgM3PiQZsPUyhds2hZRgUGe",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 3,
  "expiration_year" : 2020,
  "bin" : "489514",
  "last_four" : "0006",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Laura Jones",
  "address" : {
    "line1" : "900 Metro Center Blv",
    "line2" : null,
    "city" : "San Francisco",
    "region" : "CA",
    "postal_code" : "94404",
    "country" : "USA"
  },
  "address_verification" : "POSTAL_CODE_AND_STREET_MATCH",
  "security_code_verification" : "MATCHED",
  "created_at" : "2019-03-13T22:09:05.85Z",
  "updated_at" : "2019-03-13T22:09:31.99Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDbUcrKrk2ksC2oiirfLF17t",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe/updates"
    }
  }
}

Fetch a previously created Payment Instrument that is of type PAYMENT_CARD

HTTP Request

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

URL Parameters

Parameter Description
:PAYMENT_INSTRUMENT_ID ID of the Payment Instrument

Check for Card Updates (Account Updater)

Finix works with card networks so that your customers can continue, without interruption, using your service even if their card has changed due to it being closed, lost, or stolen. When a successful account update record is located, the Payment Instrument will be automatically updated with the new primary account number or new expiration date.

curl https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe/updates \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed \
    -d '
    {
        "merchant": "MU283Zr8JgEeVzvg8sUSGiU2"
    }'




<?php




from finix.resources import PaymentCard

card = PaymentCard(**
    {
        "name": "Laura Jones",
        "expiration_year": 2020,
        "tags": {
            "card_name": "Business Card"
        },
        "number": "4895142232120006",
        "expiration_month": 3,
        "address": {
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "94404",
            "line1": "900 Metro Center Blv",
            "country": "USA"
        },
        "security_code": "022",
        "type": "PAYMENT_CARD",
        "identity": "IDbUcrKrk2ksC2oiirfLF17t"
    }).save()
update = card.update("MU283Zr8JgEeVzvg8sUSGiU2")

Example Response:

{
  "id" : "IUmiydHvdcchenybTwr58diA",
  "application" : "APmqHR9e843RMFye7WmAj5pB",
  "merchant" : "MU283Zr8JgEeVzvg8sUSGiU2",
  "state" : "PENDING",
  "messages" : [ ],
  "created_at" : "2019-03-13T22:09:38.06Z",
  "updated_at" : "2019-03-13T22:09:38.10Z",
  "payment_instrument" : "PIgM3PiQZsPUyhds2hZRgUGe",
  "trace_id" : "083ec4a3-e035-4915-b0fa-6d6812916336",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/updates/IUmiydHvdcchenybTwr58diA"
    },
    "payment_instrument" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
    }
  }
}

Immediate Response

When first making a Post request to the updates endpoint, the state field will either be pending or failed.

  1. PENDING: The initial Account Update request has been approved by the card networks and is awaiting review.

  2. FAILED: Request rejected due to one of the following reasons:

    • Invalid credit card number
    • Invalid expiration date

Subsequent Response

Once Finix receives a response from the card network, the state of the Update resource will return either SUCCEEDED or FAILED. Each Update will also provide a message that details the reason for the outcome. If either an account number or expiration date was found, Finix will automatically update the associated Payment Instrument resource with the new details and the card will be ready for use.

  1. SUCCEEDED Messages:

    • No changes found
    • The account number was changed
    • The expiration date was changed

  2. FAILED Messages:

    • No match found
    • Invalid payment type (often due to unsupported card brands, e.g. Amex)
    • The issuing bank does not participate in the update program
    • The account was closed

HTTP Request

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

Request Arguments

Field Type Description
:MERCHANT_ID string, required ID of the Merchant
:PAYMENT_INSTRUMENT_ID string, required ID of the Payment Instrument

List all Payment Instruments

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  US9B3AqAqaf6Jab9bzgBhaBU:4f81ec6a-0dff-4b06-a262-a34f757ad6ed

import io.finix.payments.ApiClient;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.lib.Page;
import io.finix.payments.views.Instrument;

Maybe<Page<Instrument>> response = api.instruments.get();

if (! response.succeeded()) {
    ApiError error = response.error();
    System.out.println(error.getCode());
    System.out.println(error.getMessage());
    System.out.println(error.getDetails());
    throw new RuntimeException("API error attempting to list all Payment Instruments");
}

Page<Instrument> page = response.view();


<?php
use Finix\Resources\PaymentInstrument;

$paymentinstruments = PaymentInstrument::getPagination("/payment_instruments");





from finix.resources import PaymentInstrument
payment_instruments = PaymentInstrument.get()


payment_instruments = Finix::PaymentInstrument.retrieve

Example Response:

{
  "_embedded" : {
    "payment_instruments" : [ {
      "id" : "PI4TT5vFtN4BM87ac3MX3dXH",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "fingerprint" : "FPRw9NoorETQgCjFgwKPvcGsV",
      "tags" : { },
      "expiration_month" : 12,
      "expiration_year" : 2020,
      "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" : "2019-03-13T22:09:35.79Z",
      "updated_at" : "2019-03-13T22:09:35.74Z",
      "instrument_type" : "PAYMENT_CARD",
      "type" : "PAYMENT_CARD",
      "currency" : "USD",
      "identity" : "IDtYboiBEsqMo9WqqCeswAXL",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI4TT5vFtN4BM87ac3MX3dXH"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI4TT5vFtN4BM87ac3MX3dXH/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI4TT5vFtN4BM87ac3MX3dXH/transfers"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI4TT5vFtN4BM87ac3MX3dXH/verifications"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        },
        "identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
        },
        "updates" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI4TT5vFtN4BM87ac3MX3dXH/updates"
        }
      }
    }, {
      "id" : "PI5HbnvcWFY98LQQv3uiLs1r",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
      "tags" : {
        "Bank Account" : "Company Account"
      },
      "bank_code" : "123123123",
      "country" : "USA",
      "masked_account_number" : "XXXXX3123",
      "name" : "Fran Lemke",
      "account_type" : "SAVINGS",
      "created_at" : "2019-03-13T22:09:06.83Z",
      "updated_at" : "2019-03-13T22:09:08.63Z",
      "instrument_type" : "BANK_ACCOUNT",
      "type" : "BANK_ACCOUNT",
      "currency" : "USD",
      "identity" : "IDbUcrKrk2ksC2oiirfLF17t",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI5HbnvcWFY98LQQv3uiLs1r"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI5HbnvcWFY98LQQv3uiLs1r/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI5HbnvcWFY98LQQv3uiLs1r/transfers"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI5HbnvcWFY98LQQv3uiLs1r/verifications"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        },
        "identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t"
        }
      }
    }, {
      "id" : "PIgM3PiQZsPUyhds2hZRgUGe",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
      "tags" : {
        "card_name" : "Business Card"
      },
      "expiration_month" : 3,
      "expiration_year" : 2020,
      "bin" : "489514",
      "last_four" : "0006",
      "brand" : "VISA",
      "card_type" : "UNKNOWN",
      "name" : "Laura Jones",
      "address" : {
        "line1" : "900 Metro Center Blv",
        "line2" : null,
        "city" : "San Francisco",
        "region" : "CA",
        "postal_code" : "94404",
        "country" : "USA"
      },
      "address_verification" : "POSTAL_CODE_AND_STREET_MATCH",
      "security_code_verification" : "MATCHED",
      "created_at" : "2019-03-13T22:09:05.85Z",
      "updated_at" : "2019-03-13T22:09:31.99Z",
      "instrument_type" : "PAYMENT_CARD",
      "type" : "PAYMENT_CARD",
      "currency" : "USD",
      "identity" : "IDbUcrKrk2ksC2oiirfLF17t",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe/transfers"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe/verifications"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        },
        "identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDbUcrKrk2ksC2oiirfLF17t"
        },
        "updates" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIgM3PiQZsPUyhds2hZRgUGe/updates"
        }
      }
    }, {
      "id" : "PIdyidW1HNq47hDSrRjFckqn",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
      "tags" : {
        "Display Name" : "Updated Field"
      },
      "bank_code" : "123123123",
      "country" : "USA",
      "masked_account_number" : "XXXXX3123",
      "name" : "Fran Lemke",
      "account_type" : "SAVINGS",
      "created_at" : "2019-03-13T22:09:01.72Z",
      "updated_at" : "2019-03-13T22:09:02.94Z",
      "instrument_type" : "BANK_ACCOUNT",
      "type" : "BANK_ACCOUNT",
      "currency" : "USD",
      "identity" : "IDtYboiBEsqMo9WqqCeswAXL",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdyidW1HNq47hDSrRjFckqn"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdyidW1HNq47hDSrRjFckqn/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdyidW1HNq47hDSrRjFckqn/transfers"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdyidW1HNq47hDSrRjFckqn/verifications"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        },
        "identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtYboiBEsqMo9WqqCeswAXL"
        }
      }
    }, {
      "id" : "PIjyZn9cQKYRaCvPYUePZxMH",
      "application" : "APmqHR9e843RMFye7WmAj5pB",
      "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
      "tags" : {
        "Bank Account" : "Company Account"
      },
      "bank_code" : "123123123",
      "country" : "USA",
      "masked_account_number" : "XXXXX3123",
      "name" : "Fran Lemke",
      "account_type" : "SAVINGS",
      "created_at" : "2019-03-13T22:09:00.78Z",
      "updated_at" : "2019-03-13T22:09:00.77Z",
      "instrument_type" : "BANK_ACCOUNT",
      "type" : "BANK_ACCOUNT",
      "currency" : "USD",
      "identity" : "IDgcSyU8YQAT4au9JhenCQf8",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIjyZn9cQKYRaCvPYUePZxMH"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIjyZn9cQKYRaCvPYUePZxMH/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIjyZn9cQKYRaCvPYUePZxMH/transfers"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIjyZn9cQKYRaCvPYUePZxMH/verifications"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APmqHR9e843RMFye7WmAj5pB"
        },
        "identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgcSyU8YQAT4au9JhenCQf8"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" :