Deprecated API Reference

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

Debit a Bank Account (ie eCheck)

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

In compliance with NACHA’s bank account validation rule, Finix automatically validates a first-use or updated/changed bank account before proceeding with any eCheck transaction. If the bank account is flagged as invalid, the transaction is blocked. This helps prevent fraud and decreases the chances of an eCheck 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 eCheck.
  • INVALID: Could not validate bank account was valid. Creating an eCheck 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 eCheck.
attention

By default, Finix implements a 3 day business day delay on eChecks.

warning

Ensure that you create an additional buyer Identity separate from the merchant Identity. Associate the buyer Identity with the bank account you tokenize.

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

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

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

Copy
Copied
curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/vnd.json+api" \
    -H 'Finix-Version:2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	{
	    "fee": 603,
	    "currency": "USD",
	    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
	    "tags": {
	        "order_number": "21DFASJSAKAS"
	    },
	    "source": "PIr1Ru7ewBkEYVVn7SP1u5FW",
	    "amount": 6031
	}'

Example Response:

Copy
Copied
{
  "id" : "TRuR4hKLpum9ALvPv9ZpNuFA",
  "amount" : 6031,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "PENDING",
  "trace_id" : "86afaa11-d621-4e53-94ec-b9a60bf72a7f",
  "currency" : "USD",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "source" : "PIr1Ru7ewBkEYVVn7SP1u5FW",
  "destination" : null,
  "ready_to_settle_at" : null,
  "externally_funded" : "UNKNOWN",
  "fee" : 603,
  "statement_descriptor" : "FNX*FINIX FLOWERS",
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2022-06-27T21:55:52.29Z",
  "updated_at" : "2022-06-27T21:55:52.96Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDuqZpDw28f2KK6YuDk4jNLg",
  "subtype" : "API",
  "failure_code" : null,
  "failure_message" : null,
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRuR4hKLpum9ALvPv9ZpNuFA"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRuR4hKLpum9ALvPv9ZpNuFA/payment_instruments"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRuR4hKLpum9ALvPv9ZpNuFA/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRuR4hKLpum9ALvPv9ZpNuFA/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRuR4hKLpum9ALvPv9ZpNuFA/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIr1Ru7ewBkEYVVn7SP1u5FW"
    },
    "fee_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
    }
  }
}

HTTP Request

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

Request Arguments

Field Type Description
source string, required ID of the Payment Instrument that will be debited
merchant_identity string, required Identity ID of the merchant whom you're charging on behalf of
amount integer, required The total amount that will be debited in cents (e.g. 100 cents to debit $1.00)
fee integer, optional The amount of the transfer you would like to collect as your fee in cents. Defaults to zero (Must be less than or equal to the amount)
currency string, required 3-letter ISO code designating the currency of the transfers (e.g. USD)processor
processor string, optional If the Application has more than one processor association, it's required to pass the processor (e.g. DUMMY_V1)
idempotency_id string, optional A randomly generated value that you want associated with the request