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.

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

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  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772

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

<dependency>
  <groupId>io.finix.payments.processing.client</groupId>
  <artifactId>finix</artifactId>
  <version>1.0.6</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("USjxcup83KZTBBFiqDScLYMF")
                  .password("25f85644-331d-45af-8758-b22b06f48772")
                  .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" => 'USjxcup83KZTBBFiqDScLYMF',
    "password" => '25f85644-331d-45af-8758-b22b06f48772']
    );

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=("USjxcup83KZTBBFiqDScLYMF", "25f85644-331d-45af-8758-b22b06f48772"))

# To download the Ruby gem:
# gem install finix

require 'finix'

Finix.configure(
    :root_url => 'https://finix.sandbox-payments-api.com',
    :user=>'USjxcup83KZTBBFiqDScLYMF',
    :password => '25f85644-331d-45af-8758-b22b06f48772'
)

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

Username: USjxcup83KZTBBFiqDScLYMF
Password: 25f85644-331d-45af-8758-b22b06f48772
Application ID: APjMB6owJ7542dehJ6hCojzR

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

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

Create an Identity for a Merchant

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

Create a Bank Account for a Merchant

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

Onboard a New Merchant

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

View KYC Identity Verification

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

Approve and Reject a Merchant

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

Enable or Disable Payments Processing

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

Enable or Disable Settlement Functionality

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

Update Fee Profile

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

Update Risk Profile

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

Approve a Settlement

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

Upload Dispute Evidence

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

Errors

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

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

Error Code	Messages
REFER_TO_CARD_ISSUER	Please contact card issuer for more information.
INVALID_MERCHANT	Merchant not permitted for this transaction type
PICK_UP_CARD_NO_FRAUD	Please contact card issuer for more information.
DO_NOT_HONOR	Please contact card issuer for more information.
ERROR	Please attempt transaction again but if it still cannot be processed try again at a later time
PICK_UP_CARD_FRAUD_ACCOUNT	Please contact card issuer for more information.
INVALID_TRANSACTION	Issuing bank does not support this transaction type on this card. Please contact card issuer for more information.
INVALID_AMOUNT_OR_CURRENCY	Transaction violates network amount limit.
INVALID_ACCOUNT_NUMBER	The account number does not exist. Please make sure the account number is correct or contact your issuer.
NO_SUCH_ISSUER	The issuer can not be found. Please check card number to ensure it is valid.
RE_ENTER_TRANSACTION	Please attempt transaction again and contact card issuer if it still cannot be processed.
NO_ACTION_TAKEN	Please contact card issuer for more information.
UNABLE_TO_LOCATE_RECORD	The account number does not exist. Please make sure the account number is correct or contact your issuer.
FILE_TEMPORARILY_NOT_AVAILABLE	Please contact card issuer for more information.
NO_CREDIT_ACCOUNT	Issuer has declined the transaction because the card is not a credit account. Please try another card.
LOST_CARD_PICK_UP_FRAUD_ACCOUNT	Please contact card issuer for more information.
STOLEN_CARD_PICK_UP_FRAUD_ACCOUNT	Please contact card issuer for more information.
NOT_SUFFICIENT_FUNDS	Card issuer has declined the transaction as it does not have sufficient funds.
NO_CHECKING_ACCOUNT	The card is not tied to a checking account and thus cannot be processed. Please try another card.
NO_SAVINGS_ACCOUNT	The card is not tied to a savings account and thus cannot be processed. Please try another card.
EXPIRED_CARD	The expiration date is expired or missing. Please correct and try again.
INCORRECT_PIN	The PIN is invalid or missing. Please try again with the correct PIN.
TRANSACTION_NOT_PERMITTED	Transaction not permitted to cardholder. Please contact card issuer for more information.
SUSPECTED_FRAUD	Please contact card issuer for more information.
EXCEEDS_APPROVAL_AMOUNT_LIMIT	Transaction violates issuer amount limit. Please contact card issuer for more information or try with another card.
RESTRICTED_CARD	Card not supported in this region or country. Please contact card issuer for more information.
TRANSACTION_DOES_NOT_FULFILL_AML_REQUIREMENT	This transaction does not fulfill compliance requirements and cannot be processed.
EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT	Please attempt with another card or contact card issuer for more information.
ALLOWABLE_NUMBER_OF_PIN_ENTRY_TRIES_EXCEEDED	The maximum permitted number of PIN entry attempts has been exceeded. Please use another payment method.
CRYPTOGRAPHIC_ERROR_FOUND_IN_PIN	The supplied PIN is invalid.
NEGATIVE_RESULTS	Invalid security code.
CANNOT_VERIFY_PIN	The PIN is invalid or missing. Please try again with the correct PIN.
ISSUER_INOPERATIVE	Please attempt transaction again and contact card issuer if it still cannot be processed.
FINANCIAL_INSTITUTION_NOT_FOUND	The issuer can not be found. Please check card number to ensure it is valid.
TRANSACTION_NOT_COMPLETED_LAW_VIOLATION	The transaction cannot be completed because it violates a law.
SURCHARGE_AMOUNT_NOT_SUPPORTED	The supplied surcharge amount is not supported by the issuer.
TRANSACTION_AMOUNT_EXCEEDS_PREAUTHORIZED_APPROVAL_AMOUNT	Transaction violates amount limit.
CARD_AUTHENTICATION_FAILED	Please contact card issuer for more information.
STOP_PAYMENT_ORDER	Please contact card issuer for more information.

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.

Testing for specific responses and errors

Payment Facilitation Testing

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

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

Card	Description
`4000000000000036`	Payment card AVS total failure
`4000000000000127`	Payment card CVC failure

Push-to-Card Testing

Cards for Testing a Push-to-Card Payout

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

Cards for Testing a Verification

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

Guides

Overview

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

Authentication: Learn how to properly authenticate and interface with the API.
Getting Started: A step-by-step guide demonstrating the basic workflow of charging a card. This guide will walk you through provisioning merchant accounts, tokenizing cards, charging those cards, and finally settling (i.e. payout) those funds out to your merchants.
Tokenization with Hosted Fields: This guide explains how to properly tokenize cards in live via hosted fields.
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.
Pull from Card: This guide walks through using the Visa Direct API to pull payments from payment cards.
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  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772 \
    -d '
    {
        "tags": {
            "Studio Rating": "4.7"
        },
        "entity": {
            "last_name": "Sunkhronos",
            "max_transaction_amount": 12000000,
            "has_accepted_credit_cards_previously": true,
            "default_statement_descriptor": "Pollos Hermanos",
            "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": "Pollos Hermanos",
            "principal_percentage_ownership": 50,
            "email": "user@example.org",
            "mcc": "0742",
            "phone": "1234567890",
            "business_name": "Pollos Hermanos",
            "tax_id": "123456789",
            "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone": "+1 (408) 756-4497",
            "dob": {
                "year": 1978,
                "day": 27,
                "month": 6
            },
            "url": "www.PollosHermanos.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"=> "Pollos Hermanos",
            "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"=> "Pollos Hermanos",
            "principal_percentage_ownership"=> 50,
            "email"=> "user@example.org",
            "mcc"=> "0742",
            "phone"=> "1234567890",
            "business_name"=> "Pollos Hermanos",
            "tax_id"=> "123456789",
            "business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone"=> "+1 (408) 756-4497",
            "dob"=> array(
                "year"=> 1978,
                "day"=> 27,
                "month"=> 6
            ),
            "url"=> "www.PollosHermanos.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": "Pollos Hermanos",
            "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": "Pollos Hermanos",
            "principal_percentage_ownership": 50,
            "email": "user@example.org",
            "mcc": "0742",
            "phone": "1234567890",
            "business_name": "Pollos Hermanos",
            "tax_id": "123456789",
            "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone": "+1 (408) 756-4497",
            "dob": {
                "year": 1978,
                "day": 27,
                "month": 6
            },
            "url": "www.PollosHermanos.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"=> "Pollos Hermanos",
            "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"=> "Pollos Hermanos",
            "principal_percentage_ownership"=> 50,
            "email"=> "user@example.org",
            "mcc"=> "0742",
            "phone"=> "1234567890",
            "business_name"=> "Pollos Hermanos",
            "tax_id"=> "123456789",
            "business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone"=> "+1 (408) 756-4497",
            "dob"=> {
                "year"=> 1978,
                "day"=> 27,
                "month"=> 6
            },
            "url"=> "www.PollosHermanos.com",
            "annual_card_volume"=> 12000000
        }
    }).save

{
  "id" : "IDcodXFEYpYHg7yukLdvWpEu",
  "application" : "APjMB6owJ7542dehJ6hCojzR",
  "entity" : {
    "title" : "CEO",
    "first_name" : "dwayne",
    "last_name" : "Sunkhronos",
    "email" : "user@example.org",
    "business_name" : "Pollos Hermanos",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "Pollos Hermanos",
    "phone" : "1234567890",
    "business_phone" : "+1 (408) 756-4497",
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 8",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "mcc" : "0742",
    "dob" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "max_transaction_amount" : 12000000,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : "www.PollosHermanos.com",
    "annual_card_volume" : 12000000,
    "has_accepted_credit_cards_previously" : true,
    "incorporation_date" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "principal_percentage_ownership" : 50,
    "short_business_name" : null,
    "ownership_type" : "PRIVATE",
    "tax_authority" : null,
    "tax_id_provided" : true,
    "business_tax_id_provided" : true,
    "default_statement_descriptor" : "Pollos Hermanos"
  },
  "tags" : {
    "Studio Rating" : "4.7"
  },
  "created_at" : "2020-12-02T03:44:11.34Z",
  "updated_at" : "2020-12-02T03:44:11.34Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
    }
  }
}

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:

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

POST https://finix.sandbox-payments-api.com/identities/
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/
Finally, provision the Merchant account

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

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

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

HTTP Request

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

Business-specific Request Arguments

Field	Type	Description
business_name	string, required	Merchant’s full legal business name (If INDIVIDUAL_SOLE_PROPRIETORSHIP, please input first name, Full legal last name and middle initial; max 120 characters)
doing_business_as	string, required	Alternate name of the business. If no other name is used please use the same value for business_name (max 60 characters)
business_type	string, required	Please select one of the following values: INDIVIDUAL_SOLE_PROPRIETORSHIP, CORPORATION, LIMITED_LIABILITY_COMPANY, PARTNERSHIP, ASSOCIATION_ESTATE_TRUST, TAX_EXEMPT_ORGANIZATION, INTERNATIONAL_ORGANIZATION, GOVERNMENT_AGENCY
business_tax_id	string, required	Nine digit Tax Identification Number (TIN), Employer Identification Number (EIN) or if the business_type is INDIVIDUAL_SOLE_PROPRIETORSHIP and a Tax ID is not available, the principal’s Social Security Number (SSN)
url	string, required	Merchant’s publicly available website (max 100 characters)
business_phone	string, required	Customer service phone number where the merchant can be reached (max 10 characters)
incorporation_date	object, required	Date company was founded (See below for a full list of the child attributes)
business_address	object, required	Primary address for the legal entity (Full description of child attributes below)
ownership_type	string, required	Values can be either PUBLIC to indicate a publicly traded company or PRIVATE for privately held businesses
amex_mid	integer, optional	Assigned amexMid value. If provided must be 10 or 11 digits
discover_mid	integer, optional	Assigned discoverMid value

Principal-specific Request Arguments

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

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

Processing-specific Request Arguments

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

Address-object Request Arguments

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

Incorporation Date-object Request Arguments

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

DOB-object Request Arguments

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

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  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772 \
    -d '
    {
        "account_type": "SAVINGS",
        "name": "Alice",
        "tags": {
            "Bank Account": "Company Account"
        },
        "country": "USA",
        "bank_code": "123123123",
        "account_number": "123123123",
        "type": "BANK_ACCOUNT",
        "identity": "IDcodXFEYpYHg7yukLdvWpEu"
    }'

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("IDcodXFEYpYHg7yukLdvWpEu")
        .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('IDcodXFEYpYHg7yukLdvWpEu');
$bank_account = new BankAccount(
    array(
        "account_type"=> "SAVINGS",
        "name"=> "Alice",
        "tags"=> array(
            "Bank Account"=> "Company Account"
        ),
        "country"=> "USA",
        "bank_code"=> "123123123",
        "account_number"=> "123123123",
        "type"=> "BANK_ACCOUNT",
        "identity"=> "IDcodXFEYpYHg7yukLdvWpEu"
    ));
$bank_account = $identity->createBankAccount($bank_account);



from finix.resources import BankAccount

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

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

{
  "id" : "PIcxU9MAKxpRZaA6vYXkkvst",
  "application" : "APjMB6owJ7542dehJ6hCojzR",
  "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
  "tags" : {
    "Bank Account" : "Company Account"
  },
  "bank_code" : "123123123",
  "country" : "USA",
  "masked_account_number" : "XXXXX3123",
  "name" : "Alice",
  "account_type" : "SAVINGS",
  "created_at" : "2020-12-02T03:44:16.41Z",
  "updated_at" : "2020-12-02T03:44:16.42Z",
  "instrument_type" : "BANK_ACCOUNT",
  "type" : "BANK_ACCOUNT",
  "currency" : "USD",
  "identity" : "IDcodXFEYpYHg7yukLdvWpEu",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIcxU9MAKxpRZaA6vYXkkvst"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIcxU9MAKxpRZaA6vYXkkvst/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIcxU9MAKxpRZaA6vYXkkvst/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIcxU9MAKxpRZaA6vYXkkvst/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
    }
  }
}

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/IDcodXFEYpYHg7yukLdvWpEu/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772 \
    -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('IDcodXFEYpYHg7yukLdvWpEu');
$merchant = $identity->provisionMerchantOn(new Merchant());



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

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

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

merchant = identity.provision_merchant

{
  "id" : "MUvQQt3RKe7FBZ6j9eMYoo3H",
  "application" : "APjMB6owJ7542dehJ6hCojzR",
  "identity" : "IDcodXFEYpYHg7yukLdvWpEu",
  "verification" : "VIx7MuY31w93pCMDkmS15e7F",
  "merchant_profile" : "MPc2842NuDR2ZoFtvPaXfLLM",
  "processor" : "DUMMY_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "card_expiration_date_required" : true,
  "card_cvv_required" : false,
  "tags" : {
    "key_2" : "value_2"
  },
  "mcc" : "0742",
  "mid" : "FNXwZpvsP1Ti8TieSjRrFwWgT",
  "merchant_name" : "Pollos Hermanos",
  "created_at" : "2020-12-02T03:44:17.12Z",
  "updated_at" : "2020-12-02T03:44:17.47Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : {
    "mid" : "FNXwZpvsP1Ti8TieSjRrFwWgT",
    "api_key" : "secretValue"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUvQQt3RKe7FBZ6j9eMYoo3H"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUvQQt3RKe7FBZ6j9eMYoo3H/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPc2842NuDR2ZoFtvPaXfLLM"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIx7MuY31w93pCMDkmS15e7F"
    }
  }
}

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

PROVISIONING: Request is pending (state will typically change after two minutes)
- processing_enabled: False
- settlement_enabled: False
APPROVED: Merchant has been approved and can begin processing
- processing_enabled: True
- settlement_enabled: True
REJECTED: Merchant was rejected by the processor either because the information collected was invalid or it failed one of a number of regulatory and/or compliance checks (e.g. KYC, OFAC or MATCH)
- processing_enabled: False
- settlement_enabled: False

HTTP Request

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

URL Parameters

Parameter	Description
:IDENTITY_ID	ID of the Identity

Request Arguments

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

Step 4: Create an Identity for a Buyer


curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772 \
    -d '
    {
        "tags": {
            "key": "value"
        },
        "entity": {
            "phone": "7145677613",
            "first_name": "Bob",
            "last_name": "Diaz",
            "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"=> "Bob",
            "last_name"=> "Diaz",
            "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": "Bob",
            "last_name": "Diaz",
            "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"=> "Bob",
            "last_name"=> "Diaz",
            "email"=> "therock@gmail.com",
            "personal_address"=> {
                "city"=> "San Mateo",
                "country"=> "USA",
                "region"=> "CA",
                "line2"=> "Apartment 7",
                "line1"=> "741 Douglass St",
                "postal_code"=> "94114"
            }
        }
    }).save

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

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

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

HTTP Request

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

Request Arguments

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

Address-object Request Arguments

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

Step 5: Tokenize a Card



curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772 \
    -d '
    {
        "name": "Michael Jones",
        "expiration_year": 2029,
        "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": "ID7XejJuLbxqZ3yknbwyXpPg"
    }'

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("IDcodXFEYpYHg7yukLdvWpEu")
        .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('IDcodXFEYpYHg7yukLdvWpEu');
$card = new PaymentCard(
    array(
        "name"=> "Michael Jones",
        "expiration_year"=> 2029,
        "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"=> "ID7XejJuLbxqZ3yknbwyXpPg"
    ));
$card = $identity->createPaymentCard($card);



from finix.resources import PaymentCard

card = PaymentCard(**
    {
        "name": "Michael Jones",
        "expiration_year": 2029,
        "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": "ID7XejJuLbxqZ3yknbwyXpPg"
    }).save()

card = Finix::PaymentCard.new(
    {
        "name"=> "Michael Jones",
        "expiration_year"=> 2029,
        "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"=> "ID7XejJuLbxqZ3yknbwyXpPg"
    }).save

{
  "id" : "PIvuHu6vbt7GsLiFp9ykpSKZ",
  "application" : "APjMB6owJ7542dehJ6hCojzR",
  "fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 3,
  "expiration_year" : 2029,
  "bin" : "489514",
  "last_four" : "0006",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Michael 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" : "2020-12-02T03:44:19.61Z",
  "updated_at" : "2020-12-02T03:44:19.61Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "ID7XejJuLbxqZ3yknbwyXpPg",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvuHu6vbt7GsLiFp9ykpSKZ"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvuHu6vbt7GsLiFp9ykpSKZ/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvuHu6vbt7GsLiFp9ykpSKZ/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvuHu6vbt7GsLiFp9ykpSKZ/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7XejJuLbxqZ3yknbwyXpPg"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvuHu6vbt7GsLiFp9ykpSKZ/updates"
    }
  }
}

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

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

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

HTTP Request

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

Request Arguments

Field	Type	Description
identity	string, required	ID of the `Identity` that the card should be associated
type	string, required	Type of Payment Instrument (for cards input PAYMENT_CARD)
number	string, required	Credit card account number
security_code	string, optional	The 3-4 digit security code for the card (i.e. CVV code)
expiration_month	integer, required	Expiration month (e.g. 12 for December)
expiration_year	integer, required	4-digit expiration year
name	string, optional	Full name of the registered card holder
address	object, optional	Billing address (Full description of child attributes below)

Address-object Request Arguments

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

Step 6: Create Sale

curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772 \
    -d '
    {
        "merchant": "MUddiki6xZa8j8TRkXhB2L58",
        "currency": "USD",
        "amount": 252158,
        "source": "PIvuHu6vbt7GsLiFp9ykpSKZ",
        "tags": {
            "test": "sale"
        }
    }'

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"))
        .source("PIvuHu6vbt7GsLiFp9ykpSKZ")
        .merchantIdentity("IDcodXFEYpYHg7yukLdvWpEu")
        .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 debit Bank Account");
}
Transfer transfer = response.view();

<?php
use Finix\Resources\Transfer;

$debit = new Transfer(
    array(
        "merchant"=> "MUddiki6xZa8j8TRkXhB2L58",
        "currency"=> "USD",
        "amount"=> 252158,
        "source"=> "PIvuHu6vbt7GsLiFp9ykpSKZ",
        "tags"=> array(
            "test"=> "sale"
        )
    ));
$debit = $debit->save();



from finix.resources import Transfer

payout = Transfer(**
    {
        "merchant": "MUddiki6xZa8j8TRkXhB2L58",
        "currency": "USD",
        "amount": 252158,
        "source": "PIvuHu6vbt7GsLiFp9ykpSKZ",
        "tags": {
            "test": "sale"
        }
    }).save()

Finix::Transfer.new(
    array(
        "merchant"=> "MUddiki6xZa8j8TRkXhB2L58",
        "currency"=> "USD",
        "amount"=> 252158,
        "source"=> "PIvuHu6vbt7GsLiFp9ykpSKZ",
        "tags"=> array(
            "test"=> "sale"
        )
    )).save

{
  "id" : "TRnuVWWkgUyaGXHze78939MG",
  "amount" : 252158,
  "tags" : {
    "test" : "sale"
  },
  "state" : "PENDING",
  "trace_id" : "c36ef905-613f-4095-8908-0480b8728cd3",
  "currency" : "USD",
  "application" : "APjMB6owJ7542dehJ6hCojzR",
  "source" : "PIvuHu6vbt7GsLiFp9ykpSKZ",
  "destination" : null,
  "ready_to_settle_at" : null,
  "fee" : 0,
  "statement_descriptor" : "FIN*PETES COFFEE",
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2020-12-02T03:44:28.78Z",
  "updated_at" : "2020-12-02T03:44:29.42Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDnWqm9V6QiUJbsnEK7dtUCf",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRnuVWWkgUyaGXHze78939MG"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDnWqm9V6QiUJbsnEK7dtUCf"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRnuVWWkgUyaGXHze78939MG/payment_instruments"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRnuVWWkgUyaGXHze78939MG/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRnuVWWkgUyaGXHze78939MG/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRnuVWWkgUyaGXHze78939MG/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvuHu6vbt7GsLiFp9ykpSKZ"
    },
    "fee_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
    }
  }
}

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

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

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

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

HTTP Request

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

Request Arguments

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

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 USk1k2JSKnbVz3VcGdP9RTxW:7e310227-2165-4d2a-aec6-747dd9604b91 \
    -d '
    {
        "tags": {
            "key": "value"
        },
        "entity": {
            "phone": "7145677612",
            "first_name": "Collen",
            "last_name": "Chang",
            "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(IDaJoamNDjxiXLeiQZAjsPor);
$identity = $identity->save();



from finix.resources import Identity

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

{
  "id" : "IDaJoamNDjxiXLeiQZAjsPor",
  "application" : "AP3sFKxrbRmnWiioKyqfRQLL",
  "entity" : {
    "title" : null,
    "first_name" : "Collen",
    "last_name" : "Chang",
    "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_authority" : null,
    "tax_id_provided" : false,
    "business_tax_id_provided" : false,
    "default_statement_descriptor" : null
  },
  "tags" : {
    "key" : "value"
  },
  "created_at" : "2020-12-02T03:43:58.80Z",
  "updated_at" : "2020-12-02T03:43:58.80Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDaJoamNDjxiXLeiQZAjsPor"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDaJoamNDjxiXLeiQZAjsPor/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDaJoamNDjxiXLeiQZAjsPor/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDaJoamNDjxiXLeiQZAjsPor/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDaJoamNDjxiXLeiQZAjsPor/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDaJoamNDjxiXLeiQZAjsPor/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDaJoamNDjxiXLeiQZAjsPor/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDaJoamNDjxiXLeiQZAjsPor/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDaJoamNDjxiXLeiQZAjsPor/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP3sFKxrbRmnWiioKyqfRQLL"
    }
  }
}

HTTP Request

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

Request Arguments

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

Address-object Request Arguments

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

Step 2: Add a Payment Instrument for the Recipient

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u USk1k2JSKnbVz3VcGdP9RTxW:7e310227-2165-4d2a-aec6-747dd9604b91 \
    -d '
    {
        "name": "Alex Lopez",
        "expiration_year": 2029,
        "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": "IDaJoamNDjxiXLeiQZAjsPor"
    }'

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("IDcodXFEYpYHg7yukLdvWpEu")
        .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"=> "Alex Lopez",
        "expiration_year"=> 2029,
        "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"=> "IDaJoamNDjxiXLeiQZAjsPor"
    ));
$card = $identity->createPaymentCard($card);



from finix.resources import PaymentCard

card = PaymentCard(**
    {
        "name": "Michael Jones",
        "expiration_year": 2029,
        "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": "ID7XejJuLbxqZ3yknbwyXpPg"
    }).save()

card = Finix::PaymentCard.new(
    {
        "name"=> "Alex Lopez",
        "expiration_year"=> 2029,
        "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"=> "IDaJoamNDjxiXLeiQZAjsPor"
    }).save

{
  "id" : "PIoL24d4QqX3sB4NS8KFCqJ2",
  "application" : "AP3sFKxrbRmnWiioKyqfRQLL",
  "fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 3,
  "expiration_year" : 2029,
  "bin" : "489514",
  "last_four" : "0006",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Alex Lopez",
  "address" : {
    "line1" : "900 Metro Center Blv",
    "line2" : null,
    "city" : "San Francisco",
    "region" : "CA",
    "postal_code" : "94404",
    "country" : "USA"
  },
  "address_verification" : "UNKNOWN",
  "security_code_verification" : "UNKNOWN",
  "created_at" : "2020-12-02T03:44:02.35Z",
  "updated_at" : "2020-12-02T03:44:02.35Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDaJoamNDjxiXLeiQZAjsPor",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIoL24d4QqX3sB4NS8KFCqJ2"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIoL24d4QqX3sB4NS8KFCqJ2/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIoL24d4QqX3sB4NS8KFCqJ2/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIoL24d4QqX3sB4NS8KFCqJ2/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP3sFKxrbRmnWiioKyqfRQLL"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDaJoamNDjxiXLeiQZAjsPor"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIoL24d4QqX3sB4NS8KFCqJ2/updates"
    }
  }
}

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

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

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

HTTP Request

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

Request Arguments

Field	Type	Description
identity	string, required	ID of the `Identity` that the card should be associated
type	string, required	Type of Payment Instrument (for cards input PAYMENT_CARD)
number	string, required	Primary card account number
security_code	string, optional	The 3-4 digit security code for the card (i.e. CVV code)
expiration_month	integer, required	Expiration month (e.g. 12 for December)
expiration_year	integer, required	4-digit expiration year
currency	string, required	Currency that should be associated with card
name	string, optional	Full name of the registered card holder
address	object, optional	Billing address (Full description of child attributes below)

Address-object Request Arguments

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

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

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

curl https://finix.sandbox-payments-api.com/payment_instruments/PIqH42bEJy9yx1j72TYeFTFw/verifications \
    -H "Content-Type: application/vnd.json+api" \
    -u USk1k2JSKnbVz3VcGdP9RTxW:7e310227-2165-4d2a-aec6-747dd9604b91 \
    -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("PIqH42bEJy9yx1j72TYeFTFw").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="PIqH42bEJy9yx1j72TYeFTFw")

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

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

HTTP Request

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

URL Parameters

Parameter	Description
:PAYMENT_INSTRUMENT_ID	ID of the `Payment Instrument`

Request Arguments

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

Address Verification Results (address_verification_results)

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

Card Verification 2 Results (cvv2_result_code)

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

Card Type (card_type_code)

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

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

Fasts Funds Indicator (fast_funds_indicator)

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

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

Push Funds Indicator (push_funds_block_indicator)

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

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

Online Gambling Block Indicator (online_gambing_block_indicator)

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

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

Card Product ID (card_product_id)

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

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

Product Sub-Type (card_product_subtype)

Description of product subtype.

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

Card Sub-Type (card_subtype_code)

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

Letter	Description
N	Non-Reloadable
R	Reloadable

Step 4: Provision Recipient Account

curl https://finix.sandbox-payments-api.com/identities/IDaJoamNDjxiXLeiQZAjsPor/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u USk1k2JSKnbVz3VcGdP9RTxW:7e310227-2165-4d2a-aec6-747dd9604b91 \
    -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("IDaJoamNDjxiXLeiQZAjsPor").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('IDaJoamNDjxiXLeiQZAjsPor');

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



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

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

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

merchant = identity.provision_merchant

{
  "id" : "MU5DjtKye3oorkM9bQuq5zRn",
  "application" : "AP3sFKxrbRmnWiioKyqfRQLL",
  "identity" : "IDaJoamNDjxiXLeiQZAjsPor",
  "verification" : "VIwnLAmgzM3t57LQubfxjnxv",
  "merchant_profile" : "MPiE2LhdXp8DFqmAFLxsQgBk",
  "processor" : "VISA_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "card_expiration_date_required" : true,
  "card_cvv_required" : false,
  "tags" : { },
  "mcc" : null,
  "mid" : null,
  "merchant_name" : "Collen Chang",
  "created_at" : "2020-12-02T03:44:04.42Z",
  "updated_at" : "2020-12-02T03:44:04.75Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU5DjtKye3oorkM9bQuq5zRn"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDaJoamNDjxiXLeiQZAjsPor"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU5DjtKye3oorkM9bQuq5zRn/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPiE2LhdXp8DFqmAFLxsQgBk"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP3sFKxrbRmnWiioKyqfRQLL"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIwnLAmgzM3t57LQubfxjnxv"
    }
  }
}

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 USk1k2JSKnbVz3VcGdP9RTxW:7e310227-2165-4d2a-aec6-747dd9604b91 \
    -d '
    {
        "currency": "USD",
        "amount": 1510,
        "destination": "PIoL24d4QqX3sB4NS8KFCqJ2",
        "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("PIoL24d4QqX3sB4NS8KFCqJ2")
        .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"=> "PIoL24d4QqX3sB4NS8KFCqJ2",
        "tags"=> array(
            "order_number"=> "21DFASJSAKAS"
        )
    ));
$transfer = $transfer->save();



from finix.resources import Transfer

payout = Transfer(**
    {
        "name": "Alex Lopez",
        "expiration_year": 2029,
        "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": "IDaJoamNDjxiXLeiQZAjsPor"
    }).save()

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

{
  "id" : "TRkReGn7qEmc4pDAazxSzhFp",
  "amount" : 1510,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "trace_id" : "033703201998",
  "currency" : "USD",
  "application" : "AP3sFKxrbRmnWiioKyqfRQLL",
  "source" : null,
  "destination" : "PIoL24d4QqX3sB4NS8KFCqJ2",
  "ready_to_settle_at" : null,
  "fee" : 0,
  "statement_descriptor" : "FIN*FINIXPAYMENTS",
  "type" : "CREDIT",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2020-12-02T03:44:06.36Z",
  "updated_at" : "2020-12-02T03:44:07.77Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDaJoamNDjxiXLeiQZAjsPor",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP3sFKxrbRmnWiioKyqfRQLL"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRkReGn7qEmc4pDAazxSzhFp"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDaJoamNDjxiXLeiQZAjsPor"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRkReGn7qEmc4pDAazxSzhFp/payment_instruments"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRkReGn7qEmc4pDAazxSzhFp/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRkReGn7qEmc4pDAazxSzhFp/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRkReGn7qEmc4pDAazxSzhFp/disputes"
    },
    "destination" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIoL24d4QqX3sB4NS8KFCqJ2"
    },
    "fee_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
    }
  }
}

Now the final step - time to payout the recipient!

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

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

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

HTTP Request

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

Request Arguments

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

Pull-from-Card

Step 1: Create a Sender Identity

curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u USk1k2JSKnbVz3VcGdP9RTxW:7e310227-2165-4d2a-aec6-747dd9604b91 \
    -d '
    {
        "tags": {
            "key": "value"
        },
        "entity": {
            "phone": "7145677612",
            "first_name": "Steph",
            "last_name": "Curry",
            "email": "Steph@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(IDxii7h7cMTF8QoK35pGk8Ji);
$identity = $identity->save();



from finix.resources import Identity

identity = Identity(**
    {
        "tags": {
            "key": "value"
        },
        "entity": {
            "phone": "7145677612",
            "first_name": "Steph",
            "last_name": "Curry",
            "email": "Steph@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"=> "Steph",
            "last_name"=> "Curry",
            "email"=> "Steph@gmail.com",
            "personal_address"=> {
                "city"=> "San Mateo",
                "country"=> "USA",
                "region"=> "CA",
                "line2"=> "Apartment 7",
                "line1"=> "741 Douglass St",
                "postal_code"=> "94114"
            }
        }
    }).save

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

HTTP Request

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

Request Arguments

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

Address-object Request Arguments

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

Step 2: Add a Payment Instrument for the Sender

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u USk1k2JSKnbVz3VcGdP9RTxW:7e310227-2165-4d2a-aec6-747dd9604b91 \
    -d '
    {
        "name": "Jim Sterling",
        "expiration_year": 2029,
        "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": "IDxii7h7cMTF8QoK35pGk8Ji"
    }'

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("IDcodXFEYpYHg7yukLdvWpEu")
        .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"=> "Jim Sterling",
        "expiration_year"=> 2029,
        "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"=> "IDxii7h7cMTF8QoK35pGk8Ji"
    ));
$card = $identity->createPaymentCard($card);



from finix.resources import PaymentCard

card = PaymentCard(**
    {
        "name": "Jim Sterling",
        "expiration_year": 2029,
        "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": "IDxii7h7cMTF8QoK35pGk8Ji"
    }).save()

card = Finix::PaymentCard.new(
    {
        "name"=> "Jim Sterling",
        "expiration_year"=> 2029,
        "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"=> "IDxii7h7cMTF8QoK35pGk8Ji"
    }).save

{
  "id" : "PIvkHSmEQaY8zNQiyfkq5jR4",
  "application" : "AP3sFKxrbRmnWiioKyqfRQLL",
  "fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 3,
  "expiration_year" : 2029,
  "bin" : "489514",
  "last_four" : "0006",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Jim Sterling",
  "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" : "2020-12-02T03:44:03.11Z",
  "updated_at" : "2020-12-02T03:44:03.11Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDxii7h7cMTF8QoK35pGk8Ji",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvkHSmEQaY8zNQiyfkq5jR4"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvkHSmEQaY8zNQiyfkq5jR4/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvkHSmEQaY8zNQiyfkq5jR4/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvkHSmEQaY8zNQiyfkq5jR4/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP3sFKxrbRmnWiioKyqfRQLL"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDxii7h7cMTF8QoK35pGk8Ji"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvkHSmEQaY8zNQiyfkq5jR4/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.

HTTP Request

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

Request Arguments

Field	Type	Description
identity	string, required	ID of the `Identity` that the card should be associated
type	string, required	Type of Payment Instrument (for cards input PAYMENT_CARD)
number	string, required	Primary card account number
security_code	string, optional	The 3-4 digit security code for the card (i.e. CVV code)
expiration_month	integer, required	Expiration month (e.g. 12 for December)
expiration_year	integer, required	4-digit expiration year
name	string, optional	Full name of the registered card holder
currency	string, required	3-letter ISO code designating the currency of the `Payment Instruments` (e.g. USD, CAD)
address	object, optional	Billing address (Full description of child attributes below)

Address-object Request Arguments

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

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

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

curl https://finix.sandbox-payments-api.com/payment_instruments/PIoL24d4QqX3sB4NS8KFCqJ2/verifications \
    -H "Content-Type: application/vnd.json+api" \
    -u USk1k2JSKnbVz3VcGdP9RTxW:7e310227-2165-4d2a-aec6-747dd9604b91 \
    -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("PIoL24d4QqX3sB4NS8KFCqJ2").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="PIvuHu6vbt7GsLiFp9ykpSKZ")

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

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

HTTP Request

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

URL Parameters

Parameter	Description
:PAYMENT_INSTRUMENT_ID	ID of the `Payment Instrument`

Request Arguments

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

Address Verification Results (address_verification_results)

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

Card Verification 2 Results (cvv2_result_code)

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

Card Type (card_type_code)

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

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

Fasts Funds Indicator (fast_funds_indicator)

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

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

Push Funds Indicator (push_funds_block_indicator)

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

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

Online Gambling Block Indicator (online_gambing_block_indicator)

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

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

Card Product ID (card_product_id)

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

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

Product Sub-Type (card_product_subtype)

Description of product subtype.

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

Card Sub-Type (card_subtype_code)

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

Letter	Description
N	Non-Reloadable
R	Reloadable

Step 4: Provision a Sender Account

curl https://finix.sandbox-payments-api.com/identities/IDaJoamNDjxiXLeiQZAjsPor/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u USk1k2JSKnbVz3VcGdP9RTxW:7e310227-2165-4d2a-aec6-747dd9604b91 \
    -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("IDxii7h7cMTF8QoK35pGk8Ji").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('IDxii7h7cMTF8QoK35pGk8Ji');

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



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

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

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

merchant = identity.provision_merchant

{
  "id" : "MU5DjtKye3oorkM9bQuq5zRn",
  "application" : "AP3sFKxrbRmnWiioKyqfRQLL",
  "identity" : "IDaJoamNDjxiXLeiQZAjsPor",
  "verification" : "VIwnLAmgzM3t57LQubfxjnxv",
  "merchant_profile" : "MPiE2LhdXp8DFqmAFLxsQgBk",
  "processor" : "VISA_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "card_expiration_date_required" : true,
  "card_cvv_required" : false,
  "tags" : { },
  "mcc" : null,
  "mid" : null,
  "merchant_name" : "Collen Chang",
  "created_at" : "2020-12-02T03:44:04.42Z",
  "updated_at" : "2020-12-02T03:44:04.75Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU5DjtKye3oorkM9bQuq5zRn"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDaJoamNDjxiXLeiQZAjsPor"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU5DjtKye3oorkM9bQuq5zRn/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPiE2LhdXp8DFqmAFLxsQgBk"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP3sFKxrbRmnWiioKyqfRQLL"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIwnLAmgzM3t57LQubfxjnxv"
    }
  }
}

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 USk1k2JSKnbVz3VcGdP9RTxW:7e310227-2165-4d2a-aec6-747dd9604b91 \
    -d '
    {
        "currency": "USD",
        "amount": 20000,
        "source": "PIvkHSmEQaY8zNQiyfkq5jR4",
        "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("PIoL24d4QqX3sB4NS8KFCqJ2")
        .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"=> "PIvkHSmEQaY8zNQiyfkq5jR4",
        "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": "PIvkHSmEQaY8zNQiyfkq5jR4",
        "operation_key": "PULL_FROM_CARD",
        "tags": {
            "order_number": "21DFASJSAKAS"
        }
    }).save()

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

{
  "id" : "TRm14Z1bnRk1XX3KkY1Ao8Ps",
  "amount" : 20000,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "trace_id" : "033703201999",
  "currency" : "USD",
  "application" : "AP3sFKxrbRmnWiioKyqfRQLL",
  "source" : "PIvkHSmEQaY8zNQiyfkq5jR4",
  "destination" : null,
  "ready_to_settle_at" : null,
  "fee" : 0,
  "statement_descriptor" : "FIN*FINIXPAYMENTS",
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2020-12-02T03:44:08.43Z",
  "updated_at" : "2020-12-02T03:44:09.47Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDm5kpTVnncuSGfWnPCNWqhN",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP3sFKxrbRmnWiioKyqfRQLL"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRm14Z1bnRk1XX3KkY1Ao8Ps"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDm5kpTVnncuSGfWnPCNWqhN"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRm14Z1bnRk1XX3KkY1Ao8Ps/payment_instruments"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRm14Z1bnRk1XX3KkY1Ao8Ps/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRm14Z1bnRk1XX3KkY1Ao8Ps/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRm14Z1bnRk1XX3KkY1Ao8Ps/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvkHSmEQaY8zNQiyfkq5jR4"
    },
    "fee_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
    }
  }
}

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

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

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

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

HTTP Request

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

Request Arguments

Field	Type	Description
source	string, required	ID of the `Payment Instrument` where funds will be pulled from
amount	integer, required	The total amount that will be charged in cents (e.g. 100 cents to charge $1.00)
currency	string, required	3-letter ISO code designating the currency of the `Transfers` (e.g. USD, CAD)
operation_key	string, required	PULL_FROM_CARD
tags	object, optional	Key value pair for annotating custom meta data (e.g. order numbers)
country	string, optional	3-Letter Country code. This attribute is currently only applicable for our Latin America partners.

Reverse a Pull-from-Card Transfer


curl https://finix.sandbox-payments-api.com/transfers/TRm14Z1bnRk1XX3KkY1Ao8Ps/reversals \
    -H "Content-Type: application/vnd.json+api" \
    -u  USk1k2JSKnbVz3VcGdP9RTxW:7e310227-2165-4d2a-aec6-747dd9604b91 \
    -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('TRm14Z1bnRk1XX3KkY1Ao8Ps');
$refund = $debit->reverse(11);



from finix.resources import Transfer

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

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

refund = transfer.reverse(100)

{
  "id" : "TR3hW7Hxhf9Eg54knfudjTLv",
  "amount" : 100,
  "tags" : { },
  "state" : "SUCCEEDED",
  "trace_id" : "033703202000",
  "currency" : "USD",
  "application" : "AP3sFKxrbRmnWiioKyqfRQLL",
  "source" : null,
  "destination" : "PIvkHSmEQaY8zNQiyfkq5jR4",
  "ready_to_settle_at" : null,
  "fee" : 0,
  "statement_descriptor" : "FIN*FINIXPAYMENTS",
  "type" : "REVERSAL",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2020-12-02T03:44:34.57Z",
  "updated_at" : "2020-12-02T03:44:35.39Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDm5kpTVnncuSGfWnPCNWqhN",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP3sFKxrbRmnWiioKyqfRQLL"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR3hW7Hxhf9Eg54knfudjTLv"
    },
    "parent" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRm14Z1bnRk1XX3KkY1Ao8Ps"
    },
    "destination" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvkHSmEQaY8zNQiyfkq5jR4"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDm5kpTVnncuSGfWnPCNWqhN"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR3hW7Hxhf9Eg54knfudjTLv/payment_instruments"
    },
    "fee_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
    }
  }
}

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

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

API: Transfer created via an end-user API request (e.g. POST)

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

Step 3: Define input fields and configure styling

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

DefineField Arguments

Field	Type	Description
elementId	string, required	Name of HTML id
type	string, required	API attribute name that will be sent in the payload
placeholder	string, required	What the user will see in the input field

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', APjMB6owJ7542dehJ6hCojzR, 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);

{
  "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  USk1k2JSKnbVz3VcGdP9RTxW:7e310227-2165-4d2a-aec6-747dd9604b91 \
    -d '
    {
        "token": "TK4d3gUXKi4SzRxXivrhhMQ",
        "type": "TOKEN",
        "identity": "IDcodXFEYpYHg7yukLdvWpEu"
    }'

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("TK4d3gUXKi4SzRxXivrhhMQ")
    .identity("IDcodXFEYpYHg7yukLdvWpEu")
    .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"=> "TK4d3gUXKi4SzRxXivrhhMQ",
        "type"=> "TOKEN",
        "identity"=> "IDcodXFEYpYHg7yukLdvWpEu"
    ));
$card = $card->save();



from finix.resources import PaymentInstrument

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

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

{
  "id" : "PIdsNFZrDmYwqgUz3hodHKtf",
  "application" : "APjMB6owJ7542dehJ6hCojzR",
  "fingerprint" : "FPRw9NoorETQgCjFgwKPvcGsV",
  "tags" : { },
  "expiration_month" : 12,
  "expiration_year" : 2029,
  "bin" : "495703",
  "last_four" : "0454",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : null,
  "address" : {
    "line1" : "741 Douglass St",
    "line2" : "Apartment 7",
    "city" : "San Mateo",
    "region" : "CA",
    "postal_code" : "94114",
    "country" : "USA"
  },
  "address_verification" : "UNKNOWN",
  "security_code_verification" : "UNKNOWN",
  "created_at" : "2020-12-02T03:44:40.27Z",
  "updated_at" : "2020-12-02T03:44:40.27Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDcodXFEYpYHg7yukLdvWpEu",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdsNFZrDmYwqgUz3hodHKtf"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdsNFZrDmYwqgUz3hodHKtf/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdsNFZrDmYwqgUz3hodHKtf/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdsNFZrDmYwqgUz3hodHKtf/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdsNFZrDmYwqgUz3hodHKtf/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.

Android SDK
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, APjMB6owJ7542dehJ6hCojzR);;

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

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

Card Present Integration

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

Step 1: Provision Merchant with triPOS

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

<?php

HTTP Request

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

URL Parameters

Parameter	Description
:IDENTITY_ID	ID of the `Identity`

Request Arguments

Field	Type	Description
processor	string, required	Name of the processor
gateway	string, required	Name of the gateway
tags	object, optional	Key value pair for annotating custom meta data (e.g. order numbers)

{
  "id" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "verification" : "VIhjGSJCnvXLzFQZUsUaeHxb",
  "merchant_profile" : "MPgDcdhXsdcJ9MVeJrZRNp79",
  "processor" : "VANTIV_V1",
  "processing_enabled" : false,
  "settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "tags" : { },
  "created_at" : "2019-03-01T00:49:02.47Z",
  "updated_at" : "2019-03-01T00:49:02.47Z",
  "onboarding_state" : "PROVISIONING",
  "processor_details" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPgDcdhXsdcJ9MVeJrZRNp79"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIhjGSJCnvXLzFQZUsUaeHxb"
    }
  }
}

Step 2: Create Device

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

<?php

HTTP Request

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

URL Parameters

Field	Type	Description
:MERCHANT_ID	string, required	ID of Device

Request Arguments

Field	Type	Description
model	string, required	Please select one of the following values which will let Finix know the type of device being used: MX915
name	string, required	Name of device
tags	object, optional	Key value pair for annotating custom meta data (e.g. order numbers)
description	string, optional	Additional information about device (e.g. self serving terminal)

Configuration Arguments

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

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

Step 3: Activate Device

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

<?php

HTTP Request

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

URL Parameters

Field	Type	Description
:DEVICE_ID	string, required	ID of Device

Request Arguments

Field	Type	Description
action	string, required	The action parameter must include ACTIVATE for to enable device
activation_code	string, required	Input the code that’s displayed on the device screen
tags	object, optional	Key value pair for annotating custom meta data (e.g. order numbers)

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

Step 4: Authorization with EMV card

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

<?php

HTTP Request

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

Request Arguments

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

Configuration Arguments

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

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

Step 5: Capture Authorization

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

<?php

HTTP Request

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

URL Parameters

Field	Type	Description
AUTHORIZATION_ID	string, required	ID of Device

Request Arguments

Field	Type	Description
capture_amount	integer, required	The amount of the `Authorization` you would like to capture in cents.

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

Authorizations

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

Create an Authorization

curl https://finix.sandbox-payments-api.com/authorizations \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772 \
    -d '
    {
        "source": "PIvuHu6vbt7GsLiFp9ykpSKZ",
        "merchant_identity": "IDcodXFEYpYHg7yukLdvWpEu",
        "tags": {
            "order_number": "21DFASJSAKAS"
        },
        "currency": "USD",
        "amount": 100,
        "processor": "DUMMY_V1"
    }'

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("IDcodXFEYpYHg7yukLdvWpEu")
                .source("PIvuHu6vbt7GsLiFp9ykpSKZ")
                .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(
        "source"=> "PIvuHu6vbt7GsLiFp9ykpSKZ",
        "merchant_identity"=> "IDcodXFEYpYHg7yukLdvWpEu",
        "tags"=> array(
            "order_number"=> "21DFASJSAKAS"
        ),
        "currency"=> "USD",
        "amount"=> 100,
        "processor"=> "DUMMY_V1"
    ));
$authorization = $authorization->save();



from finix.resources import Authorization

authorization = Authorization(**
    {
        "source": "PIvuHu6vbt7GsLiFp9ykpSKZ",
        "merchant_identity": "IDcodXFEYpYHg7yukLdvWpEu",
        "tags": {
            "order_number": "21DFASJSAKAS"
        },
        "currency": "USD",
        "amount": 100,
        "processor": "DUMMY_V1"
    }).save()

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

{
  "id" : "AUwwukSd7ggUPAA4Kx8XiQHd",
  "application" : "APjMB6owJ7542dehJ6hCojzR",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2020-12-02T03:44:36.19Z",
  "updated_at" : "2020-12-02T03:44:36.40Z",
  "trace_id" : "2142fa5b-5acd-4ee1-936a-f20af040e95a",
  "source" : "PIvuHu6vbt7GsLiFp9ykpSKZ",
  "merchant_identity" : "IDcodXFEYpYHg7yukLdvWpEu",
  "3ds_redirect_url" : null,
  "is_void" : false,
  "void_state" : "UNATTEMPTED",
  "expires_at" : "2020-12-09T03:44:36.19Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUwwukSd7ggUPAA4Kx8XiQHd"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
    }
  }
}

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

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

HTTP Request

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

Request Arguments

Field	Type	Description
source	string, required	The `Payment Instrument` that you will be performing the authorization
merchant_identity	string, required	The ID of the `Identity` for the merchant that you are transacting on behalf of
amount	integer, required	The amount of the authorization in cents
currency	string, required	3-letter ISO code designating the currency (e.g. USD)
processor	string, optional	If the Application has more than one processor association, it’s required to pass the processor (e.g. DUMMY_V1)
tags	object, optional	Key value pair for annotating custom meta data (e.g. order numbers)
idempotency_id	string, optional	A randomly generated value that you want associated with the request

Capture an Authorization

curl https://finix.sandbox-payments-api.com/authorizations/AUwwukSd7ggUPAA4Kx8XiQHd \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772 \
    -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("AUwwukSd7ggUPAA4Kx8XiQHd").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('AUwwukSd7ggUPAA4Kx8XiQHd');
$authorization = $authorization->capture([
                    "capture_amount"=> 50,
                    "fee"=> 10
                ]);



from finix.resources import Authorization

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

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

{
  "id" : "AUwwukSd7ggUPAA4Kx8XiQHd",
  "application" : "APjMB6owJ7542dehJ6hCojzR",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : "TR84UnScrBXRPZ78okNfJ5Us",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2020-12-02T03:44:36.19Z",
  "updated_at" : "2020-12-02T03:44:38.45Z",
  "trace_id" : "2142fa5b-5acd-4ee1-936a-f20af040e95a",
  "source" : "PIvuHu6vbt7GsLiFp9ykpSKZ",
  "merchant_identity" : "IDcodXFEYpYHg7yukLdvWpEu",
  "3ds_redirect_url" : null,
  "is_void" : false,
  "void_state" : "UNATTEMPTED",
  "expires_at" : "2020-12-09T03:44:36.19Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUwwukSd7ggUPAA4Kx8XiQHd"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
    },
    "transfer" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR84UnScrBXRPZ78okNfJ5Us"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
    }
  }
}

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

HTTP Request

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

URL Parameters

Parameter	Description
:AUTHORIZATION_ID	ID of the `Authorization`

Request Arguments

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

Void an Authorization


curl https://finix.sandbox-payments-api.com/authorizations/AUoxKdjcE6SbJLcLukocUqwV \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772 \
    -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("AUwwukSd7ggUPAA4Kx8XiQHd").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('AUwwukSd7ggUPAA4Kx8XiQHd');
$authorization->void(true);
$authorization = $authorization->save();



from finix.resources import Authorization

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

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

{
  "id" : "AUoxKdjcE6SbJLcLukocUqwV",
  "application" : "APjMB6owJ7542dehJ6hCojzR",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2020-12-02T03:44:41.00Z",
  "updated_at" : "2020-12-02T03:44:42.09Z",
  "trace_id" : "676a15d6-d52f-473d-bf0f-88e4431dc68f",
  "source" : "PIvuHu6vbt7GsLiFp9ykpSKZ",
  "merchant_identity" : "IDcodXFEYpYHg7yukLdvWpEu",
  "3ds_redirect_url" : null,
  "is_void" : true,
  "void_state" : "PENDING",
  "expires_at" : "2020-12-09T03:44:41.00Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUoxKdjcE6SbJLcLukocUqwV"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
    }
  }
}

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

HTTP Request

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

URL Parameters

Parameter	Description
:AUTHORIZATION_ID	ID of the Authorization

Request Arguments

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

[Card Present] Authorization with EMV card

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

<?php

HTTP Request

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

Request Arguments

Field	Type	Description
tags	object, optional	Key value pair for annotating custom meta data (e.g. order numbers)
device	string, required	The ID of the activated device
amount	integer, required	Amount of sale
currency	string, required	Currency of sale
operation_key	string, required	Describes the operation to be performed in the transaction
device_configuration#allow_debit	boolean, optional	Sets whether device will allow debit by default or not (defaults to true)
device_configuration#prompt_signature	string, optional	Sets whether device will prompt the card holder for a signature by default or not, AMOUNT is used in conjuction with device_configuration#signature_threshold_amount so that when the threshold is reached the signature form appears on device screen (defaults to always). Options are: ALWAYS, NEVER, AMOUNT
device_configuration#check_for_duplicate_transactions	boolean, optional	Sets whether the device will check for duplicate transactions
device_configuration#signature_threshold_amount	integer, optional	Threshold set for when to prompt a signature if device_configuration#prompt_signature is set to AMOUNT (defaults to 0)
device_configuration#prompt_manual_entry	boolean, optional	Sets whether or not the default card input method will be keyed in manual entry or not (defaults to false)

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

[Card Present] Authorization with non EMV card

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

<?php

HTTP Request

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

Request Arguments

Field	Type	Description
tags	object, optional	Key value pair for annotating custom meta data (e.g. order numbers)
device	string, required	The ID of the activated device
amount	integer, required	Amount of sale
currency	string, required	Currency of sale
operation_key	string, required	Describes the operation to be performed in the transaction
device_configuration#prompt_signature	string, optional	Sets whether device will prompt the card holder for a signature by default or not, AMOUNT is used in conjuction with device_configuration#signature_threshold_amount so that when the threshold is reached the signature form appears on device screen (defaults to always). Options are: ALWAYS, NEVER, AMOUNT
device_configuration#signature_threshold_amount	integer, optional	Threshold set for when to prompt a signature if device_configuration#prompt_signature is set to AMOUNT (defaults to 0)
device_configuration#prompt_manual_entry	boolean, optional	Sets whether or not the default card input method will be keyed in manual entry or not (defaults to false)

{
  "id" : "AUiJS1VhMy8zpACLoacPFG7m",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "amount" : 150,
  "tags" : {
    "order_number" : "chris123transfer"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "card_present_details" : {
    "emv_data" : null,
    "masked_account_number" : "************0011",
    "name" : "TEST/WORLDPAY",
    "brand" : "UNKNOWN",
    "entry_mode" : "SWIPED",
    "payment_type" : "CREDIT",
    "approval_code" : "000037"
  },
  "created_at" : "2019-03-01T03:37:10.10Z",
  "updated_at" : "2019-03-01T03:37:23.63Z",
  "trace_id" : "556185b9-ceaa-490b-bae2-a662757b42e0",
  "source" : "PIaqFoGabsBTTowVr5z7jiLv",
  "merchant_identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "device" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "is_void" : false,
  "expires_at" : "2019-03-08T03:37:10.10Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUiJS1VhMy8zpACLoacPFG7m"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "device" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR"
    }
  }
}

[Card Present] Capture Authorization

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

<?php

HTTP Request

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

URL Parameters

Field	Type	Description
AUTHORIZATION_ID	string, required	ID of Authorization

Request Arguments

Field	Type	Description
capture_amount	integer, required	The amount of the `Authorization` you would like to capture in cents.

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

Fetch an Authorization


curl https://finix.sandbox-payments-api.com/authorizations/AUwwukSd7ggUPAA4Kx8XiQHd \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772

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

Maybe <Authorization> response =  api.authorizations
    .id("AUwwukSd7ggUPAA4Kx8XiQHd")
    .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('AUwwukSd7ggUPAA4Kx8XiQHd');



from finix.resources import Authorization

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

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

{
  "id" : "AUwwukSd7ggUPAA4Kx8XiQHd",
  "application" : "APjMB6owJ7542dehJ6hCojzR",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : "TR84UnScrBXRPZ78okNfJ5Us",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2020-12-02T03:44:36.19Z",
  "updated_at" : "2020-12-02T03:44:38.45Z",
  "trace_id" : "2142fa5b-5acd-4ee1-936a-f20af040e95a",
  "source" : "PIvuHu6vbt7GsLiFp9ykpSKZ",
  "merchant_identity" : "IDcodXFEYpYHg7yukLdvWpEu",
  "3ds_redirect_url" : null,
  "is_void" : false,
  "void_state" : "UNATTEMPTED",
  "expires_at" : "2020-12-09T03:44:36.19Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUwwukSd7ggUPAA4Kx8XiQHd"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
    },
    "transfer" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR84UnScrBXRPZ78okNfJ5Us"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
    }
  }
}

Fetch a previously created Authorization.

HTTP Request

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

URL Parameters

Parameter	Description
:AUTHORIZATION_ID	ID of the Authorization

List All Authorizations

curl https://finix.sandbox-payments-api.com/authorizations/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772

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

{
  "_embedded" : {
    "authorizations" : [ {
      "id" : "AUoxKdjcE6SbJLcLukocUqwV",
      "application" : "APjMB6owJ7542dehJ6hCojzR",
      "amount" : 100,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : null,
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2020-12-02T03:44:41.00Z",
      "updated_at" : "2020-12-02T03:44:42.09Z",
      "trace_id" : "676a15d6-d52f-473d-bf0f-88e4431dc68f",
      "source" : "PIvuHu6vbt7GsLiFp9ykpSKZ",
      "merchant_identity" : "IDcodXFEYpYHg7yukLdvWpEu",
      "3ds_redirect_url" : null,
      "is_void" : true,
      "void_state" : "PENDING",
      "expires_at" : "2020-12-09T03:44:41.00Z",
      "idempotency_id" : null,
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations/AUoxKdjcE6SbJLcLukocUqwV"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
        }
      }
    }, {
      "id" : "AU3azy8k6CLqd7cZDsuzXST8",
      "application" : "APjMB6owJ7542dehJ6hCojzR",
      "amount" : 100,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : null,
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2020-12-02T03:44:37.40Z",
      "updated_at" : "2020-12-02T03:44:37.55Z",
      "trace_id" : "878638f9-27c6-4192-8e02-70f47cc57a09",
      "source" : "PIvuHu6vbt7GsLiFp9ykpSKZ",
      "merchant_identity" : "IDcodXFEYpYHg7yukLdvWpEu",
      "3ds_redirect_url" : null,
      "is_void" : false,
      "void_state" : "UNATTEMPTED",
      "expires_at" : "2020-12-09T03:44:37.40Z",
      "idempotency_id" : "80513308f03d459cadfa9c0e46b5b248",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations/AU3azy8k6CLqd7cZDsuzXST8"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
        }
      }
    }, {
      "id" : "AUwwukSd7ggUPAA4Kx8XiQHd",
      "application" : "APjMB6owJ7542dehJ6hCojzR",
      "amount" : 100,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : "TR84UnScrBXRPZ78okNfJ5Us",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2020-12-02T03:44:36.19Z",
      "updated_at" : "2020-12-02T03:44:38.45Z",
      "trace_id" : "2142fa5b-5acd-4ee1-936a-f20af040e95a",
      "source" : "PIvuHu6vbt7GsLiFp9ykpSKZ",
      "merchant_identity" : "IDcodXFEYpYHg7yukLdvWpEu",
      "3ds_redirect_url" : null,
      "is_void" : false,
      "void_state" : "UNATTEMPTED",
      "expires_at" : "2020-12-09T03:44:36.19Z",
      "idempotency_id" : null,
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations/AUwwukSd7ggUPAA4Kx8XiQHd"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
        },
        "transfer" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR84UnScrBXRPZ78okNfJ5Us"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
        }
      }
    } ]
  },
  "_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
  }
}

List all Authorizations.

HTTP Request

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

Devices

A Device resource represents a card present terminal.

Create Device

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

<?php

HTTP Request

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

URL Parameters

Field	Type	Description
:MERCHANT_ID	string, required	ID of Merchant

Request Arguments

Field	Type	Description
model	string, required	Please select one of the following values which will let Finix know the type of device being used: BBPOS, MX915, MX925, IPP320, IPP350, ISC250, ISC480, ISMP4, LANE_3000, and ANDROID
name	string, required	Name of device
tags	object, optional	Key value pair for annotating custom meta data (e.g. order numbers)
description	string, optional	Additional information about device (e.g. self serving terminal)

Configuration Arguments

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

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

Activate Device

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

<?php

HTTP Request

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

URL Parameters

Field	Type	Description
:DEVICE_ID	string, required	ID of Device

Request Arguments

Field	Type	Description
activation_code	string, required	Input the code thats show up on the device screen
action	string, required	The action parameter must include ACTIVATE for to enable device
tags	object, optional	Key value pair for annotating custom meta data (e.g. order numbers)

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

Fetch Device

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

<?php

HTTP Request

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

URL Parameters

Field	Type	Description
:DEVICE_ID	string, required	ID of Device

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

Reboot Device

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

<?php

HTTP Request

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

URL Parameters

Field	Type	Description
:DEVICE_ID	string, required	ID of Device

Request Arguments

Field	Type	Description
action	string, required	The action parameter must include REBOOT to reboot the device

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

Set Idle Message on Device

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

<?php

HTTP Request

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

URL Parameters

Field	Type	Description
:DEVICE_ID	string, required	ID of Device

Request Arguments

Field	Type	Description
idle_message	string, required	ID of Device
action	string, required	The action parameter must include CREATE_IDLE_MESSAGE to create an idle message

{
  "id" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "name" : "Finix Tripos #1",
  "model" : "MX915",
  "description" : "Mike Jones",
  "serial_number" : "262-410-025",
  "idle_message" : "Michaels Juice Shop",
  "enabled" : true,
  "tags" : { },
  "created_at" : "2019-03-01T02:27:20.366",
  "updated_at" : "2019-03-11T23:19:44.399",
  "configuration_details" : {
    "allow_debit" : true,
    "check_for_duplicate_transactions" : true,
    "prompt_amount_confirmation" : true,
    "prompt_manual_entry" : false,
    "prompt_signature" : "NEVER",
    "signature_threshold_amount" : 0
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations"
    }
  }
}

Check Connectivity of Device

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

<?php

HTTP Request

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

URL Parameters

Field	Type	Description
DEVICE_ID	string, required	ID of Device

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

Deactivate Device

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

<?php

HTTP Request

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

URL Parameters

Field	Type	Description
:DEVICE_ID	string, required	ID of Device

Request Arguments

Field	Type	Description
action	string, required	The action parameter must include DEACTIVATE to deactivate the device

    {
      "id" : "DVf2H8sh4LZZC52GTUrwCPPf",
      "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
      "name" : "Finix Tripos #1",
      "model" : "MX915",
      "description" : "Mike Jones",
      "serial_number" : null,
      "idle_message" : null,
      "enabled" : false,
      "tags" : { },
      "created_at" : "2019-03-01T02:27:20.366",
      "updated_at" : "2019-03-11T23:30:05.816",
      "configuration_details" : null,
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
        },
        "merchant" : {
          "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations"
        }
      }
    }

Disputes

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

Upload Dispute Evidence

curl https://finix.sandbox-payments-api.com/disputes/DI7hjyp3P6BHV7RPwG7Ej6Yw/evidence \
    -H "Content-Type: application/pdf/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772 \
    -F 'data=@path/to/local/file' testfile.pdf

<?php


    {
        "tags": {
            "content-type": "application/pdf",
            "file-extension": ".pdf",
            "file-name": "testfile.pdf"
        },
        "created_at": "2020-12-02T04:01:03.24Z",
        "updated_at": "2020-12-02T04:01:03.24Z",
        "state": "PENDING",
        "_links": {
            "self": {
                "href": "https://finix.sandbox-payments-api.com/disputes/DI7hjyp3P6BHV7RPwG7Ej6Yw/evidence/DFtNpRaueUgs6ZwPcunUmtaq"
            }
        },
        "id": "DFtNpRaueUgs6ZwPcunUmtaq",
        "dispute": "DI7hjyp3P6BHV7RPwG7Ej6Yw"
    }

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

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

PENDING: The evidence file has not yet been submitted to the Processor. No user action is required.
SUCCEEDED: The evidence file has been successfully sent to the Processor. No further user action is required.
CANCELED: The evidence file upload was not completed due to user action.
FAILED: An issue occurred. User action is required. Any of the following issues could have occurred:
- There was an error in the system and the user should retry uploading their evidence file.
- There is an issue with the file and the user should retry uploading a different file.
- There is an issue and the user should contact Support.

HTTP Request

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

Fetch a Dispute


curl https://finix.sandbox-payments-api.com/disputes/DI7hjyp3P6BHV7RPwG7Ej6Yw \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772


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

Dispute dispute = transfer.disputeClient().fetch("DI7hjyp3P6BHV7RPwG7Ej6Yw");

<?php
use Finix\Resources\Dispute;

$dispute = Dispute::retrieve('DI7hjyp3P6BHV7RPwG7Ej6Yw');



from finix.resources import Dispute
dispute = Dispute.get(id="DI7hjyp3P6BHV7RPwG7Ej6Yw")

disputes = Finix::Dispute.retrieve(:id => "DI7hjyp3P6BHV7RPwG7Ej6Yw")

{
  "id" : "DI7hjyp3P6BHV7RPwG7Ej6Yw",
  "application" : "APjMB6owJ7542dehJ6hCojzR",
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "amount" : 888888,
  "state" : "PENDING",
  "transfer" : "TRjF8AoYtFryT3CoWwVoU96p",
  "reason" : "FRAUD",
  "message" : null,
  "action" : null,
  "identity" : "IDcodXFEYpYHg7yukLdvWpEu",
  "created_at" : "2020-12-02T03:51:02.16Z",
  "updated_at" : "2020-12-02T03:51:01.67Z",
  "occurred_at" : "2020-12-02T03:50:59.91Z",
  "respond_by" : "2020-12-09T03:51:02.14Z",
  "dispute_details" : {
    "arn" : "123"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes/DI7hjyp3P6BHV7RPwG7Ej6Yw"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
    },
    "transfer" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRjF8AoYtFryT3CoWwVoU96p"
    },
    "evidence" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes/DI7hjyp3P6BHV7RPwG7Ej6Yw/evidence"
    },
    "adjustment_transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes/DI7hjyp3P6BHV7RPwG7Ej6Yw/adjustment_transfers"
    }
  }
}

Fetch a previously created Dispute.

HTTP Request

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

URL Parameters

Parameter	Description
:DISPUTE_ID	ID of the `Dispute`

Response

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

List All Disputes

curl https://finix.sandbox-payments-api.com/disputes/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772

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

transfer.disputeClient().<Resources<Dispute>>resourcesIterator()
  .forEachRemaining(page -> {
    Collection<Dispute> disputes = page.getContent();
  })

<?php



from finix.resources import Dispute
dispute = Dispute.get()

disputes = Finix::Dispute.retrieve

{
  "_embedded" : {
    "disputes" : [ {
      "id" : "DI7hjyp3P6BHV7RPwG7Ej6Yw",
      "application" : "APjMB6owJ7542dehJ6hCojzR",
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "amount" : 888888,
      "state" : "PENDING",
      "transfer" : "TRjF8AoYtFryT3CoWwVoU96p",
      "reason" : "FRAUD",
      "message" : null,
      "action" : null,
      "identity" : "IDcodXFEYpYHg7yukLdvWpEu",
      "created_at" : "2020-12-02T03:51:02.16Z",
      "updated_at" : "2020-12-02T03:51:01.67Z",
      "occurred_at" : "2020-12-02T03:50:59.91Z",
      "respond_by" : "2020-12-09T03:51:02.14Z",
      "dispute_details" : {
        "arn" : "123"
      },
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/disputes/DI7hjyp3P6BHV7RPwG7Ej6Yw"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
        },
        "transfer" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRjF8AoYtFryT3CoWwVoU96p"
        },
        "evidence" : {
          "href" : "https://finix.sandbox-payments-api.com/disputes/DI7hjyp3P6BHV7RPwG7Ej6Yw/evidence"
        },
        "adjustment_transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/disputes/DI7hjyp3P6BHV7RPwG7Ej6Yw/adjustment_transfers"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 1
  }
}

List all Disputes.

HTTP Request

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

Response

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

Fetch Dispute Adjustment Transfers


curl https://finix.sandbox-payments-api.com/disputes/DI7hjyp3P6BHV7RPwG7Ej6Yw/adjustment_transfers \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772

<?php

{
  "_embedded" : {
    "transfers" : [ {
      "id" : "TRgVrSMpj6Xq61pgxpgajAaS",
      "amount" : 888888,
      "tags" : { },
      "state" : "SUCCEEDED",
      "trace_id" : "8f9eb656-dfd5-42cb-a615-0dd8868fb1d9",
      "currency" : "USD",
      "application" : "APjMB6owJ7542dehJ6hCojzR",
      "source" : null,
      "destination" : null,
      "ready_to_settle_at" : "2020-12-02T03:51:02.48Z",
      "fee" : 0,
      "statement_descriptor" : null,
      "type" : "DISPUTE",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2020-12-02T03:51:02.52Z",
      "updated_at" : "2020-12-02T03:51:01.67Z",
      "idempotency_id" : null,
      "merchant_identity" : "ID8bW3W9DmKEgFYF4GfDJ8or",
      "subtype" : "PLATFORM_CREDIT",
      "_links" : {
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
        },
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRgVrSMpj6Xq61pgxpgajAaS"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID8bW3W9DmKEgFYF4GfDJ8or"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRgVrSMpj6Xq61pgxpgajAaS/payment_instruments"
        },
        "disputed_transfer" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRgVrSMpj6Xq61pgxpgajAaS/disputed_transfer"
        },
        "fee_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPfwg4Zm1sVSiuMYJGRWiRxv"
        }
      }
    }, {
      "id" : "TR4FDo84y6iqvqY7BeNdhGkF",
      "amount" : 888888,
      "tags" : { },
      "state" : "SUCCEEDED",
      "trace_id" : "3376cbce-5243-491e-bd73-e98c03a962a1",
      "currency" : "USD",
      "application" : "APjMB6owJ7542dehJ6hCojzR",
      "source" : null,
      "destination" : "PIvuHu6vbt7GsLiFp9ykpSKZ",
      "ready_to_settle_at" : "2020-12-02T03:51:02.20Z",
      "fee" : 0,
      "statement_descriptor" : null,
      "type" : "DISPUTE",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2020-12-02T03:51:02.24Z",
      "updated_at" : "2020-12-02T03:51:01.67Z",
      "idempotency_id" : null,
      "merchant_identity" : "IDcodXFEYpYHg7yukLdvWpEu",
      "subtype" : "MERCHANT_DEBIT",
      "_links" : {
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
        },
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR4FDo84y6iqvqY7BeNdhGkF"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR4FDo84y6iqvqY7BeNdhGkF/payment_instruments"
        },
        "disputed_transfer" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR4FDo84y6iqvqY7BeNdhGkF/disputed_transfer"
        },
        "destination" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvuHu6vbt7GsLiFp9ykpSKZ"
        },
        "fee_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPszGRodkSNysAthUvDyqDUp"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes/DI7hjyp3P6BHV7RPwG7Ej6Yw/adjustment_transfers?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 2
  }
}

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

HTTP Request

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

URL Parameters

Parameter	Description
:DISPUTE_ID	ID of the `Dispute`

Response

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

Fetch a Dispute Evidence File


curl https://finix.sandbox-payments-api.com/disputes/DI7hjyp3P6BHV7RPwG7Ej6Yw/evidence/DFtNpRaueUgs6ZwPcunUmtaq \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772

<?php

{
  "id" : "DFtNpRaueUgs6ZwPcunUmtaq",
  "tags" : {
    "file-extension" : ".pdf",
    "content-type" : "application/pdf",
    "file-name" : "testfile.pdf"
  },
  "dispute" : "DI7hjyp3P6BHV7RPwG7Ej6Yw",
  "state" : "PENDING",
  "created_at" : "2020-12-02T04:01:03.24Z",
  "updated_at" : "2020-12-02T04:01:02.72Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes/DI7hjyp3P6BHV7RPwG7Ej6Yw/evidence/DFtNpRaueUgs6ZwPcunUmtaq"
    }
  }
}

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

HTTP Request

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

URL Parameters

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

Response

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

List Dispute Evidence Files


curl https://finix.sandbox-payments-api.com/disputes/DI7hjyp3P6BHV7RPwG7Ej6Yw/evidence \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772

<?php

{
  "_embedded" : {
    "evidences" : [ {
      "id" : "DFtNpRaueUgs6ZwPcunUmtaq",
      "tags" : {
        "file-extension" : ".pdf",
        "content-type" : "application/pdf",
        "file-name" : "testfile.pdf"
      },
      "dispute" : "DI7hjyp3P6BHV7RPwG7Ej6Yw",
      "state" : "PENDING",
      "created_at" : "2020-12-02T04:01:03.24Z",
      "updated_at" : "2020-12-02T04:01:02.72Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/disputes/DI7hjyp3P6BHV7RPwG7Ej6Yw/evidence/DFtNpRaueUgs6ZwPcunUmtaq"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes/DI7hjyp3P6BHV7RPwG7Ej6Yw/evidence?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 1
  }
}

List all uploaded Dispute evidence files.

HTTP Request

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

URL Parameters

Parameter	Description
:DISPUTE_ID	ID of the `Dispute`

Response

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

Identities

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

Create an Identity for a Buyer



curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772 \
    -d '
    {
        "tags": {
            "key": "value"
        },
        "entity": {
            "phone": "7145677613",
            "first_name": "Bob",
            "last_name": "Diaz",
            "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"=> "Bob",
            "last_name"=> "Diaz",
            "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": "Bob",
            "last_name": "Diaz",
            "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"=> "Bob",
            "last_name"=> "Diaz",
            "email"=> "therock@gmail.com",
            "personal_address"=> {
                "city"=> "San Mateo",
                "country"=> "USA",
                "region"=> "CA",
                "line2"=> "Apartment 7",
                "line1"=> "741 Douglass St",
                "postal_code"=> "94114"
            }
        }
    }).save

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

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

HTTP Request

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

Request Arguments

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

Create an Identity for a Merchant

curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772 \
    -d '
    {
        "tags": {
            "Studio Rating": "4.7"
        },
        "entity": {
            "last_name": "Sunkhronos",
            "max_transaction_amount": 12000000,
            "has_accepted_credit_cards_previously": true,
            "default_statement_descriptor": "Pollos Hermanos",
            "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": "Pollos Hermanos",
            "principal_percentage_ownership": 50,
            "email": "user@example.org",
            "mcc": "0742",
            "phone": "1234567890",
            "business_name": "Pollos Hermanos",
            "tax_id": "123456789",
            "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone": "+1 (408) 756-4497",
            "dob": {
                "year": 1978,
                "day": 27,
                "month": 6
            },
            "url": "www.PollosHermanos.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"=> "Pollos Hermanos",
            "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"=> "Pollos Hermanos",
            "principal_percentage_ownership"=> 50,
            "email"=> "user@example.org",
            "mcc"=> "0742",
            "phone"=> "1234567890",
            "business_name"=> "Pollos Hermanos",
            "tax_id"=> "123456789",
            "business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone"=> "+1 (408) 756-4497",
            "dob"=> array(
                "year"=> 1978,
                "day"=> 27,
                "month"=> 6
            ),
            "url"=> "www.PollosHermanos.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": "Pollos Hermanos",
            "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": "Pollos Hermanos",
            "principal_percentage_ownership": 50,
            "email": "user@example.org",
            "mcc": "0742",
            "phone": "1234567890",
            "business_name": "Pollos Hermanos",
            "tax_id": "123456789",
            "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone": "+1 (408) 756-4497",
            "dob": {
                "year": 1978,
                "day": 27,
                "month": 6
            },
            "url": "www.PollosHermanos.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"=> "Pollos Hermanos",
            "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"=> "Pollos Hermanos",
            "principal_percentage_ownership"=> 50,
            "email"=> "user@example.org",
            "mcc"=> "0742",
            "phone"=> "1234567890",
            "business_name"=> "Pollos Hermanos",
            "tax_id"=> "123456789",
            "business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone"=> "+1 (408) 756-4497",
            "dob"=> {
                "year"=> 1978,
                "day"=> 27,
                "month"=> 6
            },
            "url"=> "www.PollosHermanos.com",
            "annual_card_volume"=> 12000000
        }
    }).save

{
  "id" : "IDcodXFEYpYHg7yukLdvWpEu",
  "application" : "APjMB6owJ7542dehJ6hCojzR",
  "entity" : {
    "title" : "CEO",
    "first_name" : "dwayne",
    "last_name" : "Sunkhronos",
    "email" : "user@example.org",
    "business_name" : "Pollos Hermanos",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "Pollos Hermanos",
    "phone" : "1234567890",
    "business_phone" : "+1 (408) 756-4497",
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 8",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "mcc" : "0742",
    "dob" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "max_transaction_amount" : 12000000,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : "www.PollosHermanos.com",
    "annual_card_volume" : 12000000,
    "has_accepted_credit_cards_previously" : true,
    "incorporation_date" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "principal_percentage_ownership" : 50,
    "short_business_name" : null,
    "ownership_type" : "PRIVATE",
    "tax_authority" : null,
    "tax_id_provided" : true,
    "business_tax_id_provided" : true,
    "default_statement_descriptor" : "Pollos Hermanos"
  },
  "tags" : {
    "Studio Rating" : "4.7"
  },
  "created_at" : "2020-12-02T03:44:11.34Z",
  "updated_at" : "2020-12-02T03:44:11.34Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
    }
  }
}

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
amex_mid	integer, optional	Assigned AMEX MID value. If provided must be 10 or 11 digits
business_address	object, required	Primary address for the legal entity (Full description of child attributes below)
business_name	string, required	Merchant’s full legal business name (If INDIVIDUAL_SOLE_PROPRIETORSHIP, please input first name, Full legal last name and middle initial; max 120 characters)
business_phone	string, required	Customer service phone number where the merchant can be reached (max 10 characters)
business_tax_id	string, required	Nine digit Tax Identification Number (TIN), Employer Identification Number (EIN) or if the business_type is INDIVIDUAL_SOLE_PROPRIETORSHIP and a Tax ID is not available, the principal’s Social Security Number (SSN)
business_type	string, required	Please select one of the following values: INDIVIDUAL_SOLE_PROPRIETORSHIP, CORPORATION, LIMITED_LIABILITY_COMPANY, PARTNERSHIP, ASSOCIATION_ESTATE_TRUST, TAX_EXEMPT_ORGANIZATION, INTERNATIONAL_ORGANIZATION, GOVERNMENT_AGENCY
discover_mid	integer, optional	Assigned Discover MID value
doing_business_as	string, required	Alternate name of the business. If no other name is used please use the same value for business_name (max 60 characters)
incorporation_date	object, required	Date company was founded (See below for a full list of the child attributes)
ownership_type	string, required	Values can be either PUBLIC to indicate a publicly traded company or PRIVATE for privately held businesses
tax_authority	string, optional	Field is required when onboarding a Merchant with a MCC of 9311 (e.g San Francisco Water Authority)
url	string, required	Merchant’s publicly available website (max 100 characters)

Principal-specific Request Arguments

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

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

Processing-specific Request Arguments

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

Address-object Request Arguments

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

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 an Identity


curl https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772

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("IDcodXFEYpYHg7yukLdvWpEu").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('IDcodXFEYpYHg7yukLdvWpEu');



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

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

{
  "id" : "IDcodXFEYpYHg7yukLdvWpEu",
  "application" : "APjMB6owJ7542dehJ6hCojzR",
  "entity" : {
    "title" : "CEO",
    "first_name" : "dwayne",
    "last_name" : "Sunkhronos",
    "email" : "user@example.org",
    "business_name" : "Pollos Hermanos",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "Pollos Hermanos",
    "phone" : "1234567890",
    "business_phone" : "+1 (408) 756-4497",
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 8",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "mcc" : "0742",
    "dob" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "max_transaction_amount" : 12000000,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : "www.PollosHermanos.com",
    "annual_card_volume" : 12000000,
    "has_accepted_credit_cards_previously" : true,
    "incorporation_date" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "principal_percentage_ownership" : 50,
    "short_business_name" : null,
    "ownership_type" : "PRIVATE",
    "tax_authority" : null,
    "tax_id_provided" : true,
    "business_tax_id_provided" : true,
    "default_statement_descriptor" : "Pollos Hermanos"
  },
  "tags" : {
    "Studio Rating" : "4.7"
  },
  "created_at" : "2020-12-02T03:44:11.34Z",
  "updated_at" : "2020-12-02T03:44:11.17Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
    }
  }
}

Fetch a previously created Identity.

HTTP Request

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

URL Parameters

Parameter	Description
:IDENTITY_ID	ID of the Identity

List All Identities

curl https://finix.sandbox-payments-api.com/identities/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772

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

{
  "_embedded" : {
    "identities" : [ {
      "id" : "IDnWqm9V6QiUJbsnEK7dtUCf",
      "application" : "APjMB6owJ7542dehJ6hCojzR",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Petes Coffee",
        "business_type" : "CORPORATION",
        "doing_business_as" : "Petes Coffee",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.PetesCoffee.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Petes Coffee"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2020-12-02T03:44:20.88Z",
      "updated_at" : "2020-12-02T03:44:20.74Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnWqm9V6QiUJbsnEK7dtUCf"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnWqm9V6QiUJbsnEK7dtUCf/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnWqm9V6QiUJbsnEK7dtUCf/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnWqm9V6QiUJbsnEK7dtUCf/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnWqm9V6QiUJbsnEK7dtUCf/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnWqm9V6QiUJbsnEK7dtUCf/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnWqm9V6QiUJbsnEK7dtUCf/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnWqm9V6QiUJbsnEK7dtUCf/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDnWqm9V6QiUJbsnEK7dtUCf/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
        }
      }
    }, {
      "id" : "ID7XejJuLbxqZ3yknbwyXpPg",
      "application" : "APjMB6owJ7542dehJ6hCojzR",
      "entity" : {
        "title" : null,
        "first_name" : "Bob",
        "last_name" : "Diaz",
        "email" : "therock@gmail.com",
        "business_name" : null,
        "business_type" : null,
        "doing_business_as" : null,
        "phone" : "7145677613",
        "business_phone" : null,
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : null,
        "mcc" : null,
        "dob" : null,
        "max_transaction_amount" : 0,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : null,
        "annual_card_volume" : 0,
        "has_accepted_credit_cards_previously" : false,
        "incorporation_date" : null,
        "principal_percentage_ownership" : null,
        "short_business_name" : null,
        "ownership_type" : null,
        "tax_authority" : null,
        "tax_id_provided" : false,
        "business_tax_id_provided" : false,
        "default_statement_descriptor" : null
      },
      "tags" : {
        "key" : "value"
      },
      "created_at" : "2020-12-02T03:44:18.98Z",
      "updated_at" : "2020-12-02T03:44:18.87Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7XejJuLbxqZ3yknbwyXpPg"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7XejJuLbxqZ3yknbwyXpPg/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7XejJuLbxqZ3yknbwyXpPg/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7XejJuLbxqZ3yknbwyXpPg/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7XejJuLbxqZ3yknbwyXpPg/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7XejJuLbxqZ3yknbwyXpPg/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7XejJuLbxqZ3yknbwyXpPg/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7XejJuLbxqZ3yknbwyXpPg/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7XejJuLbxqZ3yknbwyXpPg/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
        }
      }
    }, {
      "id" : "IDgqYeE2zKUGwGuxURk9X7zP",
      "application" : "APjMB6owJ7542dehJ6hCojzR",
      "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_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Prestige World Wide"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2020-12-02T03:44:15.12Z",
      "updated_at" : "2020-12-02T03:44:14.99Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgqYeE2zKUGwGuxURk9X7zP"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgqYeE2zKUGwGuxURk9X7zP/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgqYeE2zKUGwGuxURk9X7zP/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgqYeE2zKUGwGuxURk9X7zP/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgqYeE2zKUGwGuxURk9X7zP/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgqYeE2zKUGwGuxURk9X7zP/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgqYeE2zKUGwGuxURk9X7zP/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgqYeE2zKUGwGuxURk9X7zP/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgqYeE2zKUGwGuxURk9X7zP/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
        }
      }
    }, {
      "id" : "IDmvzfEkeZ6z74xkZNa3tUzA",
      "application" : "APjMB6owJ7542dehJ6hCojzR",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Prestige World Wide",
        "business_type" : "INTERNATIONAL_ORGANIZATION",
        "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" : "PRIVATE",
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Prestige World Wide"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2020-12-02T03:44:14.55Z",
      "updated_at" : "2020-12-02T03:44:14.43Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmvzfEkeZ6z74xkZNa3tUzA"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmvzfEkeZ6z74xkZNa3tUzA/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmvzfEkeZ6z74xkZNa3tUzA/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmvzfEkeZ6z74xkZNa3tUzA/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmvzfEkeZ6z74xkZNa3tUzA/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmvzfEkeZ6z74xkZNa3tUzA/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmvzfEkeZ6z74xkZNa3tUzA/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmvzfEkeZ6z74xkZNa3tUzA/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmvzfEkeZ6z74xkZNa3tUzA/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
        }
      }
    }, {
      "id" : "IDon1JnsVKZTtw2T6gJsSYeK",
      "application" : "APjMB6owJ7542dehJ6hCojzR",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Lees Sandwiches",
        "business_type" : "TAX_EXEMPT_ORGANIZATION",
        "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" : "PUBLIC",
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Lees Sandwiches"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2020-12-02T03:44:13.93Z",
      "updated_at" : "2020-12-02T03:44:13.79Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDon1JnsVKZTtw2T6gJsSYeK"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDon1JnsVKZTtw2T6gJsSYeK/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDon1JnsVKZTtw2T6gJsSYeK/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDon1JnsVKZTtw2T6gJsSYeK/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDon1JnsVKZTtw2T6gJsSYeK/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDon1JnsVKZTtw2T6gJsSYeK/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDon1JnsVKZTtw2T6gJsSYeK/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDon1JnsVKZTtw2T6gJsSYeK/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDon1JnsVKZTtw2T6gJsSYeK/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
        }
      }
    }, {
      "id" : "IDirQAMoLmagaJkqPHKVoAJh",
      "application" : "APjMB6owJ7542dehJ6hCojzR",
      "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_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Bobs Burgers"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2020-12-02T03:44:13.22Z",
      "updated_at" : "2020-12-02T03:44:13.04Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDirQAMoLmagaJkqPHKVoAJh"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDirQAMoLmagaJkqPHKVoAJh/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDirQAMoLmagaJkqPHKVoAJh/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDirQAMoLmagaJkqPHKVoAJh/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDirQAMoLmagaJkqPHKVoAJh/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDirQAMoLmagaJkqPHKVoAJh/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDirQAMoLmagaJkqPHKVoAJh/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDirQAMoLmagaJkqPHKVoAJh/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDirQAMoLmagaJkqPHKVoAJh/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
        }
      }
    }, {
      "id" : "IDwF84chRCJfgkVT3p4wT55Z",
      "application" : "APjMB6owJ7542dehJ6hCojzR",
      "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_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Golds Gym"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2020-12-02T03:44:12.53Z",
      "updated_at" : "2020-12-02T03:44:12.40Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDwF84chRCJfgkVT3p4wT55Z"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDwF84chRCJfgkVT3p4wT55Z/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDwF84chRCJfgkVT3p4wT55Z/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDwF84chRCJfgkVT3p4wT55Z/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDwF84chRCJfgkVT3p4wT55Z/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDwF84chRCJfgkVT3p4wT55Z/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDwF84chRCJfgkVT3p4wT55Z/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDwF84chRCJfgkVT3p4wT55Z/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDwF84chRCJfgkVT3p4wT55Z/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
        }
      }
    }, {
      "id" : "ID5WLh8m9GkhB7ocYz7RoUeC",
      "application" : "APjMB6owJ7542dehJ6hCojzR",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Prestige World Wide",
        "business_type" : "LIMITED_LIABILITY_COMPANY",
        "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" : "PRIVATE",
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Prestige World Wide"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2020-12-02T03:44:11.94Z",
      "updated_at" : "2020-12-02T03:44:11.81Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID5WLh8m9GkhB7ocYz7RoUeC"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID5WLh8m9GkhB7ocYz7RoUeC/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID5WLh8m9GkhB7ocYz7RoUeC/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID5WLh8m9GkhB7ocYz7RoUeC/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID5WLh8m9GkhB7ocYz7RoUeC/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID5WLh8m9GkhB7ocYz7RoUeC/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID5WLh8m9GkhB7ocYz7RoUeC/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID5WLh8m9GkhB7ocYz7RoUeC/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID5WLh8m9GkhB7ocYz7RoUeC/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
        }
      }
    }, {
      "id" : "IDcodXFEYpYHg7yukLdvWpEu",
      "application" : "APjMB6owJ7542dehJ6hCojzR",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Pollos Hermanos",
        "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
        "doing_business_as" : "Pollos Hermanos",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.PollosHermanos.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Pollos Hermanos"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2020-12-02T03:44:11.34Z",
      "updated_at" : "2020-12-02T03:44:11.17Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
        }
      }
    }, {
      "id" : "IDco4UUhtNVU2A6Vs8HkRXGk",
      "application" : "APjMB6owJ7542dehJ6hCojzR",
      "entity" : {
        "title" : null,
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Square",
        "business_type" : "LIMITED_LIABILITY_COMPANY",
        "doing_business_as" : "Square",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : null,
        "dob" : {
          "day" : 27,
          "month" : 5,
          "year" : 1978
        },
        "max_transaction_amount" : 1200000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : null,
        "annual_card_volume" : 0,
        "has_accepted_credit_cards_previously" : false,
        "incorporation_date" : null,
        "principal_percentage_ownership" : null,
        "short_business_name" : null,
        "ownership_type" : null,
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : null
      },
      "tags" : {
        "application_name" : "Square"
      },
      "created_at" : "2020-12-02T03:43:49.20Z",
      "updated_at" : "2020-12-02T03:43:49.26Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDco4UUhtNVU2A6Vs8HkRXGk"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDco4UUhtNVU2A6Vs8HkRXGk/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDco4UUhtNVU2A6Vs8HkRXGk/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDco4UUhtNVU2A6Vs8HkRXGk/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDco4UUhtNVU2A6Vs8HkRXGk/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDco4UUhtNVU2A6Vs8HkRXGk/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDco4UUhtNVU2A6Vs8HkRXGk/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDco4UUhtNVU2A6Vs8HkRXGk/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDco4UUhtNVU2A6Vs8HkRXGk/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
        }
      }
    } ]
  },
  "_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
  }
}

List all Identities.

HTTP Request

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

Update an Identity

curl https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772 \
    -X PUT \
    -d '
    {
        "tags": {
            "key": "value_2"
        },
        "entity": {
            "business_phone": "+1 (408) 756-4497",
            "first_name": "Bernard",
            "last_name": "White",
            "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": "Golds Gym",
            "annual_card_volume": 12000000,
            "default_statement_descriptor": "Golds Gym",
            "url": "www.GoldsGym.com",
            "business_name": "Golds Gym",
            "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("IDcodXFEYpYHg7yukLdvWpEu").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="IDcodXFEYpYHg7yukLdvWpEu")
identity.entity["first_name"] = "Bernard"
identity.save()

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

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

{
  "id" : "IDcodXFEYpYHg7yukLdvWpEu",
  "application" : "APjMB6owJ7542dehJ6hCojzR",
  "entity" : {
    "title" : "CTO",
    "first_name" : "Bernard",
    "last_name" : "White",
    "email" : "user@example.org",
    "business_name" : "Golds Gym",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "Golds Gym",
    "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.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_authority" : null,
    "tax_id_provided" : true,
    "business_tax_id_provided" : true,
    "default_statement_descriptor" : "Golds Gym"
  },
  "tags" : {
    "key" : "value_2"
  },
  "created_at" : "2020-12-02T03:44:11.34Z",
  "updated_at" : "2020-12-02T03:50:57.09Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
    }
  }
}

Update the information of a previously created Identity. In the case of Merchant accounts, this API request does not update this information on the underlying processor. To update the Merchant’s information on the underlying processor, you must update the Merchant on the processor.

HTTP Request

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

Business-specific Request Arguments

Field	Type	Description
business_address	object, required	Primary address for the legal entity (Full description of child attributes below)
business_name	string, required	Merchant’s full legal business name (If INDIVIDUAL_SOLE_PROPRIETORSHIP, please input first name, Full legal last name and middle initial; max 120 characters)
business_phone	string, required	Customer service phone number where the merchant can be reached (max 10 characters)
business_tax_id	string, required	Nine digit Tax Identification Number (TIN), Employer Identification Number (EIN) or if the business_type is INDIVIDUAL_SOLE_PROPRIETORSHIP and a Tax ID is not available, the principal’s Social Security Number (SSN)
business_type	string, required	Please select one of the following values: INDIVIDUAL_SOLE_PROPRIETORSHIP, CORPORATION, LIMITED_LIABILITY_COMPANY, PARTNERSHIP, ASSOCIATION_ESTATE_TRUST, TAX_EXEMPT_ORGANIZATION, INTERNATIONAL_ORGANIZATION, GOVERNMENT_AGENCY
doing_business_as	string, required	Alternate name of the business. If no other name is used please use the same value for business_name (max 60 characters)
incorporation_date	object, required	Date company was founded (See below for a full list of the child attributes)
ownership_type	string, required	Values can be either PUBLIC to indicate a publicly traded company or PRIVATE for privately held businesses
url	string, required	Merchant’s publicly available website (max 100 characters)

Principal-specific Request Arguments

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

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

Processing-specific Request Arguments

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

Address-object Request Arguments

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

Incorporation Date-object Request Arguments

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

DOB-object Request Arguments

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

Provision a Merchant


curl https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772 \
    -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("IDcodXFEYpYHg7yukLdvWpEu").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('IDcodXFEYpYHg7yukLdvWpEu');

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



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

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

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

merchant = identity.provision_merchant

{
  "id" : "MUvQQt3RKe7FBZ6j9eMYoo3H",
  "application" : "APjMB6owJ7542dehJ6hCojzR",
  "identity" : "IDcodXFEYpYHg7yukLdvWpEu",
  "verification" : "VIx7MuY31w93pCMDkmS15e7F",
  "merchant_profile" : "MPc2842NuDR2ZoFtvPaXfLLM",
  "processor" : "DUMMY_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "card_expiration_date_required" : true,
  "card_cvv_required" : false,
  "tags" : {
    "key_2" : "value_2"
  },
  "mcc" : "0742",
  "mid" : "FNXwZpvsP1Ti8TieSjRrFwWgT",
  "merchant_name" : "Pollos Hermanos",
  "created_at" : "2020-12-02T03:44:17.12Z",
  "updated_at" : "2020-12-02T03:44:17.47Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : {
    "mid" : "FNXwZpvsP1Ti8TieSjRrFwWgT",
    "api_key" : "secretValue"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUvQQt3RKe7FBZ6j9eMYoo3H"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUvQQt3RKe7FBZ6j9eMYoo3H/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPc2842NuDR2ZoFtvPaXfLLM"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIx7MuY31w93pCMDkmS15e7F"
    }
  }
}

Provision a Merchant for a previously created Identity resource to begin processing transactions.

Merchant resources can have three possible states:

PROVISIONING: The request is pending (the state may change after two minutes)
APPROVED: The Merchant has been approved and can begin processing payments
REJECTED: The Merchant was rejected by the processor because of invalid underwriting information or it failed a regulatory and compliance check (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, such as a web service that connects buyers (i.e. customers) and sellers (i.e. merchants).

Provision a Merchant

curl https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772 \
    -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("IDcodXFEYpYHg7yukLdvWpEu").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('IDcodXFEYpYHg7yukLdvWpEu');

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



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

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

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

merchant = identity.provision_merchant

{
  "id" : "MUvQQt3RKe7FBZ6j9eMYoo3H",
  "application" : "APjMB6owJ7542dehJ6hCojzR",
  "identity" : "IDcodXFEYpYHg7yukLdvWpEu",
  "verification" : "VIx7MuY31w93pCMDkmS15e7F",
  "merchant_profile" : "MPc2842NuDR2ZoFtvPaXfLLM",
  "processor" : "DUMMY_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "card_expiration_date_required" : true,
  "card_cvv_required" : false,
  "tags" : {
    "key_2" : "value_2"
  },
  "mcc" : "0742",
  "mid" : "FNXwZpvsP1Ti8TieSjRrFwWgT",
  "merchant_name" : "Pollos Hermanos",
  "created_at" : "2020-12-02T03:44:17.12Z",
  "updated_at" : "2020-12-02T03:44:17.47Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : {
    "mid" : "FNXwZpvsP1Ti8TieSjRrFwWgT",
    "api_key" : "secretValue"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUvQQt3RKe7FBZ6j9eMYoo3H"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcodXFEYpYHg7yukLdvWpEu"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUvQQt3RKe7FBZ6j9eMYoo3H/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPc2842NuDR2ZoFtvPaXfLLM"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APjMB6owJ7542dehJ6hCojzR"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIx7MuY31w93pCMDkmS15e7F"
    }
  }
}

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

Merchant resources can have three possible onboarding_states:

PROVISIONING: The request is pending (the state may change after two minutes)
- processing_enabled: False
- settlement_enabled: False
APPROVED: The Merchant has been approved and can begin processing payments
- processing_enabled: True
- settlement_enabled: True
REJECTED: The Merchant was rejected by the processor because of
invalid information or it failed a regulatory and/or compliance check (e.g. KYC, OFAC, or MATCH)
- processing_enabled: False
- settlement_enabled: False

HTTP Request

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

URL Parameters

Parameter	Description
:IDENTITY_ID	ID of the Identity

Request Arguments

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

Fetch a Merchant

curl https://finix.sandbox-payments-api.com/merchants/MUvQQt3RKe7FBZ6j9eMYoo3H \
    -H "Content-Type: application/vnd.json+api" \
    -u  USjxcup83KZTBBFiqDScLYMF:25f85644-331d-45af-8758-b22b06f48772

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('MUvQQt3RKe7FBZ6j9eMYoo3H');



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

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

{</

Topics

API Endpoints

Authentication

Dashboard Overview

Create an Identity for a Merchant

Create a Bank Account for a Merchant

Onboard a New Merchant

View KYC Identity Verification

Approve and Reject a Merchant

Enable or Disable Payments Processing

Enable or Disable Settlement Functionality

Update Fee Profile

Update Risk Profile

Approve a Settlement

Upload Dispute Evidence

Errors

Idempotency Requests

Tags

Testing for specific responses and errors

Payment Facilitation Testing

Push-to-Card Testing

Guides

Overview

Getting Started

Step 1: Create an Identity for a Merchant

HTTP Request

Business-specific Request Arguments

Principal-specific Request Arguments

Processing-specific Request Arguments

Address-object Request Arguments

Incorporation Date-object Request Arguments

DOB-object Request Arguments

Step 2: Tokenize a Bank Account for Funding your Merchant

HTTP Request

Request Arguments

Step 3: Provision Merchant Account

HTTP Request

URL Parameters

Request Arguments

Step 4: Create an Identity for a Buyer

HTTP Request

Request Arguments

Address-object Request Arguments

Step 5: Tokenize a Card

HTTP Request

Request Arguments

Address-object Request Arguments

Step 6: Create Sale

HTTP Request

Request Arguments

Push-to-Card

Step 1: Create a Recipient Identity

HTTP Request

Request Arguments

Address-object Request Arguments

Step 2: Add a Payment Instrument for the Recipient

HTTP Request

Request Arguments

Address-object Request Arguments

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

HTTP Request

URL Parameters

Request Arguments

Address Verification Results (address_verification_results)

Card Verification 2 Results (cvv2_result_code)

Card Type (card_type_code)

Fasts Funds Indicator (fast_funds_indicator)

Push Funds Indicator (push_funds_block_indicator)

Online Gambling Block Indicator (online_gambing_block_indicator)

Card Product ID (card_product_id)

Product Sub-Type (card_product_subtype)

Card Sub-Type (card_subtype_code)

Step 4: Provision Recipient Account

HTTP Request

Request Arguments

Step 5: Send Payout

HTTP Request

Request Arguments

Pull-from-Card

Step 1: Create a Sender Identity