Flex docs
NAV
cURL Java PHP Python Ruby

Topics

API Endpoints

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

Authentication

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

curl https://finix.sandbox-payments-api.com/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba

/*
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("US5zMxCe9adjihGxkxwrkE7j")
                  .password("b564090b-4bd5-419a-9c05-3448eeab0eba")
                  .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" => 'US5zMxCe9adjihGxkxwrkE7j',
    "password" => 'b564090b-4bd5-419a-9c05-3448eeab0eba']
    );

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=("US5zMxCe9adjihGxkxwrkE7j", "b564090b-4bd5-419a-9c05-3448eeab0eba"))

# To download the Ruby gem:
# gem install finix

require 'finix'

Finix.configure(
    :root_url => 'https://finix.sandbox-payments-api.com',
    :user=>'US5zMxCe9adjihGxkxwrkE7j',
    :password => 'b564090b-4bd5-419a-9c05-3448eeab0eba'
)

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

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

Errors

HTTP Code Meaning
400 Bad Request – You attempted an invalid request
401 Unauthorized – You used the incorrect API key
402 Upstream Processor Error – Error caused by 3rd party service
404 Not Found – The specified resource could not be found
409 Conflict – The request cannot be completed with the specified resource in its current state
422 Unprocessable Entity – The parameters are valid but the request failed. The error is a 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 have a problem with our server. Try again later.

Idempotency Requests

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

Tags

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

Filters

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

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

Transfers and Authorizations Filters

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

Settlement Resource Filters

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

Disputes and Merchants Filters

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

Identities Filters

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

Applications Filters

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

Payment Instruments Filters

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

Reports Filters

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

Review Queue Settlements Filters

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

Guides

Overview

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

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

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

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

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  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -d '
    {
        "tags": {
            "Studio Rating": "4.7"
        },
        "entity": {
            "last_name": "Sunkhronos",
            "max_transaction_amount": 12000000,
            "has_accepted_credit_cards_previously": true,
            "default_statement_descriptor": "ACME Anchors",
            "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": "ACME Anchors",
            "principal_percentage_ownership": 50,
            "email": "user@example.org",
            "mcc": "0742",
            "phone": "1234567890",
            "business_name": "ACME Anchors",
            "tax_id": "123456789",
            "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone": "+1 (408) 756-4497",
            "dob": {
                "year": 1978,
                "day": 27,
                "month": 6
            },
            "url": "www.ACMEAnchors.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"=> "ACME Anchors",
            "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"=> "ACME Anchors",
            "principal_percentage_ownership"=> 50,
            "email"=> "user@example.org",
            "mcc"=> "0742",
            "phone"=> "1234567890",
            "business_name"=> "ACME Anchors",
            "tax_id"=> "123456789",
            "business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone"=> "+1 (408) 756-4497",
            "dob"=> array(
                "year"=> 1978,
                "day"=> 27,
                "month"=> 6
            ),
            "url"=> "www.ACMEAnchors.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": "ACME Anchors",
            "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": "ACME Anchors",
            "principal_percentage_ownership": 50,
            "email": "user@example.org",
            "mcc": "0742",
            "phone": "1234567890",
            "business_name": "ACME Anchors",
            "tax_id": "123456789",
            "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone": "+1 (408) 756-4497",
            "dob": {
                "year": 1978,
                "day": 27,
                "month": 6
            },
            "url": "www.ACMEAnchors.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"=> "ACME Anchors",
            "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"=> "ACME Anchors",
            "principal_percentage_ownership"=> 50,
            "email"=> "user@example.org",
            "mcc"=> "0742",
            "phone"=> "1234567890",
            "business_name"=> "ACME Anchors",
            "tax_id"=> "123456789",
            "business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone"=> "+1 (408) 756-4497",
            "dob"=> {
                "year"=> 1978,
                "day"=> 27,
                "month"=> 6
            },
            "url"=> "www.ACMEAnchors.com",
            "annual_card_volume"=> 12000000
        }
    }).save

Example Response:

{
  "id" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "entity" : {
    "title" : "CEO",
    "first_name" : "dwayne",
    "last_name" : "Sunkhronos",
    "email" : "user@example.org",
    "business_name" : "ACME Anchors",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "ACME Anchors",
    "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.ACMEAnchors.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" : "ACME Anchors"
  },
  "tags" : {
    "Studio Rating" : "4.7"
  },
  "created_at" : "2020-07-01T23:40:11.30Z",
  "updated_at" : "2020-07-01T23:40:11.30Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    }
  }
}

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

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

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

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

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

  3. Finally, provision the Merchant account

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

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

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

HTTP Request

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

Business-specific Request Arguments

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

Principal-specific Request Arguments

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

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

Processing-specific Request Arguments

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

Address-object Request Arguments

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

Incorporation Date-object Request Arguments

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

DOB-object Request Arguments

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

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  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -d '
    {
        "account_type": "SAVINGS",
        "name": "Alice",
        "tags": {
            "Bank Account": "Company Account"
        },
        "country": "USA",
        "bank_code": "123123123",
        "account_number": "123123123",
        "type": "BANK_ACCOUNT",
        "identity": "IDefa2LnXatPgxG5Tgs2fJfg"
    }'


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("IDefa2LnXatPgxG5Tgs2fJfg")
        .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('IDefa2LnXatPgxG5Tgs2fJfg');
$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"=> "IDefa2LnXatPgxG5Tgs2fJfg"
    ));
$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": "IDefa2LnXatPgxG5Tgs2fJfg"
    }).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"=> "IDefa2LnXatPgxG5Tgs2fJfg"
    }).save

Example Response:

{
  "id" : "PIsYRy4qAPjBvNHkh5PupFk3",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
  "tags" : {
    "Bank Account" : "Company Account"
  },
  "bank_code" : "123123123",
  "country" : "USA",
  "masked_account_number" : "XXXXX3123",
  "name" : "Alice",
  "account_type" : "SAVINGS",
  "created_at" : "2020-07-01T23:40:18.91Z",
  "updated_at" : "2020-07-01T23:40:18.91Z",
  "instrument_type" : "BANK_ACCOUNT",
  "type" : "BANK_ACCOUNT",
  "currency" : "USD",
  "identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIsYRy4qAPjBvNHkh5PupFk3"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIsYRy4qAPjBvNHkh5PupFk3/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIsYRy4qAPjBvNHkh5PupFk3/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIsYRy4qAPjBvNHkh5PupFk3/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
    }
  }
}

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/IDefa2LnXatPgxG5Tgs2fJfg/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -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('IDefa2LnXatPgxG5Tgs2fJfg');
$merchant = $identity->provisionMerchantOn(new Merchant());


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

identity = Identity.get(id="IDefa2LnXatPgxG5Tgs2fJfg")
merchant = identity.provision_merchant_on(Merchant())
identity = Finix::Identity.retrieve(:id=>"IDefa2LnXatPgxG5Tgs2fJfg")

merchant = identity.provision_merchant

Example Response:

{
  "id" : "MUkHH5FUQ6Rt5Cztp2V3sWKs",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "verification" : "VIc43RqMwe7kiQ1L4eRXjUaD",
  "merchant_profile" : "MP2iEqQAQ9utfPYQ8oBKXCDq",
  "processor" : "DUMMY_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : true,
  "card_expiration_date_required" : false,
  "card_cvv_required" : false,
  "tags" : {
    "key_2" : "value_2"
  },
  "mcc" : "0742",
  "mid" : null,
  "merchant_name" : "ACME Anchors",
  "created_at" : "2020-07-01T23:40:19.57Z",
  "updated_at" : "2020-07-01T23:40:19.83Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : {
    "api_key" : "secretValue"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUkHH5FUQ6Rt5Cztp2V3sWKs"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUkHH5FUQ6Rt5Cztp2V3sWKs/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MP2iEqQAQ9utfPYQ8oBKXCDq"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIc43RqMwe7kiQ1L4eRXjUaD"
    }
  }
}

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

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

    • processing_enabled: False
    • settlement_enabled: False
  2. APPROVED: Merchant has been approved and can begin processing

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

    • processing_enabled: False
    • settlement_enabled: False

HTTP Request

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

URL Parameters

Parameter Description
:IDENTITY_ID ID of the Identity

Request Arguments

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

Step 4: Create an Identity for a Buyer


curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -d '
    {
        "tags": {
            "key": "value"
        },
        "entity": {
            "phone": "7145677613",
            "first_name": "Collen",
            "last_name": "Jones",
            "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"=> "Collen",
            "last_name"=> "Jones",
            "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": "Collen",
            "last_name": "Jones",
            "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"=> "Collen",
            "last_name"=> "Jones",
            "email"=> "therock@gmail.com",
            "personal_address"=> {
                "city"=> "San Mateo",
                "country"=> "USA",
                "region"=> "CA",
                "line2"=> "Apartment 7",
                "line1"=> "741 Douglass St",
                "postal_code"=> "94114"
            }
        }
    }).save

Example Response:

{
  "id" : "ID7RtzR8Gyy3FWwjZx4cA2ma",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "entity" : {
    "title" : null,
    "first_name" : "Collen",
    "last_name" : "Jones",
    "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-07-01T23:40:21.89Z",
  "updated_at" : "2020-07-01T23:40:21.89Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    }
  }
}

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  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -d '
    {
        "name": "Bob 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": "ID7RtzR8Gyy3FWwjZx4cA2ma"
    }'


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("IDefa2LnXatPgxG5Tgs2fJfg")
        .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('IDefa2LnXatPgxG5Tgs2fJfg');
$card = new PaymentCard(
    array(
        "name"=> "Bob 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"=> "ID7RtzR8Gyy3FWwjZx4cA2ma"
    ));
$card = $identity->createPaymentCard($card);



from finix.resources import PaymentCard

card = PaymentCard(**
    {
        "name": "Bob 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": "ID7RtzR8Gyy3FWwjZx4cA2ma"
    }).save()
card = Finix::PaymentCard.new(
    {
        "name"=> "Bob 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"=> "ID7RtzR8Gyy3FWwjZx4cA2ma"
    }).save

Example Response:

{
  "id" : "PI2VnPygJVD5bTrXcHTJsDLf",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 3,
  "expiration_year" : 2029,
  "bin" : "489514",
  "last_four" : "0006",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Bob 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-07-01T23:40:22.66Z",
  "updated_at" : "2020-07-01T23:40:22.66Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "ID7RtzR8Gyy3FWwjZx4cA2ma",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf/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  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -d '
    {
        "merchant": "MUgauiSgsLEEUDeL9d4aVMrb",
        "currency": "USD",
        "amount": 495243,
        "source": "PI2VnPygJVD5bTrXcHTJsDLf",
        "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("PI2VnPygJVD5bTrXcHTJsDLf")
        .merchantIdentity("IDefa2LnXatPgxG5Tgs2fJfg")
        .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"=> "MUgauiSgsLEEUDeL9d4aVMrb",
        "currency"=> "USD",
        "amount"=> 495243,
        "source"=> "PI2VnPygJVD5bTrXcHTJsDLf",
        "tags"=> array(
            "test"=> "sale"
        )
    ));
$debit = $debit->save();



from finix.resources import Transfer

payout = Transfer(**
    {
        "merchant": "MUgauiSgsLEEUDeL9d4aVMrb",
        "currency": "USD",
        "amount": 495243,
        "source": "PI2VnPygJVD5bTrXcHTJsDLf",
        "tags": {
            "test": "sale"
        }
    }).save()

Finix::Transfer.new(
    array(
        "merchant"=> "MUgauiSgsLEEUDeL9d4aVMrb",
        "currency"=> "USD",
        "amount"=> 495243,
        "source"=> "PI2VnPygJVD5bTrXcHTJsDLf",
        "tags"=> array(
            "test"=> "sale"
        )
    )).save

Example Response:

{
  "id" : "TR9db9Q7Yzt4E1iRABaWsyNF",
  "amount" : 495243,
  "tags" : {
    "test" : "sale"
  },
  "state" : "PENDING",
  "trace_id" : "a795971c-f396-49b0-a901-9e73b523ba1a",
  "currency" : "USD",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "source" : "PI2VnPygJVD5bTrXcHTJsDLf",
  "destination" : null,
  "ready_to_settle_at" : null,
  "fee" : 0,
  "statement_descriptor" : null,
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2020-07-01T23:40:35.00Z",
  "updated_at" : "2020-07-01T23:40:35.62Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDo9vwBv7TzhpJyzcSrdbtRE",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR9db9Q7Yzt4E1iRABaWsyNF"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDo9vwBv7TzhpJyzcSrdbtRE"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR9db9Q7Yzt4E1iRABaWsyNF/payment_instruments"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR9db9Q7Yzt4E1iRABaWsyNF/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR9db9Q7Yzt4E1iRABaWsyNF/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR9db9Q7Yzt4E1iRABaWsyNF/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf"
    },
    "fee_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
    }
  }
}

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

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

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

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

HTTP Request

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

Request Arguments

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

Tokenization with Hosted Fields

Library summary

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

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

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

Step 1: Include library and desired HTML elements

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

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

Step 2: Initialize the payment form

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



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

The next step is to configure the library. This “card” method is the single entry point into the library. It initializes and returns a PaymentForm object that contains fields(i.e. name, number, expiration date, & 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', APs4YLHnwUEcBk1gn19VK3AA, function(err, res) {
    if (err) {
      console.log("There was an error");
    }
    // shows id of tokenized payment card
    document.getElementById('preview').innerHTML = JSON.stringify(res, null, '  ');
  })
}

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

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

Example Response:

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

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

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

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

Arguments

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

Step 5: Associate to an Identity

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  US69Pj2zDWUL9krN8KpfJLUB:10147e3f-694e-4242-86d8-d7336a996e79 \
    -d '
    {
        "token": "TKvJ6B4h5hfymgXW5Nn1SqLu",
        "type": "TOKEN",
        "identity": "IDefa2LnXatPgxG5Tgs2fJfg"
    }'

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



from finix.resources import PaymentInstrument

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

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

Example Response:

{
  "id" : "PIrJyWWqA2wzJQyDgahMzxYZ",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "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-07-01T23:40:48.27Z",
  "updated_at" : "2020-07-01T23:40:48.27Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIrJyWWqA2wzJQyDgahMzxYZ"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIrJyWWqA2wzJQyDgahMzxYZ/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIrJyWWqA2wzJQyDgahMzxYZ/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIrJyWWqA2wzJQyDgahMzxYZ/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIrJyWWqA2wzJQyDgahMzxYZ/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

Authorizations

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

Create an Authorization

curl https://finix.sandbox-payments-api.com/authorizations \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -d '
    {
        "source": "PI2VnPygJVD5bTrXcHTJsDLf",
        "merchant_identity": "IDefa2LnXatPgxG5Tgs2fJfg",
        "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("IDefa2LnXatPgxG5Tgs2fJfg")
                .source("PI2VnPygJVD5bTrXcHTJsDLf")
                .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"=> "PI2VnPygJVD5bTrXcHTJsDLf",
        "merchant_identity"=> "IDefa2LnXatPgxG5Tgs2fJfg",
        "tags"=> array(
            "order_number"=> "21DFASJSAKAS"
        ),
        "currency"=> "USD",
        "amount"=> 100,
        "processor"=> "DUMMY_V1"
    ));
$authorization = $authorization->save();




from finix.resources import Authorization

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

Example Response:

{
  "id" : "AU9rSTEFCRuZPnDa8yxZvcxK",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2020-07-01T23:40:43.64Z",
  "updated_at" : "2020-07-01T23:40:43.78Z",
  "trace_id" : "62f456c7-e73e-4ff8-9367-974d391072d3",
  "source" : "PI2VnPygJVD5bTrXcHTJsDLf",
  "merchant_identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "3ds_redirect_url" : null,
  "is_void" : false,
  "void_state" : "UNATTEMPTED",
  "expires_at" : "2020-07-08T23:40:43.64Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AU9rSTEFCRuZPnDa8yxZvcxK"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
    }
  }
}

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

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

HTTP Request

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

Request Arguments

Field Type Description
source string, required The Payment Instrument that you will be performing the authorization
merchant_identity string, required The ID of the Identity for the merchant that you are transacting on behalf of
amount integer, required The amount of the authorization in cents
currency string, required 3-letter ISO code designating the currency (e.g. USD)
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/AU9rSTEFCRuZPnDa8yxZvcxK \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -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("AU9rSTEFCRuZPnDa8yxZvcxK").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('AU9rSTEFCRuZPnDa8yxZvcxK');
$authorization = $authorization->capture([
                    "capture_amount"=> 50,
                    "fee"=> 10
                ]);



from finix.resources import Authorization

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

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



Example Response:

{
  "id" : "AU9rSTEFCRuZPnDa8yxZvcxK",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : "TR6TS3hMMBPz8Mftdm7w46iY",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2020-07-01T23:40:43.64Z",
  "updated_at" : "2020-07-01T23:40:45.65Z",
  "trace_id" : "62f456c7-e73e-4ff8-9367-974d391072d3",
  "source" : "PI2VnPygJVD5bTrXcHTJsDLf",
  "merchant_identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "3ds_redirect_url" : null,
  "is_void" : false,
  "void_state" : "UNATTEMPTED",
  "expires_at" : "2020-07-08T23:40:43.64Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AU9rSTEFCRuZPnDa8yxZvcxK"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "transfer" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR6TS3hMMBPz8Mftdm7w46iY"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
    }
  }
}

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

HTTP Request

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

URL Parameters

Parameter Description
:AUTHORIZATION_ID ID of the Authorization

Request Arguments

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

Void an Authorization


curl https://finix.sandbox-payments-api.com/authorizations/AUt1KAK6yCX5hjnjFWFYtbxq \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -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("AU9rSTEFCRuZPnDa8yxZvcxK").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('AU9rSTEFCRuZPnDa8yxZvcxK');
$authorization->void(true);
$authorization = $authorization->save();




from finix.resources import Authorization

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

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

Example Response:

{
  "id" : "AUt1KAK6yCX5hjnjFWFYtbxq",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2020-07-01T23:40:49.00Z",
  "updated_at" : "2020-07-01T23:40:49.95Z",
  "trace_id" : "8fe163a0-4fd5-41e9-a92e-a02465f1051b",
  "source" : "PI2VnPygJVD5bTrXcHTJsDLf",
  "merchant_identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "3ds_redirect_url" : null,
  "is_void" : true,
  "void_state" : "PENDING",
  "expires_at" : "2020-07-08T23:40:49.00Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUt1KAK6yCX5hjnjFWFYtbxq"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
    }
  }
}

Cancels the Authorization thereby releasing the funds. After voiding an Authorization it can no longer be captured.

HTTP Request

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

URL Parameters

Parameter Description
:AUTHORIZATION_ID ID of the Authorization

Request Arguments

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

Fetch an Authorization


curl https://finix.sandbox-payments-api.com/authorizations/AU9rSTEFCRuZPnDa8yxZvcxK \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba

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

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



from finix.resources import Authorization

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


Example Response:

{
  "id" : "AU9rSTEFCRuZPnDa8yxZvcxK",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : "TR6TS3hMMBPz8Mftdm7w46iY",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2020-07-01T23:40:43.64Z",
  "updated_at" : "2020-07-01T23:40:45.65Z",
  "trace_id" : "62f456c7-e73e-4ff8-9367-974d391072d3",
  "source" : "PI2VnPygJVD5bTrXcHTJsDLf",
  "merchant_identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "3ds_redirect_url" : null,
  "is_void" : false,
  "void_state" : "UNATTEMPTED",
  "expires_at" : "2020-07-08T23:40:43.64Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AU9rSTEFCRuZPnDa8yxZvcxK"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "transfer" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR6TS3hMMBPz8Mftdm7w46iY"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
    }
  }
}

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  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba

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

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

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

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

<?php
use Finix\Resources\Authorization;

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




from finix.resources import Authorization

authorization = Authorization.get()
authorizations = Finix::Authorization.retrieve

Example Response:

{
  "_embedded" : {
    "authorizations" : [ {
      "id" : "AUt1KAK6yCX5hjnjFWFYtbxq",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "amount" : 100,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : null,
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2020-07-01T23:40:49.00Z",
      "updated_at" : "2020-07-01T23:40:49.95Z",
      "trace_id" : "8fe163a0-4fd5-41e9-a92e-a02465f1051b",
      "source" : "PI2VnPygJVD5bTrXcHTJsDLf",
      "merchant_identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
      "3ds_redirect_url" : null,
      "is_void" : true,
      "void_state" : "PENDING",
      "expires_at" : "2020-07-08T23:40:49.00Z",
      "idempotency_id" : null,
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations/AUt1KAK6yCX5hjnjFWFYtbxq"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
        }
      }
    }, {
      "id" : "AU6nJ2LZdF7ffyaMnm23LKV9",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "amount" : 100,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : null,
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2020-07-01T23:40:44.76Z",
      "updated_at" : "2020-07-01T23:40:44.92Z",
      "trace_id" : "9ba048f3-d35f-4d8f-912f-94f8167c1be1",
      "source" : "PI2VnPygJVD5bTrXcHTJsDLf",
      "merchant_identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
      "3ds_redirect_url" : null,
      "is_void" : false,
      "void_state" : "UNATTEMPTED",
      "expires_at" : "2020-07-08T23:40:44.76Z",
      "idempotency_id" : "e4e9050524934a019eb529bb58b91fac",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations/AU6nJ2LZdF7ffyaMnm23LKV9"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
        }
      }
    }, {
      "id" : "AU9rSTEFCRuZPnDa8yxZvcxK",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "amount" : 100,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : "TR6TS3hMMBPz8Mftdm7w46iY",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2020-07-01T23:40:43.64Z",
      "updated_at" : "2020-07-01T23:40:45.65Z",
      "trace_id" : "62f456c7-e73e-4ff8-9367-974d391072d3",
      "source" : "PI2VnPygJVD5bTrXcHTJsDLf",
      "merchant_identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
      "3ds_redirect_url" : null,
      "is_void" : false,
      "void_state" : "UNATTEMPTED",
      "expires_at" : "2020-07-08T23:40:43.64Z",
      "idempotency_id" : null,
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/authorizations/AU9rSTEFCRuZPnDa8yxZvcxK"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "transfer" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR6TS3hMMBPz8Mftdm7w46iY"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 3
  }
}

HTTP Request

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

Disputes

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

Upload Dispute Evidence

curl https://finix.sandbox-payments-api.com/disputes/DIftVFbh7zUhjtQ849mhMQN8/evidence \
    -H "Content-Type: application/pdf/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -F 'data=@path/to/local/file' testfile.pdf


<?php





Example Response:


    {
        "tags": {
            "content-type": "application/pdf",
            "file-extension": ".pdf",
            "file-name": "testfile.pdf"
        },
        "created_at": "2020-07-02T00:21:19.26Z",
        "updated_at": "2020-07-02T00:21:19.27Z",
        "_links": {
            "self": {
                "href": "https://finix.sandbox-payments-api.com/disputes/DIftVFbh7zUhjtQ849mhMQN8/evidence/DFiziCZdP8uqWV24d2ziTZCN"
            }
        },
        "id": "DFiziCZdP8uqWV24d2ziTZCN",
        "dispute": "DIftVFbh7zUhjtQ849mhMQN8"
    }

HTTP Request

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

Fetch a Dispute


curl https://finix.sandbox-payments-api.com/disputes/DIftVFbh7zUhjtQ849mhMQN8 \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba



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

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

<?php
use Finix\Resources\Dispute;

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



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

disputes = Finix::Dispute.retrieve

Example Response:

{
  "id" : "DIftVFbh7zUhjtQ849mhMQN8",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "amount" : 888888,
  "state" : "PENDING",
  "transfer" : "TRc8RtSEugnW4bMuxZy2FG3t",
  "reason" : "FRAUD",
  "message" : null,
  "action" : null,
  "identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "created_at" : "2020-07-01T23:42:12.99Z",
  "updated_at" : "2020-07-01T23:42:12.63Z",
  "occurred_at" : "2020-07-01T23:41:14.74Z",
  "respond_by" : "2020-07-08T23:42:12.97Z",
  "dispute_details" : {
    "arn" : "123"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes/DIftVFbh7zUhjtQ849mhMQN8"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "transfer" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRc8RtSEugnW4bMuxZy2FG3t"
    },
    "evidence" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes/DIftVFbh7zUhjtQ849mhMQN8/evidence"
    },
    "adjustment_transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes/DIftVFbh7zUhjtQ849mhMQN8/adjustment_transfers"
    }
  }
}

HTTP Request

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

URL Parameters

Parameter Description
:DISPUTE_ID ID of the Dispute

List all Disputes

curl https://finix.sandbox-payments-api.com/disputes/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba

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(:id => "DIftVFbh7zUhjtQ849mhMQN8")

Example Response:

{
  "_embedded" : {
    "disputes" : [ {
      "id" : "DIftVFbh7zUhjtQ849mhMQN8",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "amount" : 888888,
      "state" : "PENDING",
      "transfer" : "TRc8RtSEugnW4bMuxZy2FG3t",
      "reason" : "FRAUD",
      "message" : null,
      "action" : null,
      "identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
      "created_at" : "2020-07-01T23:42:12.99Z",
      "updated_at" : "2020-07-01T23:42:12.63Z",
      "occurred_at" : "2020-07-01T23:41:14.74Z",
      "respond_by" : "2020-07-08T23:42:12.97Z",
      "dispute_details" : {
        "arn" : "123"
      },
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/disputes/DIftVFbh7zUhjtQ849mhMQN8"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "transfer" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRc8RtSEugnW4bMuxZy2FG3t"
        },
        "evidence" : {
          "href" : "https://finix.sandbox-payments-api.com/disputes/DIftVFbh7zUhjtQ849mhMQN8/evidence"
        },
        "adjustment_transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/disputes/DIftVFbh7zUhjtQ849mhMQN8/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
  }
}

HTTP Request

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

Identities

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

Create an Identity for a Buyer



curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -d '
    {
        "tags": {
            "key": "value"
        },
        "entity": {
            "phone": "7145677613",
            "first_name": "Collen",
            "last_name": "Jones",
            "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"=> "Collen",
            "last_name"=> "Jones",
            "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": "Collen",
            "last_name": "Jones",
            "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"=> "Collen",
            "last_name"=> "Jones",
            "email"=> "therock@gmail.com",
            "personal_address"=> {
                "city"=> "San Mateo",
                "country"=> "USA",
                "region"=> "CA",
                "line2"=> "Apartment 7",
                "line1"=> "741 Douglass St",
                "postal_code"=> "94114"
            }
        }
    }).save

Example Response:

{
  "id" : "ID7RtzR8Gyy3FWwjZx4cA2ma",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "entity" : {
    "title" : null,
    "first_name" : "Collen",
    "last_name" : "Jones",
    "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-07-01T23:40:21.89Z",
  "updated_at" : "2020-07-01T23:40:21.89Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    }
  }
}

All fields for a buyer’s Identity are optional. However, a business_type field should not be passed. Passing a business_type indicates that the Identity should be treated as a merchant.

HTTP Request

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

Request Arguments

Field Type Description
first_name string, optional First name
last_name string, optional Last name
phone string, optional Phone number
email string, optional Email address
line1 string, optional First line of the address (max 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
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)

Fetch a Identity


curl https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba

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


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

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


Example Response:

{
  "id" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "entity" : {
    "title" : "CEO",
    "first_name" : "dwayne",
    "last_name" : "Sunkhronos",
    "email" : "user@example.org",
    "business_name" : "ACME Anchors",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "ACME Anchors",
    "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.ACMEAnchors.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" : "ACME Anchors"
  },
  "tags" : {
    "Studio Rating" : "4.7"
  },
  "created_at" : "2020-07-01T23:40:11.30Z",
  "updated_at" : "2020-07-01T23:40:11.21Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    }
  }
}

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  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba


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

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

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

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

<?php
use Finix\Resources\Identity;

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




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

identities = Finix::Identity.retrieve


Example Response:

{
  "_embedded" : {
    "identities" : [ {
      "id" : "IDo9vwBv7TzhpJyzcSrdbtRE",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Pawny City Hall",
        "business_type" : "CORPORATION",
        "doing_business_as" : "Pawny City Hall",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.PawnyCityHall.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Pawny City Hall"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2020-07-01T23:40:24.06Z",
      "updated_at" : "2020-07-01T23:40:23.97Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo9vwBv7TzhpJyzcSrdbtRE"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo9vwBv7TzhpJyzcSrdbtRE/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo9vwBv7TzhpJyzcSrdbtRE/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo9vwBv7TzhpJyzcSrdbtRE/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo9vwBv7TzhpJyzcSrdbtRE/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo9vwBv7TzhpJyzcSrdbtRE/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo9vwBv7TzhpJyzcSrdbtRE/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo9vwBv7TzhpJyzcSrdbtRE/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo9vwBv7TzhpJyzcSrdbtRE/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        }
      }
    }, {
      "id" : "ID7RtzR8Gyy3FWwjZx4cA2ma",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "entity" : {
        "title" : null,
        "first_name" : "Collen",
        "last_name" : "Jones",
        "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-07-01T23:40:21.89Z",
      "updated_at" : "2020-07-01T23:40:21.84Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        }
      }
    }, {
      "id" : "IDtxwX5wa5CBW5wh1RpjooWH",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "ACME Anchors",
        "business_type" : "GOVERNMENT_AGENCY",
        "doing_business_as" : "ACME Anchors",
        "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.ACMEAnchors.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" : "ACME Anchors"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2020-07-01T23:40:16.19Z",
      "updated_at" : "2020-07-01T23:40:16.11Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtxwX5wa5CBW5wh1RpjooWH"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtxwX5wa5CBW5wh1RpjooWH/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtxwX5wa5CBW5wh1RpjooWH/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtxwX5wa5CBW5wh1RpjooWH/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtxwX5wa5CBW5wh1RpjooWH/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtxwX5wa5CBW5wh1RpjooWH/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtxwX5wa5CBW5wh1RpjooWH/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtxwX5wa5CBW5wh1RpjooWH/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtxwX5wa5CBW5wh1RpjooWH/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        }
      }
    }, {
      "id" : "IDiBxNnqSYdRw6TmqpuRztLv",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Dunder Mifflin",
        "business_type" : "INTERNATIONAL_ORGANIZATION",
        "doing_business_as" : "Dunder Mifflin",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.DunderMifflin.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_authority" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Dunder Mifflin"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2020-07-01T23:40:15.55Z",
      "updated_at" : "2020-07-01T23:40:15.45Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDiBxNnqSYdRw6TmqpuRztLv"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDiBxNnqSYdRw6TmqpuRztLv/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDiBxNnqSYdRw6TmqpuRztLv/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDiBxNnqSYdRw6TmqpuRztLv/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDiBxNnqSYdRw6TmqpuRztLv/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDiBxNnqSYdRw6TmqpuRztLv/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDiBxNnqSYdRw6TmqpuRztLv/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDiBxNnqSYdRw6TmqpuRztLv/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDiBxNnqSYdRw6TmqpuRztLv/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        }
      }
    }, {
      "id" : "ID4cnqGnds4zirjvwkCNeGXy",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Golds Gym",
        "business_type" : "TAX_EXEMPT_ORGANIZATION",
        "doing_business_as" : "Golds Gym",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.GoldsGym.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PUBLIC",
        "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-07-01T23:40:13.76Z",
      "updated_at" : "2020-07-01T23:40:13.66Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4cnqGnds4zirjvwkCNeGXy"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4cnqGnds4zirjvwkCNeGXy/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4cnqGnds4zirjvwkCNeGXy/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4cnqGnds4zirjvwkCNeGXy/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4cnqGnds4zirjvwkCNeGXy/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4cnqGnds4zirjvwkCNeGXy/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4cnqGnds4zirjvwkCNeGXy/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4cnqGnds4zirjvwkCNeGXy/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4cnqGnds4zirjvwkCNeGXy/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        }
      }
    }, {
      "id" : "IDdGhUsxeqZrru4SWmMyjDGf",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Prestige World Wide",
        "business_type" : "ASSOCIATION_ESTATE_TRUST",
        "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-07-01T23:40:13.06Z",
      "updated_at" : "2020-07-01T23:40:12.97Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdGhUsxeqZrru4SWmMyjDGf"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdGhUsxeqZrru4SWmMyjDGf/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdGhUsxeqZrru4SWmMyjDGf/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdGhUsxeqZrru4SWmMyjDGf/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdGhUsxeqZrru4SWmMyjDGf/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdGhUsxeqZrru4SWmMyjDGf/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdGhUsxeqZrru4SWmMyjDGf/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdGhUsxeqZrru4SWmMyjDGf/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDdGhUsxeqZrru4SWmMyjDGf/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        }
      }
    }, {
      "id" : "IDtKr9Jo98qpSks8EU5syH43",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Petes Coffee",
        "business_type" : "PARTNERSHIP",
        "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-07-01T23:40:12.45Z",
      "updated_at" : "2020-07-01T23:40:12.37Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtKr9Jo98qpSks8EU5syH43"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtKr9Jo98qpSks8EU5syH43/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtKr9Jo98qpSks8EU5syH43/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtKr9Jo98qpSks8EU5syH43/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtKr9Jo98qpSks8EU5syH43/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtKr9Jo98qpSks8EU5syH43/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtKr9Jo98qpSks8EU5syH43/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtKr9Jo98qpSks8EU5syH43/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDtKr9Jo98qpSks8EU5syH43/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        }
      }
    }, {
      "id" : "IDi8yCiqrrUABjpsu2wpsJiV",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Golds Gym",
        "business_type" : "LIMITED_LIABILITY_COMPANY",
        "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-07-01T23:40:11.89Z",
      "updated_at" : "2020-07-01T23:40:11.81Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDi8yCiqrrUABjpsu2wpsJiV"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDi8yCiqrrUABjpsu2wpsJiV/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDi8yCiqrrUABjpsu2wpsJiV/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDi8yCiqrrUABjpsu2wpsJiV/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDi8yCiqrrUABjpsu2wpsJiV/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDi8yCiqrrUABjpsu2wpsJiV/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDi8yCiqrrUABjpsu2wpsJiV/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDi8yCiqrrUABjpsu2wpsJiV/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDi8yCiqrrUABjpsu2wpsJiV/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        }
      }
    }, {
      "id" : "IDefa2LnXatPgxG5Tgs2fJfg",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "ACME Anchors",
        "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
        "doing_business_as" : "ACME Anchors",
        "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.ACMEAnchors.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" : "ACME Anchors"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2020-07-01T23:40:11.30Z",
      "updated_at" : "2020-07-01T23:40:11.21Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        }
      }
    }, {
      "id" : "IDmrMnzW6WEAzQBBGVYSKbQs",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "entity" : {
        "title" : null,
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Facebook",
        "business_type" : "LIMITED_LIABILITY_COMPANY",
        "doing_business_as" : "Facebook",
        "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" : "Facebook"
      },
      "created_at" : "2020-07-01T23:39:46.75Z",
      "updated_at" : "2020-07-01T23:39:46.82Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmrMnzW6WEAzQBBGVYSKbQs"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmrMnzW6WEAzQBBGVYSKbQs/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmrMnzW6WEAzQBBGVYSKbQs/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmrMnzW6WEAzQBBGVYSKbQs/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmrMnzW6WEAzQBBGVYSKbQs/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmrMnzW6WEAzQBBGVYSKbQs/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmrMnzW6WEAzQBBGVYSKbQs/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmrMnzW6WEAzQBBGVYSKbQs/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmrMnzW6WEAzQBBGVYSKbQs/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 10
  }
}

HTTP Request

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

Update an Identity

curl https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -X PUT \
    -d '
    {
        "tags": {
            "key": "value_2"
        },
        "entity": {
            "business_phone": "+1 (408) 756-4497",
            "first_name": "Bernard",
            "last_name": "Chang",
            "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": "Bobs Burgers",
            "annual_card_volume": 12000000,
            "default_statement_descriptor": "Bobs Burgers",
            "url": "www.BobsBurgers.com",
            "business_name": "Bobs Burgers",
            "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("IDefa2LnXatPgxG5Tgs2fJfg").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="IDefa2LnXatPgxG5Tgs2fJfg")
identity.entity["first_name"] = "Bernard"
identity.save()

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

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

Example Response:

{
  "id" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "entity" : {
    "title" : "CTO",
    "first_name" : "Bernard",
    "last_name" : "Chang",
    "email" : "user@example.org",
    "business_name" : "Bobs Burgers",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "Bobs Burgers",
    "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.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" : {
    "key" : "value_2"
  },
  "created_at" : "2020-07-01T23:40:11.30Z",
  "updated_at" : "2020-07-01T23:41:11.64Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    }
  }
}

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

HTTP Request

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

Business-specific Request Arguments

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

Principal-specific Request Arguments

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

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

Processing-specific Request Arguments

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

Address-object Request Arguments

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

Incorporation Date-object Request Arguments

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

DOB-object Request Arguments

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

Merchants

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

Fetch a Merchant

curl https://finix.sandbox-payments-api.com/merchants/MUkHH5FUQ6Rt5Cztp2V3sWKs \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba

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



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

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

Example Response:

{
  "id" : "MUkHH5FUQ6Rt5Cztp2V3sWKs",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "verification" : "VIc43RqMwe7kiQ1L4eRXjUaD",
  "merchant_profile" : "MP2iEqQAQ9utfPYQ8oBKXCDq",
  "processor" : "DUMMY_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "card_expiration_date_required" : false,
  "card_cvv_required" : false,
  "tags" : {
    "key_2" : "value_2"
  },
  "mcc" : "0742",
  "mid" : null,
  "merchant_name" : "ACME Anchors",
  "created_at" : "2020-07-01T23:40:19.57Z",
  "updated_at" : "2020-07-01T23:40:22.27Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : {
    "api_key" : "secretValue"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUkHH5FUQ6Rt5Cztp2V3sWKs"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUkHH5FUQ6Rt5Cztp2V3sWKs/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MP2iEqQAQ9utfPYQ8oBKXCDq"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIc43RqMwe7kiQ1L4eRXjUaD"
    }
  }
}

HTTP Request

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

URL Parameters

Parameter Description
:MERCHANT_ID ID of the Merchant

List all Merchants

curl https://finix.sandbox-payments-api.com/merchants/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba

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

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

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

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

<?php
use Finix\Resources\Merchant;

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




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

merchants = Finix::Merchant.retrieve

Example Response:

{
  "_embedded" : {
    "merchants" : [ {
      "id" : "MUgauiSgsLEEUDeL9d4aVMrb",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "identity" : "IDo9vwBv7TzhpJyzcSrdbtRE",
      "verification" : "VIoFMqRQ7NF7GQ5KhYeymbPS",
      "merchant_profile" : "MP8XaNf7SHNMiwBzsPQja87S",
      "processor" : "DUMMY_V1",
      "processing_enabled" : true,
      "settlement_enabled" : true,
      "gross_settlement_enabled" : false,
      "creating_transfer_from_report_enabled" : false,
      "card_expiration_date_required" : false,
      "card_cvv_required" : false,
      "tags" : {
        "key_2" : "value_2"
      },
      "mcc" : "0742",
      "mid" : null,
      "merchant_name" : "Pawny City Hall",
      "created_at" : "2020-07-01T23:40:25.64Z",
      "updated_at" : "2020-07-01T23:40:27.82Z",
      "onboarding_state" : "APPROVED",
      "processor_details" : {
        "api_key" : "secretValue"
      },
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/merchants/MUgauiSgsLEEUDeL9d4aVMrb"
        },
        "identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo9vwBv7TzhpJyzcSrdbtRE"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/merchants/MUgauiSgsLEEUDeL9d4aVMrb/verifications"
        },
        "merchant_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MP8XaNf7SHNMiwBzsPQja87S"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "verification" : {
          "href" : "https://finix.sandbox-payments-api.com/verifications/VIoFMqRQ7NF7GQ5KhYeymbPS"
        }
      }
    }, {
      "id" : "MUkHH5FUQ6Rt5Cztp2V3sWKs",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
      "verification" : "VIc43RqMwe7kiQ1L4eRXjUaD",
      "merchant_profile" : "MP2iEqQAQ9utfPYQ8oBKXCDq",
      "processor" : "DUMMY_V1",
      "processing_enabled" : true,
      "settlement_enabled" : true,
      "gross_settlement_enabled" : false,
      "creating_transfer_from_report_enabled" : false,
      "card_expiration_date_required" : false,
      "card_cvv_required" : false,
      "tags" : {
        "key_2" : "value_2"
      },
      "mcc" : "0742",
      "mid" : null,
      "merchant_name" : "ACME Anchors",
      "created_at" : "2020-07-01T23:40:19.57Z",
      "updated_at" : "2020-07-01T23:40:22.27Z",
      "onboarding_state" : "APPROVED",
      "processor_details" : {
        "api_key" : "secretValue"
      },
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/merchants/MUkHH5FUQ6Rt5Cztp2V3sWKs"
        },
        "identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/merchants/MUkHH5FUQ6Rt5Cztp2V3sWKs/verifications"
        },
        "merchant_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MP2iEqQAQ9utfPYQ8oBKXCDq"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "verification" : {
          "href" : "https://finix.sandbox-payments-api.com/verifications/VIc43RqMwe7kiQ1L4eRXjUaD"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 2
  }
}

HTTP Request

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

Payment Instruments

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

Create a Payment Card



curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -d '
    {
        "name": "Bob 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": "ID7RtzR8Gyy3FWwjZx4cA2ma"
    }'


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("IDefa2LnXatPgxG5Tgs2fJfg")
        .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('IDefa2LnXatPgxG5Tgs2fJfg');
$card = new PaymentCard(
    array(
        "name"=> "Bob 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"=> "ID7RtzR8Gyy3FWwjZx4cA2ma"
    ));
$card = $identity->createPaymentCard($card);



from finix.resources import PaymentCard

card = PaymentCard(**
    {
        "name": "Bob 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": "ID7RtzR8Gyy3FWwjZx4cA2ma"
    }).save()
card = Finix::PaymentCard.new(
    {
        "name"=> "Bob 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"=> "ID7RtzR8Gyy3FWwjZx4cA2ma"
    }).save

Example Response:

{
  "id" : "PI2VnPygJVD5bTrXcHTJsDLf",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 3,
  "expiration_year" : 2029,
  "bin" : "489514",
  "last_four" : "0006",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Bob 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-07-01T23:40:22.66Z",
  "updated_at" : "2020-07-01T23:40:22.66Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "ID7RtzR8Gyy3FWwjZx4cA2ma",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf/updates"
    }
  }
}

Please review our guide on how to tokenize cards via the tokenization with hosted fields form

HTTP Request

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

Request Arguments

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

Address-object Request Arguments

Field Type Description
line1 string, optional First line of the address (max 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

Create a Bank Account


curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -d '
    {
        "account_type": "SAVINGS",
        "name": "Alice",
        "tags": {
            "Bank Account": "Company Account"
        },
        "country": "USA",
        "bank_code": "123123123",
        "account_number": "123123123",
        "type": "BANK_ACCOUNT",
        "identity": "IDefa2LnXatPgxG5Tgs2fJfg"
    }'


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("IDefa2LnXatPgxG5Tgs2fJfg")
        .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('IDefa2LnXatPgxG5Tgs2fJfg');
$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"=> "IDefa2LnXatPgxG5Tgs2fJfg"
    ));
$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": "IDefa2LnXatPgxG5Tgs2fJfg"
    }).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"=> "IDefa2LnXatPgxG5Tgs2fJfg"
    }).save

Example Response:

{
  "id" : "PIsYRy4qAPjBvNHkh5PupFk3",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
  "tags" : {
    "Bank Account" : "Company Account"
  },
  "bank_code" : "123123123",
  "country" : "USA",
  "masked_account_number" : "XXXXX3123",
  "name" : "Alice",
  "account_type" : "SAVINGS",
  "created_at" : "2020-07-01T23:40:18.91Z",
  "updated_at" : "2020-07-01T23:40:18.91Z",
  "instrument_type" : "BANK_ACCOUNT",
  "type" : "BANK_ACCOUNT",
  "currency" : "USD",
  "identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIsYRy4qAPjBvNHkh5PupFk3"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIsYRy4qAPjBvNHkh5PupFk3/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIsYRy4qAPjBvNHkh5PupFk3/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIsYRy4qAPjBvNHkh5PupFk3/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
    }
  }
}

HTTP Request

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

Request Arguments

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

Associate a Token

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -d '
    {
        "token": "TKvJ6B4h5hfymgXW5Nn1SqLu",
        "type": "TOKEN",
        "identity": "IDefa2LnXatPgxG5Tgs2fJfg"
    }'


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



from finix.resources import PaymentInstrument

payment_instrument = PaymentInstrument(**
    {
        "token": "TKvJ6B4h5hfymgXW5Nn1SqLu",
        "type": "TOKEN",
        "identity": "IDefa2LnXatPgxG5Tgs2fJfg"
    }).save()
card = Finix::PaymentInstrument.new(
    {
        "token"=> "TKvJ6B4h5hfymgXW5Nn1SqLu",
        "type"=> "TOKEN",
        "identity"=> "IDefa2LnXatPgxG5Tgs2fJfg"
    }).save

Example Response:

{
  "id" : "PIrJyWWqA2wzJQyDgahMzxYZ",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "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-07-01T23:40:48.27Z",
  "updated_at" : "2020-07-01T23:40:48.27Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIrJyWWqA2wzJQyDgahMzxYZ"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIrJyWWqA2wzJQyDgahMzxYZ/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIrJyWWqA2wzJQyDgahMzxYZ/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIrJyWWqA2wzJQyDgahMzxYZ/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIrJyWWqA2wzJQyDgahMzxYZ/updates"
    }
  }
}

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

HTTP Request

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

Request Arguments

Field Type Description
token string, required ID for the Token that was returned via the tokenization client or hosted iframe
type string, required Must pass TOKEN as the value
identity string, required ID for the Identity resource which the account is to be associated

Fetch a Bank Account

curl https://finix.sandbox-payments-api.com/payment_instruments/PIsYRy4qAPjBvNHkh5PupFk3 \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \

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

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

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

Instrument bankAccountView = response.view();

<?php
use Finix\Resources\PaymentInstrument;

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



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

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

Example Response:

{
  "id" : "PIsYRy4qAPjBvNHkh5PupFk3",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
  "tags" : {
    "Display Name" : "Updated Field"
  },
  "bank_code" : "123123123",
  "country" : "USA",
  "masked_account_number" : "XXXXX3123",
  "name" : "Alice",
  "account_type" : "SAVINGS",
  "created_at" : "2020-07-01T23:40:18.91Z",
  "updated_at" : "2020-07-01T23:40:21.15Z",
  "instrument_type" : "BANK_ACCOUNT",
  "type" : "BANK_ACCOUNT",
  "currency" : "USD",
  "identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIsYRy4qAPjBvNHkh5PupFk3"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIsYRy4qAPjBvNHkh5PupFk3/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIsYRy4qAPjBvNHkh5PupFk3/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIsYRy4qAPjBvNHkh5PupFk3/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
    }
  }
}

Fetch a previously created Payment Instrument that is of type BANK_ACCOUNT

HTTP Request

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

URL Parameters

Parameter Description
:PAYMENT_INSTRUMENT_ID ID of the Payment Instrument

List all Payment Instruments

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba
import io.finix.payments.ApiClient;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.lib.Page;
import io.finix.payments.views.Instrument;

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

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

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

<?php
use Finix\Resources\PaymentInstrument;

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




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

payment_instruments = Finix::PaymentInstrument.retrieve

Example Response:

{
  "_embedded" : {
    "payment_instruments" : [ {
      "id" : "PIrJyWWqA2wzJQyDgahMzxYZ",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "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-07-01T23:40:48.27Z",
      "updated_at" : "2020-07-01T23:40:48.27Z",
      "instrument_type" : "PAYMENT_CARD",
      "type" : "PAYMENT_CARD",
      "currency" : "USD",
      "identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIrJyWWqA2wzJQyDgahMzxYZ"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIrJyWWqA2wzJQyDgahMzxYZ/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIrJyWWqA2wzJQyDgahMzxYZ/transfers"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIrJyWWqA2wzJQyDgahMzxYZ/verifications"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
        },
        "updates" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIrJyWWqA2wzJQyDgahMzxYZ/updates"
        }
      }
    }, {
      "id" : "PI9PdAER8MEL5nVw1u7qauYG",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
      "tags" : {
        "Bank Account" : "Company Account"
      },
      "bank_code" : "123123123",
      "country" : "USA",
      "masked_account_number" : "XXXXX3123",
      "name" : "Alice",
      "account_type" : "SAVINGS",
      "created_at" : "2020-07-01T23:40:25.02Z",
      "updated_at" : "2020-07-01T23:40:25.02Z",
      "instrument_type" : "BANK_ACCOUNT",
      "type" : "BANK_ACCOUNT",
      "currency" : "USD",
      "identity" : "IDo9vwBv7TzhpJyzcSrdbtRE",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI9PdAER8MEL5nVw1u7qauYG"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI9PdAER8MEL5nVw1u7qauYG/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI9PdAER8MEL5nVw1u7qauYG/transfers"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI9PdAER8MEL5nVw1u7qauYG/verifications"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo9vwBv7TzhpJyzcSrdbtRE"
        }
      }
    }, {
      "id" : "PI9rtsXYNWgMghHqF92LYgoP",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
      "tags" : {
        "Bank Account" : "Company Account"
      },
      "bank_code" : "123123123",
      "country" : "USA",
      "masked_account_number" : "XXXXX3123",
      "name" : "Alice",
      "account_type" : "SAVINGS",
      "created_at" : "2020-07-01T23:40:23.41Z",
      "updated_at" : "2020-07-01T23:40:23.41Z",
      "instrument_type" : "BANK_ACCOUNT",
      "type" : "BANK_ACCOUNT",
      "currency" : "USD",
      "identity" : "ID7RtzR8Gyy3FWwjZx4cA2ma",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI9rtsXYNWgMghHqF92LYgoP"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI9rtsXYNWgMghHqF92LYgoP/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI9rtsXYNWgMghHqF92LYgoP/transfers"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI9rtsXYNWgMghHqF92LYgoP/verifications"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma"
        }
      }
    }, {
      "id" : "PI2VnPygJVD5bTrXcHTJsDLf",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
      "tags" : {
        "card_name" : "Business Card"
      },
      "expiration_month" : 3,
      "expiration_year" : 2029,
      "bin" : "489514",
      "last_four" : "0006",
      "brand" : "VISA",
      "card_type" : "UNKNOWN",
      "name" : "Bob Sterling",
      "address" : {
        "line1" : "900 Metro Center Blv",
        "line2" : null,
        "city" : "San Francisco",
        "region" : "CA",
        "postal_code" : "94404",
        "country" : "USA"
      },
      "address_verification" : "POSTAL_CODE_AND_STREET_MATCH",
      "security_code_verification" : "MATCHED",
      "created_at" : "2020-07-01T23:40:22.66Z",
      "updated_at" : "2020-07-01T23:40:22.66Z",
      "instrument_type" : "PAYMENT_CARD",
      "type" : "PAYMENT_CARD",
      "currency" : "USD",
      "identity" : "ID7RtzR8Gyy3FWwjZx4cA2ma",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf/transfers"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf/verifications"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID7RtzR8Gyy3FWwjZx4cA2ma"
        },
        "updates" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf/updates"
        }
      }
    }, {
      "id" : "PIsYRy4qAPjBvNHkh5PupFk3",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
      "tags" : {
        "Display Name" : "Updated Field"
      },
      "bank_code" : "123123123",
      "country" : "USA",
      "masked_account_number" : "XXXXX3123",
      "name" : "Alice",
      "account_type" : "SAVINGS",
      "created_at" : "2020-07-01T23:40:18.91Z",
      "updated_at" : "2020-07-01T23:40:18.91Z",
      "instrument_type" : "BANK_ACCOUNT",
      "type" : "BANK_ACCOUNT",
      "currency" : "USD",
      "identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIsYRy4qAPjBvNHkh5PupFk3"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIsYRy4qAPjBvNHkh5PupFk3/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIsYRy4qAPjBvNHkh5PupFk3/transfers"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIsYRy4qAPjBvNHkh5PupFk3/verifications"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
        }
      }
    }, {
      "id" : "PI3wTnUVw8NUZuhrJGgaGk3q",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
      "tags" : {
        "Bank Account" : "Company Account"
      },
      "bank_code" : "123123123",
      "country" : "USA",
      "masked_account_number" : "XXXXX3123",
      "name" : "Alice",
      "account_type" : "SAVINGS",
      "created_at" : "2020-07-01T23:40:17.12Z",
      "updated_at" : "2020-07-01T23:40:17.12Z",
      "instrument_type" : "BANK_ACCOUNT",
      "type" : "BANK_ACCOUNT",
      "currency" : "USD",
      "identity" : "IDmrMnzW6WEAzQBBGVYSKbQs",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI3wTnUVw8NUZuhrJGgaGk3q"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI3wTnUVw8NUZuhrJGgaGk3q/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI3wTnUVw8NUZuhrJGgaGk3q/transfers"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI3wTnUVw8NUZuhrJGgaGk3q/verifications"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDmrMnzW6WEAzQBBGVYSKbQs"
        }
      }
    }, {
      "id" : "PIdPw1UzYK3j4SnwQHK8yQkE",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
      "tags" : {
        "test2" : "tami4",
        "test" : "tami2",
        "testing" : "tami"
      },
      "bank_code" : "123123123",
      "country" : "USA",
      "masked_account_number" : "XXXXX3123",
      "name" : "Fran Lemke",
      "account_type" : "SAVINGS",
      "created_at" : "2020-07-01T23:39:47.98Z",
      "updated_at" : "2020-07-01T23:39:47.98Z",
      "instrument_type" : "BANK_ACCOUNT",
      "type" : "BANK_ACCOUNT",
      "currency" : "USD",
      "identity" : "ID8bW3W9DmKEgFYF4GfDJ8or",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdPw1UzYK3j4SnwQHK8yQkE"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdPw1UzYK3j4SnwQHK8yQkE/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdPw1UzYK3j4SnwQHK8yQkE/transfers"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIdPw1UzYK3j4SnwQHK8yQkE/verifications"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID8bW3W9DmKEgFYF4GfDJ8or"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 7
  }
}

HTTP Request

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

Settlements

A Settlement is a logical construct representing a collection (i.e. batch) of Transfers that are intended to be paid out to a specific Merchant.

In v2 of the settlement engine, the destination attribute will be deprecated from all API’s that return the settlement resource (e.g. STxxx). The destination field will be stored in settlements/:SETTLEMENT_ID/funding_transfers.

Fetch a Settlement by ID [v2]

curl https://finix.sandbox-payments-api.com/settlement_engine/settlements/STgwGQUx7scCZELCgeY8nuTv \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \


<?php





Example Response:

{
  "id" : "STgwGQUx7scCZELCgeY8nuTv",
  "tags" : { },
  "status" : "APPROVED",
  "currency" : "USD",
  "total_amount" : -888888,
  "total_fee_amount" : 0,
  "transfer_debit_count" : 0,
  "transfer_debit_amount" : 0,
  "transfer_credit_count" : 0,
  "transfer_credit_amount" : 0,
  "fee_count" : 0,
  "reverse_count" : 0,
  "reverse_amount" : 0,
  "dispute_debit_count" : 1,
  "dispute_debit_amount" : 888888,
  "dispute_credit_count" : 0,
  "dispute_credit_amount" : 0,
  "adjustment_debit_count" : 0,
  "adjustment_debit_amount" : 0,
  "adjustment_credit_count" : 0,
  "adjustment_credit_amount" : 0,
  "processor_type" : "DUMMY_V1",
  "exception" : false,
  "created_at" : "2020-07-01T23:42:14.44Z",
  "updated_at" : "2020-07-02T00:21:23.13Z",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "merchant" : "MUkHH5FUQ6Rt5Cztp2V3sWKs",
  "settlement_group" : "SGgwGqT4tEEwp3rCNc65NGez",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/settlement_engine/STgwGQUx7scCZELCgeY8nuTv"
    }
  }
}

Fetch a previously created Settlement

HTTP Request

GET https://finix.sandbox-payments-api.com/settlement_engine/settlements/:SETTLEMENT_ID

URL Parameters

Parameter Description
:SETTLEMENT_ID ID of the Settlement

Response

Field Type Description
id string Settlement ID
adjustment_credit_count integer Number of adjustments that are negative for a Merchant in a Settlement
adjustment_debit_count integer Number of adjustments that are positive for a Merchant in a Settlement
dispute_credit_count integer Number of credits that are negative for a Merchant in a Settlement
dispute_debit_count integer Number of credits that are positive for a Merchant in a Settlement
exception boolean The default is “false”. When the field is set to “true”, the Settlement contains exceptions that were removed from another Settlement
fee_count integer Number of Fees collected in a Settlement
merchant_id string Merchant ID
net_amount integer Total amount minus the total Fee amount
processor_type string Processor type
reverse_count integer Number of reversals
settlement_group_id string A collection of Settlements that can be combined into a single line item
status string Settlement status. Statuses available are: PENDING, AWAITING APPROVAL, STAGED, APPROVED
tags object Key value pair for annotating custom meta data
total_amount integer Total of all Transfers in a Settlement
total_fee_amount integer Sum of all fees collected from a Settlement
transfer_credit_count integer Number of Transfers that are negative for a Merchant in a Settlement
transfer_debit_count integer Number of Transfers that are positive for a Merchant in a Settlement

List all Settlements [v2]

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

<?php





Example Response:

{
  "_embedded" : {
    "settlements" : [ {
      "id" : "STgwGQUx7scCZELCgeY8nuTv",
      "tags" : { },
      "status" : "APPROVED",
      "currency" : "USD",
      "total_amount" : -888888,
      "total_fee_amount" : 0,
      "transfer_debit_count" : 0,
      "transfer_debit_amount" : 0,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 0,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 1,
      "dispute_debit_amount" : 888888,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-07-01T23:42:14.44Z",
      "updated_at" : "2020-07-02T00:21:23.13Z",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "merchant" : "MUkHH5FUQ6Rt5Cztp2V3sWKs",
      "settlement_group" : "SGgwGqT4tEEwp3rCNc65NGez",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/STgwGQUx7scCZELCgeY8nuTv"
        }
      }
    }, {
      "id" : "STc9BiUtacYBSWcy2StuHaao",
      "tags" : { },
      "status" : "AWAITING_APPROVAL",
      "currency" : "USD",
      "total_amount" : 1132645,
      "total_fee_amount" : 0,
      "transfer_debit_count" : 2,
      "transfer_debit_amount" : 1132645,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 0,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 0,
      "dispute_debit_amount" : 0,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-07-01T23:41:14.91Z",
      "updated_at" : "2020-07-01T23:45:25.68Z",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "merchant" : "MUgauiSgsLEEUDeL9d4aVMrb",
      "settlement_group" : "SGc9ARNdEjY8dtxVGLwpRahR",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/STc9BiUtacYBSWcy2StuHaao"
        }
      }
    }, {
      "id" : "STsdTyPs6jM3Wwk3bsEvJzne",
      "tags" : { },
      "status" : "AWAITING_APPROVAL",
      "currency" : "USD",
      "total_amount" : 0,
      "total_fee_amount" : 54321,
      "transfer_debit_count" : 0,
      "transfer_debit_amount" : 0,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 1,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 0,
      "dispute_debit_amount" : 0,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-07-01T18:51:10.25Z",
      "updated_at" : "2020-07-01T19:15:26.03Z",
      "application" : "AP9zkqrwL9dnrNeoX5rGPib6",
      "merchant" : "MUxviQSQincADf3DdTWJ8tZ9",
      "settlement_group" : "SGsdNatXbWamwwKjSKiRD5aG",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/STsdTyPs6jM3Wwk3bsEvJzne"
        }
      }
    }, {
      "id" : "STftU6PiUnpsH2Hofui67XDY",
      "tags" : { },
      "status" : "AWAITING_APPROVAL",
      "currency" : "USD",
      "total_amount" : 0,
      "total_fee_amount" : 54321,
      "transfer_debit_count" : 0,
      "transfer_debit_amount" : 0,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 1,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 0,
      "dispute_debit_amount" : 0,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-07-01T17:51:14.86Z",
      "updated_at" : "2020-07-01T18:15:27.23Z",
      "application" : "AP9zkqrwL9dnrNeoX5rGPib6",
      "merchant" : "MUxviQSQincADf3DdTWJ8tZ9",
      "settlement_group" : "SGftTJNKf8N14Xnki8XYWQJB",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/STftU6PiUnpsH2Hofui67XDY"
        }
      }
    }, {
      "id" : "ST4hciYicywaG2ppdNNSxFuU",
      "tags" : { },
      "status" : "AWAITING_APPROVAL",
      "currency" : "USD",
      "total_amount" : 0,
      "total_fee_amount" : 108642,
      "transfer_debit_count" : 0,
      "transfer_debit_amount" : 0,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 2,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 0,
      "dispute_debit_amount" : 0,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-07-01T16:51:26.69Z",
      "updated_at" : "2020-07-01T17:15:25.82Z",
      "application" : "AP9zkqrwL9dnrNeoX5rGPib6",
      "merchant" : "MUxviQSQincADf3DdTWJ8tZ9",
      "settlement_group" : "SG4hbSP285Nx57mfX5SBkvHp",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/ST4hciYicywaG2ppdNNSxFuU"
        }
      }
    }, {
      "id" : "STpSVm3nAihdBBMXRaJ4a59s",
      "tags" : { },
      "status" : "AWAITING_APPROVAL",
      "currency" : "USD",
      "total_amount" : 10,
      "total_fee_amount" : 100,
      "transfer_debit_count" : 1,
      "transfer_debit_amount" : 10,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 1,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 0,
      "dispute_debit_amount" : 0,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-07-01T01:39:50.97Z",
      "updated_at" : "2020-07-01T12:15:40.78Z",
      "application" : "APpLzXocRgscUduT8y9JTAMm",
      "merchant" : "MUa7yXpFMxXxHeRpXEwWAevZ",
      "settlement_group" : "SGpSUVofkUTcjCpgHeyWFVME",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/STpSVm3nAihdBBMXRaJ4a59s"
        }
      }
    }, {
      "id" : "SToKsqTPCJ2HcXX9Nj5kCUs1",
      "tags" : { },
      "status" : "AWAITING_APPROVAL",
      "currency" : "USD",
      "total_amount" : 470016,
      "total_fee_amount" : 135894,
      "transfer_debit_count" : 4,
      "transfer_debit_amount" : 1358904,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 9,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 1,
      "dispute_debit_amount" : 888888,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-06-30T21:50:31.74Z",
      "updated_at" : "2020-06-30T22:15:25.73Z",
      "application" : "APrjmjk8UymuAujt8uboKBui",
      "merchant" : "MUbyv5gG4Ab8ms7sjGZLKdpQ",
      "settlement_group" : "SGoKs24b2eofA5KPfZtzEWGq",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/SToKsqTPCJ2HcXX9Nj5kCUs1"
        }
      }
    }, {
      "id" : "STkyDZ8Bb4P5cBySGwZ3nJZs",
      "tags" : { },
      "status" : "APPROVED",
      "currency" : "USD",
      "total_amount" : 963508,
      "total_fee_amount" : 57680,
      "transfer_debit_count" : 2,
      "transfer_debit_amount" : 963508,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 3,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 0,
      "dispute_debit_amount" : 0,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-06-30T21:49:48.46Z",
      "updated_at" : "2020-06-30T22:30:00.53Z",
      "application" : "APrjmjk8UymuAujt8uboKBui",
      "merchant" : "MUmvpXnn1bETsLAVAVehL9Qr",
      "settlement_group" : "SGkyDB5eVP3Csd6s8PaseueJ",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/STkyDZ8Bb4P5cBySGwZ3nJZs"
        }
      }
    }, {
      "id" : "STuYCRWtz7PHGD6aqNURTjEU",
      "tags" : { },
      "status" : "AWAITING_APPROVAL",
      "currency" : "USD",
      "total_amount" : 146178,
      "total_fee_amount" : 3024,
      "transfer_debit_count" : 1,
      "transfer_debit_amount" : 146178,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 2,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 0,
      "dispute_debit_amount" : 0,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-06-30T15:18:14.02Z",
      "updated_at" : "2020-06-30T15:45:25.47Z",
      "application" : "APpLzXocRgscUduT8y9JTAMm",
      "merchant" : "MUuBhHFA2kaFFDMuTCPNDnUi",
      "settlement_group" : "SGuYCpYyaGc7yrLPm2pn7j1h",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/STuYCRWtz7PHGD6aqNURTjEU"
        }
      }
    }, {
      "id" : "STY3e6GHm7ane3r4BALrYNn",
      "tags" : { },
      "status" : "AWAITING_APPROVAL",
      "currency" : "USD",
      "total_amount" : 1190931,
      "total_fee_amount" : 119096,
      "transfer_debit_count" : 4,
      "transfer_debit_amount" : 1190931,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 9,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 0,
      "dispute_debit_amount" : 0,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-06-30T03:30:22.79Z",
      "updated_at" : "2020-06-30T12:15:40.66Z",
      "application" : "AP5vJSS1N3Gst7CGXecgEsM7",
      "merchant" : "MUgQDNPMtayT8i75JoUpt923",
      "settlement_group" : "SGY2TngAg47gGKRSXZNYHA1",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/STY3e6GHm7ane3r4BALrYNn"
        }
      }
    }, {
      "id" : "ST4fHhkDa1Ne3345HH6oBc6i",
      "tags" : { },
      "status" : "AWAITING_APPROVAL",
      "currency" : "USD",
      "total_amount" : 829492,
      "total_fee_amount" : 57847,
      "transfer_debit_count" : 2,
      "transfer_debit_amount" : 829492,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 3,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 0,
      "dispute_debit_amount" : 0,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-06-30T03:09:25.38Z",
      "updated_at" : "2020-06-30T12:15:43.43Z",
      "application" : "AP5vJSS1N3Gst7CGXecgEsM7",
      "merchant" : "MUiP67tA9HK8tPmE9HwizzLX",
      "settlement_group" : "SG4fGXK1tBVFXNuBSCWPeP4o",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/ST4fHhkDa1Ne3345HH6oBc6i"
        }
      }
    }, {
      "id" : "ST4932wpvAtmujgZJ9pkr19P",
      "tags" : { },
      "status" : "AWAITING_APPROVAL",
      "currency" : "USD",
      "total_amount" : -888888,
      "total_fee_amount" : 0,
      "transfer_debit_count" : 0,
      "transfer_debit_amount" : 0,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 0,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 1,
      "dispute_debit_amount" : 888888,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-06-30T03:09:23.81Z",
      "updated_at" : "2020-06-30T12:15:43.81Z",
      "application" : "AP5vJSS1N3Gst7CGXecgEsM7",
      "merchant" : "MUgQDNPMtayT8i75JoUpt923",
      "settlement_group" : "SG492EQZY78rmfoVfFWSEcY3",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/ST4932wpvAtmujgZJ9pkr19P"
        }
      }
    }, {
      "id" : "ST8cRDTdjeNVdFPvLLGL3rfi",
      "tags" : { },
      "status" : "AWAITING_APPROVAL",
      "currency" : "USD",
      "total_amount" : -888888,
      "total_fee_amount" : 0,
      "transfer_debit_count" : 0,
      "transfer_debit_amount" : 0,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 0,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 1,
      "dispute_debit_amount" : 888888,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-06-30T02:27:22.07Z",
      "updated_at" : "2020-06-30T12:15:40.44Z",
      "application" : "APpxPesBddCtkfZuRDRhZ8vn",
      "merchant" : "MUrNc6cT5HDF5p9g6gr3QrA2",
      "settlement_group" : "SG8cR8Bq6aREqywzKSaNb897",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/ST8cRDTdjeNVdFPvLLGL3rfi"
        }
      }
    }, {
      "id" : "ST4cNexPoZpmsw7kq1v8myix",
      "tags" : { },
      "status" : "AWAITING_APPROVAL",
      "currency" : "USD",
      "total_amount" : 1012194,
      "total_fee_amount" : 54131,
      "transfer_debit_count" : 2,
      "transfer_debit_amount" : 1012194,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 3,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 0,
      "dispute_debit_amount" : 0,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-06-30T02:26:27.71Z",
      "updated_at" : "2020-06-30T12:15:43.65Z",
      "application" : "APpxPesBddCtkfZuRDRhZ8vn",
      "merchant" : "MUaA3oVmog5QuB7rHt8gMJQm",
      "settlement_group" : "SG4cMSxfJKMTPrLh3WutqpqX",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/ST4cNexPoZpmsw7kq1v8myix"
        }
      }
    }, {
      "id" : "ST5qowuncwYmFwxW5xggFDPT",
      "tags" : { },
      "status" : "AWAITING_APPROVAL",
      "currency" : "USD",
      "total_amount" : -888888,
      "total_fee_amount" : 0,
      "transfer_debit_count" : 0,
      "transfer_debit_amount" : 0,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 0,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 1,
      "dispute_debit_amount" : 888888,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-06-30T01:29:28.28Z",
      "updated_at" : "2020-06-30T12:15:40.45Z",
      "application" : "APn4C4dsCmsxBmcU6gEEgvkA",
      "merchant" : "MUu9zwSorP7B8VWQpRtSpmdF",
      "settlement_group" : "SG5qo7NSZrxnJJC1gB9CPKSC",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/ST5qowuncwYmFwxW5xggFDPT"
        }
      }
    }, {
      "id" : "STwA31EDhbzxdYvHEJSDP5Cd",
      "tags" : { },
      "status" : "AWAITING_APPROVAL",
      "currency" : "USD",
      "total_amount" : 927653,
      "total_fee_amount" : 86539,
      "transfer_debit_count" : 2,
      "transfer_debit_amount" : 927653,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 3,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 0,
      "dispute_debit_amount" : 0,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-06-30T01:28:14.29Z",
      "updated_at" : "2020-06-30T12:15:40.18Z",
      "application" : "APn4C4dsCmsxBmcU6gEEgvkA",
      "merchant" : "MUgqaZ75Wth83rtKcMmgdQ6i",
      "settlement_group" : "SGwA2A1w2NbvVZ84AcFx3JJD",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/STwA31EDhbzxdYvHEJSDP5Cd"
        }
      }
    }, {
      "id" : "ST2nrVmrFDfWvKzL1vvnStLU",
      "tags" : { },
      "status" : "APPROVED",
      "currency" : "USD",
      "total_amount" : 438534,
      "total_fee_amount" : 9072,
      "transfer_debit_count" : 3,
      "transfer_debit_amount" : 438534,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 6,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 0,
      "dispute_debit_amount" : 0,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-06-29T22:08:20.91Z",
      "updated_at" : "2020-06-30T02:08:40.02Z",
      "application" : "APpLzXocRgscUduT8y9JTAMm",
      "merchant" : "MUuBhHFA2kaFFDMuTCPNDnUi",
      "settlement_group" : "SG2nqCJA1WnnMAq2juzPJfwy",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/ST2nrVmrFDfWvKzL1vvnStLU"
        }
      }
    }, {
      "id" : "STasUx2yYCY35CgCiABKvVvC",
      "tags" : { },
      "status" : "AWAITING_APPROVAL",
      "currency" : "USD",
      "total_amount" : 40468664,
      "total_fee_amount" : 811174,
      "transfer_debit_count" : 18,
      "transfer_debit_amount" : 40468664,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 36,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 0,
      "dispute_debit_amount" : 0,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-06-29T19:47:00.95Z",
      "updated_at" : "2020-06-29T20:15:25.74Z",
      "application" : "APtAjyxTYR3ALsYVqt494TdT",
      "merchant" : "MUw2iXfRfhTGCPuR6DxoDppg",
      "settlement_group" : "SGasU1qBCPKeMuvK7ynyWDaD",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/STasUx2yYCY35CgCiABKvVvC"
        }
      }
    }, {
      "id" : "ST95dNVkkC9kj85KtgQjrNZm",
      "tags" : { },
      "status" : "AWAITING_APPROVAL",
      "currency" : "USD",
      "total_amount" : 1673713,
      "total_fee_amount" : 167375,
      "transfer_debit_count" : 4,
      "transfer_debit_amount" : 1673713,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 9,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 0,
      "dispute_debit_amount" : 0,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-06-29T19:46:42.05Z",
      "updated_at" : "2020-06-29T20:15:25.46Z",
      "application" : "APkPYGfSsPeEtNaYegRnUANe",
      "merchant" : "MUnSjh29ftuPeEjRHJq7PiYD",
      "settlement_group" : "SG95dt8yYKJVBi4DgGMNF3vw",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/ST95dNVkkC9kj85KtgQjrNZm"
        }
      }
    }, {
      "id" : "ST8WNvD9Lgn8NQbkr19YpeKn",
      "tags" : { },
      "status" : "APPROVED",
      "currency" : "USD",
      "total_amount" : 1558556,
      "total_fee_amount" : 155859,
      "transfer_debit_count" : 4,
      "transfer_debit_amount" : 1558556,
      "transfer_credit_count" : 0,
      "transfer_credit_amount" : 0,
      "fee_count" : 9,
      "reverse_count" : 0,
      "reverse_amount" : 0,
      "dispute_debit_count" : 0,
      "dispute_debit_amount" : 0,
      "dispute_credit_count" : 0,
      "dispute_credit_amount" : 0,
      "adjustment_debit_count" : 0,
      "adjustment_debit_amount" : 0,
      "adjustment_credit_count" : 0,
      "adjustment_credit_amount" : 0,
      "processor_type" : "DUMMY_V1",
      "exception" : false,
      "created_at" : "2020-06-29T19:46:40.32Z",
      "updated_at" : "2020-06-30T03:49:07.89Z",
      "application" : "AP9N2tv6MALHyNVZ155enpti",
      "merchant" : "MUmAuoGwb2vQMKYwBpGQ7tHr",
      "settlement_group" : "SG8WN6L1dWcUJtbBfQujV4bD",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/settlement_engine/ST8WNvD9Lgn8NQbkr19YpeKn"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/settlement_engine/settlements?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    },
    "next" : {
      "href" : "https://finix.sandbox-payments-api.com/settlement_engine/settlements?offset=20&limit=20&sort=created_at,desc&sort=id,desc"
    },
    "last" : {
      "href" : "https://finix.sandbox-payments-api.com/settlement_engine/settlements?offset=3920&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 3921
  }
}

This call displays all settlements in the review queue and their status.

HTTP Request

GET https://finix.sandbox-payments-api.com/settlement_engine/settlements

Response

Field Type Description
id string Review Queue ID
adjustment_credit_count integer Number of adjustments that are negative for a Merchant in a Settlement
adjustment_debit_count integer Number of adjustments that are positive for a Merchant in a Settlement
dispute_credit_count integer Number of credits that are negative for a Merchant in a Settlement
dispute_debit_count integer Number of credits that are positive for a Merchant in a Settlement
exception boolean The default is “false”. When the field is set to “true”, the Settlement contains exceptions that were removed from another Settlement
fee_count integer Number of fees collected in a Settlement
merchant_id string Merchant ID
net_amount *integer Total amount minus the total fee amount
processor_type string Processor type
reverse_count integer Number of reversals
settlement_group_id string A collection of settlements that can be combined into a single line item
status string Settlement status. Statuses available are: PENDING, AWAITING APPROVAL, STAGED, APPROVED
tags object Key value pair for annotating custom meta data
total_amount integer Total of all Transfers in a Settlement
total_fee_amount integer Sum of all fees collected from a Settlement
transfer_credit_count integer Number of Transfers that are negative for a Merchant in a Settlement
transfer_debit_count integer Number of Transfers that are positive for a Merchant in a Settlement

List Transfers in a Batch Settlement [v2]

curl https://finix.sandbox-payments-api.com/settlement_engine/settlements/STgwGQUx7scCZELCgeY8nuTv/transfers \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba

<?php





Example Response:

{
  "_embedded" : {
    "transfers" : [ {
      "id" : "TR5fb8Hvxwrdx4AUPY7QYA2F",
      "amount" : 888888,
      "tags" : { },
      "state" : "SUCCEEDED",
      "trace_id" : "565925dd-5c70-4827-b779-cca50a99176c",
      "currency" : "USD",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "source" : null,
      "destination" : "PI2VnPygJVD5bTrXcHTJsDLf",
      "ready_to_settle_at" : "2020-07-01T23:42:13.08Z",
      "fee" : 0,
      "statement_descriptor" : null,
      "idempotency_id" : null,
      "merchant_identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
      "type" : "DISPUTE",
      "messages" : [ ],
      "raw" : null,
      "subtype" : "MERCHANT_DEBIT",
      "_links" : {
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR5fb8Hvxwrdx4AUPY7QYA2F"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR5fb8Hvxwrdx4AUPY7QYA2F/payment_instruments"
        },
        "disputed_transfer" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR5fb8Hvxwrdx4AUPY7QYA2F/disputed_transfer"
        },
        "destination" : {
          "href" : "https://finix.sandbox-payments-api.com/instruments/PI2VnPygJVD5bTrXcHTJsDLf"
        }
      }
    }, {
      "id" : "TR7j1vpc2xfaj3dxZgTVFhop",
      "amount" : 888888,
      "tags" : { },
      "state" : "SUCCEEDED",
      "trace_id" : "28b4e54d-6cfa-4f4c-a76a-c00c8e050566",
      "currency" : "USD",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "source" : null,
      "destination" : null,
      "ready_to_settle_at" : "2020-07-01T23:42:13.43Z",
      "fee" : 0,
      "statement_descriptor" : null,
      "idempotency_id" : null,
      "merchant_identity" : "ID8bW3W9DmKEgFYF4GfDJ8or",
      "type" : "DISPUTE",
      "messages" : [ ],
      "raw" : null,
      "subtype" : "PLATFORM_CREDIT",
      "_links" : {
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR7j1vpc2xfaj3dxZgTVFhop"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID8bW3W9DmKEgFYF4GfDJ8or"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR7j1vpc2xfaj3dxZgTVFhop/payment_instruments"
        },
        "disputed_transfer" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR7j1vpc2xfaj3dxZgTVFhop/disputed_transfer"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/settlement_engine/settlements/STgwGQUx7scCZELCgeY8nuTv/transfers?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 2
  }
}

List the batch of Transfers of type DEBIT and REFUND that comprise the net settled amount of a Settlement.

HTTP Request

GET https://finix.sandbox-payments-api.com/settlement_engine/settlements/:SETTLEMENT_ID/transfers

URL Parameters

Parameter Description
:SETTLEMENT_ID ID of the Settlement

Response

Field Type Description
id string Transfer ID
amount integer The total amount that will be debited in cents (e.g. 100 cents to debit $1.00)
application string Application ID
currency string Currency type
destination string Payment instrument ID of destination for funds
fee integer 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)
fee_type string Description of the Fee type. This description is determined by the type of Fee Profile set up in the dashboard
idempotency_id string A randomly generated value that you want associated with the request
merchant_identity string Identity ID of the Merchant whom you’re charging on behalf of
messages string Displays specific decline fields from the Processor
raw string Raw Processor response. It holds data that the Processor sends to us after we initiate a Transfer
ready_to_settle_at string Timestamp of when the Transfer is ready to be settled
source string Payment instrument ID of the source of funds
state string State of the Transfer
statement_descriptor string Description of the purchase that appears on a credit card statement
subtype string Additional Transfer information
tags object Key value pair for annotating custom meta data (e.g. order numbers)
trace_ID string The ID assigned to this transaction by the Processor
type string Type of Transfer. Options include: TRANSFER, FEE, REVERSE, SETTLEMENT, and DISPUTE

View Funding Instructions in a Batch Settlement [v2]

curl https://finix.sandbox-payments-api.com/settlement_engine/settlements/STgwGQUx7scCZELCgeY8nuTv/funding_instructions \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba

<?php





Example Response:

{
  "_embedded" : {
    "funding_instructions" : [ {
      "id" : "FIwkGtDbYgf3FtubHADt8JEF",
      "tags" : { },
      "state" : "SUBMITTING",
      "name" : "PLATFORM_FUNDING_INSTRUCTION",
      "level" : "PLATFORM",
      "amount" : 888888,
      "currency" : "USD",
      "source_instrument_id" : "PIwXJenjFpZP7qdnbfSoW3fz",
      "destination_instrument_id" : "PItx92Xp5KTc6MD6YTg2wGHy",
      "rail" : "PAYFAC_CREDIT",
      "overridden" : false,
      "deferred_submission_time" : null,
      "submission_offset_business_days" : null,
      "created_at" : "2020-07-02T00:21:23.13Z",
      "updated_at" : "2020-07-02T00:21:23.13Z"
    }, {
      "id" : "FIwkGaQniSrTYGfMYWFE3ghz",
      "tags" : { },
      "state" : "SUBMITTING",
      "name" : "MERCHANT_FUNDING_INSTRUCTION",
      "level" : "MERCHANT",
      "amount" : -888888,
      "currency" : "USD",
      "source_instrument_id" : "PIwXJenjFpZP7qdnbfSoW3fz",
      "destination_instrument_id" : "PIsYRy4qAPjBvNHkh5PupFk3",
      "rail" : "PAYFAC_CREDIT",
      "overridden" : false,
      "deferred_submission_time" : null,
      "submission_offset_business_days" : null,
      "created_at" : "2020-07-02T00:21:23.13Z",
      "updated_at" : "2020-07-02T00:21:23.13Z"
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/settlement_engine/settlements/STgwGQUx7scCZELCgeY8nuTv/funding_instructions?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 2
  }
}

This call displays the funding instructions for each Settlement ID. This displays the following information on the Funding Transfers in the dashboard: Created, Type, State, and Amount.

HTTP Request

GET https://finix.sandbox-payments-api.com/settlements/:SETTLEMENT_ID/funding_instructions

URL Parameters

Parameter Description
:SETTLEMENT_ID ID of the Settlement

Response

Field Type Description
id string Review Queue ID
amount integer Total amount for the funding instructions
code string The end state of the funding instructions
created_at string Timestamp when the resource was created
currency string Currency type
destination_instrument_id string Payment instrument ID of destination for funds
level string Description of the level to be paid
name string Description of the funding instructions
overriden boolean The default is “false”. When it is set to “true”, the customer has changed the default payment for a Settlement
rail instrument The rail used for a the funding instructions
source_instrument_id string Payment instrument ID of source of funds
tags objects Key value pair for annotating custom meta data
updated_at string Timestamp when any change occurs to any of the fields listed above

Transfers

A Transfer represents any flow of funds either to or from a Payment Instrument. For example, a Transfer is a credit to a bank account refund to a card.

A Transfer can have one of three types: Debit, Credit, or Reversal. Each type indicates a different funds flow. For example:

Transfers can have four possible states values: PENDING, SUCCEEDED, FAILED, or CANCELED.

By default, Transfers will be in a PENDING state and will eventually (typically within an hour) update to SUCCEEDED.

ready_to_settle_at field can have 2 possible values:

  1. null: Funds have been captured, but are not yet ready to be paid out
  2. TIMESTAMP: A UTC timestamp that specifies when the funds will be available to be payout out. Once in the past, the Transfer will be eligible for inclusion in a batch Settlement.

Debit a Bank Account (ie eCheck)

Returns: Note eCheck transactions can be rejected for up to sixty days for a variety of reasons including insufficient funds, closed accounts, or a revoked authorization (i.e. dispute). Because of the 60 day threshold, Finix can configure a delay in the settling of an eCheck. For example, your application can implement a six day delay in order to feel more confident that the eCheck will not be rejected.

When a return occurs a Transfer of type REVERSAL with a subtype SYSTEM is automatically created and will negatively impact the future settlement.

curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -d '
    {
        "fee": 17868,
        "currency": "USD",
        "merchant_identity": "IDefa2LnXatPgxG5Tgs2fJfg",
        "tags": {
            "order_number": "21DFASJSAKAS"
        },
        "source": "PI9rtsXYNWgMghHqF92LYgoP",
        "amount": 178684,
        "processor": "DUMMY_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;
import java.util.Currency;

TransferForm form = TransferForm.builder()
        .amount(100L)
        .currency(Currency.getInstance("USD"))
        .source("PI2VnPygJVD5bTrXcHTJsDLf")
        .merchantIdentity("IDefa2LnXatPgxG5Tgs2fJfg")
        .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(
        "fee"=> 17868,
        "currency"=> "USD",
        "merchant_identity"=> "IDefa2LnXatPgxG5Tgs2fJfg",
        "tags"=> array(
            "order_number"=> "21DFASJSAKAS"
        ),
        "source"=> "PI9rtsXYNWgMghHqF92LYgoP",
        "amount"=> 178684,
        "processor"=> "DUMMY_V1"
    ));
$debit = $debit->save();



from finix.resources import Transfer

payout = Transfer(**
    {
        "fee": 17868,
        "currency": "USD",
        "merchant_identity": "IDefa2LnXatPgxG5Tgs2fJfg",
        "tags": {
            "order_number": "21DFASJSAKAS"
        },
        "source": "PI9rtsXYNWgMghHqF92LYgoP",
        "amount": 178684,
        "processor": "DUMMY_V1"
    }).save()

Finix::Transfer.new(
    {
        "fee"=> 17868,
        "currency"=> "USD",
        "merchant_identity"=> "IDefa2LnXatPgxG5Tgs2fJfg",
        "tags"=> {
            "order_number"=> "21DFASJSAKAS"
        },
        "source"=> "PI9rtsXYNWgMghHqF92LYgoP",
        "amount"=> 178684,
        "processor"=> "DUMMY_V1"
    }).save

Example Response:

{
  "id" : "TR942TB1eEF8ubys2ewSrThx",
  "amount" : 178684,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "PENDING",
  "trace_id" : "b5ce4daa-7517-4ae3-9690-88e4ae17ff7a",
  "currency" : "USD",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "source" : "PI9rtsXYNWgMghHqF92LYgoP",
  "destination" : null,
  "ready_to_settle_at" : null,
  "fee" : 17868,
  "statement_descriptor" : null,
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2020-07-01T23:40:32.86Z",
  "updated_at" : "2020-07-01T23:40:33.38Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR942TB1eEF8ubys2ewSrThx"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR942TB1eEF8ubys2ewSrThx/payment_instruments"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR942TB1eEF8ubys2ewSrThx/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR942TB1eEF8ubys2ewSrThx/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR942TB1eEF8ubys2ewSrThx/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI9rtsXYNWgMghHqF92LYgoP"
    },
    "fee_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
    }
  }
}

A Transfer representing a customer payment where funds are obtained from a bank account (i.e. ACH Debit, eCheck). These specific Transfers are distinguished by their type which return DEBIT.

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_identity string, required Identity 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
processor string, optional If the Application has more than one processor association, it’s required to pass the processor (e.g. DUMMY_V1)
idempotency_id string, optional A randomly generated value that you want associated with the request

Create Sale

Combines both the create authorization and capture authorization API calls into one.

curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -d '
    {
        "merchant": "MUgauiSgsLEEUDeL9d4aVMrb",
        "currency": "USD",
        "amount": 495243,
        "source": "PI2VnPygJVD5bTrXcHTJsDLf",
        "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("PI2VnPygJVD5bTrXcHTJsDLf")
        .merchantIdentity("IDefa2LnXatPgxG5Tgs2fJfg")
        .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"=> "MUgauiSgsLEEUDeL9d4aVMrb",
        "currency"=> "USD",
        "amount"=> 495243,
        "source"=> "PI2VnPygJVD5bTrXcHTJsDLf",
        "tags"=> array(
            "test"=> "sale"
        )
    ));
$debit = $debit->save();



from finix.resources import Transfer

payout = Transfer(**
    {
        "merchant": "MUgauiSgsLEEUDeL9d4aVMrb",
        "currency": "USD",
        "amount": 495243,
        "source": "PI2VnPygJVD5bTrXcHTJsDLf",
        "tags": {
            "test": "sale"
        }
    }).save()

Finix::Transfer.new(
    array(
        "merchant"=> "MUgauiSgsLEEUDeL9d4aVMrb",
        "currency"=> "USD",
        "amount"=> 495243,
        "source"=> "PI2VnPygJVD5bTrXcHTJsDLf",
        "tags"=> array(
            "test"=> "sale"
        )
    )).save

Example Response:

{
  "id" : "TR9db9Q7Yzt4E1iRABaWsyNF",
  "amount" : 495243,
  "tags" : {
    "test" : "sale"
  },
  "state" : "PENDING",
  "trace_id" : "a795971c-f396-49b0-a901-9e73b523ba1a",
  "currency" : "USD",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "source" : "PI2VnPygJVD5bTrXcHTJsDLf",
  "destination" : null,
  "ready_to_settle_at" : null,
  "fee" : 0,
  "statement_descriptor" : null,
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2020-07-01T23:40:35.00Z",
  "updated_at" : "2020-07-01T23:40:35.62Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDo9vwBv7TzhpJyzcSrdbtRE",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR9db9Q7Yzt4E1iRABaWsyNF"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDo9vwBv7TzhpJyzcSrdbtRE"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR9db9Q7Yzt4E1iRABaWsyNF/payment_instruments"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR9db9Q7Yzt4E1iRABaWsyNF/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR9db9Q7Yzt4E1iRABaWsyNF/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR9db9Q7Yzt4E1iRABaWsyNF/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf"
    },
    "fee_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
    }
  }
}

A Transfer representing a customer payment where funds are obtained from a payment card. These specific Transfers are distinguished by their type which return DEBIT.

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)

Fetch a Transfer


curl https://finix.sandbox-payments-api.com/transfers/TR942TB1eEF8ubys2ewSrThx \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba


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

Maybe<Transfer> response = api.transfers
    .id("TR942TB1eEF8ubys2ewSrThx")
    .get();

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

Transfer transferView = response.view();

<?php
use Finix\Resources\Transfer;

$transfer = Transfer::retrieve('TR942TB1eEF8ubys2ewSrThx');





from finix.resources import Transfer
transfer = Transfer.get(id="TR942TB1eEF8ubys2ewSrThx")

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

Example Response:

{
  "id" : "TR942TB1eEF8ubys2ewSrThx",
  "amount" : 178684,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "PENDING",
  "trace_id" : "b5ce4daa-7517-4ae3-9690-88e4ae17ff7a",
  "currency" : "USD",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "source" : "PI9rtsXYNWgMghHqF92LYgoP",
  "destination" : null,
  "ready_to_settle_at" : null,
  "fee" : 17868,
  "statement_descriptor" : "FIN*ACME ANCHORS",
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2020-07-01T23:40:32.86Z",
  "updated_at" : "2020-07-01T23:40:33.38Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR942TB1eEF8ubys2ewSrThx"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR942TB1eEF8ubys2ewSrThx/payment_instruments"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR942TB1eEF8ubys2ewSrThx/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR942TB1eEF8ubys2ewSrThx/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR942TB1eEF8ubys2ewSrThx/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI9rtsXYNWgMghHqF92LYgoP"
    },
    "fee_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
    }
  }
}

HTTP Request

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

URL Parameters

Parameter Description
:TRANSFER_ID ID of the Transfer

Refund a Debit


curl https://finix.sandbox-payments-api.com/transfers/TR942TB1eEF8ubys2ewSrThx/reversals \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -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('TR942TB1eEF8ubys2ewSrThx');
$refund = $debit->reverse(11);



from finix.resources import Transfer

transfer = Transfer.get(id="TR942TB1eEF8ubys2ewSrThx")
transfer.reverse(**
                  {
                  "refund_amount" : 100
                  }
                )
transfer = Finix::Transfer.retrieve(:id=> "TR942TB1eEF8ubys2ewSrThx")

refund = transfer.reverse(100)

Example Response:

{
  "id" : "TRqpBtvtVBednqaaiQDqNW2P",
  "amount" : 204725,
  "tags" : { },
  "state" : "SUCCEEDED",
  "trace_id" : "c5a74bdd-bcd8-4f23-b8b4-7f8ffd00ec51",
  "currency" : "USD",
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "source" : null,
  "destination" : "PI2VnPygJVD5bTrXcHTJsDLf",
  "ready_to_settle_at" : null,
  "fee" : 0,
  "statement_descriptor" : null,
  "type" : "REVERSAL",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2020-07-01T23:40:40.42Z",
  "updated_at" : "2020-07-01T23:40:40.80Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRqpBtvtVBednqaaiQDqNW2P"
    },
    "parent" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR9vg68NG1t84Gqb2fceYz4K"
    },
    "destination" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRqpBtvtVBednqaaiQDqNW2P/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 two subtypes indicating how they were created:

HTTP Request

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

URL Parameters

Parameter Description
:TRANSFER_ID ID of the original Transfer

Request Arguments

Field Type Description
refund_amount integer, required The amount of the refund in cents (Must be equal to or less than the amount of the original Transfer)

List all Transfers

curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba

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

Maybe<Page<Transfer>> request = api.transfers.get();

if (! request.succeeded()) {
    ApiError error = request.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 Transfers");
}

Page<Transfer> page = request.view();

<?php
use Finix\Resources\Transfer;

$transfers = Transfer::getPagination("/transfers");




from finix.resources import Transfer
transfer = Transfer.get()

transfers = Finix::Transfer.retrieve

Example Response:

{
  "_embedded" : {
    "transfers" : [ {
      "id" : "TR6TS3hMMBPz8Mftdm7w46iY",
      "amount" : 100,
      "tags" : { },
      "state" : "PENDING",
      "trace_id" : "62f456c7-e73e-4ff8-9367-974d391072d3",
      "currency" : "USD",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "source" : "PI2VnPygJVD5bTrXcHTJsDLf",
      "destination" : null,
      "ready_to_settle_at" : null,
      "fee" : 10,
      "statement_descriptor" : "FIN*ACME ANCHORS",
      "type" : "DEBIT",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2020-07-01T23:40:45.64Z",
      "updated_at" : "2020-07-01T23:40:45.86Z",
      "idempotency_id" : null,
      "merchant_identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
      "subtype" : "API",
      "_links" : {
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR6TS3hMMBPz8Mftdm7w46iY"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR6TS3hMMBPz8Mftdm7w46iY/payment_instruments"
        },
        "reversals" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR6TS3hMMBPz8Mftdm7w46iY/reversals"
        },
        "fees" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR6TS3hMMBPz8Mftdm7w46iY/fees"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR6TS3hMMBPz8Mftdm7w46iY/disputes"
        },
        "source" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf"
        },
        "fee_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
        }
      }
    }, {
      "id" : "TRqpBtvtVBednqaaiQDqNW2P",
      "amount" : 204725,
      "tags" : { },
      "state" : "SUCCEEDED",
      "trace_id" : "5d722174-2625-4932-a4a9-67944d0129e6",
      "currency" : "USD",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "source" : null,
      "destination" : "PI2VnPygJVD5bTrXcHTJsDLf",
      "ready_to_settle_at" : null,
      "fee" : 0,
      "statement_descriptor" : "FIN*ACME ANCHORS",
      "type" : "REVERSAL",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2020-07-01T23:40:40.42Z",
      "updated_at" : "2020-07-01T23:40:40.80Z",
      "idempotency_id" : null,
      "merchant_identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
      "subtype" : "API",
      "_links" : {
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRqpBtvtVBednqaaiQDqNW2P"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRqpBtvtVBednqaaiQDqNW2P/payment_instruments"
        },
        "parent" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR9vg68NG1t84Gqb2fceYz4K"
        },
        "destination" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf"
        },
        "fee_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
        }
      }
    }, {
      "id" : "TR9vg68NG1t84Gqb2fceYz4K",
      "amount" : 204725,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "CANCELED",
      "trace_id" : "b9cf4d4b-1a43-45c0-978e-7a40b10291ba",
      "currency" : "USD",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "source" : "PI2VnPygJVD5bTrXcHTJsDLf",
      "destination" : null,
      "ready_to_settle_at" : null,
      "fee" : 20473,
      "statement_descriptor" : "FIN*ACME ANCHORS",
      "type" : "DEBIT",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2020-07-01T23:40:39.00Z",
      "updated_at" : "2020-07-01T23:40:40.38Z",
      "idempotency_id" : null,
      "merchant_identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
      "subtype" : "API",
      "_links" : {
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR9vg68NG1t84Gqb2fceYz4K"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR9vg68NG1t84Gqb2fceYz4K/payment_instruments"
        },
        "reversals" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR9vg68NG1t84Gqb2fceYz4K/reversals"
        },
        "fees" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR9vg68NG1t84Gqb2fceYz4K/fees"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR9vg68NG1t84Gqb2fceYz4K/disputes"
        },
        "source" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf"
        },
        "fee_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
        }
      }
    }, {
      "id" : "TR9db9Q7Yzt4E1iRABaWsyNF",
      "amount" : 495243,
      "tags" : {
        "test" : "sale"
      },
      "state" : "PENDING",
      "trace_id" : "a795971c-f396-49b0-a901-9e73b523ba1a",
      "currency" : "USD",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "source" : "PI2VnPygJVD5bTrXcHTJsDLf",
      "destination" : null,
      "ready_to_settle_at" : null,
      "fee" : 0,
      "statement_descriptor" : "FIN*PAWNY CITY HALL",
      "type" : "DEBIT",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2020-07-01T23:40:35.00Z",
      "updated_at" : "2020-07-01T23:40:35.62Z",
      "idempotency_id" : null,
      "merchant_identity" : "IDo9vwBv7TzhpJyzcSrdbtRE",
      "subtype" : "API",
      "_links" : {
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR9db9Q7Yzt4E1iRABaWsyNF"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo9vwBv7TzhpJyzcSrdbtRE"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR9db9Q7Yzt4E1iRABaWsyNF/payment_instruments"
        },
        "reversals" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR9db9Q7Yzt4E1iRABaWsyNF/reversals"
        },
        "fees" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR9db9Q7Yzt4E1iRABaWsyNF/fees"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR9db9Q7Yzt4E1iRABaWsyNF/disputes"
        },
        "source" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf"
        },
        "fee_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
        }
      }
    }, {
      "id" : "TR942TB1eEF8ubys2ewSrThx",
      "amount" : 178684,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "PENDING",
      "trace_id" : "b5ce4daa-7517-4ae3-9690-88e4ae17ff7a",
      "currency" : "USD",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "source" : "PI9rtsXYNWgMghHqF92LYgoP",
      "destination" : null,
      "ready_to_settle_at" : null,
      "fee" : 17868,
      "statement_descriptor" : "FIN*ACME ANCHORS",
      "type" : "DEBIT",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2020-07-01T23:40:32.86Z",
      "updated_at" : "2020-07-01T23:40:33.38Z",
      "idempotency_id" : null,
      "merchant_identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
      "subtype" : "API",
      "_links" : {
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR942TB1eEF8ubys2ewSrThx"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR942TB1eEF8ubys2ewSrThx/payment_instruments"
        },
        "reversals" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR942TB1eEF8ubys2ewSrThx/reversals"
        },
        "fees" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR942TB1eEF8ubys2ewSrThx/fees"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR942TB1eEF8ubys2ewSrThx/disputes"
        },
        "source" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI9rtsXYNWgMghHqF92LYgoP"
        },
        "fee_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
        }
      }
    }, {
      "id" : "TR8UxsRkXex15TZpViQ72py8",
      "amount" : 292067,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "PENDING",
      "trace_id" : "e3ad5c0b-ee2f-46bb-81aa-56957fb8eefe",
      "currency" : "USD",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "source" : "PI2VnPygJVD5bTrXcHTJsDLf",
      "destination" : null,
      "ready_to_settle_at" : null,
      "fee" : 29207,
      "statement_descriptor" : "FIN*ACME ANCHORS",
      "type" : "DEBIT",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2020-07-01T23:40:30.87Z",
      "updated_at" : "2020-07-01T23:40:31.50Z",
      "idempotency_id" : "412dadf313a845f49f0c84858574d099",
      "merchant_identity" : "IDefa2LnXatPgxG5Tgs2fJfg",
      "subtype" : "API",
      "_links" : {
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR8UxsRkXex15TZpViQ72py8"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDefa2LnXatPgxG5Tgs2fJfg"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR8UxsRkXex15TZpViQ72py8/payment_instruments"
        },
        "reversals" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR8UxsRkXex15TZpViQ72py8/reversals"
        },
        "fees" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR8UxsRkXex15TZpViQ72py8/fees"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR8UxsRkXex15TZpViQ72py8/disputes"
        },
        "source" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI2VnPygJVD5bTrXcHTJsDLf"
        },
        "fee_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
        }
      }
    }, {
      "id" : "TR8LkJQRuSydr97bkH1sg27S",
      "amount" : 637402,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "PENDING",
      "trace_id" : "d80354e1-a756-4b0d-8ef1-67f0e8fba301",
      "currency" : "USD",
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "source" : "PI9rtsXYNWgMghHqF92LYgoP",
      "destination" : null,
      "ready_to_settle_at" : null,
      "fee" : 63740,
      "statement_descriptor" : "FIN*PAWNY CITY HALL",
      "type" : "DEBIT",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2020-07-01T23:40:28.94Z",
      "updated_at" : "2020-07-01T23:40:29.51Z",
      "idempotency_id" : null,
      "merchant_identity" : "IDo9vwBv7TzhpJyzcSrdbtRE",
      "subtype" : "API",
      "_links" : {
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        },
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR8LkJQRuSydr97bkH1sg27S"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDo9vwBv7TzhpJyzcSrdbtRE"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR8LkJQRuSydr97bkH1sg27S/payment_instruments"
        },
        "reversals" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR8LkJQRuSydr97bkH1sg27S/reversals"
        },
        "fees" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR8LkJQRuSydr97bkH1sg27S/fees"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR8LkJQRuSydr97bkH1sg27S/disputes"
        },
        "source" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI9rtsXYNWgMghHqF92LYgoP"
        },
        "fee_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPrATYzpomaTRtdo2BssRoGx"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 7
  }
}

HTTP Request

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

Webhooks

Webhooks allow you to build or set up integrations which subscribe to certain automated notifications (i.e. events) on the Finix API. When one of those events is triggered, we’ll send a HTTP POST payload to the webhook’s configured URL. Instead of forcing you to pull info from the API, webhooks push notifications to your configured URL endpoint. Webhooks are particularly useful for updating asynchronous state changes in Transfers, Merchant account provisioning, and listening for notifications of newly created Disputes.

In v2 of the settlement engine, the destination attribute will be deprecated from the Settlement Webhook event. The destination field will be returned in the transfer (type = created; entity = transfer) Webhook event.

Create a Webhook


curl https://finix.sandbox-payments-api.com/webhooks \
    -H "Content-Type: application/vnd.json+api" \
    -u US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -d '
                    {
                    "url" : "http://requestb.in/1jb5zu11"
                    }
                '

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

WebhookForm form = WebhookForm.builder()
    .url("http://requestb.in/1jb5zu11")
    .build();

Maybe<Webhook> request = api.webhooks.post(form);

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

<?php
use Finix\Resources\Webhook;

$webhook = new Webhook(
                    array(
                    "url" => "http=>//requestb.in/1jb5zu11"
                    )
                );
$webhook = $webhook->save();



from finix.resources import Webhook
webhook = Webhook(**
                    {
                    "url" : "http://requestb.in/1jb5zu11"
                    }
                ).save()

webhook = Finix::Webhook.new(
                    {
                    "url" => "http=>//requestb.in/1jb5zu11"
                    }
                ).save

Example Response:

{
  "id" : "WHbf4mjxCioff8abZUUBvVeT",
  "url" : "http://requestb.in/1jb5zu11",
  "enabled" : true,
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "created_at" : "2020-07-01T23:40:10.26Z",
  "updated_at" : "2020-07-01T23:40:10.26Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/webhooks/WHbf4mjxCioff8abZUUBvVeT"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    }
  }
}

HTTP Request

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

Request Arguments

Field Type Description
url string, required The HTTP or HTTPS url where the callbacks will be sent via POST request (max 120 characters)

Update Webhook

curl https://finix.sandbox-payments-api.com/webhooks/WHbf4mjxCioff8abZUUBvVeT \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba \
    -X PUT \
    -d '
                    {
                    "url" : "https://requestb.in/1bexhoq1"
                    }
        '


<?php





Example Response:

{
  "id" : "WHbf4mjxCioff8abZUUBvVeT",
  "url" : "https://requestb.in/1bexhoq1",
  "enabled" : true,
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "created_at" : "2020-07-01T23:40:10.26Z",
  "updated_at" : "2020-07-01T23:40:10.76Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/webhooks/WHbf4mjxCioff8abZUUBvVeT"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    }
  }
}

HTTP Request

PUT https://finix.sandbox-payments-api.com/webhooks/:WEBHOOK_ID

Fetch a Webhook




curl https://finix.sandbox-payments-api.com/webhooks/WHbf4mjxCioff8abZUUBvVeT \
    -H "Content-Type: application/vnd.json+api" \
    -u US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba


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

Maybe<Webhook> response = api.webhooks
        .id("WHbf4mjxCioff8abZUUBvVeT")
        .get();

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

<?php
use Finix\Resources\Webhook;

$webhook = Webhook::retrieve('WHbf4mjxCioff8abZUUBvVeT');





from finix.resources import Webhook
webhook = Webhook.get(id="WHbf4mjxCioff8abZUUBvVeT")

webhook = Finix::Webhook.retrieve(:id=> "WHbf4mjxCioff8abZUUBvVeT")


Example Response:

{
  "id" : "WHbf4mjxCioff8abZUUBvVeT",
  "url" : "https://requestb.in/1bexhoq1",
  "enabled" : true,
  "application" : "APs4YLHnwUEcBk1gn19VK3AA",
  "created_at" : "2020-07-01T23:40:10.26Z",
  "updated_at" : "2020-07-01T23:40:10.76Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/webhooks/WHbf4mjxCioff8abZUUBvVeT"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
    }
  }
}

HTTP Request

GET https://finix.sandbox-payments-api.com/webhooks/:WEBHOOK_ID

URL Parameters

Parameter Description
:WEBHOOK_ID ID of the Webhook

List all Webhooks

curl https://finix.sandbox-payments-api.com/webhooks/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  US5zMxCe9adjihGxkxwrkE7j:b564090b-4bd5-419a-9c05-3448eeab0eba

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

Maybe<Page<Webhook>> response = api.webhooks.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 Webhooks");
}

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

<?php
use Finix\Resources\Webhook;

$webhooks = Webhook::getPagination("/webhooks");




from finix.resources import Webhook
webhooks = Webhook.get()

webhooks = Finix::Webhook.retrieve

Example Response:

{
  "_embedded" : {
    "webhooks" : [ {
      "id" : "WHbf4mjxCioff8abZUUBvVeT",
      "url" : "https://requestb.in/1bexhoq1",
      "enabled" : true,
      "application" : "APs4YLHnwUEcBk1gn19VK3AA",
      "created_at" : "2020-07-01T23:40:10.26Z",
      "updated_at" : "2020-07-01T23:40:10.76Z",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/webhooks/WHbf4mjxCioff8abZUUBvVeT"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APs4YLHnwUEcBk1gn19VK3AA"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/webhooks?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 1
  }
}

HTTP Request

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

Sample Payloads

<?php


Created Authorization


{
  "type" : "created",
  "entity" : "authorization",
  "occurred_at" : "2016-07-06T08:15:21.734",
  "_embedded" : {
    "authorizations" : [ {
      "amount" : 100,
      "trace_id" : "5e157d2f-1362-4ab2-86af-3f97a8f28f0d",
      "created_at" : "2016-07-06T08:15:21.63Z",
      "source" : "PIeAkgVK9TPBnmyf6CSskv5i",
      "merchant_identity" : "IDradKrsCKMYJyj3VFKimKuy",
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "transfer" : null,
      "expires_at" : "2016-07-13T08:15:21.63Z",
      "updated_at" : "2016-07-06T08:15:21.65Z",
      "is_void" : false,
      "currency" : "USD",
      "id" : "AUfU8FU7RfgTmhfRagrF1RpS",
      "state" : "SUCCEEDED"
    } ]
  }
}

Created New Transfer

{
 "type" : "created",
  "entity" : "transfer",
  "occurred_at" : "2016-07-06T07:41:38.466",
  "_embedded" : {
    "transfers" : [ {
      "amount" : 100,
      "trace_id" : "e87b8ebc-177e-4e11-9cc3-6cfcfae7adc8",
      "fee" : 0,
      "destination" : "PIg3pCsoqrygp1gCvBNvfT3x",
      "created_at" : "2016-07-06T07:41:38.24Z",
      "source" : "PI2f1E5JVeQriDMeDpULnae3",
      "merchant_identity" : "IDoXe9ce6ztf6Pbpoq2WbeMt",
      "type" : "REVERSAL",
      "tags" : { },
      "statement_descriptor" : "PLD*POLLOS HERMANOS",
      "application" : "APdHz4LE8cNmJbbK7WW2egcg",
      "updated_at" : "2016-07-06T07:41:38.37Z",
      "currency" : "USD",</