Topics
API Endpoints
We provide two distinct base urls for making API requests depending on whether you would like to utilize the sandbox or production environments. These two environments are completely separate and share no information, including API credentials. For testing please use the Staging API and when you are ready to process live transactions use the Production endpoint.
Staging API:
https://api-staging.finix.ioProduction API:
https://api.finix.io
Authentication
# With CURL, just supply your username as basic auth (-u) in the header of each request as follows:
curl https://api-staging.finix.io/ \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99
/*
Add the following to your pom.xml (Maven file):
<dependency>
<groupId>io.finix.payments.processing.client</groupId>
<artifactId>finix</artifactId>
<version>1.0.0</version>
</dependency>
...
<repositories>
<repository>
<id>ossrh</id>
<url>https://oss.sonatype.org/content/repositories/</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>
*/
import io.finix.payments.ApiClient;
import io.finix.payments.views.*;
import io.finix.payments.forms.*;
//...
public static void main(String[] args) {
ApiClient api = ApiClient.builder()
.url("https://api-staging.finix.io")
.user("USsUqmy5wjayACofMgEUYhUj")
.password("00392938-e379-4c6b-bb60-f06bd382fb99")
.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://api-staging.finix.io',
"username" => 'USsUqmy5wjayACofMgEUYhUj',
"password" => '00392938-e379-4c6b-bb60-f06bd382fb99']
);
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://api-staging.finix.io", auth=("USsUqmy5wjayACofMgEUYhUj", "00392938-e379-4c6b-bb60-f06bd382fb99"))
# To download the Ruby gem:
# gem install finix
require 'finix'
Finix.configure(
:root_url => 'https://api-staging.finix.io',
:user=>'USsUqmy5wjayACofMgEUYhUj',
:password => '00392938-e379-4c6b-bb60-f06bd382fb99'
)
To communicate with the Finix API you’ll need to authenticate your requests
via http basic access authentication with a username and password, which you
can locate in your dashboard. If you do not have a dashboard feel free to test
the API with the credentials below:
Username:
USsUqmy5wjayACofMgEUYhUjPassword:
00392938-e379-4c6b-bb60-f06bd382fb99Application ID:
APhSYuXuvHHMGzkhnjumcmqB
Your Application is a resource that represents your web app. In other words,
any web service that connects buyers (i.e. customers) and sellers
(i.e. merchants).
Dashboard Overview
Below are videos of some of the common actions that you will be performing when using the dashboard.
Sign Up
If you haven’t signed up yet, please create a user account.
Create Production Account
Once you’ve played with a sandbox account, you’re ready to create a production Application.
Create an Identity for a Merchant
Simply select Identity on the sidebar, click “Create new identity”, and fill out the form with the Merchant's underwriting information.
Create a Bank Account for a Merchant
First, select Merchant on the sidebar, then click the “Payment instruments” tab. Next, click “Add bank account”, and fill out the form with the Merchant's bank account information.
Onboarding a New Merchant
To begin, select Merchant on the sidebar, then select your desired merchant. Next, click the “Processors” tab and click “Create verification”. Lastly, click “Create” to onboard the merchant.
View KYC Identity Verification
You are able to view important KYC information for Merchants by first selecting Merchants, then clicking your desired Merchant. This will take you the summary view of the Merchant you selected. Now just click the Processor tab and scroll down to the Verification container.
Approve Merchant
Want to approve a Merchant? Under review queues in the sidebar, you’ll see Merchants- a list of all pending Merchants under your Application. You have the ability to approve one by one, or approve an entire page.
Enable or Disable Processing Functionality
Enable or disable Merchant's ability to create new Transfers and Authorizations by navigating to Merchants on the sidebar. Then select your desired Merchant and click the Processors tab. Finally, click the edit button and configure a Merchant's processing ability to your liking.
Enable or Disable Settlement Functionality
Disable or disable Merchant's ability to create new Settlementsby navigating to Merchants on the sidebar. Then select your desired Merchant and click the Processors tab. Finally, click the edit button and configure a Merchant's settlement ability to your liking.
Edit Fees & Interchange Plus
Want to edit an Application's fixed fee, basis points, ACH fee, or toggle interchange plus? First, click Application on the sidebar and then click the Processors tab. Once you pick which processor you want to configure, you’ll be presented with a modal allowing you edit fees and interchange plus.
Enable CVV & AVS
Finix offers you the ability to configure Address Verification System (AVS) and CVV rules as part of our fraud risk system, to help you ensure that transactions are being made by only authorized users. How? Simply click Application on the sidebar, then click the Processors tab. Select the desired processor, and then click edit on the Security configuration.
Approve a Settlement
Want to approve a Settlement? Under review queues in the sidebar, you’ll see Settlements- a list of all pending Settlements under your Application. You have the ability to approve one by one, or approve an entire page.
Upload Dispute Evidence
Have evidence for your dispute? Click Disputes, select the desired dispute, then scroll down to the Evidence container, and click Upload File.
Errors
| HTTP Code | Meaning |
|---|---|
| 400 | Bad Request – You’ve attemped an invalid request |
| 401 | Unauthorized – You have used the incorrect API key |
| 402 | Upstream Processor Error – Errors caused by 3rd party service |
| 404 | Not Found – The specified resource could not be found |
| 422 | Unprocessable Entity – The parameters were valid but the request failed. The error is usually some misunderstanding of various steps that have to be executed in order (e.g. attempting to initiate a transfer on behalf of a merchant that has not yet been approved) |
| 500 | Internal Server Error – We had a problem with our server. Try again later. |
Below are the different error values that the messages attribute will return for Push to Card.
| Error Code | Messages |
|---|---|
| REFER_TO_CARD_ISSUER | Please contact card issuer for more information. |
| INVALID_MERCHANT | Merchant not permitted for this transaction type |
| PICK_UP_CARD_NO_FRAUD | Please contact card issuer for more information. |
| DO_NOT_HONOR | Please contact card issuer for more information. |
| ERROR | Please attempt transaction again but if it still cannot be processed try again at a later time |
| PICK_UP_CARD_FRAUD_ACCOUNT | Please contact card issuer for more information. |
| INVALID_TRANSACTION | Issuing bank does not support this transaction type on this card. Please contact card issuer for more information. |
| INVALID_AMOUNT_OR_CURRENCY | Transaction violates network amount limit. |
| INVALID_ACCOUNT_NUMBER | The account number does not exist. Please make sure the account number is correct or contact your issuer. |
| NO_SUCH_ISSUER | The issuer can not be found. Please check card number to ensure it is valid. |
| RE_ENTER_TRANSACTION | Please attempt transaction again and contact card issuer if it still cannot be processed. |
| NO_ACTION_TAKEN | Please contact card issuer for more information. |
| UNABLE_TO_LOCATE_RECORD | The account number does not exist. Please make sure the account number is correct or contact your issuer. |
| FILE_TEMPORARILY_NOT_AVAILABLE | Please contact card issuer for more information. |
| NO_CREDIT_ACCOUNT | Issuer has declined the transaction because the card is not a credit account. Please try another card. |
| LOST_CARD_PICK_UP_FRAUD_ACCOUNT | Please contact card issuer for more information. |
| STOLEN_CARD_PICK_UP_FRAUD_ACCOUNT | Please contact card issuer for more information. |
| NOT_SUFFICIENT_FUNDS | Card issuer has declined the transaction as it does not have sufficient funds. |
| NO_CHECKING_ACCOUNT | The card is not tied to a checking account and thus cannot be processed. Please try another card. |
| NO_SAVINGS_ACCOUNT | The card is not tied to a savings account and thus cannot be processed. Please try another card. |
| EXPIRED_CARD | The expiration date is expired or missing. Please correct and try again. |
| INCORRECT_PIN | The PIN is invalid or missing. Please try again with the correct PIN. |
| TRANSACTION_NOT_PERMITTED | Transaction not permitted to cardholder. Please contact card issuer for more information. |
| SUSPECTED_FRAUD | Please contact card issuer for more information. |
| EXCEEDS_APPROVAL_AMOUNT_LIMIT | Transaction violates issuer amount limit. Please contact card issuer for more information or try with another card. |
| RESTRICTED_CARD | Card not supported in this region or country. Please contact card issuer for more information. |
| TRANSACTION_DOES_NOT_FULFILL_AML_REQUIREMENT | This transaction does not fulfill compliance requirements and cannot be processed. |
| EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT | Please attempt with another card or contact card issuer for more information. |
| ALLOWABLE_NUMBER_OF_PIN_ENTRY_TRIES_EXCEEDED | The maximum permitted number of PIN entry attempts has been exceeded. Please use another payment method. |
| CRYPTOGRAPHIC_ERROR_FOUND_IN_PIN | The supplied PIN is invalid. |
| NEGATIVE_RESULTS | Invalid security code. |
| CANNOT_VERIFY_PIN | The PIN is invalid or missing. Please try again with the correct PIN. |
| ISSUER_INOPERATIVE | Please attempt transaction again and contact card issuer if it still cannot be processed. |
| FINANCIAL_INSTITUTION_NOT_FOUND | The issuer can not be found. Please check card number to ensure it is valid. |
| TRANSACTION_NOT_COMPLETED_LAW_VIOLATION | The transaction cannot be completed because it violates a law. |
| SURCHARGE_AMOUNT_NOT_SUPPORTED | The supplied surcharge amount is not supported by the issuer. |
| TRANSACTION_AMOUNT_EXCEEDS_PREAUTHORIZED_APPROVAL_AMOUNT | Transaction violates amount limit. |
| CARD_AUTHENTICATION_FAILED | Please contact card issuer for more information. |
| STOP_PAYMENT_ORDER | Please contact card issuer for more information. |
Idempotency Requests
You’ll notice the authorization and transfer object have a field named idempotency_id which ensures the API request is only performed once. Why is this important? We’ve all experienced a hanging request while on a checkout page and feared that if we refresh or submit the payment again we’ll be charged twice. With Finix, we remove the ambiguity by having the user generate a unique idempotency_id and sending it with the normal payload. If the user attempts a request with the same idempotency_id, the response will raise an exception. Now you can rest assured that when you create an authorization or debit a bank account that the user will be protected from potential network issues by simply passing idempotency_id in body of the request.
Tags
All Finix objects (i.e. Authorization, Application, Identity, Merchant, Payment Instrument, Settlement, Transfer) include a tags attribute that allows the user to include key-value metadata to their object. For example, when creating a Payment Instrument, you may want to include more data about the card. Simply pass a custom key and value, such as “card-type”: “business card”. Or when creating an Authorization, you may want to include specific information about the transaction, such as a unique ID or additional information about the transaction.
Testing for specific responses and errors
Before taking your integration to production, use the information below to test it thoroughly. Please note, once a Payment Instrument has been flagged with AVS or CVC, it will continue to throw the respective error.
| Amount | Description |
|---|---|
100 |
Success amount |
102 |
Failed amount |
888888 |
Disputed amount |
193 |
Insufficient funds amount |
194 |
Invalid card number amount |
889986 |
AVS total failure amount |
889987 |
CVC failure amount |
| Card | Description |
|---|---|
4000000000000036 |
Payment card AVS total failure |
4000000000000127 |
Payment card CVC failure |
Below are the different error codes and message values that are returned for Push to Card.
| Scenario | number | security_code | address.line1 | postal_code | region | city | country | address_verification_results | cvv2_result_code |
|---|---|---|---|---|---|---|---|---|---|
| Successful push to card payout (credit card) | 4957030420210454 | 999 | 801 Metro Center Blv | 94404 | CA | San Francisco | USA | Y | M |
| Successful push to card payout (debit card) | 4895142232120006 | 022 | 900 Metro Center Blv | 94404 | CA | San Francisco | USA | M | M |
| Invalid account number | 4957040000000001 | 999 | 801 Metro Center Blv | 94404 | CA | San Francisco | USA | I | P |
| Invalid Zip Code and CVV2 values | 4957030420210488 | 227 | 900 Metro Center Blv | 94402 | CA | San Francisco | USA | A | N |
| Invalid CVV2 value | 4957030420210496 | 664 | 900 Metro Center Blv | 94404 | CA | San Francisco | USA | Y | N |
| Invalid Address, Zip code and CVV2 values | 4957030420210504 | 322 | 901 Metro Center Blv | 94404 | CA | San Francisco | USA | Z | N |
Guides
Overview
These guides provide a collection of resources for utilizing the Finix API and its client libraries. We offer a number of client libraries for interfacing with the API, and you can view example code snippets for each in the dark area to the right.
Authentication: Learn how to properly authenticate and interface with the API.
Getting Started: A step-by-step guide demonstrating the basic workflow of charging a card. This guide will walk you through provisioning merchant accounts, tokenizing cards, charging those cards, and finally settling (i.e. payout) those funds out to your merchants.
Embedded Tokenization: This guide explains how to properly tokenize cards in production via our embedded iframe.
Tokenization with Hosted Fields: This guide explains how to properly tokenize cards in production via hosted fields.
Getting Started
Step 1: Create an Identity for a Merchant
curl https://api-staging.finix.io/identities \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"tags": {
"Studio Rating": "4.7"
},
"entity": {
"last_name": "Sunkhronos",
"max_transaction_amount": 12000000,
"has_accepted_credit_cards_previously": true,
"default_statement_descriptor": "Golds Gym",
"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": "Golds Gym",
"principal_percentage_ownership": 50,
"email": "user@example.org",
"mcc": "0742",
"phone": "1234567890",
"business_name": "Golds Gym",
"tax_id": "123456789",
"business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
"business_phone": "+1 (408) 756-4497",
"dob": {
"year": 1978,
"day": 27,
"month": 6
},
"url": "www.GoldsGym.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"=> "Golds Gym",
"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"=> "Golds Gym",
"principal_percentage_ownership"=> 50,
"email"=> "user@example.org",
"mcc"=> "0742",
"phone"=> "1234567890",
"business_name"=> "Golds Gym",
"tax_id"=> "123456789",
"business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP",
"business_phone"=> "+1 (408) 756-4497",
"dob"=> array(
"year"=> 1978,
"day"=> 27,
"month"=> 6
),
"url"=> "www.GoldsGym.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": "Golds Gym",
"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": "Golds Gym",
"principal_percentage_ownership": 50,
"email": "user@example.org",
"mcc": "0742",
"phone": "1234567890",
"business_name": "Golds Gym",
"tax_id": "123456789",
"business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
"business_phone": "+1 (408) 756-4497",
"dob": {
"year": 1978,
"day": 27,
"month": 6
},
"url": "www.GoldsGym.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"=> "Golds Gym",
"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"=> "Golds Gym",
"principal_percentage_ownership"=> 50,
"email"=> "user@example.org",
"mcc"=> "0742",
"phone"=> "1234567890",
"business_name"=> "Golds Gym",
"tax_id"=> "123456789",
"business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP",
"business_phone"=> "+1 (408) 756-4497",
"dob"=> {
"year"=> 1978,
"day"=> 27,
"month"=> 6
},
"url"=> "www.GoldsGym.com",
"annual_card_volume"=> 12000000
}
}).save
Example Response:
{
"id" : "IDpSEHq3qRRSxvqzUkipefAM",
"entity" : {
"title" : "CEO",
"first_name" : "dwayne",
"last_name" : "Sunkhronos",
"email" : "user@example.org",
"business_name" : "Golds Gym",
"business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
"doing_business_as" : "Golds Gym",
"phone" : "1234567890",
"business_phone" : "+1 (408) 756-4497",
"personal_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"business_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 8",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"mcc" : "0742",
"dob" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"max_transaction_amount" : 12000000,
"amex_mid" : null,
"discover_mid" : null,
"url" : "www.GoldsGym.com",
"annual_card_volume" : 12000000,
"has_accepted_credit_cards_previously" : true,
"incorporation_date" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"principal_percentage_ownership" : 50,
"short_business_name" : null,
"ownership_type" : "PRIVATE",
"tax_id_provided" : true,
"business_tax_id_provided" : true,
"default_statement_descriptor" : "Golds Gym"
},
"tags" : {
"Studio Rating" : "4.7"
},
"created_at" : "2018-04-26T00:45:15.68Z",
"updated_at" : "2018-04-26T00:45:15.68Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"verifications" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/verifications"
},
"merchants" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/merchants"
},
"settlements" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/settlements"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/transfers"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/payment_instruments"
},
"disputes" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/disputes"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}
Before we can begin charging cards we’ll need to provision a Merchant account for your seller. This requires 3-steps, which we’ll go into greater detail in the next few sections:
First, create an
Identityresource with the merchant’s underwriting and identity verification informationPOST https://api-staging.finix.io/identities/Second, create a
Payment Instrumentrepresenting the merchant’s bank account where processed funds will be settled (i.e. deposited)POST https://api-staging.finix.io/payment_instruments/Finally, provision the
MerchantaccountPOST https://api-staging.finix.io/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://api-staging.finix.io/identities
Business-specific Request Arguments
| Field | Type | Description |
|---|---|---|
| business_name | string, required | Merchant’s full legal business name (If INDIVIDUAL_SOLE_PROPRIETORSHIP, please input first name, Full legal last name and middle initial; max 120 characters) |
| doing_business_as | string, required | Alternate name of the business. If no other name is used please use the same value for business_name (max 60 characters) |
| business_type | string, required | Please select one of the following values: INDIVIDUAL_SOLE_PROPRIETORSHIP, CORPORATION, LIMITED_LIABILITY_COMPANY, PARTNERSHIP, ASSOCIATION_ESTATE_TRUST, TAX_EXEMPT_ORGANIZATION, INTERNATIONAL_ORGANIZATION, GOVERNMENT_AGENCY |
| business_tax_id | string, required | Nine digit Tax Identification Number (TIN), Employer Identification Number (EIN) or if the business_type is INDIVIDUAL_SOLE_PROPRIETORSHIP and a Tax ID is not available, the principal’s Social Security Number (SSN) |
| url | string, required | Merchant’s publicly available website (max 100 characters) |
| business_phone | string, required | Customer service phone number where the merchant can be reached (max 10 characters) |
| incorporation_date | object, required | Date company was founded (See below for a full list of the child attributes) |
| business_address | object, required | Primary address for the legal entity (Full description of child attributes below) |
| ownership_type | string, required | Values can be either PUBLIC to indicate a publicly traded company or PRIVATE for privately held businesses |
Principal-specific Request Arguments
(i.e. authorized representative or primary contact responsible for the account)
| Field | Type | Description |
|---|---|---|
| first_name | string, required | Full legal first name of the merchant’s principal representative (max 20 characters) |
| last_name | string, required | Full legal last name of the merchant’s principal representative (max 20 characters) |
| title | string, required | Principal’s corporate title or role (i.e. Chief Executive Officer, CFO, etc.; max 60 characters) |
| principal_percentage_ownership | integer, required | Percentage of company owned by the principal (min 0; max 100) |
| tax_id | string, required | Nine digit Social Security Number (SSN) for the principal |
| dob | object, required | Principal’s date of birth (Full description of child attributes below) |
| phone | string, required | Principal’s phone number (max 10 characters) |
| string, required | Principal’s email address where they can be reached (max 100 characters) | |
| personal_address | object, required | Principal’s personal home address. This field is used for identity verification purposes (Full description of child attributes below) |
Processing-specific Request Arguments
| Field | Type | Description |
|---|---|---|
| default_statement_descriptor | string, required | Billing descriptor displayed on the buyer’s bank or card statement (Length must be between 1 and 20 characters) |
| annual_card_volume | integer, required | Approximate annual credit card sales expected to be processed in cents by this merchant (max 23 characters) |
| max_transaction_amount | integer, required | Maximum amount that can be transacted for a single transaction in cents (max 12 characters) |
| mcc | string, required | Merchant Category Code (MCC) that this merchant will be classified under |
| has_accepted_credit_cards_previously | boolean, optional | Defaults to false if not passed |
Address-object Request Arguments
| Field | Type | Description |
|---|---|---|
| line1 | string, required | First line of the address (max 60 characters) |
| line2 | string, optional | Second line of the address (max 60 characters) |
| city | string, required | City (max 20 characters) |
| region | string, required | 2-letter State code |
| postal_code | string, required | Zip or Postal code (max 7 characters) |
| country | string, required | 3-Letter Country code |
Incorporation Date-object Request Arguments
| Field | Type | Description |
|---|---|---|
| day | integer, required | Day business was incorporated (between 1 and 31) |
| month | integer, required | Month business was incorporated (between 1 and 12) |
| year | integer, required | Year business was incorporated (4-digit) |
DOB-object Request Arguments
| Field | Type | Description |
|---|---|---|
| day | integer, required | Day of birth (between 1 and 31) |
| month | integer, required | Month of birth (between 1 and 12) |
| year | integer, required | Year of birth (4-digit) |
Step 2: Tokenize a Bank Account for Funding your Merchant
curl https://api-staging.finix.io/payment_instruments \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"account_type": "SAVINGS",
"name": "Fran Lemke",
"tags": {
"Bank Account": "Company Account"
},
"country": "USA",
"bank_code": "123123123",
"account_number": "123123123",
"type": "BANK_ACCOUNT",
"identity": "IDpSEHq3qRRSxvqzUkipefAM"
}'
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("IDpSEHq3qRRSxvqzUkipefAM")
.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('IDpSEHq3qRRSxvqzUkipefAM');
$bank_account = new BankAccount(
array(
"account_type"=> "SAVINGS",
"name"=> "Fran Lemke",
"tags"=> array(
"Bank Account"=> "Company Account"
),
"country"=> "USA",
"bank_code"=> "123123123",
"account_number"=> "123123123",
"type"=> "BANK_ACCOUNT",
"identity"=> "IDpSEHq3qRRSxvqzUkipefAM"
));
$bank_account = $identity->createBankAccount($bank_account);
from finix.resources import BankAccount
bank_account = BankAccount(**
{
"account_type": "SAVINGS",
"name": "Fran Lemke",
"tags": {
"Bank Account": "Company Account"
},
"country": "USA",
"bank_code": "123123123",
"account_number": "123123123",
"type": "BANK_ACCOUNT",
"identity": "IDpSEHq3qRRSxvqzUkipefAM"
}).save()
bank_account = Finix::BankAccount.new(
{
"account_type"=> "SAVINGS",
"name"=> "Fran Lemke",
"tags"=> {
"Bank Account"=> "Company Account"
},
"country"=> "USA",
"bank_code"=> "123123123",
"account_number"=> "123123123",
"type"=> "BANK_ACCOUNT",
"identity"=> "IDpSEHq3qRRSxvqzUkipefAM"
}).save
Example Response:
{
"id" : "PI4aYS5haEPAit9L3j9hTar1",
"fingerprint" : "FPR-1215770130",
"tags" : {
"Bank Account" : "Company Account"
},
"bank_code" : "123123123",
"country" : "USA",
"masked_account_number" : "XXXXX3123",
"name" : "Fran Lemke",
"account_type" : "SAVINGS",
"created_at" : "2018-04-26T00:45:20.03Z",
"updated_at" : "2018-04-26T00:45:20.03Z",
"instrument_type" : "BANK_ACCOUNT",
"type" : "BANK_ACCOUNT",
"currency" : "USD",
"identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1/transfers"
},
"verifications" : {
"href" : "https://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1/verifications"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
}
}
}
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://api-staging.finix.io/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://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/merchants \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-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('IDpSEHq3qRRSxvqzUkipefAM');
$merchant = $identity->provisionMerchantOn(new Merchant());
from finix.resources import Identity
from finix.resources import Merchant
identity = Identity.get(id="IDpSEHq3qRRSxvqzUkipefAM")
merchant = identity.provision_merchant_on(Merchant())
identity = Finix::Identity.retrieve(:id=>"IDpSEHq3qRRSxvqzUkipefAM")
merchant = identity.provision_merchant
Example Response:
{
"id" : "MUwHAaGeNNmW5JF6oMjzWdDQ",
"identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"verification" : "VI8FBZnMgGReYM6KnCncEbMR",
"merchant_profile" : "MP4xt1veRZLAjbhAHdrZGqrb",
"processor" : "DUMMY_V1",
"processing_enabled" : false,
"settlement_enabled" : false,
"creating_transfer_from_report_enabled" : false,
"tags" : { },
"created_at" : "2018-04-26T00:45:21.07Z",
"updated_at" : "2018-04-26T00:45:21.07Z",
"onboarding_state" : "PROVISIONING",
"processor_details" : { },
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"verifications" : {
"href" : "https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ/verifications"
},
"merchant_profile" : {
"href" : "https://api-staging.finix.io/merchant_profiles/MP4xt1veRZLAjbhAHdrZGqrb"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"verification" : {
"href" : "https://api-staging.finix.io/verifications/VI8FBZnMgGReYM6KnCncEbMR"
}
}
}
Now that we’ve associated a Payment Instrument with our seller’s Identity
we’re ready to provision a Merchant account. This is the last step before you
can begin processing on their behalf. Luckily you’ve already done most of the
heavy lifting. Just make one final POST request, and you’ll be returned a
Merchant resource. Take a second to inspect this newly created resource,
particularly the onboarding_state, which can have 3 potential states that
indicate its ability to process and settle funds:
PROVISIONING: Request is pending (state will typically change after two minutes)- processing_enabled: False
- settlement_enabled: False
APPROVED: Merchant has been approved and can begin processing- processing_enabled: True
- settlement_enabled: True
REJECTED: Merchant was rejected by the processor either because the information collected was invalid or it failed one of a number of regulatory and/or compliance checks (e.g. KYC, OFAC or MATCH)- processing_enabled: False
- settlement_enabled: False
HTTP Request
POST https://api-staging.finix.io/identities/:IDENTITY_ID/merchants
URL Parameters
| Parameter | Description |
|---|---|
| :IDENTITY_ID | ID of the Identity |
Step 4: Create an Identity for a Buyer
curl https://api-staging.finix.io/identities \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"tags": {
"key": "value"
},
"entity": {
"phone": "7145677613",
"first_name": "Alex",
"last_name": "Curry",
"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"=> "Alex",
"last_name"=> "Curry",
"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": "Alex",
"last_name": "Curry",
"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"=> "Alex",
"last_name"=> "Curry",
"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" : "IDuYo7qjbtB6kMVeebe4Z6NN",
"entity" : {
"title" : null,
"first_name" : "Alex",
"last_name" : "Curry",
"email" : "therock@gmail.com",
"business_name" : null,
"business_type" : null,
"doing_business_as" : null,
"phone" : "7145677613",
"business_phone" : null,
"personal_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"business_address" : null,
"mcc" : null,
"dob" : null,
"max_transaction_amount" : 0,
"amex_mid" : null,
"discover_mid" : null,
"url" : null,
"annual_card_volume" : 0,
"has_accepted_credit_cards_previously" : false,
"incorporation_date" : null,
"principal_percentage_ownership" : null,
"short_business_name" : null,
"ownership_type" : null,
"tax_id_provided" : false,
"business_tax_id_provided" : false,
"default_statement_descriptor" : null
},
"tags" : {
"key" : "value"
},
"created_at" : "2018-04-26T00:45:22.21Z",
"updated_at" : "2018-04-26T00:45:22.21Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN"
},
"verifications" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/verifications"
},
"merchants" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/merchants"
},
"settlements" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/settlements"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/transfers"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/payment_instruments"
},
"disputes" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/disputes"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}
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://api-staging.finix.io/identities
Request Arguments
| Field | Type | Description |
|---|---|---|
| first_name | string, optional | First name |
| last_name | string, optional | Last name |
| string, optional | ||
| phone | string, optional | Phone number |
| tags | object, optional | Key value pair for annotating custom meta data (e.g. order numbers) |
| personal_address | object, optional | Customers shipping address or billing address (Full description of child attributes below) |
Address-object Request Arguments
| Field | Type | Description |
|---|---|---|
| line1 | string, required | First line of the address (max 60 characters) |
| line2 | string, optional | Second line of the address (max 60 characters) |
| city | string, required | City (max 20 characters) |
| region | string, required | 2-letter State code |
| postal_code | string, required | Zip or Postal code (max 7 characters) |
| country | string, required | 3-Letter Country code |
Step 5: Tokenize a Card
curl https://api-staging.finix.io/payment_instruments \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"name": "Michae Lopez",
"expiration_year": 2020,
"tags": {
"card_name": "Business Card"
},
"number": "4957030420210454",
"expiration_month": 12,
"address": {
"city": "San Mateo",
"country": "USA",
"region": "CA",
"line2": "Apartment 7",
"line1": "741 Douglass St",
"postal_code": "94114"
},
"security_code": "112",
"type": "PAYMENT_CARD",
"identity": "IDuYo7qjbtB6kMVeebe4Z6NN"
}'
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("IDpSEHq3qRRSxvqzUkipefAM")
.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('IDpSEHq3qRRSxvqzUkipefAM');
$card = new PaymentCard(
array(
"name"=> "Michae Lopez",
"expiration_year"=> 2020,
"tags"=> array(
"card_name"=> "Business Card"
),
"number"=> "4957030420210454",
"expiration_month"=> 12,
"address"=> array(
"city"=> "San Mateo",
"country"=> "USA",
"region"=> "CA",
"line2"=> "Apartment 7",
"line1"=> "741 Douglass St",
"postal_code"=> "94114"
),
"security_code"=> "112",
"type"=> "PAYMENT_CARD",
"identity"=> "IDuYo7qjbtB6kMVeebe4Z6NN"
));
$card = $identity->createPaymentCard($card);
from finix.resources import PaymentCard
card = PaymentCard(**
{
"name": "Michae Lopez",
"expiration_year": 2020,
"tags": {
"card_name": "Business Card"
},
"number": "4957030420210454",
"expiration_month": 12,
"address": {
"city": "San Mateo",
"country": "USA",
"region": "CA",
"line2": "Apartment 7",
"line1": "741 Douglass St",
"postal_code": "94114"
},
"security_code": "112",
"type": "PAYMENT_CARD",
"identity": "IDuYo7qjbtB6kMVeebe4Z6NN"
}).save()
card = Finix::PaymentCard.new(
{
"name"=> "Michae Lopez",
"expiration_year"=> 2020,
"tags"=> {
"card_name"=> "Business Card"
},
"number"=> "4957030420210454",
"expiration_month"=> 12,
"address"=> {
"city"=> "San Mateo",
"country"=> "USA",
"region"=> "CA",
"line2"=> "Apartment 7",
"line1"=> "741 Douglass St",
"postal_code"=> "94114"
},
"security_code"=> "112",
"type"=> "PAYMENT_CARD",
"identity"=> "IDuYo7qjbtB6kMVeebe4Z6NN"
}).save
Example Response:
{
"id" : "PIss82nFMq4zmbLZgtrMhpQW",
"fingerprint" : "FPR16393928",
"tags" : {
"card_name" : "Business Card"
},
"expiration_month" : 12,
"expiration_year" : 2020,
"bin" : "495703",
"last_four" : "0454",
"brand" : "VISA",
"card_type" : "UNKNOWN",
"name" : "Michae Lopez",
"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" : "2018-04-26T00:45:26.14Z",
"updated_at" : "2018-04-26T00:45:26.14Z",
"instrument_type" : "PAYMENT_CARD",
"type" : "PAYMENT_CARD",
"currency" : "USD",
"identity" : "IDuYo7qjbtB6kMVeebe4Z6NN",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/transfers"
},
"verifications" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/verifications"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN"
},
"updates" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/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://api-staging.finix.io/payment_instruments
Request Arguments
| Field | Type | Description |
|---|---|---|
| identity | string, required | ID of the Identity that the card should be associated |
| type | string, required | Type of Payment Instrument (for cards input PAYMENT_CARD) |
| number | string, required | Credit card account number |
| security_code | string, optional | The 3-4 digit security code for the card (i.e. CVV code) |
| expiration_month | integer, required | Expiration month (e.g. 12 for December) |
| expiration_year | integer, required | 4-digit expiration year |
| name | string, optional | Full name of the registered card holder |
| address | object, optional | Billing address (Full description of child attributes below) |
Address-object Request Arguments
| Field | Type | Description |
|---|---|---|
| line1 | string, required | First line of the address (max 60 characters) |
| line2 | string, optional | Second line of the address (max 60 characters) |
| city | string, required | City (max 20 characters) |
| region | string, required | 2-letter State code |
| postal_code | string, required | Zip or Postal code (max 7 characters) |
| country | string, required | 3-Letter Country code |
Step 6: Create an Authorization
curl https://api-staging.finix.io/authorizations \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"merchant_identity": "IDpSEHq3qRRSxvqzUkipefAM",
"currency": "USD",
"amount": 100,
"source": "PIss82nFMq4zmbLZgtrMhpQW",
"tags": {
"order_number": "21DFASJSAKAS"
}
}'
import io.finix.payments.ApiClient;
import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
AuthorizationCreateForm formCreateAuthorization = AuthorizationCreateForm.builder()
.amount(10000L)
.merchantIdentity("IDpSEHq3qRRSxvqzUkipefAM")
.source("PIss82nFMq4zmbLZgtrMhpQW")
.build();
Maybe<Authorization> response = api.authorizations.post(formCreateAuthorization);
if (! response.succeeded()) {
ApiError error = response.error();
System.out.println(error.getMessage());
throw new RuntimeException("API error attempting to creating Authorization");
}
Authorization authorization = response.view();
<?php
use Finix\Resources\Authorization;
$authorization = new Authorization(
array(
"merchant_identity"=> "IDpSEHq3qRRSxvqzUkipefAM",
"currency"=> "USD",
"amount"=> 100,
"source"=> "PIss82nFMq4zmbLZgtrMhpQW",
"tags"=> array(
"order_number"=> "21DFASJSAKAS"
)
));
$authorization = $authorization->save();
from finix.resources import Authorization
authorization = Authorization(**
{
"merchant_identity": "IDpSEHq3qRRSxvqzUkipefAM",
"currency": "USD",
"amount": 100,
"source": "PIss82nFMq4zmbLZgtrMhpQW",
"tags": {
"order_number": "21DFASJSAKAS"
}
}).save()
authorization = Finix::Authorization.new(
{
"merchant_identity"=> "IDpSEHq3qRRSxvqzUkipefAM",
"currency"=> "USD",
"amount"=> 100,
"source"=> "PIss82nFMq4zmbLZgtrMhpQW",
"tags"=> {
"order_number"=> "21DFASJSAKAS"
}
}).save
Example Response:
{
"id" : "AUf7d2dGYeQEyMsrKMuQimTX",
"amount" : 100,
"tags" : {
"order_number" : "21DFASJSAKAS"
},
"state" : "SUCCEEDED",
"currency" : "USD",
"transfer" : null,
"messages" : [ ],
"raw" : null,
"created_at" : "2018-04-26T00:45:31.64Z",
"updated_at" : "2018-04-26T00:45:31.69Z",
"trace_id" : "d009e729-1e42-461a-b9bc-32da02b7e915",
"source" : "PIss82nFMq4zmbLZgtrMhpQW",
"merchant_identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"is_void" : false,
"expires_at" : "2018-05-03T00:45:31.64Z",
"idempotency_id" : null,
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/authorizations/AUf7d2dGYeQEyMsrKMuQimTX"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"merchant_identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
}
}
}
At this point we’ve created resources representing the merchant, the buyer, and the buyer’s card.
Next you’ll need to create an Authorization. What’s a Authorization? Glad
you asked! An Authorization (also known as a card hold) reserves a specific
amount on a card to be captured (i.e. debited) at a later point, usually within
7 days. When an Authorization is captured it produces a Transfer resource.
To create an Authorization we’ll supply the buyer’s Payment Instrument ID
as the source field and the seller’s Identity ID in the merchant_identity field.
Note that the amount field is in cents.
Simple enough, right? You’ll also want to store the ID from that Authorization
for your records so that we can capture those funds in the next step.
Authorizations have two possible states SUCCEEDED and FAILED. If the Authorization
has succeeded, it must be captured before the expires_at or the funds will
be released.
HTTP Request
POST https://api-staging.finix.io/authorizations
Request Arguments
| Field | Type | Description |
|---|---|---|
| source | string, required | The buyer’s Payment Instrument ID that you will be performing the authorization |
| merchant_identity | string, required | The ID of the Identity for the merchant that you are transacting on behalf of |
| amount | integer, required | The amount of the authorization in cents |
| currency | string, required | 3-letter ISO code designating the currency (e.g. USD) |
| tags | object, optional | Key value pair for annotating custom meta data (e.g. order numbers) |
Step 7: Capture the Authorization
curl https://api-staging.finix.io/authorizations/AUf7d2dGYeQEyMsrKMuQimTX \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-X PUT \
-d '
{
"fee": "10",
"capture_amount": 100
}'
import io.finix.payments.ApiClient;
import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
AuthorizationUpdateForm form = AuthorizationUpdateForm.builder()
.captureAmount(100L)
.fee(10L)
.statementDescriptor("Order 123")
.build();
Maybe<Authorization> response = api.authorizations.id("AUf7d2dGYeQEyMsrKMuQimTX").put(form);
if (! response.succeeded()) {
ApiError error = response.error();
System.out.println(error.getMessage());
throw new RuntimeException("API error attempting to capture authorization");
}
Authorization capturedAuthorization = response.view();
<?php
use Finix\Resources\Authorization;
$authorization = Authorization::retrieve('AUf7d2dGYeQEyMsrKMuQimTX');
$authorization = $authorization->capture(50, 10);
from finix.resources import Authorization
authorization = Authorization.get(id="AUf7d2dGYeQEyMsrKMuQimTX")
authorization.capture(**
{
"fee": "10",
"capture_amount": 100
})
authorization = Finix::Authorization.retrieve(:id=>"AUf7d2dGYeQEyMsrKMuQimTX")
authorization = authorization.capture(
{
"fee"=> "10",
"capture_amount"=> 100
})
Example Response:
{
"id" : "AUf7d2dGYeQEyMsrKMuQimTX",
"amount" : 100,
"tags" : {
"order_number" : "21DFASJSAKAS"
},
"state" : "SUCCEEDED",
"currency" : "USD",
"transfer" : "TRgKRebvAj8BCnQcpGseiH8c",
"messages" : [ ],
"raw" : null,
"created_at" : "2018-04-26T00:45:31.64Z",
"updated_at" : "2018-04-26T00:45:32.95Z",
"trace_id" : "d009e729-1e42-461a-b9bc-32da02b7e915",
"source" : "PIss82nFMq4zmbLZgtrMhpQW",
"merchant_identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"is_void" : false,
"expires_at" : "2018-05-03T00:45:31.64Z",
"idempotency_id" : null,
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/authorizations/AUf7d2dGYeQEyMsrKMuQimTX"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"transfer" : {
"href" : "https://api-staging.finix.io/transfers/TRgKRebvAj8BCnQcpGseiH8c"
},
"merchant_identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
}
}
}
Now that we have the funds held on a card, we’ll need to capture them. Failing to do so will result in the funds being released (i.e. returned) to the buyer.
Note you can capture any amount less than or equal to the amount of the original
Authorization. You will also want to pass a fee. The fee field is the amount
in cents you would like to keep before settling out to the merchant. For example,
if you’re charging the buyer $100 on behalf of your merchant, and you’re taking
a 10% service fee you’ll want to pass 1000 as the fee. This way when the
funds are eventually settled out only $90 will be disbursed to your merchant.
Once successfully captured the transfer field of the Authorization will
contain the ID for the corresponding Transfer resource. By default, Transfers
will be in a PENDING state. PENDING means that the system hasn’t submitted the
capture request as they are submitted via batch request. Once submited
the state of the Transfer will update to SUCCEEDED.
Next we’re going to show you how to settle out the funds to your merchant.
HTTP Request
PUT https://api-staging.finix.io/authorizations/:AUTHORIZATION_ID
URL Parameters
| Parameter | Description |
|---|---|
| :AUTHORIZATION_ID | ID of the Authorization |
Request Arguments
| Field | Type | Description |
|---|---|---|
| capture_amount | integer, required | The amount of the Authorization you would like to capture in cents. Must be less than or equal to the amount of the Authorization |
| fee | integer, optional | Amount of the captured Authorization you would like to collect as your fee. Must be less than or equal to the amount |
Step 8: Create a Batch Settlement
curl https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/settlements \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"currency": "USD",
"tags": {
"Internal Daily Settlement ID": "21DFASJSAKAS"
}
}'
import io.finix.payments.ApiClient;
import io.finix.payments.forms.SettlementForm;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.views.*;
import java.util.Currency;
Settlement settlement = identity.createSettlement(
Settlement.builder()
.currency("USD")
.build()
);
SettlementForm formSettlement = SettlementForm.builder()
.currency(Currency.getInstance("USD"))
.build();
Transfer transfer = api.transfers.id("AUf7d2dGYeQEyMsrKMuQimTX").get().view();
Maybe<Settlement> response = api.identities.id("IDpSEHq3qRRSxvqzUkipefAM").settlements.post(formSettlement);
if (! response.succeeded()) {
throw new RuntimeException("API error attempting to create batch settlement");
}
Settlement settlementBatch = response.view();
<?php
use Finix\Resources\Identity;
use Finix\Resources\Settlement;
$identity = Identity::retrieve('IDpSEHq3qRRSxvqzUkipefAM');
$settlement = new Settlement(
array(
"currency"=> "USD",
"tags"=> array(
"Internal Daily Settlement ID"=> "21DFASJSAKAS"
)
));
$settlement = $identity->createSettlement($settlement);
from finix.resources import Identity
from finix.resources import Settlement
identity = Identity.get(id="IDpSEHq3qRRSxvqzUkipefAM")
settlement = Settlement(**
{
"currency": "USD",
"tags": {
"Internal Daily Settlement ID": "21DFASJSAKAS"
}
})
identity.create_settlement(settlement)
identity = Finix::Identity.retrieve(:id=>"IDpSEHq3qRRSxvqzUkipefAM")
settlement = identity.create_settlement(
{
"currency"=> "USD",
"tags"=> {
"Internal Daily Settlement ID"=> "21DFASJSAKAS"
}
})
Example Response:
{
"id" : "ST4fuHXj16toWtLVZZ7Up92z",
"tags" : {
"Internal Daily Settlement ID" : "21DFASJSAKAS"
},
"identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"currency" : "USD",
"created_at" : "2018-04-26T00:49:55.19Z",
"updated_at" : "2018-04-26T00:49:55.21Z",
"processor" : "DUMMY_V1",
"total_amount" : 1931119,
"total_fees" : 193204,
"total_fee" : 193204,
"net_amount" : 1737915,
"destination" : null,
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"funding_transfers" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/funding_transfers"
},
"transfers" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers"
},
"fees" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers?type=fee"
},
"reversals" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers?type=reverse"
},
"credits" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers?type=credit"
},
"debits" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers?type=debit"
}
}
}
Awesome! Now you know how to charge a card. Next you need to settle out the
funds to your merchant’s bank account (i.e. issue an ACH Credit). To do so you
will create a Settlement resource. A Settlement is a logical construct
representing a collection (i.e. batch) of Transfers that are intended to be
paid out to a specific Merchant.
Each settlement is comprised of all the Transfers that have a SUCCEEDED state and
that have not yet been previously settled out. In other words, if a merchant has a
Transfer in the PENDING state it will not be included in the batch settlement.
In addition, Settlements will include any refunded Transfers as a deduction.
The total_amount minus the total_fee equals the net_amount (the amount in cents
that will be deposited into your merchant’s bank account).
Note that for reconciliation purposes each Settlement contains a transfers
link which returns a list of all the
Transfers that comprise the batch.
HTTP Request
POST https://api-staging.finix.io/identities/:IDENTITY_ID/settlements
Request Arguments
| Field | Type | Description |
|---|---|---|
| currency | integer, required | 3-letter currency code that the funds should be deposited (e.g. USD) |
| tags | object, optional | Key value pair for annotating custom meta data (e.g. order numbers) |
Push-to-Card
Step 1: Create a Recipient Identity
curl https://api-staging.finix.io/identities \
-H "Content-Type: application/vnd.json+api" \
-u US9FfRMSFoESwaNEdLKHxqgJ:7d8ba811-a988-4bd8-b811-142203c6d551 \
-d '
{
"tags": {
"key": "value"
},
"entity": {
"phone": "7145677612",
"first_name": "Bob",
"last_name": "Lopez",
"email": "Bob@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(IDu19o8zShWiVzkJCoVNxFbQ);
$identity = $identity->save();
from finix.resources import Identity
identity = Identity(**
{
"tags": {
"key": "value"
},
"entity": {
"phone": "7145677612",
"first_name": "Bob",
"last_name": "Lopez",
"email": "Bob@gmail.com",
"personal_address": {
"city": "San Mateo",
"country": "USA",
"region": "CA",
"line2": "Apartment 7",
"line1": "741 Douglass St",
"postal_code": "94114"
}
}
}).save()
identity = Finix::Identity.new(
{
"tags"=> {
"key"=> "value"
},
"entity"=> {
"phone"=> "7145677612",
"first_name"=> "Bob",
"last_name"=> "Lopez",
"email"=> "Bob@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" : "IDu19o8zShWiVzkJCoVNxFbQ",
"entity" : {
"title" : null,
"first_name" : "Bob",
"last_name" : "Lopez",
"email" : "Bob@gmail.com",
"business_name" : null,
"business_type" : null,
"doing_business_as" : null,
"phone" : "7145677612",
"business_phone" : null,
"personal_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"business_address" : null,
"mcc" : null,
"dob" : null,
"max_transaction_amount" : 0,
"amex_mid" : null,
"discover_mid" : null,
"url" : null,
"annual_card_volume" : 0,
"has_accepted_credit_cards_previously" : false,
"incorporation_date" : null,
"principal_percentage_ownership" : null,
"short_business_name" : null,
"ownership_type" : null,
"tax_id_provided" : false,
"business_tax_id_provided" : false,
"default_statement_descriptor" : null
},
"tags" : {
"key" : "value"
},
"created_at" : "2018-04-26T00:45:08.98Z",
"updated_at" : "2018-04-26T00:45:08.98Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities/IDu19o8zShWiVzkJCoVNxFbQ"
},
"verifications" : {
"href" : "https://api-staging.finix.io/identities/IDu19o8zShWiVzkJCoVNxFbQ/verifications"
},
"merchants" : {
"href" : "https://api-staging.finix.io/identities/IDu19o8zShWiVzkJCoVNxFbQ/merchants"
},
"settlements" : {
"href" : "https://api-staging.finix.io/identities/IDu19o8zShWiVzkJCoVNxFbQ/settlements"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/identities/IDu19o8zShWiVzkJCoVNxFbQ/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/identities/IDu19o8zShWiVzkJCoVNxFbQ/transfers"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/identities/IDu19o8zShWiVzkJCoVNxFbQ/payment_instruments"
},
"disputes" : {
"href" : "https://api-staging.finix.io/identities/IDu19o8zShWiVzkJCoVNxFbQ/disputes"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/AP51MRy5CzXHL4hwdDm4B7Dc"
}
}
}
Let’s start with the first step by creating an Identity resource. Each Identity represents either a person or a business. We use this resource to associate cards and payouts. This structure makes it simple to manage and reconcile payment instruments and payout history. Accounting of funds is done using the Identity so it’s recommended to have an Identity per recipient of funds. Additionally, the Identity resource is optionally used to collect KYC information.
HTTP Request
POST https://api-staging.finix.io/identities
Request Arguments
| Field | Type | Description |
|---|---|---|
| first_name | string, optional | First name |
| last_name | string, optional | Last name |
| string, optional | ||
| phone | string, optional | Phone number |
| tags | object, optional | Key value pair for annotating custom meta data (e.g. order numbers) |
| personal_address | object, optional | Customers shipping address or billing address (Full description of child attributes below) |
Address-object Request Arguments
| Field | Type | Description |
|---|---|---|
| line1 | string, required | First line of the address (max 60 characters) |
| line2 | string, optional | Second line of the address (max 60 characters) |
| city | string, required | City (max 20 characters) |
| region | string, required | 2-letter State code |
| postal_code | string, required | Zip or Postal code (max 7 characters) |
| country | string, required | 3-Letter Country code |
Step 2: Add a Payment Instrument for the Recipient
curl https://api-staging.finix.io/payment_instruments \
-H "Content-Type: application/vnd.json+api" \
-u US9FfRMSFoESwaNEdLKHxqgJ:7d8ba811-a988-4bd8-b811-142203c6d551 \
-d '
{
"name": "Collen Lopez",
"expiration_year": 2020,
"tags": {
"card_name": "Business Card"
},
"number": "4957030420210454",
"expiration_month": 12,
"address": {
"city": "San Mateo",
"country": "USA",
"region": "CA",
"line2": "Apartment 7",
"line1": "741 Douglass St",
"postal_code": "94114"
},
"security_code": "112",
"type": "PAYMENT_CARD",
"identity": "IDu19o8zShWiVzkJCoVNxFbQ"
}'
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("IDpSEHq3qRRSxvqzUkipefAM")
.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('IDu19o8zShWiVzkJCoVNxFbQ');
$card = new PaymentCard(
array(
"name"=> "Collen Lopez",
"expiration_year"=> 2020,
"tags"=> array(
"card_name"=> "Business Card"
),
"number"=> "4957030420210454",
"expiration_month"=> 12,
"address"=> array(
"city"=> "San Mateo",
"country"=> "USA",
"region"=> "CA",
"line2"=> "Apartment 7",
"line1"=> "741 Douglass St",
"postal_code"=> "94114"
),
"security_code"=> "112",
"type"=> "PAYMENT_CARD",
"identity"=> "IDu19o8zShWiVzkJCoVNxFbQ"
));
$card = $identity->createPaymentCard($card);
from finix.resources import PaymentCard
card = PaymentCard(**
{
"name": "Michae Lopez",
"expiration_year": 2020,
"tags": {
"card_name": "Business Card"
},
"number": "4957030420210454",
"expiration_month": 12,
"address": {
"city": "San Mateo",
"country": "USA",
"region": "CA",
"line2": "Apartment 7",
"line1": "741 Douglass St",
"postal_code": "94114"
},
"security_code": "112",
"type": "PAYMENT_CARD",
"identity": "IDuYo7qjbtB6kMVeebe4Z6NN"
}).save()
card = Finix::PaymentCard.new(
{
"name"=> "Collen Lopez",
"expiration_year"=> 2020,
"tags"=> {
"card_name"=> "Business Card"
},
"number"=> "4957030420210454",
"expiration_month"=> 12,
"address"=> {
"city"=> "San Mateo",
"country"=> "USA",
"region"=> "CA",
"line2"=> "Apartment 7",
"line1"=> "741 Douglass St",
"postal_code"=> "94114"
},
"security_code"=> "112",
"type"=> "PAYMENT_CARD",
"identity"=> "IDu19o8zShWiVzkJCoVNxFbQ"
}).save
Example Response:
{
"id" : "PIboPQdA8VRzgaQh34dJF6ET",
"fingerprint" : "FPR436313288",
"tags" : {
"card_name" : "Business Card"
},
"expiration_month" : 12,
"expiration_year" : 2020,
"bin" : "495703",
"last_four" : "0454",
"brand" : "VISA",
"card_type" : "UNKNOWN",
"name" : "Collen Lopez",
"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" : "2018-04-26T00:45:10.26Z",
"updated_at" : "2018-04-26T00:45:10.26Z",
"instrument_type" : "PAYMENT_CARD",
"type" : "PAYMENT_CARD",
"currency" : "USD",
"identity" : "IDu19o8zShWiVzkJCoVNxFbQ",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIboPQdA8VRzgaQh34dJF6ET"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIboPQdA8VRzgaQh34dJF6ET/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIboPQdA8VRzgaQh34dJF6ET/transfers"
},
"verifications" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIboPQdA8VRzgaQh34dJF6ET/verifications"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/AP51MRy5CzXHL4hwdDm4B7Dc"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDu19o8zShWiVzkJCoVNxFbQ"
},
"updates" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIboPQdA8VRzgaQh34dJF6ET/updates"
}
}
}
Now that we’ve created an Identity for our recipient, we’ll need to tokenize a credit card where funds will be disbursed.
In the API, credit cards are represented by the Payment Instrument resource.
To classify the Payment Instrument as a credit card you’ll need to pass PAYMENT_CARD in the type field of your request, and you’ll also want to pass the ID of the Identity that you created in the last step via the identity field to properly associate it with your recipient.
HTTP Request
POST https://api-staging.finix.io/payment_instruments
Request Arguments
| Field | Type | Description |
|---|---|---|
| identity | string, required | ID of the Identity that the card should be associated |
| type | string, required | Type of Payment Instrument (for cards input PAYMENT_CARD) |
| number | string, required | Credit card account number |
| security_code | string, optional | The 3-4 digit security code for the card (i.e. CVV code) |
| expiration_month | integer, required | Expiration month (e.g. 12 for December) |
| expiration_year | integer, required | 4-digit expiration year |
| name | string, optional | Full name of the registered card holder |
| address | object, optional | Billing address (Full description of child attributes below) |
Address-object Request Arguments
| Field | Type | Description |
|---|---|---|
| line1 | string, required | First line of the address (max 60 characters) |
| line2 | string, optional | Second line of the address (max 60 characters) |
| city | string, required | City (max 20 characters) |
| region | string, required | 2-letter State code |
| postal_code | string, required | Zip or Postal code (max 7 characters) |
| country | string, required | 3-Letter Country code |
Step 3: Verify card is eligible to receive push-to-card disbursements
Now that we’ve associated a payment instrument to a recipient, we’ll need to verify whether or not the card is eligible to receive push-to-card disbursements. How? By making a request to the Verifications endpoint. The returned Verification resource returns a set of general attributes and details about the card in question (e.g. card type, issuer information). For example, the inquiry_details object will contain a push_funds_block_indicator attribute that indicates if it is eligible for push-to-card disbursements. Below you’ll see a number of fields and the potential responses.
curl https://api-staging.finix.io/payment_instruments/PIboPQdA8VRzgaQh34dJF6ET/verifications \
-H "Content-Type: application/vnd.json+api" \
-u US9FfRMSFoESwaNEdLKHxqgJ:7d8ba811-a988-4bd8-b811-142203c6d551 \
-d '
{
"processor": "VISA_V1"
}'
import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
VerificationForm verificationForm = VerificationForm.builder()
.processor("VISA_V1")
.build();
Maybe<Verification> verificationResponse = api.instruments.id("PIboPQdA8VRzgaQh34dJF6ET").verifications.post(verificationForm);
if (! verificationResponse.succeeded()) {
ApiError error = verificationResponse.error();
System.out.println(error.getCode());
throw new RuntimeException("API error attempting to create a Verification");
}
Verification verification = verificationResponse.view();
<?php
from finix.resources import PaymentInstrument
from finix.resources import Verification
payment_card = PaymentInstrument.get(id="PIss82nFMq4zmbLZgtrMhpQW")
verify = payment_card.verify_on(Verification(**
{
"processor": "VISA_V1"
}))
Example Response:
{
"id" : "VIgTdSU9hQ5tUkaSj8Hv4vop",
"tags" : { },
"messages" : [ ],
"raw" : {
"validation_details" : {
"systems_trace_audit_number" : "193315",
"transaction_identifier" : "136049294563589",
"action_code" : "N7",
"response_code" : "5",
"address_verification_results" : "N",
"cvv2_result_code" : "N"
},
"inquiry_details" : {
"systems_trace_audit_number" : "193315",
"card_type_code" : "C",
"billing_currency_code" : 986,
"billing_currency_minor_digits" : 2,
"issuer_name" : "Visa Test Bank",
"card_issuer_country_code" : 76,
"fast_funds_indicator" : "N",
"push_funds_block_indicator" : "N",
"online_gambing_block_indicator" : "Y"
},
"general_inquiry_details" : {
"systems_trace_audit_number" : "193315",
"status" : {
"status_code" : "CDI000",
"status_description" : "Success"
}
}
},
"processor" : "VISA_V1",
"state" : "SUCCEEDED",
"created_at" : "2018-04-26T00:45:13.12Z",
"updated_at" : "2018-04-26T00:45:14.27Z",
"trace_id" : "193315",
"payment_instrument" : "PIboPQdA8VRzgaQh34dJF6ET",
"merchant" : null,
"identity" : null,
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/verifications/VIgTdSU9hQ5tUkaSj8Hv4vop"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/AP51MRy5CzXHL4hwdDm4B7Dc"
},
"payment_instrument" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIboPQdA8VRzgaQh34dJF6ET"
}
}
}
HTTP Request
POST https://api-staging.finix.io/payment_instruments/:PAYMENT_INSTRUMENT_ID/verifications
URL Parameters
| Parameter | Description |
|---|---|
| :PAYMENT_INSTRUMENT_ID | ID of the Payment Instrument |
Request Arguments
| Field | Type | Description |
|---|---|---|
| processor | string, required | The name of the processor, which needs to be: VISA_V1 |
Address Verification Results (address_verification_results)
| Letter | Description |
|---|---|
| D, F, M, Y | Address verified |
| A, B, C, G, I, N, P, R, S, U, W | Address not verified |
| Z | Postal/ZIP match, street addresses do not match or street address not included in request |
Card Verification 2 Results (cvv2_result_code)
| Letter | Description |
|---|---|
| M | CVV and expiration verified |
| N, P, S | CVV not verified |
| U | Issuer does not participate in CVV2 service |
Card Type (card_type_code)
This one-character code indicates whether the account is credit, debit, prepaid, deferred debit, or charge.
| Letter | Description |
|---|---|
| C | Credit |
| D | Debit |
| H | Charge Card |
| P | Prepaid |
| R | Deferred Debit |
Fasts Funds Indicator (fast_funds_indicator)
Indicates whether or not the card is Fast Funds eligible (i.e. if the funds will settle in 30 mins or less). If not eligible, typically funds will settle within 2 business days.
| Letter | Description |
|---|---|
| B, D | Fast Funds eligible |
| N | Not eligible for Fast Funds |
Push Funds Indicator (push_funds_block_indicator)
This code indicates if the associated card can receive push-to-card disbursements.
| Letter | Description |
|---|---|
| A, B, C | Accepts push-to-card payments |
| N | Does not accept push-to-card payments |
Online Gambling Block Indicator (online_gambing_block_indicator)
Indicates if the card can receive push-payments for online gambling payouts.
| Letter | Description |
|---|---|
| Y | Blocked for online gambling payouts |
| N | Not blocked for online gambling payouts |
Card Product ID (card_product_id)
A combination of card brand, platform, class and scheme.
| Letter | Description |
|---|---|
| A | Visa Traditional |
| AX | American Express |
| B | Visa Traditional Rewards |
| C | Visa Signature |
| D | Visa Signature Preferred |
| DI | Discover |
| DN | Diners |
| E | Proprietary ATM |
| F | Visa Classic |
| G | Visa Business |
| G1 | Visa Signature Business |
| G2 | Visa Business Check Card |
| G3 | Visa Business Enhanced |
| G4 | Visa Infinite Business |
| G5 | Visa Business Rewards |
| I | Visa Infinite |
| I1 | Visa Infinite Privilege |
| I2 | Visa UHNW |
| J3 | Visa Healthcare |
| JC | JCB |
| K | Visa Corporate T&E |
| K1 | Visa Government Corporate T&E |
| L | Visa Electron |
| M | MasterCard |
| N | Visa Platinum |
| N1 | Visa Rewards |
| N2 | Visa Select |
| P | Visa Gold |
| Q | Private Label |
| Q1 | Private Label Prepaid |
| Q2 | Private Label Basic |
| Q3 | Private Label Standard |
| Q4 | Private Label Enhanced |
| Q5 | Private Label Specialized |
| Q6 | Private Label Premium |
| R | Proprietary |
| S | Visa Purchasing |
| S1 | Visa Purchasing with Fleet |
| S2 | Visa Government Purchasing |
| S3 | Visa Government Purchasing with Fleet |
| S4 | Visa Commercial Agriculture |
| S5 | Visa Commercial Transport |
| S6 | Visa Commercial Marketplace |
| U | Visa Travel Money |
| V | Visa V PAY |
Product Sub-Type (card_product_subtype)
Description of product subtype.
| Letter | Description |
|---|---|
| AC | Agriculture Maintenance Account |
| AE | Agriculture Debit Account/Electron |
| AG | Agriculture |
| AI | Agriculture Investment Loan |
| CG | Brazil Cargo |
| CS | Construction |
| DS | Distribution |
| HC | Healthcare |
| LP | Visa Large Purchase Advantage |
| MA | Visa Mobile Agent |
| MB | Interoperable Mobile Branchless Banking |
| MG | Visa Mobile General |
| VA | Visa Vale - Supermarket |
| VF | Visa Vale - Fuel |
| VR | Visa Vale - Restaurant |
Card Sub-Type (card_subtype_code)
The code for account funding source subtype, such as reloadable and non-reloadable.
| Letter | Description |
|---|---|
| N | Non-Reloadable |
| R | Reloadable |
Step 4: Provision Recipient Account
curl https://api-staging.finix.io/identities/IDu19o8zShWiVzkJCoVNxFbQ/merchants \
-H "Content-Type: application/vnd.json+api" \
-u US9FfRMSFoESwaNEdLKHxqgJ:7d8ba811-a988-4bd8-b811-142203c6d551 \
-d '
{
"processor": "VISA_V1"
}'
import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import com.google.common.collect.ImmutableMap;
Maybe<Identity> response = api.identities.id("IDu19o8zShWiVzkJCoVNxFbQ").get();
if (! response.succeeded()) {
ApiError error = response.error();
System.out.println(error.getCode());
throw new RuntimeException("API error attempting to fetch Identity");
}
Identity identity = response.view();
MerchantUnderwritingForm form = MerchantUnderwritingForm.builder()
.tags(ImmutableMap.of("key", "value"))
.build();
Maybe<Merchant> merchantResponse = api.identities.id(identity.id).merchants.post(form);
if (! merchantResponse.succeeded()) {
ApiError error = merchantResponse.error();
System.out.println(error.getCode());
throw new RuntimeException("API error attempting to provision Merchant");
}
Merchant merchant = merchantResponse.view();
<?php
use Finix\Resources\Identity;
use Finix\Resources\Merchant;
$identity = Identity::retrieve('IDu19o8zShWiVzkJCoVNxFbQ');
$merchant = $identity->provisionMerchantOn(new Merchant());
from finix.resources import Identity
from finix.resources import Merchant
identity = Identity.get(id="PIboPQdA8VRzgaQh34dJF6ET")
merchant = identity.provision_merchant_on(Merchant())
identity = Finix::Identity.retrieve(:id=>"IDu19o8zShWiVzkJCoVNxFbQ")
merchant = identity.provision_merchant
Example Response:
{
"id" : "MUwri2PM2GWxbyjWEzPxZ2Pd",
"identity" : "IDu19o8zShWiVzkJCoVNxFbQ",
"verification" : "VInfVz3uRXahasWFdLeX8Nnx",
"merchant_profile" : "MP5NCsb6JHjVuhnMK2HoXqB8",
"processor" : "VISA_V1",
"processing_enabled" : false,
"settlement_enabled" : false,
"creating_transfer_from_report_enabled" : false,
"tags" : { },
"created_at" : "2018-04-26T00:45:10.72Z",
"updated_at" : "2018-04-26T00:45:10.72Z",
"onboarding_state" : "PROVISIONING",
"processor_details" : { },
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/merchants/MUwri2PM2GWxbyjWEzPxZ2Pd"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDu19o8zShWiVzkJCoVNxFbQ"
},
"verifications" : {
"href" : "https://api-staging.finix.io/merchants/MUwri2PM2GWxbyjWEzPxZ2Pd/verifications"
},
"merchant_profile" : {
"href" : "https://api-staging.finix.io/merchant_profiles/MP5NCsb6JHjVuhnMK2HoXqB8"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/AP51MRy5CzXHL4hwdDm4B7Dc"
},
"verification" : {
"href" : "https://api-staging.finix.io/verifications/VInfVz3uRXahasWFdLeX8Nnx"
}
}
}
Now that we’ve associated a Payment Instrument with our recipient’s Identity we’re ready to provision a Recipient account. This is the last step before you can begin paying out an Identity. Luckily you’ve already done most of the heavy lifting. Just make one final POST request, and you’ll be returned a Merchant resource.
HTTP Request
POST https://api-staging.finix.io/identities/identityID/merchants
Request Arguments
| Field | Type | Description |
|---|---|---|
| processor | string, optional | Name of Processor |
Step 5: Send Payout
curl https://api-staging.finix.io/transfers \
-H "Content-Type: application/vnd.json+api" \
-u US9FfRMSFoESwaNEdLKHxqgJ:7d8ba811-a988-4bd8-b811-142203c6d551 \
-d '
{
"currency": "USD",
"amount": 1510,
"destination": "PIboPQdA8VRzgaQh34dJF6ET",
"tags": {
"order_number": "21DFASJSAKAS"
}
}'
import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import com.google.common.collect.ImmutableMap;
import java.util.Currency;
TransferForm form = TransferForm.builder()
.amount(100L)
.currency(Currency.getInstance("USD"))
.idempotencyId("Idsfk23jnasdfkjf")
.destination("PIboPQdA8VRzgaQh34dJF6ET")
.tags(ImmutableMap.of("order_number", "21DFASJSAKAS"))
.build();
Maybe<Transfer> response = api.transfers.post(form);
if (! response.succeeded()) {
ApiError error = response.error();
System.out.println(error.getCode());
throw new RuntimeException("API error attempting to create Transfer");
}
Transfer transfer = response.view();
<?php
use Finix\Resources\Transfer;
$transfer = new Transfer(
array(
"currency"=> "USD",
"amount"=> 1510,
"destination"=> "PIboPQdA8VRzgaQh34dJF6ET",
"tags"=> array(
"order_number"=> "21DFASJSAKAS"
)
));
$transfer = $transfer->save();
from finix.resources import Transfer
payout = Transfer(**
{
"name": "Collen Lopez",
"expiration_year": 2020,
"tags": {
"card_name": "Business Card"
},
"number": "4957030420210454",
"expiration_month": 12,
"address": {
"city": "San Mateo",
"country": "USA",
"region": "CA",
"line2": "Apartment 7",
"line1": "741 Douglass St",
"postal_code": "94114"
},
"security_code": "112",
"type": "PAYMENT_CARD",
"identity": "IDu19o8zShWiVzkJCoVNxFbQ"
}).save()
transfer = Finix::Transfer.new(
{
"currency"=> "USD",
"amount"=> 1510,
"destination"=> "PIboPQdA8VRzgaQh34dJF6ET",
"tags"=> {
"order_number"=> "21DFASJSAKAS"
}
}).save
Example Response:
{
"id" : "TRaDfXHwgwsTueYMNzuNfcNF",
"amount" : 1510,
"tags" : {
"order_number" : "21DFASJSAKAS"
},
"state" : "SUCCEEDED",
"trace_id" : "193314",
"currency" : "USD",
"application" : "AP51MRy5CzXHL4hwdDm4B7Dc",
"source" : null,
"destination" : "PIboPQdA8VRzgaQh34dJF6ET",
"ready_to_settle_at" : null,
"fee" : 0,
"statement_descriptor" : "FIN*FINIXPAYMENTS",
"type" : "CREDIT",
"messages" : [ ],
"raw" : null,
"created_at" : "2018-04-26T00:45:11.84Z",
"updated_at" : "2018-04-26T00:45:12.61Z",
"idempotency_id" : null,
"merchant_identity" : "IDu19o8zShWiVzkJCoVNxFbQ",
"subtype" : "API",
"_links" : {
"application" : {
"href" : "https://api-staging.finix.io/applications/AP51MRy5CzXHL4hwdDm4B7Dc"
},
"self" : {
"href" : "https://api-staging.finix.io/transfers/TRaDfXHwgwsTueYMNzuNfcNF"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/transfers/TRaDfXHwgwsTueYMNzuNfcNF/payment_instruments"
},
"merchant_identity" : {
"href" : "https://api-staging.finix.io/identities/IDu19o8zShWiVzkJCoVNxFbQ"
},
"reversals" : {
"href" : "https://api-staging.finix.io/transfers/TRaDfXHwgwsTueYMNzuNfcNF/reversals"
},
"fees" : {
"href" : "https://api-staging.finix.io/transfers/TRaDfXHwgwsTueYMNzuNfcNF/fees"
},
"disputes" : {
"href" : "https://api-staging.finix.io/transfers/TRaDfXHwgwsTueYMNzuNfcNF/disputes"
},
"destination" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIboPQdA8VRzgaQh34dJF6ET"
}
}
}
Now the final step - time to payout the recipient!
Next you’ll need to create a Transfer. What’s a Transfer? Glad you asked! A Transfer represents any flow of funds either to or from a Payment Instrument. In this case a Payout to a card.
To create a Transfer we’ll simply supply the Payment Instrument ID of the previously tokenized card as the destination field. Also, be sure to note that the amount field is in cents.
Simple enough, right? You’ll also want to store the ID from that Transfer for your records. Transfers can have two possible states SUCCEEDED and FAILED.
HTTP Request
POST https://api-staging.finix.io/transfers
Request Arguments
| Field | Type | Description |
|---|---|---|
| destination | string, required | ID of the Payment Instrument where funds will be sent |
| amount | integer, required | The total amount that will be charged in cents (e.g. 100 cents to charge $1.00) |
| currency | string, required | 3-letter ISO code designating the currency of the Transfers (e.g. USD) |
| tags | object, optional | Key value pair for annotating custom meta data (e.g. order numbers) |
Embedded Tokenization
Our embedded tokenization form ensures you remain out of PCI scope, while providing your end-users with a sleek, and seamless checkout experience.
With our form, sensitive card data never touches your servers and keeps you out of PCI scope by sending this info over SSL directly to Finix. For your convenience we’ve provided a jsfiddle as a live example.
Step 1: Create a Button
<!DOCTYPE html>
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<body>
<button id="show-form">Add Your Card</button>
</body>
</html>
Before collecting the sensitive payment information, we will need to add a button to the HTML where we’ll be hosting the iframe so that end-users can input their details.
We have provided a simple example to the right.
Step 2: Include library
To use the iframe you will need to include the library on the webpage where you’re hosting the aforementioned button. Please include the script as demonstrated to the right. Please refrain from hosting the iframe library locally as doing so prevents important updates.
<script type="text/javascript" src="https://forms.finixpymnts.com/finix.js"></script>
Step 3: Configure the client
<script type="text/javascript">
document.addEventListener("DOMContentLoaded", function(event) {
document.getElementById('show-form').addEventListener('click', function() {
.openTokenizeCardForm({
applicationName: 'Business Name',
applicationId: 'APhSYuXuvHHMGzkhnjumcmqB',
environment: 'sandbox',
}, function (tokenizedResponse) {
// Define a callback to send your token to your back-end server
});
});
});
</script>
Next we need to configure the client so that it associates the card with your Application. We will also need to register a click event that fires when our users click on the button, thereby rendering the iframe on the page. Then when the form is submitted you’ll be returned a unique Token resource representing the submitted card details. We will also need to define a callback for handling that response.
In the next step we’ll show you how to claim the instrument via an authenticated HTTPS request on your back-end for future use.
Example Response:
{
"id" : "TKs1igXSvbb5aCtXCDGVwgPf",
"fingerprint" : "FPR405642276",
"created_at" : "2018-04-26T00:45:34.26Z",
"updated_at" : "2018-04-26T00:45:34.26Z",
"instrument_type" : "PAYMENT_CARD",
"expires_at" : "2018-04-27T00:45:34.26Z",
"currency" : "USD",
"_links" : {
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}
Step 4: Associate the Token
curl https://api-staging.finix.io/payment_instruments \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"token": "TKs1igXSvbb5aCtXCDGVwgPf",
"type": "TOKEN",
"identity": "IDpSEHq3qRRSxvqzUkipefAM"
}'
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("TKs1igXSvbb5aCtXCDGVwgPf")
.identity("IDpSEHq3qRRSxvqzUkipefAM")
.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"=> "TKs1igXSvbb5aCtXCDGVwgPf",
"type"=> "TOKEN",
"identity"=> "IDpSEHq3qRRSxvqzUkipefAM"
));
$card = $card->save();
from finix.resources import PaymentInstrument
payment_instrument = PaymentInstrument(**
{
"token": "TKs1igXSvbb5aCtXCDGVwgPf",
"type": "TOKEN",
"identity": "IDpSEHq3qRRSxvqzUkipefAM"
}).save()
card = Finix::PaymentInstrument.new(
{
"token"=> "TKs1igXSvbb5aCtXCDGVwgPf",
"type"=> "TOKEN",
"identity"=> "IDpSEHq3qRRSxvqzUkipefAM"
}).save
Example Response:
{
"id" : "PIs1igXSvbb5aCtXCDGVwgPf",
"fingerprint" : "FPR405642276",
"tags" : { },
"expiration_month" : 12,
"expiration_year" : 2020,
"bin" : "495703",
"last_four" : "0454",
"brand" : "VISA",
"card_type" : "UNKNOWN",
"name" : null,
"address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"address_verification" : "UNKNOWN",
"security_code_verification" : "UNKNOWN",
"created_at" : "2018-04-26T00:45:34.66Z",
"updated_at" : "2018-04-26T00:45:34.66Z",
"instrument_type" : "PAYMENT_CARD",
"type" : "PAYMENT_CARD",
"currency" : "USD",
"identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf/transfers"
},
"verifications" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf/verifications"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"updates" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf/updates"
}
}
}
Associate the newly tokenized card or bank with the instrument owner’s Identity.
HTTP Request
POST https://api-staging.finix.io/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 |
Tokenization with Hosted Fields
Library summary
The PaymentForm library is a javascript library that allows you secure your sensitive credit and debit card data. By having the end-user input their data into an iFrame, it prevents third-parties from accessing the information.
Once the fields are initialized the library communicates the state of the fields through a JavaScript callback. The state object includes information about the validity, focused value and if the user has entered information in the field.
For a complete example of how to use the library please refer to this jsFiddle example.
Step 1: Include library and desired HTML elements
<script type="text/javascript" src="https://forms.finixpymnts.com/finix.js"></script>
First we’ll need to include the library on the webpage where you’re hosting your form. Please include the script as demonstrated to the right.
Step 2: Initialize the payment form
window.PaymentForm.card(function(state, binInformation)-> PaymentForm
const paymentForm = window.PaymentForm.card(function(state, binInformation){
// Logic for interacting with form's potential states (see jsFiddle for example)
});
The next step is to configure the library. This “card” method is the single entry point into the library. It initializes and returns a PaymentForm object that contains fields(i.e. name, number, expiration date, & CVV).
Step 3: Define input fields and configure styling
Now that we have a PaymentForm object we’ll want to style it
DefineField Arguments
| Field | Type | Description |
|---|---|---|
| elementId | string, required | Name of HTML id |
| type | string, required | API attribute name that will be sent in the payload |
| placholder | string, required | What the user will see in the input field |
function defineField(elementId, type, placeholder) {
// call field method with desired css styling
const f = form.field(type, {
placeholder,
styles: {
default: {
color: "black",
},
success: {
color: '#5cb85c',
},
error: {
color: '#d9534f',
},
}
});
// appends each field wrapper (that contains placeholder and styles) to the appropriate div
document.getElementById(elementId).appendChild(f);
}
defineField("field-wrapper-number", "number", '4111 1111 1111 1111');
defineField("field-wrapper-name", "name", 'Bo Jackson');
defineField("field-wrapper-expiration_date", "expiration_date", '02/2020');
defineField("field-wrapper-security_code", "security_code", '411');
Step 4: Submit payload and handle response
Form#submit(environment, applicationID, callback)-> Form
/*
Form#submit(environment, applicationID, callback)-> Form
*/
function submitForm() {
// sandbox or production for environment
form.submit('sandbox', 'APu7v3CBcRGqh2G5yM52NHPd', 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 production for production |
| 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://api-staging.finix.io/payment_instruments \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"token": "TKs1igXSvbb5aCtXCDGVwgPf",
"type": "TOKEN",
"identity": "IDpSEHq3qRRSxvqzUkipefAM"
}'
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("TKs1igXSvbb5aCtXCDGVwgPf")
.identity("IDpSEHq3qRRSxvqzUkipefAM")
.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"=> "TKs1igXSvbb5aCtXCDGVwgPf",
"type"=> "TOKEN",
"identity"=> "IDpSEHq3qRRSxvqzUkipefAM"
));
$card = $card->save();
from finix.resources import PaymentInstrument
payment_instrument = PaymentInstrument(**
{
"token": "TKs1igXSvbb5aCtXCDGVwgPf",
"type": "TOKEN",
"identity": "IDpSEHq3qRRSxvqzUkipefAM"
}).save()
card = Finix::PaymentInstrument.new(
{
"token"=> "TKs1igXSvbb5aCtXCDGVwgPf",
"type"=> "TOKEN",
"identity"=> "IDpSEHq3qRRSxvqzUkipefAM"
}).save
Example Response:
{
"id" : "PIs1igXSvbb5aCtXCDGVwgPf",
"fingerprint" : "FPR405642276",
"tags" : { },
"expiration_month" : 12,
"expiration_year" : 2020,
"bin" : "495703",
"last_four" : "0454",
"brand" : "VISA",
"card_type" : "UNKNOWN",
"name" : null,
"address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"address_verification" : "UNKNOWN",
"security_code_verification" : "UNKNOWN",
"created_at" : "2018-04-26T00:45:34.66Z",
"updated_at" : "2018-04-26T00:45:34.66Z",
"instrument_type" : "PAYMENT_CARD",
"type" : "PAYMENT_CARD",
"currency" : "USD",
"identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf/transfers"
},
"verifications" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf/verifications"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"updates" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf/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://api-staging.finix.io/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://api-staging.finix.io/authorizations \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"merchant_identity": "IDpSEHq3qRRSxvqzUkipefAM",
"currency": "USD",
"amount": 100,
"source": "PIss82nFMq4zmbLZgtrMhpQW",
"tags": {
"order_number": "21DFASJSAKAS"
}
}'
import io.finix.payments.ApiClient;
import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
AuthorizationCreateForm formCreateAuthorization = AuthorizationCreateForm.builder()
.amount(10000L)
.merchantIdentity("IDpSEHq3qRRSxvqzUkipefAM")
.source("PIss82nFMq4zmbLZgtrMhpQW")
.build();
Maybe<Authorization> response = api.authorizations.post(formCreateAuthorization);
if (! response.succeeded()) {
ApiError error = response.error();
System.out.println(error.getMessage());
throw new RuntimeException("API error attempting to creating Authorization");
}
Authorization authorization = response.view();
<?php
use Finix\Resources\Authorization;
$authorization = new Authorization(
array(
"merchant_identity"=> "IDpSEHq3qRRSxvqzUkipefAM",
"currency"=> "USD",
"amount"=> 100,
"source"=> "PIss82nFMq4zmbLZgtrMhpQW",
"tags"=> array(
"order_number"=> "21DFASJSAKAS"
)
));
$authorization = $authorization->save();
from finix.resources import Authorization
authorization = Authorization(**
{
"merchant_identity": "IDpSEHq3qRRSxvqzUkipefAM",
"currency": "USD",
"amount": 100,
"source": "PIss82nFMq4zmbLZgtrMhpQW",
"tags": {
"order_number": "21DFASJSAKAS"
}
}).save()
authorization = Finix::Authorization.new(
{
"merchant_identity"=> "IDpSEHq3qRRSxvqzUkipefAM",
"currency"=> "USD",
"amount"=> 100,
"source"=> "PIss82nFMq4zmbLZgtrMhpQW",
"tags"=> {
"order_number"=> "21DFASJSAKAS"
}
}).save
Example Response:
{
"id" : "AUf7d2dGYeQEyMsrKMuQimTX",
"amount" : 100,
"tags" : {
"order_number" : "21DFASJSAKAS"
},
"state" : "SUCCEEDED",
"currency" : "USD",
"transfer" : null,
"messages" : [ ],
"raw" : null,
"created_at" : "2018-04-26T00:45:31.64Z",
"updated_at" : "2018-04-26T00:45:31.69Z",
"trace_id" : "d009e729-1e42-461a-b9bc-32da02b7e915",
"source" : "PIss82nFMq4zmbLZgtrMhpQW",
"merchant_identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"is_void" : false,
"expires_at" : "2018-05-03T00:45:31.64Z",
"idempotency_id" : null,
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/authorizations/AUf7d2dGYeQEyMsrKMuQimTX"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"merchant_identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
}
}
}
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://api-staging.finix.io/authorizations
Request Arguments
| Field | Type | Description |
|---|---|---|
| source | string, required | The Payment Instrument that you will be performing the authorization |
| merchant_identity | string, required | The ID of the Identity for the merchant that you are transacting on behalf of |
| amount | integer, required | The amount of the authorization in cents |
| currency | string, required | 3-letter ISO code designating the currency (e.g. USD) |
| tags | object, optional | Key value pair for annotating custom meta data (e.g. order numbers) |
| idempotency_id | string, optional | A randomly generated value that you want associated with the request |
Capture an Authorization
curl https://api-staging.finix.io/authorizations/AUf7d2dGYeQEyMsrKMuQimTX \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-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("AUf7d2dGYeQEyMsrKMuQimTX").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('AUf7d2dGYeQEyMsrKMuQimTX');
$authorization = $authorization->capture([
"capture_amount"=> 50,
"fee"=> 10
]);
from finix.resources import Authorization
authorization = Authorization.get(id="AUf7d2dGYeQEyMsrKMuQimTX")
authorization.capture(**
{
"fee": "10",
"capture_amount": 100
})
authorization = Finix::Authorization.retrieve(:id=>"AUf7d2dGYeQEyMsrKMuQimTX")
authorization = authorization.capture(
{
"fee"=> "10",
"capture_amount"=> 100
})
Example Response:
{
"id" : "AUf7d2dGYeQEyMsrKMuQimTX",
"amount" : 100,
"tags" : {
"order_number" : "21DFASJSAKAS"
},
"state" : "SUCCEEDED",
"currency" : "USD",
"transfer" : "TRgKRebvAj8BCnQcpGseiH8c",
"messages" : [ ],
"raw" : null,
"created_at" : "2018-04-26T00:45:31.64Z",
"updated_at" : "2018-04-26T00:45:32.95Z",
"trace_id" : "d009e729-1e42-461a-b9bc-32da02b7e915",
"source" : "PIss82nFMq4zmbLZgtrMhpQW",
"merchant_identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"is_void" : false,
"expires_at" : "2018-05-03T00:45:31.64Z",
"idempotency_id" : null,
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/authorizations/AUf7d2dGYeQEyMsrKMuQimTX"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"transfer" : {
"href" : "https://api-staging.finix.io/transfers/TRgKRebvAj8BCnQcpGseiH8c"
},
"merchant_identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
}
}
}
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://api-staging.finix.io/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://api-staging.finix.io/authorizations/AUa6wHv6V9mcrifHoWiszmyJ \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-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("AUf7d2dGYeQEyMsrKMuQimTX").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('AUf7d2dGYeQEyMsrKMuQimTX');
$authorization->void(true);
$authorization = $authorization->save();
from finix.resources import Authorization
authorization = Authorization.get(id="AUf7d2dGYeQEyMsrKMuQimTX")
authorization.void()
authorization = Finix::Authorization.retrieve(:id=>"AUf7d2dGYeQEyMsrKMuQimTX")
authorization = authorization.void
Example Response:
{
"id" : "AUa6wHv6V9mcrifHoWiszmyJ",
"amount" : 100,
"tags" : {
"order_number" : "21DFASJSAKAS"
},
"state" : "SUCCEEDED",
"currency" : "USD",
"transfer" : null,
"messages" : [ ],
"raw" : null,
"created_at" : "2018-04-26T00:45:35.32Z",
"updated_at" : "2018-04-26T00:45:35.84Z",
"trace_id" : "6dd8e0ce-379b-4eaf-ba8e-6d1003da7d4d",
"source" : "PIss82nFMq4zmbLZgtrMhpQW",
"merchant_identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"is_void" : true,
"expires_at" : "2018-05-03T00:45:35.32Z",
"idempotency_id" : null,
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/authorizations/AUa6wHv6V9mcrifHoWiszmyJ"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"merchant_identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
}
}
}
Cancels the Authorization thereby releasing the funds. After voiding an
Authorization it can no longer be captured.
HTTP Request
PUT https://api-staging.finix.io/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://api-staging.finix.io/authorizations/AUf7d2dGYeQEyMsrKMuQimTX \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99
import io.finix.ApiClient;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.views.Authorization;
Maybe <Authorization> response = api.authorizations
.id("AUf7d2dGYeQEyMsrKMuQimTX")
.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('AUf7d2dGYeQEyMsrKMuQimTX');
from finix.resources import Authorization
authorization = Authorization.get(id="AUf7d2dGYeQEyMsrKMuQimTX")
authorization = Finix::Authorization.retrieve(:id=>"AUf7d2dGYeQEyMsrKMuQimTX")
Example Response:
{
"id" : "AUf7d2dGYeQEyMsrKMuQimTX",
"amount" : 100,
"tags" : {
"order_number" : "21DFASJSAKAS"
},
"state" : "SUCCEEDED",
"currency" : "USD",
"transfer" : "TRgKRebvAj8BCnQcpGseiH8c",
"messages" : [ ],
"raw" : null,
"created_at" : "2018-04-26T00:45:31.64Z",
"updated_at" : "2018-04-26T00:45:32.95Z",
"trace_id" : "d009e729-1e42-461a-b9bc-32da02b7e915",
"source" : "PIss82nFMq4zmbLZgtrMhpQW",
"merchant_identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"is_void" : false,
"expires_at" : "2018-05-03T00:45:31.64Z",
"idempotency_id" : null,
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/authorizations/AUf7d2dGYeQEyMsrKMuQimTX"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"transfer" : {
"href" : "https://api-staging.finix.io/transfers/TRgKRebvAj8BCnQcpGseiH8c"
},
"merchant_identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
}
}
}
HTTP Request
GET https://api-staging.finix.io/authorizations/:AUTHORIZATION_ID
URL Parameters
| Parameter | Description |
|---|---|
| :AUTHORIZATION_ID | ID of the Authorization |
List all Authorizations
curl https://api-staging.finix.io/authorizations/ \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99
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" : "AUa6wHv6V9mcrifHoWiszmyJ",
"amount" : 100,
"tags" : {
"order_number" : "21DFASJSAKAS"
},
"state" : "SUCCEEDED",
"currency" : "USD",
"transfer" : null,
"messages" : [ ],
"raw" : null,
"created_at" : "2018-04-26T00:45:35.32Z",
"updated_at" : "2018-04-26T00:45:35.84Z",
"trace_id" : "6dd8e0ce-379b-4eaf-ba8e-6d1003da7d4d",
"source" : "PIss82nFMq4zmbLZgtrMhpQW",
"merchant_identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"is_void" : true,
"expires_at" : "2018-05-03T00:45:35.32Z",
"idempotency_id" : null,
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/authorizations/AUa6wHv6V9mcrifHoWiszmyJ"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"merchant_identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
}
}
}, {
"id" : "AUvtHwMvxC1p41jXTgaxiPCq",
"amount" : 100,
"tags" : {
"order_number" : "21DFASJSAKAS"
},
"state" : "SUCCEEDED",
"currency" : "USD",
"transfer" : null,
"messages" : [ ],
"raw" : null,
"created_at" : "2018-04-26T00:45:32.45Z",
"updated_at" : "2018-04-26T00:45:32.48Z",
"trace_id" : "eef32b54-7e0a-414f-a9ab-42f4cb90a15c",
"source" : "PIss82nFMq4zmbLZgtrMhpQW",
"merchant_identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"is_void" : false,
"expires_at" : "2018-05-03T00:45:32.45Z",
"idempotency_id" : "e70805be01814de1b4fbd32f2d4a93dc",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/authorizations/AUvtHwMvxC1p41jXTgaxiPCq"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"merchant_identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
}
}
}, {
"id" : "AUf7d2dGYeQEyMsrKMuQimTX",
"amount" : 100,
"tags" : {
"order_number" : "21DFASJSAKAS"
},
"state" : "SUCCEEDED",
"currency" : "USD",
"transfer" : "TRgKRebvAj8BCnQcpGseiH8c",
"messages" : [ ],
"raw" : null,
"created_at" : "2018-04-26T00:45:31.64Z",
"updated_at" : "2018-04-26T00:45:32.95Z",
"trace_id" : "d009e729-1e42-461a-b9bc-32da02b7e915",
"source" : "PIss82nFMq4zmbLZgtrMhpQW",
"merchant_identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"is_void" : false,
"expires_at" : "2018-05-03T00:45:31.64Z",
"idempotency_id" : null,
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/authorizations/AUf7d2dGYeQEyMsrKMuQimTX"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"transfer" : {
"href" : "https://api-staging.finix.io/transfers/TRgKRebvAj8BCnQcpGseiH8c"
},
"merchant_identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/authorizations?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
}
},
"page" : {
"offset" : 0,
"limit" : 20,
"count" : 3
}
}
HTTP Request
GET https://api-staging.finix.io/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://api-staging.finix.io/disputes/DI4FyQE9gFyBU58TCh4d28yW/evidence \
-H "Content-Type: application/pdf/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-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": "2018-04-26T00:49:53.70Z",
"updated_at": "2018-04-26T00:49:53.70Z",
"_links": {
"self": {
"href": "https://api-staging.finix.io/disputes/DI4FyQE9gFyBU58TCh4d28yW/evidence/DF7BZbaJiiXbn2TvdZoR4dmE"
}
},
"id": "DF7BZbaJiiXbn2TvdZoR4dmE",
"dispute": "DI4FyQE9gFyBU58TCh4d28yW"
}
HTTP Request
POST https://api-staging.finix.io/disputes/:DISPUTE_ID/evidence
Fetch a Dispute
curl https://api-staging.finix.io/disputes/DI4FyQE9gFyBU58TCh4d28yW \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99
import io.finix.payments.processing.client.model.Dispute;
Dispute dispute = transfer.disputeClient().fetch("DI4FyQE9gFyBU58TCh4d28yW");
<?php
use Finix\Resources\Dispute;
$dispute = Dispute::retrieve('DI4FyQE9gFyBU58TCh4d28yW');
from finix.resources import Dispute
dispute = Dispute.get(id="DI4FyQE9gFyBU58TCh4d28yW")
disputes = Finix::Dispute.retrieve
Example Response:
{
"id" : "DI4FyQE9gFyBU58TCh4d28yW",
"tags" : {
"order_number" : "21DFASJSAKAS"
},
"amount" : 0,
"state" : "PENDING",
"transfer" : "TRcyQXViPasqiGJyUwYQ15uT",
"reason" : "FRAUD",
"identity" : "IDuYo7qjbtB6kMVeebe4Z6NN",
"created_at" : "2018-04-26T00:46:07.09Z",
"updated_at" : "2018-04-26T00:46:06.97Z",
"occurred_at" : "2018-04-26T00:45:50.05Z",
"respond_by" : "2018-05-03T00:46:07.08Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/disputes/DI4FyQE9gFyBU58TCh4d28yW"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"transfer" : {
"href" : "https://api-staging.finix.io/transfers/TRcyQXViPasqiGJyUwYQ15uT"
},
"evidence" : {
"href" : "https://api-staging.finix.io/disputes/DI4FyQE9gFyBU58TCh4d28yW/evidence"
}
}
}
HTTP Request
GET https://api-staging.finix.io/disputes/:DISPUTE_ID
URL Parameters
| Parameter | Description |
|---|---|
| :DISPUTE_ID | ID of the Dispute |
List all Disputes
curl https://api-staging.finix.io/disputes/ \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99
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 => "DI4FyQE9gFyBU58TCh4d28yW")
Example Response:
{
"_embedded" : {
"disputes" : [ {
"id" : "DI4FyQE9gFyBU58TCh4d28yW",
"tags" : {
"order_number" : "21DFASJSAKAS"
},
"amount" : 0,
"state" : "PENDING",
"transfer" : "TRcyQXViPasqiGJyUwYQ15uT",
"reason" : "FRAUD",
"identity" : "IDuYo7qjbtB6kMVeebe4Z6NN",
"created_at" : "2018-04-26T00:46:07.09Z",
"updated_at" : "2018-04-26T00:46:06.97Z",
"occurred_at" : "2018-04-26T00:45:50.05Z",
"respond_by" : "2018-05-03T00:46:07.08Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/disputes/DI4FyQE9gFyBU58TCh4d28yW"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"transfer" : {
"href" : "https://api-staging.finix.io/transfers/TRcyQXViPasqiGJyUwYQ15uT"
},
"evidence" : {
"href" : "https://api-staging.finix.io/disputes/DI4FyQE9gFyBU58TCh4d28yW/evidence"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/disputes?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
}
},
"page" : {
"offset" : 0,
"limit" : 20,
"count" : 1
}
}
HTTP Request
GET https://api-staging.finix.io/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://api-staging.finix.io/identities \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"tags": {
"key": "value"
},
"entity": {
"phone": "7145677613",
"first_name": "Alex",
"last_name": "Curry",
"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"=> "Alex",
"last_name"=> "Curry",
"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": "Alex",
"last_name": "Curry",
"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"=> "Alex",
"last_name"=> "Curry",
"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" : "IDuYo7qjbtB6kMVeebe4Z6NN",
"entity" : {
"title" : null,
"first_name" : "Alex",
"last_name" : "Curry",
"email" : "therock@gmail.com",
"business_name" : null,
"business_type" : null,
"doing_business_as" : null,
"phone" : "7145677613",
"business_phone" : null,
"personal_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"business_address" : null,
"mcc" : null,
"dob" : null,
"max_transaction_amount" : 0,
"amex_mid" : null,
"discover_mid" : null,
"url" : null,
"annual_card_volume" : 0,
"has_accepted_credit_cards_previously" : false,
"incorporation_date" : null,
"principal_percentage_ownership" : null,
"short_business_name" : null,
"ownership_type" : null,
"tax_id_provided" : false,
"business_tax_id_provided" : false,
"default_statement_descriptor" : null
},
"tags" : {
"key" : "value"
},
"created_at" : "2018-04-26T00:45:22.21Z",
"updated_at" : "2018-04-26T00:45:22.21Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN"
},
"verifications" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/verifications"
},
"merchants" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/merchants"
},
"settlements" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/settlements"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/transfers"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/payment_instruments"
},
"disputes" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/disputes"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}
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://api-staging.finix.io/identities
Request Arguments
| Field | Type | Description |
|---|---|---|
| first_name | string, optional | First name |
| last_name | string, optional | Last name |
| phone | string, optional | Phone number |
| string, optional | Email address | |
| line1 | string, optional | First line of the address (max 60 characters) |
| line2 | string, optional | Second line of the address (max 60 characters) |
| city | string, optional | City (max 20 characters) |
| region | string, optional | 2-letter State code |
| postal_code | string, optional | Zip or Postal code (max 7 characters) |
| country | string, optional | 3-Letter Country code |
| tags | object, optional | Key value pair for annotating custom meta data (e.g. order numbers) |
Create an Identity for a Merchant
curl https://api-staging.finix.io/identities \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"tags": {
"Studio Rating": "4.7"
},
"entity": {
"last_name": "Sunkhronos",
"max_transaction_amount": 12000000,
"has_accepted_credit_cards_previously": true,
"default_statement_descriptor": "Golds Gym",
"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": "Golds Gym",
"principal_percentage_ownership": 50,
"email": "user@example.org",
"mcc": "0742",
"phone": "1234567890",
"business_name": "Golds Gym",
"tax_id": "123456789",
"business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
"business_phone": "+1 (408) 756-4497",
"dob": {
"year": 1978,
"day": 27,
"month": 6
},
"url": "www.GoldsGym.com",
"annual_card_volume": 12000000
}
}'
import io.finix.payments.ApiClient;
import io.finix.payments.enums.BusinessType;
import io.finix.payments.forms.Address;
import io.finix.payments.forms.Date;
import io.finix.payments.forms.IdentityEntityForm;
import io.finix.payments.forms.IdentityForm;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.views.Identity;
IdentityForm form = IdentityForm.builder()
.entity(IdentityEntityForm.builder()
.firstName("dwayne")
.lastName("Sunkhronos")
.email("user@example.org")
.businessName("business inc")
.businessType(BusinessType.LIMITED_LIABILITY_COMPANY)
.doingBusinessAs("doingBusinessAs")
.phone("1234567890")
.businessPhone("+1 (408) 756-4497")
.taxId("123456789")
.businessTaxId("123456789")
.personalAddress(Address.builder()
.line1("741 Douglass St")
.line2("Apartment 7")
.city("San Mateo")
.region("CA")
.postalCode("94114")
.country("USA")
.build())
.businessAddress(Address.builder()
.line1("741 Douglass St")
.line2("Apartment 7")
.city("San Mateo")
.region("CA")
.postalCode("94114")
.country("USA")
.build())
.dob(Date.builder().day(Integer.valueOf(27)).month(Integer.valueOf(5)).year(Integer.valueOf(1978)).build())
.maxTransactionAmount(Long.valueOf(1000L))
.mcc("7399").url("http://sample-entity.com")
.annualCardVolume(Long.valueOf(100L))
.defaultStatementDescriptor("Business Inc")
.incorporationDate(Date.builder().day(Integer.valueOf(1)).month(Integer.valueOf(12)).year(Integer.valueOf(2012)).build())
.principalPercentageOwnership(Integer.valueOf(51)).build()).build();
Maybe<Identity> response = api.identities.post(form);
if(! response.succeeded().booleanValue()) {
ApiError error = response.error();
System.out.println(error.getCode());
throw new RuntimeException("API error attempting to create Identity");
}
Identity identity = (Identity)response.view();
<?php
use Finix\Resources\Identity;
$identity = new Identity(
array(
"tags"=> array(
"Studio Rating"=> "4.7"
),
"entity"=> array(
"last_name"=> "Sunkhronos",
"max_transaction_amount"=> 12000000,
"has_accepted_credit_cards_previously"=> true,
"default_statement_descriptor"=> "Golds Gym",
"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"=> "Golds Gym",
"principal_percentage_ownership"=> 50,
"email"=> "user@example.org",
"mcc"=> "0742",
"phone"=> "1234567890",
"business_name"=> "Golds Gym",
"tax_id"=> "123456789",
"business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP",
"business_phone"=> "+1 (408) 756-4497",
"dob"=> array(
"year"=> 1978,
"day"=> 27,
"month"=> 6
),
"url"=> "www.GoldsGym.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": "Golds Gym",
"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": "Golds Gym",
"principal_percentage_ownership": 50,
"email": "user@example.org",
"mcc": "0742",
"phone": "1234567890",
"business_name": "Golds Gym",
"tax_id": "123456789",
"business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
"business_phone": "+1 (408) 756-4497",
"dob": {
"year": 1978,
"day": 27,
"month": 6
},
"url": "www.GoldsGym.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"=> "Golds Gym",
"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"=> "Golds Gym",
"principal_percentage_ownership"=> 50,
"email"=> "user@example.org",
"mcc"=> "0742",
"phone"=> "1234567890",
"business_name"=> "Golds Gym",
"tax_id"=> "123456789",
"business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP",
"business_phone"=> "+1 (408) 756-4497",
"dob"=> {
"year"=> 1978,
"day"=> 27,
"month"=> 6
},
"url"=> "www.GoldsGym.com",
"annual_card_volume"=> 12000000
}
}).save
Example Response:
{
"id" : "IDpSEHq3qRRSxvqzUkipefAM",
"entity" : {
"title" : "CEO",
"first_name" : "dwayne",
"last_name" : "Sunkhronos",
"email" : "user@example.org",
"business_name" : "Golds Gym",
"business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
"doing_business_as" : "Golds Gym",
"phone" : "1234567890",
"business_phone" : "+1 (408) 756-4497",
"personal_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"business_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 8",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"mcc" : "0742",
"dob" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"max_transaction_amount" : 12000000,
"amex_mid" : null,
"discover_mid" : null,
"url" : "www.GoldsGym.com",
"annual_card_volume" : 12000000,
"has_accepted_credit_cards_previously" : true,
"incorporation_date" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"principal_percentage_ownership" : 50,
"short_business_name" : null,
"ownership_type" : "PRIVATE",
"tax_id_provided" : true,
"business_tax_id_provided" : true,
"default_statement_descriptor" : "Golds Gym"
},
"tags" : {
"Studio Rating" : "4.7"
},
"created_at" : "2018-04-26T00:45:15.68Z",
"updated_at" : "2018-04-26T00:45:15.68Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"verifications" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/verifications"
},
"merchants" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/merchants"
},
"settlements" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/settlements"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/transfers"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/payment_instruments"
},
"disputes" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/disputes"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}
Create an Identity resource with the merchant’s underwriting information.
HTTP Request
POST https://api-staging.finix.io/identities
Business-specific Request Arguments
| Field | Type | Description |
|---|---|---|
| business_name | string, required | Merchant’s full legal business name (If INDIVIDUAL_SOLE_PROPRIETORSHIP, please input first name, Full legal last name and middle initial; max 120 characters) |
| doing_business_as | string, required | Alternate name of the business. If no other name is used please use the same value for business_name (max 60 characters) |
| business_type | string, required | Please select one of the following values: INDIVIDUAL_SOLE_PROPRIETORSHIP, CORPORATION, LIMITED_LIABILITY_COMPANY, PARTNERSHIP, ASSOCIATION_ESTATE_TRUST, TAX_EXEMPT_ORGANIZATION, INTERNATIONAL_ORGANIZATION, GOVERNMENT_AGENCY |
| business_tax_id | string, required | Nine digit Tax Identification Number (TIN), Employer Identification Number (EIN) or if the business_type is INDIVIDUAL_SOLE_PROPRIETORSHIP and a Tax ID is not available, the principal’s Social Security Number (SSN) |
| url | string, required | Merchant’s publicly available website (max 100 characters) |
| business_phone | string, required | Customer service phone number where the merchant can be reached (max 10 characters) |
| incorporation_date | object, required | Date company was founded (See below for a full list of the child attributes) |
| business_address | object, required | Primary address for the legal entity (Full description of child attributes below) |
| ownership_type | string, required | Values can be either PUBLIC to indicate a publicly traded company or PRIVATE for privately held businesses |
Principal-specific Request Arguments
(i.e. authorized representative or primary contact responsible for the account)
| Field | Type | Description |
|---|---|---|
| first_name | string, required | Full legal first name of the merchant’s principal representative (max 20 characters) |
| last_name | string, required | Full legal last name of the merchant’s principal representative (max 20 characters) |
| title | string, required | Principal’s corporate title or role (i.e. Chief Executive Officer, CFO, etc.; max 60 characters) |
| principal_percentage_ownership | integer, required | Percentage of company owned by the principal (min 0; max 100) |
| tax_id | string, required | Nine digit Social Security Number (SSN) for the principal |
| dob | object, required | Principal’s date of birth (Full description of child attributes below) |
| phone | string, required | Principal’s phone number (max 10 characters) |
| string, required | Principal’s email address where they can be reached (max 100 characters) | |
| personal_address | object, required | Principal’s personal home address. This field is used for identity verification purposes (Full description of child attributes below) |
Processing-specific Request Arguments
| Field | Type | Description |
|---|---|---|
| default_statement_descriptor | string, required | Billing descriptor displayed on the buyer’s bank or card statement (Length must be between 1 and 20 characters) |
| annual_card_volume | integer, required | Approximate annual credit card sales expected to be processed in cents by this merchant (max 23 characters) |
| max_transaction_amount | integer, required | Maximum amount that can be transacted for a single transaction in cents (max 12 characters) |
| mcc | string, required | Merchant Category Code (MCC) that this merchant will be classified under |
| has_accepted_credit_cards_previously | boolean, optional | Defaults to false if not passed |
Address-object Request Arguments
| Field | Type | Description |
|---|---|---|
| line1 | string, required | First line of the address (max 60 characters) |
| line2 | string, optional | Second line of the address (max 60 characters) |
| city | string, required | City (max 20 characters) |
| region | string, required | 2-letter State code |
| postal_code | string, required | Zip or Postal code (max 7 characters) |
| country | string, required | 3-Letter Country code |
Incorporation Date-object Request Arguments
| Field | Type | Description |
|---|---|---|
| day | integer, required | Day business was incorporated (between 1 and 31) |
| month | integer, required | Month business was incorporated (between 1 and 12) |
| year | integer, required | Year business was incorporated (4-digit) |
DOB-object Request Arguments
| Field | Type | Description |
|---|---|---|
| day | integer, required | Day of birth (between 1 and 31) |
| month | integer, required | Month of birth (between 1 and 12) |
| year | integer, required | Year of birth (4-digit) |
Fetch a Identity
curl https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99
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("IDpSEHq3qRRSxvqzUkipefAM").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('IDpSEHq3qRRSxvqzUkipefAM');
from finix.resources import Identity
identity = Identity.get(id="IDpSEHq3qRRSxvqzUkipefAM")
identity = Finix::Identity.retrieve(:id=>"IDpSEHq3qRRSxvqzUkipefAM")
Example Response:
{
"id" : "IDpSEHq3qRRSxvqzUkipefAM",
"entity" : {
"title" : "CEO",
"first_name" : "dwayne",
"last_name" : "Sunkhronos",
"email" : "user@example.org",
"business_name" : "Golds Gym",
"business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
"doing_business_as" : "Golds Gym",
"phone" : "1234567890",
"business_phone" : "+1 (408) 756-4497",
"personal_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"business_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 8",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"mcc" : "0742",
"dob" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"max_transaction_amount" : 12000000,
"amex_mid" : null,
"discover_mid" : null,
"url" : "www.GoldsGym.com",
"annual_card_volume" : 12000000,
"has_accepted_credit_cards_previously" : true,
"incorporation_date" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"principal_percentage_ownership" : 50,
"short_business_name" : null,
"ownership_type" : "PRIVATE",
"tax_id_provided" : true,
"business_tax_id_provided" : true,
"default_statement_descriptor" : "Golds Gym"
},
"tags" : {
"Studio Rating" : "4.7"
},
"created_at" : "2018-04-26T00:45:15.68Z",
"updated_at" : "2018-04-26T00:45:15.66Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"verifications" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/verifications"
},
"merchants" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/merchants"
},
"settlements" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/settlements"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/transfers"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/payment_instruments"
},
"disputes" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/disputes"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}
HTTP Request
GET https://api-staging.finix.io/identities/:IDENTITY_ID
URL Parameters
| Parameter | Description |
|---|---|
| :IDENTITY_ID | ID of the Identity |
List all Identities
curl https://api-staging.finix.io/identities/ \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99
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" : "IDuYo7qjbtB6kMVeebe4Z6NN",
"entity" : {
"title" : null,
"first_name" : "Alex",
"last_name" : "Curry",
"email" : "therock@gmail.com",
"business_name" : null,
"business_type" : null,
"doing_business_as" : null,
"phone" : "7145677613",
"business_phone" : null,
"personal_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"business_address" : null,
"mcc" : null,
"dob" : null,
"max_transaction_amount" : 0,
"amex_mid" : null,
"discover_mid" : null,
"url" : null,
"annual_card_volume" : 0,
"has_accepted_credit_cards_previously" : false,
"incorporation_date" : null,
"principal_percentage_ownership" : null,
"short_business_name" : null,
"ownership_type" : null,
"tax_id_provided" : false,
"business_tax_id_provided" : false,
"default_statement_descriptor" : null
},
"tags" : {
"key" : "value"
},
"created_at" : "2018-04-26T00:45:22.21Z",
"updated_at" : "2018-04-26T00:45:22.19Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN"
},
"verifications" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/verifications"
},
"merchants" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/merchants"
},
"settlements" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/settlements"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/transfers"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/payment_instruments"
},
"disputes" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN/disputes"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}, {
"id" : "IDaB81N87H4rBHUU62BKkyLF",
"entity" : {
"title" : "CEO",
"first_name" : "dwayne",
"last_name" : "Sunkhronos",
"email" : "user@example.org",
"business_name" : "Golds Gym",
"business_type" : "GOVERNMENT_AGENCY",
"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_id_provided" : true,
"business_tax_id_provided" : true,
"default_statement_descriptor" : "Golds Gym"
},
"tags" : {
"Studio Rating" : "4.7"
},
"created_at" : "2018-04-26T00:45:19.18Z",
"updated_at" : "2018-04-26T00:45:19.16Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities/IDaB81N87H4rBHUU62BKkyLF"
},
"verifications" : {
"href" : "https://api-staging.finix.io/identities/IDaB81N87H4rBHUU62BKkyLF/verifications"
},
"merchants" : {
"href" : "https://api-staging.finix.io/identities/IDaB81N87H4rBHUU62BKkyLF/merchants"
},
"settlements" : {
"href" : "https://api-staging.finix.io/identities/IDaB81N87H4rBHUU62BKkyLF/settlements"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/identities/IDaB81N87H4rBHUU62BKkyLF/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/identities/IDaB81N87H4rBHUU62BKkyLF/transfers"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/identities/IDaB81N87H4rBHUU62BKkyLF/payment_instruments"
},
"disputes" : {
"href" : "https://api-staging.finix.io/identities/IDaB81N87H4rBHUU62BKkyLF/disputes"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}, {
"id" : "IDuvXcRDRkPgLjNbt6xqiNkA",
"entity" : {
"title" : "CEO",
"first_name" : "dwayne",
"last_name" : "Sunkhronos",
"email" : "user@example.org",
"business_name" : "Pawny City Hall",
"business_type" : "INTERNATIONAL_ORGANIZATION",
"doing_business_as" : "Pawny City Hall",
"phone" : "1234567890",
"business_phone" : "+1 (408) 756-4497",
"personal_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"business_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 8",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"mcc" : "0742",
"dob" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"max_transaction_amount" : 12000000,
"amex_mid" : null,
"discover_mid" : null,
"url" : "www.PawnyCityHall.com",
"annual_card_volume" : 12000000,
"has_accepted_credit_cards_previously" : true,
"incorporation_date" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"principal_percentage_ownership" : 50,
"short_business_name" : null,
"ownership_type" : "PRIVATE",
"tax_id_provided" : true,
"business_tax_id_provided" : true,
"default_statement_descriptor" : "Pawny City Hall"
},
"tags" : {
"Studio Rating" : "4.7"
},
"created_at" : "2018-04-26T00:45:18.58Z",
"updated_at" : "2018-04-26T00:45:18.56Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities/IDuvXcRDRkPgLjNbt6xqiNkA"
},
"verifications" : {
"href" : "https://api-staging.finix.io/identities/IDuvXcRDRkPgLjNbt6xqiNkA/verifications"
},
"merchants" : {
"href" : "https://api-staging.finix.io/identities/IDuvXcRDRkPgLjNbt6xqiNkA/merchants"
},
"settlements" : {
"href" : "https://api-staging.finix.io/identities/IDuvXcRDRkPgLjNbt6xqiNkA/settlements"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/identities/IDuvXcRDRkPgLjNbt6xqiNkA/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/identities/IDuvXcRDRkPgLjNbt6xqiNkA/transfers"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/identities/IDuvXcRDRkPgLjNbt6xqiNkA/payment_instruments"
},
"disputes" : {
"href" : "https://api-staging.finix.io/identities/IDuvXcRDRkPgLjNbt6xqiNkA/disputes"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}, {
"id" : "IDgdYT19eU5pQTsvjmqdK3yq",
"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_id_provided" : true,
"business_tax_id_provided" : true,
"default_statement_descriptor" : "Golds Gym"
},
"tags" : {
"Studio Rating" : "4.7"
},
"created_at" : "2018-04-26T00:45:17.97Z",
"updated_at" : "2018-04-26T00:45:17.95Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities/IDgdYT19eU5pQTsvjmqdK3yq"
},
"verifications" : {
"href" : "https://api-staging.finix.io/identities/IDgdYT19eU5pQTsvjmqdK3yq/verifications"
},
"merchants" : {
"href" : "https://api-staging.finix.io/identities/IDgdYT19eU5pQTsvjmqdK3yq/merchants"
},
"settlements" : {
"href" : "https://api-staging.finix.io/identities/IDgdYT19eU5pQTsvjmqdK3yq/settlements"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/identities/IDgdYT19eU5pQTsvjmqdK3yq/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/identities/IDgdYT19eU5pQTsvjmqdK3yq/transfers"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/identities/IDgdYT19eU5pQTsvjmqdK3yq/payment_instruments"
},
"disputes" : {
"href" : "https://api-staging.finix.io/identities/IDgdYT19eU5pQTsvjmqdK3yq/disputes"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}, {
"id" : "IDa4Nq8VspY3EfoxdBjCAu1R",
"entity" : {
"title" : "CEO",
"first_name" : "dwayne",
"last_name" : "Sunkhronos",
"email" : "user@example.org",
"business_name" : "Pawny City Hall",
"business_type" : "ASSOCIATION_ESTATE_TRUST",
"doing_business_as" : "Pawny City Hall",
"phone" : "1234567890",
"business_phone" : "+1 (408) 756-4497",
"personal_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"business_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 8",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"mcc" : "0742",
"dob" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"max_transaction_amount" : 12000000,
"amex_mid" : null,
"discover_mid" : null,
"url" : "www.PawnyCityHall.com",
"annual_card_volume" : 12000000,
"has_accepted_credit_cards_previously" : true,
"incorporation_date" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"principal_percentage_ownership" : 50,
"short_business_name" : null,
"ownership_type" : "PRIVATE",
"tax_id_provided" : true,
"business_tax_id_provided" : true,
"default_statement_descriptor" : "Pawny City Hall"
},
"tags" : {
"Studio Rating" : "4.7"
},
"created_at" : "2018-04-26T00:45:17.56Z",
"updated_at" : "2018-04-26T00:45:17.54Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities/IDa4Nq8VspY3EfoxdBjCAu1R"
},
"verifications" : {
"href" : "https://api-staging.finix.io/identities/IDa4Nq8VspY3EfoxdBjCAu1R/verifications"
},
"merchants" : {
"href" : "https://api-staging.finix.io/identities/IDa4Nq8VspY3EfoxdBjCAu1R/merchants"
},
"settlements" : {
"href" : "https://api-staging.finix.io/identities/IDa4Nq8VspY3EfoxdBjCAu1R/settlements"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/identities/IDa4Nq8VspY3EfoxdBjCAu1R/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/identities/IDa4Nq8VspY3EfoxdBjCAu1R/transfers"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/identities/IDa4Nq8VspY3EfoxdBjCAu1R/payment_instruments"
},
"disputes" : {
"href" : "https://api-staging.finix.io/identities/IDa4Nq8VspY3EfoxdBjCAu1R/disputes"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}, {
"id" : "IDtjVzqq6ZNVbd3PfK7t3oSa",
"entity" : {
"title" : "CEO",
"first_name" : "dwayne",
"last_name" : "Sunkhronos",
"email" : "user@example.org",
"business_name" : "Bobs Burgers",
"business_type" : "PARTNERSHIP",
"doing_business_as" : "Bobs Burgers",
"phone" : "1234567890",
"business_phone" : "+1 (408) 756-4497",
"personal_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"business_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 8",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"mcc" : "0742",
"dob" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"max_transaction_amount" : 12000000,
"amex_mid" : null,
"discover_mid" : null,
"url" : "www.BobsBurgers.com",
"annual_card_volume" : 12000000,
"has_accepted_credit_cards_previously" : true,
"incorporation_date" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"principal_percentage_ownership" : 50,
"short_business_name" : null,
"ownership_type" : "PRIVATE",
"tax_id_provided" : true,
"business_tax_id_provided" : true,
"default_statement_descriptor" : "Bobs Burgers"
},
"tags" : {
"Studio Rating" : "4.7"
},
"created_at" : "2018-04-26T00:45:16.99Z",
"updated_at" : "2018-04-26T00:45:16.98Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities/IDtjVzqq6ZNVbd3PfK7t3oSa"
},
"verifications" : {
"href" : "https://api-staging.finix.io/identities/IDtjVzqq6ZNVbd3PfK7t3oSa/verifications"
},
"merchants" : {
"href" : "https://api-staging.finix.io/identities/IDtjVzqq6ZNVbd3PfK7t3oSa/merchants"
},
"settlements" : {
"href" : "https://api-staging.finix.io/identities/IDtjVzqq6ZNVbd3PfK7t3oSa/settlements"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/identities/IDtjVzqq6ZNVbd3PfK7t3oSa/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/identities/IDtjVzqq6ZNVbd3PfK7t3oSa/transfers"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/identities/IDtjVzqq6ZNVbd3PfK7t3oSa/payment_instruments"
},
"disputes" : {
"href" : "https://api-staging.finix.io/identities/IDtjVzqq6ZNVbd3PfK7t3oSa/disputes"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}, {
"id" : "ID8wYJ8V14iAWrMA7idUatfh",
"entity" : {
"title" : "CEO",
"first_name" : "dwayne",
"last_name" : "Sunkhronos",
"email" : "user@example.org",
"business_name" : "Pawny City Hall",
"business_type" : "LIMITED_LIABILITY_COMPANY",
"doing_business_as" : "Pawny City Hall",
"phone" : "1234567890",
"business_phone" : "+1 (408) 756-4497",
"personal_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"business_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 8",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"mcc" : "0742",
"dob" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"max_transaction_amount" : 12000000,
"amex_mid" : null,
"discover_mid" : null,
"url" : "www.PawnyCityHall.com",
"annual_card_volume" : 12000000,
"has_accepted_credit_cards_previously" : true,
"incorporation_date" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"principal_percentage_ownership" : 50,
"short_business_name" : null,
"ownership_type" : "PRIVATE",
"tax_id_provided" : true,
"business_tax_id_provided" : true,
"default_statement_descriptor" : "Pawny City Hall"
},
"tags" : {
"Studio Rating" : "4.7"
},
"created_at" : "2018-04-26T00:45:16.58Z",
"updated_at" : "2018-04-26T00:45:16.56Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities/ID8wYJ8V14iAWrMA7idUatfh"
},
"verifications" : {
"href" : "https://api-staging.finix.io/identities/ID8wYJ8V14iAWrMA7idUatfh/verifications"
},
"merchants" : {
"href" : "https://api-staging.finix.io/identities/ID8wYJ8V14iAWrMA7idUatfh/merchants"
},
"settlements" : {
"href" : "https://api-staging.finix.io/identities/ID8wYJ8V14iAWrMA7idUatfh/settlements"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/identities/ID8wYJ8V14iAWrMA7idUatfh/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/identities/ID8wYJ8V14iAWrMA7idUatfh/transfers"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/identities/ID8wYJ8V14iAWrMA7idUatfh/payment_instruments"
},
"disputes" : {
"href" : "https://api-staging.finix.io/identities/ID8wYJ8V14iAWrMA7idUatfh/disputes"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}, {
"id" : "IDcaGy8SuULNkvWvvKroWGfS",
"entity" : {
"title" : "CEO",
"first_name" : "dwayne",
"last_name" : "Sunkhronos",
"email" : "user@example.org",
"business_name" : "Lees Sandwiches",
"business_type" : "CORPORATION",
"doing_business_as" : "Lees Sandwiches",
"phone" : "1234567890",
"business_phone" : "+1 (408) 756-4497",
"personal_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"business_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 8",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"mcc" : "0742",
"dob" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"max_transaction_amount" : 12000000,
"amex_mid" : null,
"discover_mid" : null,
"url" : "www.LeesSandwiches.com",
"annual_card_volume" : 12000000,
"has_accepted_credit_cards_previously" : true,
"incorporation_date" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"principal_percentage_ownership" : 50,
"short_business_name" : null,
"ownership_type" : "PRIVATE",
"tax_id_provided" : true,
"business_tax_id_provided" : true,
"default_statement_descriptor" : "Lees Sandwiches"
},
"tags" : {
"Studio Rating" : "4.7"
},
"created_at" : "2018-04-26T00:45:16.14Z",
"updated_at" : "2018-04-26T00:45:16.12Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities/IDcaGy8SuULNkvWvvKroWGfS"
},
"verifications" : {
"href" : "https://api-staging.finix.io/identities/IDcaGy8SuULNkvWvvKroWGfS/verifications"
},
"merchants" : {
"href" : "https://api-staging.finix.io/identities/IDcaGy8SuULNkvWvvKroWGfS/merchants"
},
"settlements" : {
"href" : "https://api-staging.finix.io/identities/IDcaGy8SuULNkvWvvKroWGfS/settlements"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/identities/IDcaGy8SuULNkvWvvKroWGfS/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/identities/IDcaGy8SuULNkvWvvKroWGfS/transfers"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/identities/IDcaGy8SuULNkvWvvKroWGfS/payment_instruments"
},
"disputes" : {
"href" : "https://api-staging.finix.io/identities/IDcaGy8SuULNkvWvvKroWGfS/disputes"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}, {
"id" : "IDpSEHq3qRRSxvqzUkipefAM",
"entity" : {
"title" : "CEO",
"first_name" : "dwayne",
"last_name" : "Sunkhronos",
"email" : "user@example.org",
"business_name" : "Golds Gym",
"business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
"doing_business_as" : "Golds Gym",
"phone" : "1234567890",
"business_phone" : "+1 (408) 756-4497",
"personal_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"business_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 8",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"mcc" : "0742",
"dob" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"max_transaction_amount" : 12000000,
"amex_mid" : null,
"discover_mid" : null,
"url" : "www.GoldsGym.com",
"annual_card_volume" : 12000000,
"has_accepted_credit_cards_previously" : true,
"incorporation_date" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"principal_percentage_ownership" : 50,
"short_business_name" : null,
"ownership_type" : "PRIVATE",
"tax_id_provided" : true,
"business_tax_id_provided" : true,
"default_statement_descriptor" : "Golds Gym"
},
"tags" : {
"Studio Rating" : "4.7"
},
"created_at" : "2018-04-26T00:45:15.68Z",
"updated_at" : "2018-04-26T00:45:15.66Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"verifications" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/verifications"
},
"merchants" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/merchants"
},
"settlements" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/settlements"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/transfers"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/payment_instruments"
},
"disputes" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/disputes"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}, {
"id" : "IDqmXMUNztTYNUU52FvHDCts",
"entity" : {
"title" : null,
"first_name" : "dwayne",
"last_name" : "Sunkhronos",
"email" : "user@example.org",
"business_name" : "Dwolla",
"business_type" : "LIMITED_LIABILITY_COMPANY",
"doing_business_as" : "Dwolla",
"phone" : "1234567890",
"business_phone" : "+1 (408) 756-4497",
"personal_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"business_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 8",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"mcc" : null,
"dob" : {
"day" : 27,
"month" : 5,
"year" : 1978
},
"max_transaction_amount" : 1200000,
"amex_mid" : null,
"discover_mid" : null,
"url" : null,
"annual_card_volume" : 0,
"has_accepted_credit_cards_previously" : false,
"incorporation_date" : null,
"principal_percentage_ownership" : null,
"short_business_name" : null,
"ownership_type" : null,
"tax_id_provided" : true,
"business_tax_id_provided" : true,
"default_statement_descriptor" : null
},
"tags" : {
"application_name" : "Dwolla"
},
"created_at" : "2018-04-26T00:45:03.21Z",
"updated_at" : "2018-04-26T00:45:03.22Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities/IDqmXMUNztTYNUU52FvHDCts"
},
"verifications" : {
"href" : "https://api-staging.finix.io/identities/IDqmXMUNztTYNUU52FvHDCts/verifications"
},
"merchants" : {
"href" : "https://api-staging.finix.io/identities/IDqmXMUNztTYNUU52FvHDCts/merchants"
},
"settlements" : {
"href" : "https://api-staging.finix.io/identities/IDqmXMUNztTYNUU52FvHDCts/settlements"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/identities/IDqmXMUNztTYNUU52FvHDCts/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/identities/IDqmXMUNztTYNUU52FvHDCts/transfers"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/identities/IDqmXMUNztTYNUU52FvHDCts/payment_instruments"
},
"disputes" : {
"href" : "https://api-staging.finix.io/identities/IDqmXMUNztTYNUU52FvHDCts/disputes"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
}
},
"page" : {
"offset" : 0,
"limit" : 20,
"count" : 10
}
}
HTTP Request
GET https://api-staging.finix.io/identities/
Update an Identity
curl https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-X PUT \
-d '
{
"tags": {
"key": "value_2"
},
"entity": {
"business_phone": "+1 (408) 756-4497",
"first_name": "Bernard",
"last_name": "Jones",
"title": "CTO",
"dob": {
"year": 1988,
"day": 2,
"month": 5
},
"ownership_type": "PRIVATE",
"has_accepted_credit_cards_previously": true,
"mcc": "0742",
"phone": "7144177878",
"business_tax_id": "123456789",
"max_transaction_amount": 1200000,
"principal_percentage_ownership": 50,
"doing_business_as": "Lees Sandwiches",
"annual_card_volume": 12000000,
"default_statement_descriptor": "Lees Sandwiches",
"url": "www.LeesSandwiches.com",
"business_name": "Lees Sandwiches",
"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("IDpSEHq3qRRSxvqzUkipefAM").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="IDpSEHq3qRRSxvqzUkipefAM")
identity.entity["first_name"] = "Bernard"
identity.save()
identity = Finix::Identity.retrieve(:id=>"IDpSEHq3qRRSxvqzUkipefAM")
identity.entity["first_name"] = "Bernard"
identity.save
Example Response:
{
"id" : "IDpSEHq3qRRSxvqzUkipefAM",
"entity" : {
"title" : "CTO",
"first_name" : "Bernard",
"last_name" : "Jones",
"email" : "user@example.org",
"business_name" : "Lees Sandwiches",
"business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
"doing_business_as" : "Lees Sandwiches",
"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.LeesSandwiches.com",
"annual_card_volume" : 12000000,
"has_accepted_credit_cards_previously" : true,
"incorporation_date" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"principal_percentage_ownership" : 50,
"short_business_name" : null,
"ownership_type" : "PRIVATE",
"tax_id_provided" : true,
"business_tax_id_provided" : true,
"default_statement_descriptor" : "Lees Sandwiches"
},
"tags" : {
"key" : "value_2"
},
"created_at" : "2018-04-26T00:45:15.68Z",
"updated_at" : "2018-04-26T00:45:48.11Z",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"verifications" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/verifications"
},
"merchants" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/merchants"
},
"settlements" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/settlements"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/transfers"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/payment_instruments"
},
"disputes" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/disputes"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}
Update the information of a previously created Identity. Please note that in
the case of merchant accounts this API request alone does not update this
information on the underlying processor. To update the merchant’s information
on the underlying processor you must update the merchant on the
processor.
HTTP Request
POST https://api-staging.finix.io/identities
Business-specific Request Arguments
| Field | Type | Description |
|---|---|---|
| business_name | string, required | Merchant’s full legal business name (If INDIVIDUAL_SOLE_PROPRIETORSHIP, please input first name, Full legal last name and middle initial; max 120 characters) |
| doing_business_as | string, required | Alternate name of the business. If no other name is used please use the same value for business_name (max 60 characters) |
| business_type | string, required | Please select one of the following values: INDIVIDUAL_SOLE_PROPRIETORSHIP, CORPORATION, LIMITED_LIABILITY_COMPANY, PARTNERSHIP, ASSOCIATION_ESTATE_TRUST, TAX_EXEMPT_ORGANIZATION, INTERNATIONAL_ORGANIZATION, GOVERNMENT_AGENCY |
| business_tax_id | string, required | Nine digit Tax Identification Number (TIN), Employer Identification Number (EIN) or if the business_type is INDIVIDUAL_SOLE_PROPRIETORSHIP and a Tax ID is not available, the principal’s Social Security Number (SSN) |
| url | string, required | Merchant’s publicly available website (max 100 characters) |
| business_phone | string, required | Customer service phone number where the merchant can be reached (max 10 characters) |
| incorporation_date | object, required | Date company was founded (See below for a full list of the child attributes) |
| business_address | object, required | Primary address for the legal entity (Full description of child attributes below) |
| ownership_type | string, required | Values can be either PUBLIC to indicate a publicly traded company or PRIVATE for privately held businesses |
Principal-specific Request Arguments
(i.e. authorized representative or primary contact responsible for the account)
| Field | Type | Description |
|---|---|---|
| first_name | string, required | Full legal first name of the merchant’s principal representative (max 20 characters) |
| last_name | string, required | Full legal last name of the merchant’s principal representative (max 20 characters) |
| title | string, required | Principal’s corporate title or role (i.e. Chief Executive Officer, CFO, etc.; max 60 characters) |
| principal_percentage_ownership | integer, required | Percentage of company owned by the principal (min 0; max 100) |
| tax_id | string, required | Nine digit Social Security Number (SSN) for the principal |
| dob | object, required | Principal’s date of birth (Full description of child attributes below) |
| phone | string, required | Principal’s phone number (max 10 characters) |
| string, required | Principal’s email address where they can be reached (max 100 characters) | |
| personal_address | object, required | Principal’s personal home address. This field is used for identity verification purposes (Full description of child attributes below) |
Processing-specific Request Arguments
| Field | Type | Description |
|---|---|---|
| default_statement_descriptor | string, required | Billing descriptor displayed on the buyer’s bank or card statement (Length must be between 1 and 20 characters) |
| annual_card_volume | integer, required | Approximate annual credit card sales expected to be processed in cents by this merchant (max 23 characters) |
| max_transaction_amount | integer, required | Maximum amount that can be transacted for a single transaction in cents (max 12 characters) |
| mcc | string, required | Merchant Category Code (MCC) that this merchant will be classified under |
| has_accepted_credit_cards_previously | boolean, optional | Defaults to false if not passed |
Address-object Request Arguments
| Field | Type | Description |
|---|---|---|
| line1 | string, optional | First line of the address (max 60 characters) |
| line2 | string, optional | Second line of the address (max 60 characters) |
| city | string, required | City (max 20 characters) |
| region | string, optional | 2-letter State code |
| postal_code | string, optional | Zip or Postal code (max 7 characters) |
| country | string, optional | 3-Letter Country code |
Incorporation Date-object Request Arguments
| Field | Type | Description |
|---|---|---|
| day | integer, required | Day business was incorporated (between 1 and 31) |
| month | integer, required | Month business was incorporated (between 1 and 12) |
| year | integer, required | Year business was incorporated (4-digit) |
DOB-object Request Arguments
| Field | Type | Description |
|---|---|---|
| day | integer, required | Day of birth (between 1 and 31) |
| month | integer, required | Month of birth (between 1 and 12) |
| year | integer, required | Year of birth (4-digit) |
Provision a Merchant
curl https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/merchants \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"processor": null,
"tags": {
"key_2": "value_2"
}
}'
import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
import com.google.common.collect.ImmutableMap;
Maybe<Identity> response = api.identities.id("IDpSEHq3qRRSxvqzUkipefAM").get();
if (! response.succeeded()) {
ApiError error = response.error();
System.out.println(error.getCode());
throw new RuntimeException("API error attempting to fetch Identity");
}
Identity identity = response.view();
MerchantUnderwritingForm form = MerchantUnderwritingForm.builder()
.tags(ImmutableMap.of("key", "value"))
.build();
Maybe<Merchant> merchantResponse = api.identities.id(identity.id).merchants.post(form);
if (! merchantResponse.succeeded()) {
ApiError error = merchantResponse.error();
System.out.println(error.getCode());
throw new RuntimeException("API error attempting to provision Merchant");
}
Merchant merchant = merchantResponse.view();
<?php
use Finix\Resources\Identity;
use Finix\Resources\Merchant;
$identity = Identity::retrieve('IDpSEHq3qRRSxvqzUkipefAM');
$merchant = $identity->provisionMerchantOn(new Merchant());
from finix.resources import Identity
from finix.resources import Merchant
identity = Identity.get(id="IDpSEHq3qRRSxvqzUkipefAM")
merchant = identity.provision_merchant_on(Merchant())
identity = Finix::Identity.retrieve(:id=>"IDpSEHq3qRRSxvqzUkipefAM")
merchant = identity.provision_merchant
Example Response:
{
"id" : "MUwHAaGeNNmW5JF6oMjzWdDQ",
"identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"verification" : "VI8FBZnMgGReYM6KnCncEbMR",
"merchant_profile" : "MP4xt1veRZLAjbhAHdrZGqrb",
"processor" : "DUMMY_V1",
"processing_enabled" : false,
"settlement_enabled" : false,
"creating_transfer_from_report_enabled" : false,
"tags" : { },
"created_at" : "2018-04-26T00:45:21.07Z",
"updated_at" : "2018-04-26T00:45:21.07Z",
"onboarding_state" : "PROVISIONING",
"processor_details" : { },
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"verifications" : {
"href" : "https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ/verifications"
},
"merchant_profile" : {
"href" : "https://api-staging.finix.io/merchant_profiles/MP4xt1veRZLAjbhAHdrZGqrb"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"verification" : {
"href" : "https://api-staging.finix.io/verifications/VI8FBZnMgGReYM6KnCncEbMR"
}
}
}
Provision a Merchant for a previously created Identity resource to begin
transacting on their behalf.
Merchant resources can have 3 potential states:
PROVISIONING: Request is pending (state will typically change after two minutes)APPROVED: Merchant has been approved and can begin processingREJECTED: Merchant was rejected by the processor either because the underwriting information collected was invalid or it failed one a number of regulatory and compliance checks (e.g. KYC, OFAC or MATCH)
HTTP Request
POST https://api-staging.finix.io/identities/identity_id/merchants
URL Parameters
| Parameter | Description |
|---|---|
| identity_id | ID of the Identity |
Merchants
A Merchant resource represents a business’s merchant account on a processor. In other words, any web service that connects buyers (i.e.
customers) and sellers (i.e. merchants).
Provision a Merchant
curl https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/merchants \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"processor": null,
"tags": {
"key_2": "value_2"
}
}'
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.views.*;
import io.finix.payments.forms.*;
MerchantUnderwritingForm form = MerchantUnderwritingForm.builder()
.processor(null)
.tags(ImmutableMap.of("key", "value"))
.build();
Maybe<Merchant> underwriteMerchant = api.identities.id("IDpSEHq3qRRSxvqzUkipefAM").merchants.post(form);
if(! underwriteMerchant.succeeded()){
System.out.println(underwriteMerchant.error());
}
Merchant provisionMerchant = underwriteMerchant.view();
<?php
use Finix\Resources\Identity;
use Finix\Resources\Merchant;
$identity = Identity::retrieve('IDpSEHq3qRRSxvqzUkipefAM');
$merchant = $identity->provisionMerchantOn(new Merchant());
from finix.resources import Identity
from finix.resources import Merchant
identity = Identity.get(id="IDpSEHq3qRRSxvqzUkipefAM")
merchant = identity.provision_merchant_on(Merchant())
identity = Finix::Identity.retrieve(:id => "MUwHAaGeNNmW5JF6oMjzWdDQ")
merchant = identity.provision_merchant
Example Response:
{
"id" : "MUwHAaGeNNmW5JF6oMjzWdDQ",
"identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"verification" : "VI8FBZnMgGReYM6KnCncEbMR",
"merchant_profile" : "MP4xt1veRZLAjbhAHdrZGqrb",
"processor" : "DUMMY_V1",
"processing_enabled" : false,
"settlement_enabled" : false,
"creating_transfer_from_report_enabled" : false,
"tags" : { },
"created_at" : "2018-04-26T00:45:21.07Z",
"updated_at" : "2018-04-26T00:45:21.07Z",
"onboarding_state" : "PROVISIONING",
"processor_details" : { },
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"verifications" : {
"href" : "https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ/verifications"
},
"merchant_profile" : {
"href" : "https://api-staging.finix.io/merchant_profiles/MP4xt1veRZLAjbhAHdrZGqrb"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"verification" : {
"href" : "https://api-staging.finix.io/verifications/VI8FBZnMgGReYM6KnCncEbMR"
}
}
}
Provision a Merchant for a previously created Identity resource to begin
transacting on their behalf.
Merchant resources can have three potential onboarding_states:
PROVISIONING: Request is pending (state will typically change after two minutes)- processing_enabled: False
- settlement_enabled: False
APPROVED: Merchant has been approved and can begin processing- processing_enabled: True
- settlement_enabled: True
REJECTED: Merchant was rejected by the processor either because the information collected was invalid or it failed one of a number of regulatory and/or compliance checks (e.g. KYC, OFAC or MATCH)- processing_enabled: False
- settlement_enabled: False
HTTP Request
POST https://api-staging.finix.io/identities/:IDENTITY_ID/merchants
URL Parameters
| Parameter | Description |
|---|---|
| :IDENTITY_ID | ID of the Identity |
Fetch a Merchant
curl https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99
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('MUwHAaGeNNmW5JF6oMjzWdDQ');
from finix.resources import Merchant
merchant = Merchant.get(id="MUwHAaGeNNmW5JF6oMjzWdDQ")
merchant = Finix::Merchant.retrieve(:id => "MUwHAaGeNNmW5JF6oMjzWdDQ")
Example Response:
{
"id" : "MUwHAaGeNNmW5JF6oMjzWdDQ",
"identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"verification" : null,
"merchant_profile" : "MP4xt1veRZLAjbhAHdrZGqrb",
"processor" : "DUMMY_V1",
"processing_enabled" : true,
"settlement_enabled" : true,
"creating_transfer_from_report_enabled" : false,
"tags" : { },
"created_at" : "2018-04-26T00:45:21.07Z",
"updated_at" : "2018-04-26T00:45:21.17Z",
"onboarding_state" : "APPROVED",
"processor_details" : {
"api_key" : "secretValue"
},
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"verifications" : {
"href" : "https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ/verifications"
},
"merchant_profile" : {
"href" : "https://api-staging.finix.io/merchant_profiles/MP4xt1veRZLAjbhAHdrZGqrb"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}
HTTP Request
GET https://api-staging.finix.io/merchants/:MERCHANT_ID
URL Parameters
| Parameter | Description |
|---|---|
| :MERCHANT_ID | ID of the Merchant |
Reattempt Merchant Provisioning
curl https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ/verifications \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '{}'
Merchant merchant = client.merchantsClient().fetch("MUwHAaGeNNmW5JF6oMjzWdDQ");
Verification verification = merchant.verify(
Verification.builder().build()
);
<?php
use Finix\Resources\Merchant;
use Finix\Resources\Verification;
$merchant = Merchant::retrieve('MUwHAaGeNNmW5JF6oMjzWdDQ');
$verification = new Verification();
$verification = $merchant->verifyOn($verification);
from finix.resources import Merchant
from finix.resources import Verification
merchant = Merchant.get(id="MUwHAaGeNNmW5JF6oMjzWdDQ")
verification = merchant.verify_on(Verification())
merchant = Finix::Merchant.retrieve(:id => "MUwHAaGeNNmW5JF6oMjzWdDQ")
verification = merchant.verify
Example Response:
{
"id" : "VIheJgdEVEwuVp8dxR23xNHm",
"tags" : { },
"messages" : [ ],
"raw" : null,
"processor" : "DUMMY_V1",
"state" : "PENDING",
"created_at" : "2018-04-26T00:45:49.38Z",
"updated_at" : "2018-04-26T00:45:49.41Z",
"trace_id" : "4b3ed27b-e3b9-4214-94af-4fd7b1f62e46",
"payment_instrument" : null,
"merchant" : "MUwHAaGeNNmW5JF6oMjzWdDQ",
"identity" : null,
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/verifications/VIheJgdEVEwuVp8dxR23xNHm"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"merchant" : {
"href" : "https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ"
}
}
}
Re-attempt provisioning a Merchant account on a processor if the previous attempt
returned a FAILED onboarding_state.
HTTP Request
POST https://api-staging.finix.io/merchants/:MERCHANT_ID/verifications
URL Parameters
| Parameter | Description |
|---|---|
| :MERCHANT_ID | ID of the Merchant |
Update Info on Processor
curl https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ/verifications \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '{}'
<?php
use Finix\Resources\Merchant;
use Finix\Resources\Verification;
$merchant = Merchant::retrieve('MUwHAaGeNNmW5JF6oMjzWdDQ');
$verification = new Verification();
$verification = $merchant->verifyOn($verification);
from finix.resources import Merchant
merchant = Merchant.get(id="MUwHAaGeNNmW5JF6oMjzWdDQ")
merchant.entity["first_name"] = "Michael"
merchant.save()
merchant = Finix::Merchant.retrieve(:id => "MUwHAaGeNNmW5JF6oMjzWdDQ")
verification = merchant.entity["default_statement_descriptor"] = "Prestige World Wide"
Example Response:
{
"id" : "VIheJgdEVEwuVp8dxR23xNHm",
"tags" : { },
"messages" : [ ],
"raw" : null,
"processor" : "DUMMY_V1",
"state" : "PENDING",
"created_at" : "2018-04-26T00:45:49.38Z",
"updated_at" : "2018-04-26T00:45:49.41Z",
"trace_id" : "4b3ed27b-e3b9-4214-94af-4fd7b1f62e46",
"payment_instrument" : null,
"merchant" : "MUwHAaGeNNmW5JF6oMjzWdDQ",
"identity" : null,
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/verifications/VIheJgdEVEwuVp8dxR23xNHm"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"merchant" : {
"href" : "https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ"
}
}
}
Update Identity information (e.g. default_statement_descriptor, KYC info, etc.)
on the underlying processor.
HTTP Request
POST https://api-staging.finix.io/merchants/:MERCHANT_ID/verifications
URL Parameters
| Parameter | Description |
|---|---|
| :MERCHANT_ID | ID of the Merchant |
List all Merchants
curl https://api-staging.finix.io/merchants/ \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99
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" : "MUwHAaGeNNmW5JF6oMjzWdDQ",
"identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"verification" : null,
"merchant_profile" : "MP4xt1veRZLAjbhAHdrZGqrb",
"processor" : "DUMMY_V1",
"processing_enabled" : true,
"settlement_enabled" : true,
"creating_transfer_from_report_enabled" : false,
"tags" : { },
"created_at" : "2018-04-26T00:45:21.07Z",
"updated_at" : "2018-04-26T00:45:21.17Z",
"onboarding_state" : "APPROVED",
"processor_details" : {
"api_key" : "secretValue"
},
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"verifications" : {
"href" : "https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ/verifications"
},
"merchant_profile" : {
"href" : "https://api-staging.finix.io/merchant_profiles/MP4xt1veRZLAjbhAHdrZGqrb"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/merchants?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
}
},
"page" : {
"offset" : 0,
"limit" : 20,
"count" : 1
}
}
HTTP Request
GET https://api-staging.finix.io/merchants/
List Merchant Verifications
curl https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ/verifications \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99
<?php
use Finix\Resources\Merchant;
use Finix\Resources\Verification;
$merchant = Merchant::retrieve('MUwHAaGeNNmW5JF6oMjzWdDQ');
$verifications = Verification::getPagination($merchant->getHref("verifications"));
from finix.resources import Merchant
merchant = Merchant.get(id="MUwHAaGeNNmW5JF6oMjzWdDQ")
verifications = merchant.verifications
merchant = Finix::Merchant.retrieve(:id => "MUwHAaGeNNmW5JF6oMjzWdDQ")
verifications = merchant.verifications
Example Response:
{
"_embedded" : {
"verifications" : [ {
"id" : "VI8FBZnMgGReYM6KnCncEbMR",
"tags" : {
"key_2" : "value_2"
},
"messages" : [ ],
"raw" : "RawDummyMerchantUnderwriteResult",
"processor" : "DUMMY_V1",
"state" : "SUCCEEDED",
"created_at" : "2018-04-26T00:45:21.09Z",
"updated_at" : "2018-04-26T00:45:21.22Z",
"trace_id" : "a033d2a0-c0b2-43ef-b973-58999b475f4e",
"payment_instrument" : null,
"merchant" : "MUwHAaGeNNmW5JF6oMjzWdDQ",
"identity" : null,
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/verifications/VI8FBZnMgGReYM6KnCncEbMR"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"merchant" : {
"href" : "https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/merchants/MUwHAaGeNNmW5JF6oMjzWdDQ/verifications?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
}
},
"page" : {
"offset" : 0,
"limit" : 20,
"count" : 1
}
}
Retrieve all attempts to onboard (i.e. provision) a merchant onto a processor.
HTTP Request
GET https://api-staging.finix.io/merchants/:MERCHANT_ID/verifications
URL Parameters
| Parameter | Description |
|---|---|
| :MERCHANT_ID | ID of the Merchant |
Payment Instruments
A Payment Instrument resource represents either a credit card or bank account.
A Payment Instrument may be tokenized multiple times and each tokenization produces
a unique ID. Each ID may only be associated one time and to only one Identity.
Once associated, a Payment Instrument may not be disassociated from an
Identity.
Create a Payment Card
curl https://api-staging.finix.io/payment_instruments \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"name": "Michae Lopez",
"expiration_year": 2020,
"tags": {
"card_name": "Business Card"
},
"number": "4957030420210454",
"expiration_month": 12,
"address": {
"city": "San Mateo",
"country": "USA",
"region": "CA",
"line2": "Apartment 7",
"line1": "741 Douglass St",
"postal_code": "94114"
},
"security_code": "112",
"type": "PAYMENT_CARD",
"identity": "IDuYo7qjbtB6kMVeebe4Z6NN"
}'
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("IDpSEHq3qRRSxvqzUkipefAM")
.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('IDpSEHq3qRRSxvqzUkipefAM');
$card = new PaymentCard(
array(
"name"=> "Michae Lopez",
"expiration_year"=> 2020,
"tags"=> array(
"card_name"=> "Business Card"
),
"number"=> "4957030420210454",
"expiration_month"=> 12,
"address"=> array(
"city"=> "San Mateo",
"country"=> "USA",
"region"=> "CA",
"line2"=> "Apartment 7",
"line1"=> "741 Douglass St",
"postal_code"=> "94114"
),
"security_code"=> "112",
"type"=> "PAYMENT_CARD",
"identity"=> "IDuYo7qjbtB6kMVeebe4Z6NN"
));
$card = $identity->createPaymentCard($card);
from finix.resources import PaymentCard
card = PaymentCard(**
{
"name": "Michae Lopez",
"expiration_year": 2020,
"tags": {
"card_name": "Business Card"
},
"number": "4957030420210454",
"expiration_month": 12,
"address": {
"city": "San Mateo",
"country": "USA",
"region": "CA",
"line2": "Apartment 7",
"line1": "741 Douglass St",
"postal_code": "94114"
},
"security_code": "112",
"type": "PAYMENT_CARD",
"identity": "IDuYo7qjbtB6kMVeebe4Z6NN"
}).save()
card = Finix::PaymentCard.new(
{
"name"=> "Michae Lopez",
"expiration_year"=> 2020,
"tags"=> {
"card_name"=> "Business Card"
},
"number"=> "4957030420210454",
"expiration_month"=> 12,
"address"=> {
"city"=> "San Mateo",
"country"=> "USA",
"region"=> "CA",
"line2"=> "Apartment 7",
"line1"=> "741 Douglass St",
"postal_code"=> "94114"
},
"security_code"=> "112",
"type"=> "PAYMENT_CARD",
"identity"=> "IDuYo7qjbtB6kMVeebe4Z6NN"
}).save
Example Response:
{
"id" : "PIss82nFMq4zmbLZgtrMhpQW",
"fingerprint" : "FPR16393928",
"tags" : {
"card_name" : "Business Card"
},
"expiration_month" : 12,
"expiration_year" : 2020,
"bin" : "495703",
"last_four" : "0454",
"brand" : "VISA",
"card_type" : "UNKNOWN",
"name" : "Michae Lopez",
"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" : "2018-04-26T00:45:26.14Z",
"updated_at" : "2018-04-26T00:45:26.14Z",
"instrument_type" : "PAYMENT_CARD",
"type" : "PAYMENT_CARD",
"currency" : "USD",
"identity" : "IDuYo7qjbtB6kMVeebe4Z6NN",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/transfers"
},
"verifications" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/verifications"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN"
},
"updates" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/updates"
}
}
}
Please review our guide on how to tokenize cards via the embedded tokenization form
HTTP Request
POST https://api-staging.finix.io/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, optional | First line of the address (max 60 characters) |
| line2 | string, optional | Second line of the address (max 60 characters) |
| city | string, optional | City (max 20 characters) |
| region | string, optional | 2-letter State code |
| postal_code | string, optional | Zip or Postal code (max 7 characters) |
| country | string, optional | 3-Letter Country code |
Create a Bank Account
curl https://api-staging.finix.io/payment_instruments \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"account_type": "SAVINGS",
"name": "Fran Lemke",
"tags": {
"Bank Account": "Company Account"
},
"country": "USA",
"bank_code": "123123123",
"account_number": "123123123",
"type": "BANK_ACCOUNT",
"identity": "IDpSEHq3qRRSxvqzUkipefAM"
}'
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("IDpSEHq3qRRSxvqzUkipefAM")
.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('IDpSEHq3qRRSxvqzUkipefAM');
$bank_account = new BankAccount(
array(
"account_type"=> "SAVINGS",
"name"=> "Fran Lemke",
"tags"=> array(
"Bank Account"=> "Company Account"
),
"country"=> "USA",
"bank_code"=> "123123123",
"account_number"=> "123123123",
"type"=> "BANK_ACCOUNT",
"identity"=> "IDpSEHq3qRRSxvqzUkipefAM"
));
$bank_account = $identity->createBankAccount($bank_account);
from finix.resources import BankAccount
bank_account = BankAccount(**
{
"account_type": "SAVINGS",
"name": "Fran Lemke",
"tags": {
"Bank Account": "Company Account"
},
"country": "USA",
"bank_code": "123123123",
"account_number": "123123123",
"type": "BANK_ACCOUNT",
"identity": "IDpSEHq3qRRSxvqzUkipefAM"
}).save()
bank_account = Finix::BankAccount.new(
{
"account_type"=> "SAVINGS",
"name"=> "Fran Lemke",
"tags"=> {
"Bank Account"=> "Company Account"
},
"country"=> "USA",
"bank_code"=> "123123123",
"account_number"=> "123123123",
"type"=> "BANK_ACCOUNT",
"identity"=> "IDpSEHq3qRRSxvqzUkipefAM"
}).save
Example Response:
{
"id" : "PI4aYS5haEPAit9L3j9hTar1",
"fingerprint" : "FPR-1215770130",
"tags" : {
"Bank Account" : "Company Account"
},
"bank_code" : "123123123",
"country" : "USA",
"masked_account_number" : "XXXXX3123",
"name" : "Fran Lemke",
"account_type" : "SAVINGS",
"created_at" : "2018-04-26T00:45:20.03Z",
"updated_at" : "2018-04-26T00:45:20.03Z",
"instrument_type" : "BANK_ACCOUNT",
"type" : "BANK_ACCOUNT",
"currency" : "USD",
"identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1/transfers"
},
"verifications" : {
"href" : "https://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1/verifications"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
}
}
}
HTTP Request
POST https://api-staging.finix.io/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://api-staging.finix.io/payment_instruments \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"token": "TKs1igXSvbb5aCtXCDGVwgPf",
"type": "TOKEN",
"identity": "IDpSEHq3qRRSxvqzUkipefAM"
}'
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("TKs1igXSvbb5aCtXCDGVwgPf")
.identity("IDpSEHq3qRRSxvqzUkipefAM")
.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"=> "TKs1igXSvbb5aCtXCDGVwgPf",
"type"=> "TOKEN",
"identity"=> "IDpSEHq3qRRSxvqzUkipefAM"
));
$card = $card->save();
from finix.resources import PaymentInstrument
payment_instrument = PaymentInstrument(**
{
"token": "TKs1igXSvbb5aCtXCDGVwgPf",
"type": "TOKEN",
"identity": "IDpSEHq3qRRSxvqzUkipefAM"
}).save()
card = Finix::PaymentInstrument.new(
{
"token"=> "TKs1igXSvbb5aCtXCDGVwgPf",
"type"=> "TOKEN",
"identity"=> "IDpSEHq3qRRSxvqzUkipefAM"
}).save
Example Response:
{
"id" : "PIs1igXSvbb5aCtXCDGVwgPf",
"fingerprint" : "FPR405642276",
"tags" : { },
"expiration_month" : 12,
"expiration_year" : 2020,
"bin" : "495703",
"last_four" : "0454",
"brand" : "VISA",
"card_type" : "UNKNOWN",
"name" : null,
"address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"address_verification" : "UNKNOWN",
"security_code_verification" : "UNKNOWN",
"created_at" : "2018-04-26T00:45:34.66Z",
"updated_at" : "2018-04-26T00:45:34.66Z",
"instrument_type" : "PAYMENT_CARD",
"type" : "PAYMENT_CARD",
"currency" : "USD",
"identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf/transfers"
},
"verifications" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf/verifications"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"updates" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf/updates"
}
}
}
Associate the newly tokenized card or bank with the instrument owner’s Identity.
HTTP Request
POST https://api-staging.finix.io/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://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1 \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
import io.finix.payments.ApiClient;
import io.finix.payments.views.Instrument;
import io.finix.payments.interfaces.Maybe;
Maybe<Instrument> response = api.paymentInstruments
.id("PI4aYS5haEPAit9L3j9hTar1")
.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('PI4aYS5haEPAit9L3j9hTar1');
from finix.resources import PaymentInstrument
bank_account = PaymentInstrument.get(id="PI4aYS5haEPAit9L3j9hTar1")
bank_account = Finix::BankAccount.retrieve(:id=> "PI4aYS5haEPAit9L3j9hTar1")
Example Response:
{
"id" : "PI4aYS5haEPAit9L3j9hTar1",
"fingerprint" : "FPR-1215770130",
"tags" : {
"Display Name" : "Updated Field"
},
"bank_code" : "123123123",
"country" : "USA",
"masked_account_number" : "XXXXX3123",
"name" : "Fran Lemke",
"account_type" : "SAVINGS",
"created_at" : "2018-04-26T00:45:20.03Z",
"updated_at" : "2018-04-26T00:45:20.48Z",
"instrument_type" : "BANK_ACCOUNT",
"type" : "BANK_ACCOUNT",
"currency" : "USD",
"identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1/transfers"
},
"verifications" : {
"href" : "https://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1/verifications"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
}
}
}
Fetch a previously created Payment Instrument that is of type BANK_ACCOUNT
HTTP Request
GET https://api-staging.finix.io/payment_instruments/:PAYMENT_INSTRUMENT_ID
URL Parameters
| Parameter | Description |
|---|---|
| :PAYMENT_INSTRUMENT_ID | ID of the Payment Instrument |
Fetch a Payment Card
curl https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
Maybe<PaymentCard> response = api.instruments
.id("PIss82nFMq4zmbLZgtrMhpQW")
.get();
if (! response.succeeded()) {
ApiError error = response.error();
System.out.println(error.getCode());
throw new RuntimeException("API error attempting to fetch Payment Card");
}
PaymentCard card = response.view();
<?php
use Finix\Resources\PaymentInstrument;
$card = PaymentInstrument::retrieve('PIss82nFMq4zmbLZgtrMhpQW');
from finix.resources import PaymentInstrument
credit_card = PaymentInstrument.get(id="PIss82nFMq4zmbLZgtrMhpQW")
card = Finix::PaymentCard.retrieve(:id=> "PIss82nFMq4zmbLZgtrMhpQW")
Example Response:
{
"id" : "PIss82nFMq4zmbLZgtrMhpQW",
"fingerprint" : "FPR16393928",
"tags" : {
"card_name" : "Business Card"
},
"expiration_month" : 12,
"expiration_year" : 2020,
"bin" : "495703",
"last_four" : "0454",
"brand" : "VISA",
"card_type" : "UNKNOWN",
"name" : "Michae Lopez",
"address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"address_verification" : "POSTAL_CODE_AND_STREET_MATCH",
"security_code_verification" : "MATCHED",
"created_at" : "2018-04-26T00:45:26.14Z",
"updated_at" : "2018-04-26T00:45:31.67Z",
"instrument_type" : "PAYMENT_CARD",
"type" : "PAYMENT_CARD",
"currency" : "USD",
"identity" : "IDuYo7qjbtB6kMVeebe4Z6NN",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/transfers"
},
"verifications" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/verifications"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN"
},
"updates" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/updates"
}
}
}
Fetch a previously created Payment Instrument that is of type PAYMENT_CARD
HTTP Request
GET https://api-staging.finix.io/payment_instruments/:PAYMENT_INSTRUMENT_ID
URL Parameters
| Parameter | Description |
|---|---|
| :PAYMENT_INSTRUMENT_ID | ID of the Payment Instrument |
Check for Card Updates (Account Updater)
Finix works with card networks so that your customers can continue, without interruption, using your service even if their card has changed due to it being closed, lost, or stolen. When a successful account update record is located, the Payment Instrument will be automatically updated with the new primary account number or new expiration date.
curl https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/updates \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"merchant": "MUwHAaGeNNmW5JF6oMjzWdDQ"
}'
<?php
from finix.resources import PaymentCard
card = PaymentCard(**
{
"name": "Michae Lopez",
"expiration_year": 2020,
"tags": {
"card_name": "Business Card"
},
"number": "4957030420210454",
"expiration_month": 12,
"address": {
"city": "San Mateo",
"country": "USA",
"region": "CA",
"line2": "Apartment 7",
"line1": "741 Douglass St",
"postal_code": "94114"
},
"security_code": "112",
"type": "PAYMENT_CARD",
"identity": "IDuYo7qjbtB6kMVeebe4Z6NN"
}).save()
update = card.update("MUwHAaGeNNmW5JF6oMjzWdDQ")
Example Response:
{
"id" : "IUrHEMsi6RWu2p3Yg7x7Ni7T",
"application" : "APhSYuXuvHHMGzkhnjumcmqB",
"merchant" : "MUwHAaGeNNmW5JF6oMjzWdDQ",
"state" : "PENDING",
"messages" : [ ],
"created_at" : "2018-04-26T00:45:36.43Z",
"updated_at" : "2018-04-26T00:45:36.45Z",
"payment_instrument" : "PIss82nFMq4zmbLZgtrMhpQW",
"trace_id" : "5dee6c52-c23b-42f8-a9da-690d6fce9dd8",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/updates/IUrHEMsi6RWu2p3Yg7x7Ni7T"
},
"payment_instrument" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
}
}
}
Immediate Response
When first making a Post request to the updates endpoint, the state field will either be pending or failed.
PENDING: The initial Account Update request has been approved by the card networks and is awaiting review.FAILED: Request rejected due to one of the following reasons:- Invalid credit card number
- Invalid expiration date
Subsequent Response
Once Finix receives a response from the card network, the state of the Update resource will return either SUCCEEDED or FAILED. Each Update will also provide a message that details the reason for the outcome. If either an account number or expiration date was found, Finix will automatically update the
associated Payment Instrument resource with the new details and the card will be
ready for use.
SUCCEEDEDMessages:- No changes found
- The account number was changed
- The expiration date was changed
FAILEDMessages:- No match found
- Invalid payment type (often due to unsupported card brands, e.g. Amex)
- The issuing bank does not participate in the update program
- The account was closed
HTTP Request
POST https://api-staging.finix.io/payment_instruments/:PAYMENT_INSTRUMENT_ID/updates/
Request Arguments
| Field | Type | Description |
|---|---|---|
| :MERCHANT_ID | string, required | ID of the Merchant |
| :PAYMENT_INSTRUMENT_ID | string, required | ID of the Payment Instrument |
List all Payment Instruments
curl https://api-staging.finix.io/payment_instruments \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99
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" : "PIs1igXSvbb5aCtXCDGVwgPf",
"fingerprint" : "FPR405642276",
"tags" : { },
"expiration_month" : 12,
"expiration_year" : 2020,
"bin" : "495703",
"last_four" : "0454",
"brand" : "VISA",
"card_type" : "UNKNOWN",
"name" : null,
"address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"address_verification" : "UNKNOWN",
"security_code_verification" : "UNKNOWN",
"created_at" : "2018-04-26T00:45:34.66Z",
"updated_at" : "2018-04-26T00:45:34.62Z",
"instrument_type" : "PAYMENT_CARD",
"type" : "PAYMENT_CARD",
"currency" : "USD",
"identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf/transfers"
},
"verifications" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf/verifications"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"updates" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIs1igXSvbb5aCtXCDGVwgPf/updates"
}
}
}, {
"id" : "PItpNsKkNE8b5pe1m55peM6Z",
"fingerprint" : "FPR-1215770130",
"tags" : {
"Bank Account" : "Company Account"
},
"bank_code" : "123123123",
"country" : "USA",
"masked_account_number" : "XXXXX3123",
"name" : "Fran Lemke",
"account_type" : "SAVINGS",
"created_at" : "2018-04-26T00:45:26.56Z",
"updated_at" : "2018-04-26T00:45:26.54Z",
"instrument_type" : "BANK_ACCOUNT",
"type" : "BANK_ACCOUNT",
"currency" : "USD",
"identity" : "IDuYo7qjbtB6kMVeebe4Z6NN",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/payment_instruments/PItpNsKkNE8b5pe1m55peM6Z"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/payment_instruments/PItpNsKkNE8b5pe1m55peM6Z/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/payment_instruments/PItpNsKkNE8b5pe1m55peM6Z/transfers"
},
"verifications" : {
"href" : "https://api-staging.finix.io/payment_instruments/PItpNsKkNE8b5pe1m55peM6Z/verifications"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN"
}
}
}, {
"id" : "PIss82nFMq4zmbLZgtrMhpQW",
"fingerprint" : "FPR16393928",
"tags" : {
"card_name" : "Business Card"
},
"expiration_month" : 12,
"expiration_year" : 2020,
"bin" : "495703",
"last_four" : "0454",
"brand" : "VISA",
"card_type" : "UNKNOWN",
"name" : "Michae Lopez",
"address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"address_verification" : "POSTAL_CODE_AND_STREET_MATCH",
"security_code_verification" : "MATCHED",
"created_at" : "2018-04-26T00:45:26.14Z",
"updated_at" : "2018-04-26T00:45:31.67Z",
"instrument_type" : "PAYMENT_CARD",
"type" : "PAYMENT_CARD",
"currency" : "USD",
"identity" : "IDuYo7qjbtB6kMVeebe4Z6NN",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/transfers"
},
"verifications" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/verifications"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDuYo7qjbtB6kMVeebe4Z6NN"
},
"updates" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/updates"
}
}
}, {
"id" : "PI4aYS5haEPAit9L3j9hTar1",
"fingerprint" : "FPR-1215770130",
"tags" : {
"Display Name" : "Updated Field"
},
"bank_code" : "123123123",
"country" : "USA",
"masked_account_number" : "XXXXX3123",
"name" : "Fran Lemke",
"account_type" : "SAVINGS",
"created_at" : "2018-04-26T00:45:20.03Z",
"updated_at" : "2018-04-26T00:45:20.48Z",
"instrument_type" : "BANK_ACCOUNT",
"type" : "BANK_ACCOUNT",
"currency" : "USD",
"identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1/transfers"
},
"verifications" : {
"href" : "https://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1/verifications"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
}
}
}, {
"id" : "PIiJTZczdbPjeLWsQ6NBKLU",
"fingerprint" : "FPR-1215770130",
"tags" : {
"Bank Account" : "Company Account"
},
"bank_code" : "123123123",
"country" : "USA",
"masked_account_number" : "XXXXX3123",
"name" : "Fran Lemke",
"account_type" : "SAVINGS",
"created_at" : "2018-04-26T00:45:19.59Z",
"updated_at" : "2018-04-26T00:45:19.57Z",
"instrument_type" : "BANK_ACCOUNT",
"type" : "BANK_ACCOUNT",
"currency" : "USD",
"identity" : "IDqmXMUNztTYNUU52FvHDCts",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIiJTZczdbPjeLWsQ6NBKLU"
},
"authorizations" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIiJTZczdbPjeLWsQ6NBKLU/authorizations"
},
"transfers" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIiJTZczdbPjeLWsQ6NBKLU/transfers"
},
"verifications" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIiJTZczdbPjeLWsQ6NBKLU/verifications"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDqmXMUNztTYNUU52FvHDCts"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/payment_instruments?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
}
},
"page" : {
"offset" : 0,
"limit" : 20,
"count" : 5
}
}
HTTP Request
GET https://api-staging.finix.io/payment_instruments
Payment Instrument Verification
curl https://api-staging.finix.io/payment_instruments/PIss82nFMq4zmbLZgtrMhpQW/verifications \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"processor": "VISA_V1"
}'
import io.finix.payments.forms.*;
import io.finix.payments.views.*;
import io.finix.payments.interfaces.ApiError;
import io.finix.payments.interfaces.Maybe;
VerificationForm verificationForm = VerificationForm.builder()
.processor("VISA_V1")
.build();
Maybe<Verification> verificationResponse = api.instruments.id("PIboPQdA8VRzgaQh34dJF6ET").verifications.post(verificationForm);
if (! verificationResponse.succeeded()) {
ApiError error = verificationResponse.error();
System.out.println(error.getCode());
throw new RuntimeException("API error attempting to create a Verification");
}
Verification verification = verificationResponse.view();
<?php
from finix.resources import PaymentInstrument
from finix.resources import Verification
payment_card = PaymentInstrument.get(id="PIss82nFMq4zmbLZgtrMhpQW")
verification = payment_card.verify_on(Verification(**
{
"processor": "VISA_V1"
}))
Example Response:
{
"id" : "VIgTdSU9hQ5tUkaSj8Hv4vop",
"tags" : { },
"messages" : [ ],
"raw" : {
"validation_details" : {
"systems_trace_audit_number" : "193315",
"transaction_identifier" : "136049294563589",
"action_code" : "N7",
"response_code" : "5",
"address_verification_results" : "N",
"cvv2_result_code" : "N"
},
"inquiry_details" : {
"systems_trace_audit_number" : "193315",
"card_type_code" : "C",
"billing_currency_code" : 986,
"billing_currency_minor_digits" : 2,
"issuer_name" : "Visa Test Bank",
"card_issuer_country_code" : 76,
"fast_funds_indicator" : "N",
"push_funds_block_indicator" : "N",
"online_gambing_block_indicator" : "Y"
},
"general_inquiry_details" : {
"systems_trace_audit_number" : "193315",
"status" : {
"status_code" : "CDI000",
"status_description" : "Success"
}
}
},
"processor" : "VISA_V1",
"state" : "SUCCEEDED",
"created_at" : "2018-04-26T00:45:13.12Z",
"updated_at" : "2018-04-26T00:45:14.27Z",
"trace_id" : "193315",
"payment_instrument" : "PIboPQdA8VRzgaQh34dJF6ET",
"merchant" : null,
"identity" : null,
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/verifications/VIgTdSU9hQ5tUkaSj8Hv4vop"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/AP51MRy5CzXHL4hwdDm4B7Dc"
},
"payment_instrument" : {
"href" : "https://api-staging.finix.io/payment_instruments/PIboPQdA8VRzgaQh34dJF6ET"
}
}
}
HTTP Request
POST https://api-staging.finix.io/payment_instruments/:PAYMENT_INSTRUMENT_ID/verifications
URL Parameters
| Parameter | Description |
|---|---|
| :PAYMENT_INSTRUMENT_ID | ID of the Payment Instrument |
Request Arguments
| Field | Type | Description |
|---|---|---|
| processor | string, required | The name of the processor, which needs to be: VISA_V1 |
Address Verification Results (address_verification_results)
| Letter | Description |
|---|---|
| D, F, M, Y | Address verified |
| A, B, C, G, I, N, P, R, S, U, W | Address not verified |
| Z | Postal/ZIP match, street addresses do not match or street address not included in request |
Card Verification 2 Results (cvv2_result_code)
| Letter | Description |
|---|---|
| M | CVV and expiration dates verified |
| N, P, S | Either CVV or expiration date is incorrect |
| U | Issuer does not participate in CVV2 service |
Card Type (card_type_code)
This one-character code indicates whether the account is credit, debit, prepaid, deferred debit, or charge.
| Letter | Description |
|---|---|
| C | Credit |
| D | Debit |
| H | Charge Card |
| P | Prepaid |
| R | Deferred Debit |
Fasts Funds Indicator (fast_funds_indicator)
Indicates whether or not the card is Fast Funds eligible (i.e. if the funds will settle in 30 mins or less). If not eligible, typically funds will settle within 2 business days.
| Letter | Description |
|---|---|
| B, D | Fast Funds eligible |
| N | Not eligible for Fast Funds |
Push Funds Indicator (push_funds_block_indicator)
This code indicates if the associated card can receive push-to-card disbursements.
| Letter | Description |
|---|---|
| A, B, C | Accepts push-to-card payments |
| N | Does not accept push-to-card payments |
Online Gambling Block Indicator (online_gambing_block_indicator)
Indicates if the card can receive push-payments for online gambling payouts.
| Letter | Description |
|---|---|
| Y | Blocked for online gambling payouts |
| N | Not blocked for online gambling payouts |
Card Product ID (card_product_id)
A combination of card brand, platform, class and scheme.
| Letter | Description |
|---|---|
| A | Visa Traditional |
| AX | American Express |
| B | Visa Traditional Rewards |
| C | Visa Signature |
| D | Visa Signature Preferred |
| DI | Discover |
| DN | Diners |
| E | Proprietary ATM |
| F | Visa Classic |
| G | Visa Business |
| G1 | Visa Signature Business |
| G2 | Visa Business Check Card |
| G3 | Visa Business Enhanced |
| G4 | Visa Infinite Business |
| G5 | Visa Business Rewards |
| I | Visa Infinite |
| I1 | Visa Infinite Privilege |
| I2 | Visa UHNW |
| J3 | Visa Healthcare |
| JC | JCB |
| K | Visa Corporate T&E |
| K1 | Visa Government Corporate T&E |
| L | Visa Electron |
| M | MasterCard |
| N | Visa Platinum |
| N1 | Visa Rewards |
| N2 | Visa Select |
| P | Visa Gold |
| Q | Private Label |
| Q1 | Private Label Prepaid |
| Q2 | Private Label Basic |
| Q3 | Private Label Standard |
| Q4 | Private Label Enhanced |
| Q5 | Private Label Specialized |
| Q6 | Private Label Premium |
| R | Proprietary |
| S | Visa Purchasing |
| S1 | Visa Purchasing with Fleet |
| S2 | Visa Government Purchasing |
| S3 | Visa Government Purchasing with Fleet |
| S4 | Visa Commercial Agriculture |
| S5 | Visa Commercial Transport |
| S6 | Visa Commercial Marketplace |
| U | Visa Travel Money |
| V | Visa V PAY |
Product Sub-Type (card_product_subtype)
Description of product subtype.
| Letter | Description |
|---|---|
| AC | Agriculture Maintenance Account |
| AE | Agriculture Debit Account/Electron |
| AG | Agriculture |
| AI | Agriculture Investment Loan |
| CG | Brazil Cargo |
| CS | Construction |
| DS | Distribution |
| HC | Healthcare |
| LP | Visa Large Purchase Advantage |
| MA | Visa Mobile Agent |
| MB | Interoperable Mobile Branchless Banking |
| MG | Visa Mobile General |
| VA | Visa Vale - Supermarket |
| VF | Visa Vale - Fuel |
| VR | Visa Vale - Restaurant |
Card Sub-Type (card_subtype_code)
The code for account funding source subtype, such as reloadable and non-reloadable.
| Letter | Description |
|---|---|
| N | Non-Reloadable |
| R | Reloadable |
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.
Create a Batch Settlement
curl https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM/settlements \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
-d '
{
"currency": "USD",
"tags": {
"Internal Daily Settlement ID": "21DFASJSAKAS"
}
}'
import io.finix.payments.ApiClient;
import io.finix.payments.forms.SettlementForm;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.views.*;
import java.util.Currency;
Settlement settlement = identity.createSettlement(
Settlement.builder()
.currency("USD")
.build()
);
SettlementForm formSettlement = SettlementForm.builder()
.currency(Currency.getInstance("USD"))
.build();
Transfer transfer = api.transfers.id("AUf7d2dGYeQEyMsrKMuQimTX").get().view();
Maybe<Settlement> response = api.identities.id("IDpSEHq3qRRSxvqzUkipefAM").settlements.post(formSettlement);
if (! response.succeeded()) {
throw new RuntimeException("API error attempting to create batch settlement");
}
Settlement settlementBatch = response.view();
<?php
use Finix\Resources\Identity;
use Finix\Resources\Settlement;
$identity = Identity::retrieve('IDpSEHq3qRRSxvqzUkipefAM');
$settlement = new Settlement(
array(
"currency"=> "USD",
"tags"=> array(
"Internal Daily Settlement ID"=> "21DFASJSAKAS"
)
));
$settlement = $identity->createSettlement($settlement);
from finix.resources import Identity
from finix.resources import Settlement
identity = Identity.get(id="IDpSEHq3qRRSxvqzUkipefAM")
settlement = Settlement(**
{
"currency": "USD",
"tags": {
"Internal Daily Settlement ID": "21DFASJSAKAS"
}
})
identity.create_settlement(settlement)
identity = Finix::Identity.retrieve(:id=>"IDpSEHq3qRRSxvqzUkipefAM")
settlement = identity.create_settlement(
{
"currency"=> "USD",
"tags"=> {
"Internal Daily Settlement ID"=> "21DFASJSAKAS"
}
})
Example Response:
{
"id" : "ST4fuHXj16toWtLVZZ7Up92z",
"tags" : {
"Internal Daily Settlement ID" : "21DFASJSAKAS"
},
"identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"currency" : "USD",
"created_at" : "2018-04-26T00:49:55.19Z",
"updated_at" : "2018-04-26T00:49:55.21Z",
"processor" : "DUMMY_V1",
"total_amount" : 1931119,
"total_fees" : 193204,
"total_fee" : 193204,
"net_amount" : 1737915,
"destination" : null,
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"funding_transfers" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/funding_transfers"
},
"transfers" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers"
},
"fees" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers?type=fee"
},
"reversals" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers?type=reverse"
},
"credits" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers?type=credit"
},
"debits" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers?type=debit"
}
}
}
Each settlement is comprised of all the Transfers that have a SUCCEEDED state and
that have not been previously settled out. In other words, if a merchant has a
Transfer in the PENDING state it will not be included in the batch settlement.
In addition, Settlements will include any refunded Transfers as a deduction.
The total_amount minus the total_fee equals the net_amount (the amount in cents
that will be deposited into your merchant’s bank account).
HTTP Request
POST https://api-staging.finix.io/identities/:IDENTITY_ID/settlements
URL Parameters
| Parameter | Description |
|---|---|
| :IDENTITY_ID | ID of the Identity for the merchant you wish to settle out |
Request Arguments
| Field | Type | Description |
|---|---|---|
| currency | integer, required | 3-letter currency code that the funds should be deposited (e.g. USD) |
| tags | object, optional | Key value pair for annotating custom meta data (e.g. order numbers) |
Fetch a Batch Settlement
curl https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99 \
import io.finix.payments.ApiClient;
import io.finix.payments.interfaces.Maybe;
import io.finix.payments.views.Settlement;
Maybe<Settlement> response = api.settlements
.id("ST4fuHXj16toWtLVZZ7Up92z")
.get();
if(! response.succeeded()){
System.out.println(response.error());
System.out.println(response.error().getDetails());
throw new RuntimeException("API error attempting to fetch settlement");
}
Settlement settlementView = response.view();
<?php
use Finix\Resources\Settlement;
$settlement = Settlement::retrieve('ST4fuHXj16toWtLVZZ7Up92z');
from finix.resources import Settlements
settlement = Settlements.get(id="ST4fuHXj16toWtLVZZ7Up92z")
settlement = Finix::Settlement.retrieve(:id=>"ST4fuHXj16toWtLVZZ7Up92z")
Example Response:
{
"id" : "ST4fuHXj16toWtLVZZ7Up92z",
"tags" : {
"Internal Daily Settlement ID" : "21DFASJSAKAS"
},
"identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"currency" : "USD",
"created_at" : "2018-04-26T00:49:55.19Z",
"updated_at" : "2018-04-26T00:49:56.41Z",
"processor" : "DUMMY_V1",
"total_amount" : 1931119,
"total_fees" : 193204,
"total_fee" : 193204,
"net_amount" : 1737915,
"destination" : "PI4aYS5haEPAit9L3j9hTar1",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"funding_transfers" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/funding_transfers"
},
"transfers" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers"
},
"fees" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers?type=fee"
},
"reversals" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers?type=reverse"
},
"credits" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers?type=credit"
},
"debits" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers?type=debit"
}
}
}
Fetch a previously created Settlement.
HTTP Request
POST https://api-staging.finix.io/settlements/:SETTLEMENT_ID/
URL Parameters
| Parameter | Description |
|---|---|
| :SETTLEMENT_ID | ID of the Settlement |
List all Batch Settlements
curl https://api-staging.finix.io/settlements/ \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99
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.Settlement;
Maybe<Page<Settlement>> request = api.settlements.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 Settlements");
}
Page<Settlement> page = request.view();
<?php
use Finix\Resources\Settlement;
$settlements = Settlement::getPagination("/settlements");
from finix.resources import Settlement
settlements = Settlement.get()
settlements = Finix::Settlement.retrieve
Example Response:
{
"_embedded" : {
"settlements" : [ {
"id" : "ST4fuHXj16toWtLVZZ7Up92z",
"tags" : {
"Internal Daily Settlement ID" : "21DFASJSAKAS"
},
"identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"currency" : "USD",
"created_at" : "2018-04-26T00:49:55.19Z",
"updated_at" : "2018-04-26T00:49:56.41Z",
"processor" : "DUMMY_V1",
"total_amount" : 1931119,
"total_fees" : 193204,
"total_fee" : 193204,
"net_amount" : 1737915,
"destination" : "PI4aYS5haEPAit9L3j9hTar1",
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z"
},
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"funding_transfers" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/funding_transfers"
},
"transfers" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers"
},
"fees" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers?type=fee"
},
"reversals" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers?type=reverse"
},
"credits" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers?type=credit"
},
"debits" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers?type=debit"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/settlements?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
}
},
"page" : {
"offset" : 0,
"limit" : 20,
"count" : 1
}
}
List the Transfers of type CREDIT that result from issuing funding instructions
for the Settlement.
HTTP Request
GET https://api-staging.finix.io/settlements/:SETTLEMENT_ID/funding_transfers
URL Parameters
| Parameter | Description |
|---|---|
| :SETTLEMENT_ID | ID of the Settlement |
List Funding Transfers in a Batch Settlement
curl https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/funding_transfers \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99
Settlement settlement = client.settlementsClient().fetch("ST4fuHXj16toWtLVZZ7Up92z");
settlement.fundingTransfersClient().<Resources<Transfer>>resourcesIterator()
.forEachRemaining(page -> {
Collection<Transfer> transfers = page.getContent();
transfers.forEach(transfer ->
// do something
);
});
}
<?php
use Finix\Resources\Settlement;
$settlement = Settlement::retrieve('ST4fuHXj16toWtLVZZ7Up92z');
$settlements = Settlement::getPagination($settlement->getHref("funding_transfers"));
from finix.resources import Settlements
settlement = Settlement.get(id="ST4fuHXj16toWtLVZZ7Up92z")
transfers = settlement.funding_transfers
settlement = Finix::Settlement.retrieve(:id=>"ST4fuHXj16toWtLVZZ7Up92z")
transfers = settlement.funding_transfers
Example Response:
{
"_embedded" : {
"transfers" : [ {
"id" : "TR6ygANy3TBkH2obgBFJpfbd",
"amount" : 1737915,
"tags" : {
"Internal Daily Settlement ID" : "21DFASJSAKAS"
},
"state" : "PENDING",
"trace_id" : "fa40a2ea-5de6-435a-bf95-e8064a9e28c9",
"currency" : "USD",
"application" : "APhSYuXuvHHMGzkhnjumcmqB",
"source" : null,
"destination" : "PI4aYS5haEPAit9L3j9hTar1",
"ready_to_settle_at" : null,
"fee" : 0,
"statement_descriptor" : null,
"type" : "CREDIT",
"messages" : [ ],
"raw" : null,
"created_at" : "2018-04-26T00:49:56.21Z",
"updated_at" : "2018-04-26T00:49:56.32Z",
"idempotency_id" : null,
"merchant_identity" : "IDpSEHq3qRRSxvqzUkipefAM",
"subtype" : "API",
"_links" : {
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"self" : {
"href" : "https://api-staging.finix.io/transfers/TR6ygANy3TBkH2obgBFJpfbd"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/transfers/TR6ygANy3TBkH2obgBFJpfbd/payment_instruments"
},
"merchant_identity" : {
"href" : "https://api-staging.finix.io/identities/IDpSEHq3qRRSxvqzUkipefAM"
},
"reversals" : {
"href" : "https://api-staging.finix.io/transfers/TR6ygANy3TBkH2obgBFJpfbd/reversals"
},
"fees" : {
"href" : "https://api-staging.finix.io/transfers/TR6ygANy3TBkH2obgBFJpfbd/fees"
},
"disputes" : {
"href" : "https://api-staging.finix.io/transfers/TR6ygANy3TBkH2obgBFJpfbd/disputes"
},
"destination" : {
"href" : "https://api-staging.finix.io/payment_instruments/PI4aYS5haEPAit9L3j9hTar1"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/funding_transfers?offset=0&limit=20&sort=created_at,desc&sort=id,desc"
}
},
"page" : {
"offset" : 0,
"limit" : 20,
"count" : 1
}
}
List the Transfers of type CREDIT that result from issuing a Settlement.
HTTP Request
GET https://api-staging.finix.io/settlements/:SETTLEMENT_ID/funding_transfers
URL Parameters
| Parameter | Description |
|---|---|
| :SETTLEMENT_ID | ID of the Settlement |
List Transfers in a Batch Settlement
curl https://api-staging.finix.io/settlements/ST4fuHXj16toWtLVZZ7Up92z/transfers \
-H "Content-Type: application/vnd.json+api" \
-u USsUqmy5wjayACofMgEUYhUj:00392938-e379-4c6b-bb60-f06bd382fb99
Settlement settlement = client.settlementsClient().fetch("ST4fuHXj16toWtLVZZ7Up92z");
settlement.transfersClient().<Resources<Transfer>>resourcesIterator()
.forEachRemaining(page -> {
Collection<Transfer> transfers = page.getContent();
transfers.forEach(transfer ->
// do something
);
});
}
<?php
use Finix\Resources\Settlement;
$settlement = Settlement::retrieve('ST4fuHXj16toWtLVZZ7Up92z');
$settlements = Settlement::getPagination($settlement->getHref("transfers"));
settlement = Finix::Settlement.retrieve(:id=>"ST4fuHXj16toWtLVZZ7Up92z")
transfers = settlement.transfers
Example Response:
{
"_embedded" : {
"transfers" : [ {
"id" : "TRqBnk5q6sk9FwnkprZiAXWG",
"amount" : 71011,
"tags" : { },
"state" : "SUCCEEDED",
"trace_id" : "4655530b-3a83-4e6a-93bf-1ab502f061b3",
"currency" : "USD",
"application" : "APhSYuXuvHHMGzkhnjumcmqB",
"source" : null,
"destination" : null,
"ready_to_settle_at" : "2018-04-26T00:49:10.07Z",
"fee" : 0,
"statement_descriptor" : null,
"type" : "FEE",
"messages" : [ ],
"raw" : null,
"created_at" : "2018-04-26T00:49:09.89Z",
"updated_at" : "2018-04-26T00:49:10.07Z",
"idempotency_id" : null,
"merchant_identity" : "IDqmXMUNztTYNUU52FvHDCts",
"subtype" : "APPLICATION_FEE",
"_links" : {
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"self" : {
"href" : "https://api-staging.finix.io/transfers/TRqBnk5q6sk9FwnkprZiAXWG"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/transfers/TRqBnk5q6sk9FwnkprZiAXWG/payment_instruments"
},
"merchant_identity" : {
"href" : "https://api-staging.finix.io/identities/IDqmXMUNztTYNUU52FvHDCts"
},
"parent" : {
"href" : "https://api-staging.finix.io/transfers/TRcyQXViPasqiGJyUwYQ15uT"
},
"fee_profile" : {
"href" : "https://api-staging.finix.io/fee_profiles/FPoTWG52QtQ9ePRKihs6Zpbv"
}
}
}, {
"id" : "TRfLZhoFZAiSaKrh6qqddV6j",
"amount" : 17878,
"tags" : { },
"state" : "SUCCEEDED",
"trace_id" : "7f4f2f36-ebdf-4c71-a39d-fc1178bafce2",
"currency" : "USD",
"application" : "APhSYuXuvHHMGzkhnjumcmqB",
"source" : null,
"destination" : null,
"ready_to_settle_at" : "2018-04-26T00:49:09.73Z",
"fee" : 0,
"statement_descriptor" : null,
"type" : "FEE",
"messages" : [ ],
"raw" : null,
"created_at" : "2018-04-26T00:49:09.56Z",
"updated_at" : "2018-04-26T00:49:09.72Z",
"idempotency_id" : null,
"merchant_identity" : "ID8bW3W9DmKEgFYF4GfDJ8or",
"subtype" : "PLATFORM_FEE",
"_links" : {
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"self" : {
"href" : "https://api-staging.finix.io/transfers/TRfLZhoFZAiSaKrh6qqddV6j"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/transfers/TRfLZhoFZAiSaKrh6qqddV6j/payment_instruments"
},
"merchant_identity" : {
"href" : "https://api-staging.finix.io/identities/ID8bW3W9DmKEgFYF4GfDJ8or"
},
"parent" : {
"href" : "https://api-staging.finix.io/transfers/TRcyQXViPasqiGJyUwYQ15uT"
},
"fee_profile" : {
"href" : "https://api-staging.finix.io/fee_profiles/FPoTWG52QtQ9ePRKihs6Zpbv"
}
}
}, {
"id" : "TR9xgArHPCv6nDSd9zkgnVgw",
"amount" : 68558,
"tags" : { },
"state" : "SUCCEEDED",
"trace_id" : "ab29c34c-e58d-447c-950b-d76df75d59f7",
"currency" : "USD",
"application" : "APhSYuXuvHHMGzkhnjumcmqB",
"source" : null,
"destination" : null,
"ready_to_settle_at" : "2018-04-26T00:49:09.30Z",
"fee" : 0,
"statement_descriptor" : null,
"type" : "FEE",
"messages" : [ ],
"raw" : null,
"created_at" : "2018-04-26T00:49:09.12Z",
"updated_at" : "2018-04-26T00:49:09.30Z",
"idempotency_id" : null,
"merchant_identity" : "IDqmXMUNztTYNUU52FvHDCts",
"subtype" : "APPLICATION_FEE",
"_links" : {
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"self" : {
"href" : "https://api-staging.finix.io/transfers/TR9xgArHPCv6nDSd9zkgnVgw"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/transfers/TR9xgArHPCv6nDSd9zkgnVgw/payment_instruments"
},
"merchant_identity" : {
"href" : "https://api-staging.finix.io/identities/IDqmXMUNztTYNUU52FvHDCts"
},
"parent" : {
"href" : "https://api-staging.finix.io/transfers/TRiPbE83xWJXJEXAb54HjUNV"
},
"fee_profile" : {
"href" : "https://api-staging.finix.io/fee_profiles/FPoTWG52QtQ9ePRKihs6Zpbv"
}
}
}, {
"id" : "TRoyg6w9m7LYn3ZAPaUr6eSe",
"amount" : 17265,
"tags" : { },
"state" : "SUCCEEDED",
"trace_id" : "1030ace6-9c51-43ca-a51a-892a4879bf85",
"currency" : "USD",
"application" : "APhSYuXuvHHMGzkhnjumcmqB",
"source" : null,
"destination" : null,
"ready_to_settle_at" : "2018-04-26T00:49:08.94Z",
"fee" : 0,
"statement_descriptor" : null,
"type" : "FEE",
"messages" : [ ],
"raw" : null,
"created_at" : "2018-04-26T00:49:08.76Z",
"updated_at" : "2018-04-26T00:49:08.93Z",
"idempotency_id" : null,
"merchant_identity" : "ID8bW3W9DmKEgFYF4GfDJ8or",
"subtype" : "PLATFORM_FEE",
"_links" : {
"application" : {
"href" : "https://api-staging.finix.io/applications/APhSYuXuvHHMGzkhnjumcmqB"
},
"self" : {
"href" : "https://api-staging.finix.io/transfers/TRoyg6w9m7LYn3ZAPaUr6eSe"
},
"payment_instruments" : {
"href" : "https://api-staging.finix.io/transfers/TRoyg6w9m7LYn3ZAPaUr6eSe/payment_instruments"
},
"merchant_identity" : {
"href" : "https://api-staging.finix.io/identities/ID8bW3W9DmKEgFYF4GfDJ8or"
},
"parent" : {
"href" : "https://api-staging.finix.io/transfers/TRiPbE83xWJXJEXAb54HjUNV"
},
"fee_profile" : {
"href" : "https://api-staging.finix.io/fee_profiles/FPoTWG52QtQ9ePRKihs6Zpbv"
}
}
}, {
"id" : "TRdb3FfXeqfwru531V467Aqb",
"amount" : 102,
"tags" : { },
"state" : "SUCCEEDED",
"trace_id" : "a6fbc1d9-d502-4a23-9ad0-4c8bd8dee451",
"currency" : "USD",
"application" : "APhSYuXuvHHMGzkhnjumcmqB",
"source" : null,
"destination" : null,
"ready_to_settle_at" : "2018-04-26T00:49:08.48Z",
"fee" : 0,
"statement_descriptor" : null,
"type" : "FEE",
"messages" : [ ],
"raw" :