Deprecated API Reference

This API Reference is being deprecated. Please use the New API Reference.

Create a Bank Account

Create a Payment Instrument resource using the details of a bank account.

warning

You'll need to create an additional buyer Identity separate from the merchant Identity. Use the buyer Identity with the bank account detail when creating a Payment Instrument.

For Flex, Finix automatically validates a first-use or updated/changed bank account before proceeding with an ACH transaction in compliance with NACHA’s bank account validation rule. If the bank account is flagged as invalid, the transaction is blocked. This helps prevent fraud and decreases the chances of an ACH return. The following values can be returned for bank_account_validation_check:

  • NOT_ATTEMPTED: Default value for new bank accounts that haven’t been validated yet.
  • VALID: Bank account was found to be open and accepts ACH.
  • INVALID: Could not validate bank account was valid. Creating an ACH with a bank account that’s marked as INVALID will result in a failure. Please reach out to the bank account holder for a new form of payment.
  • INCONCLUSIVE: Bank account validation was inconclusive. Bank accounts that are marked as INCONCLUSIVE will be allowed to create an ACH.
Copy
Copied
curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -H 'Finix-Version:2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	{
	    "account_number": "123123123",
	    "account_type": "SAVINGS",
	    "bank_code": "123123123",
	    "country": "USA",
	    "identity": "IDpYDM7J9n57q849o9E9yNrG",
	    "name": "John",
	    "tags": {
	        "Bank Account": "Company Account"
	    },
	    "type": "BANK_ACCOUNT"
	}'

Example Response:

Copy
Copied
{
  "id" : "PIkDbNSomYF8mqYgjxDJyqZ3",
  "created_at" : "2022-10-10T01:34:53.15Z",
  "updated_at" : "2022-10-10T01:34:53.15Z",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "created_via" : "API",
  "currency" : "USD",
  "enabled" : true,
  "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
  "identity" : "IDpYDM7J9n57q849o9E9yNrG",
  "instrument_type" : "BANK_ACCOUNT",
  "account_type" : "SAVINGS",
  "bank_account_validation_check" : "NOT_ATTEMPTED",
  "bank_code" : "123123123",
  "country" : "USA",
  "masked_account_number" : "XXXXX3123",
  "name" : "John",
  "tags" : {
    "Bank Account" : "Company Account"
  },
  "type" : "BANK_ACCOUNT",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIkDbNSomYF8mqYgjxDJyqZ3"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIkDbNSomYF8mqYgjxDJyqZ3/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIkDbNSomYF8mqYgjxDJyqZ3/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIkDbNSomYF8mqYgjxDJyqZ3/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG"
    }
  }
}

HTTP Request

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

Request Arguments

Field Type Description
account_number string, required Bank account number.
account_type string, required Either CHECKING or SAVINGS.
attempt_bank_account_validation_check boolean, optional Set to true if you want to request a bank account validation. Default value is false.
bank_code string, required Bank routing number.
country string, optional Country code.
identity string, required ID for the Identity resource which the account is associated.
name string, required Account owner's full name (max 40 characters).
type string, required Type of Payment Instrument (for bank accounts use BANK_ACCOUNT).