ACH (v1)
This is the official reference documentation for the SVB ACH API. Please see the authentication documentation for access information.
ACH API follows the same conventions as SVB’s other APIs. Please see documentation on API conventions for more information.
ACH is an electronic payments network that transfers more than $40 trillion per year and has been in operation for more than 40 years. It’s a great way to transfer money between bank accounts at a very low cost. SVB’s ACH API is designed to be the easiest way to transact over the ACH network.

ACH Transfer Workflow

Typically ACH transfers take 1-2 business days to complete after specified effective date. API processing timelines page can be referenced for further details on estimating payment delivery.

 

ACH status lifecycle

 

STATUS DESCRIPTION
      pending

 Initial status after creation. Pending ACH transfers are queued for processing and settlement. An ACH transfer   can be canceled as long as it remains in the pending state. Depending on when the API request is made, a           transfer may be in pending status for anywhere from a few minutes to a few hours.

      canceled

 ACH transfer was canceled prior to being picked up for processing. See Update an ACH transfer below for       more information on how to cancel a transfer.

     processing

 ACH transfer has been sent for processing. The transfer is in transit to the clearinghouse and may no longer be   canceled.

hold

 ACH transfer has been paused for human review. This may happen infrequently for anti-fraud or compliance  reasons.

succeeded

 ACH transfer was successfully completed. An idiosyncrasy of the ACH network protocol is that the originator of a   successful transfer never receives an affirmative confirmation. As a result, the API will mark a transfer   as succeeded after an appropriate period of time (3 days), according to SVB’s own best practices.

failed

 ACH transfer failed. Failures can be for a variety of reasons, including incorrect account numbers or insufficient   funds.

corrected

 ACH transfer succeeded, but the recipient bank has sent corrected transfer information for future transfers.   Pursuant to NACHA rules, you are required to send any future transactions with the updated information.

 

Payment Tracking

ACH API provides a unique trace number, "fed trace number", to track payment status. In most cases, trace number will be assigned within 24 hours of payment submission. Fed trace number is generated by the downstream batching system and can be used for tracking the transfer within SVB payment platform.

Fed trace number can be retrieved using the retrieve an ACH endpoint. 

ACH Transfer Object

ACH transfer object contains all the information needed to transfer money, including bank account information, amount, and dates. Transfer object also contains payment status and other additional ACH transaction details. 

NAME TYPE DESCRIPTION SAMPLE VALUE / USE CASE
 account_number  string  SVB bank account number originating the ACH transfer. Only accounts that have been   explicitly   enabled for API access may be passed here.  For testing on sandbox, use the account   number '1111111111'.
addenda string Addenda entry specified by the originator. Becomes an addenda row in the NACHA file for ccd, ppd and web payment types. Alphanumeric field with an 80 character limit. Information is this field 
 amount  int  

 Amount of money to transfer, specified in cents.

 To pass in $10.55, use "1055" as the   amount. No decimals should be used to   represent amount. 

batch_id  string

 A unique ID indicating the batch this transfer was sent with. Can be used to reconcile   with your SVB bank statements. Will be null until the transfer reaches processing status.

 Batch ID that is assigned after the API   request is processed and batched for   NACHA. GET endpoint and the batch ID   can be used to list ACH transfers   processed in the same batch. 
company_entry_description  string  Description of the transaction specified by the originator, applies to the batch header.  CED field displays on the NACHA file.   This field can also be used to group ACH   API requests in the same batch. 
counterparty_id  string  Specifies the counterparty used in the transfer. Applies to transfers that use Counterparty   API to specify receiver details.   Counterparty API can be used to   tokenize receiver information and only   pass in the ID of the receiver. In such   cases, the response will not return   receiver and their account information.
currency  enum("USD")  Currency type for the transfer.  Currently, ACH API only supports USD as   the currency.
direction enum("credit", "debit")  Direct of the ACH transfer. 

 Credit is used in cases where the money   is pushed to receiver's account.

 Debit is used in cases where the money   is pulled from receiver's account.

effective_date date  Date of when the transfer should initiate.   Defaults to tomorrow's date.   Effective_date can be used to place   future dated transactions. Effective date   cannot be in the past. 
fed_trace_number string  Trace ID assigned by the downstream batching system. This field will be returned from the GET call once it is assigned  This number can be used to track a payment within the ACH network.
id string  Unique identifier of each ACH API transfer request.   This field will be used to retrieve further   transaction details and payment status.
memo string

 Optional 15 digit alphanumeric string that be used to pass data to the recipient bank. 

 For person to person WEB credit transactions, this field is required and should contain   the name of the consumer (originator).

 An invoice or transaction reference   number can be sent to recipient bank by   using this field.
metadata  object  Optional metadata to associate with the API request.   This field can be used to assign a client   generated reference number to the   request. Metadata supports a   "key":"value" assignment. This field is   not passed to NACHA or the recipient   financial institution. 
receiver_account_number string  Bank account number that is receiving the ACH transfer request.

 For credit transfers,   receiver_account_number will be the   account number to receive funds. 

 For debit transfers,   receiver_account_number will the   account number that the funds will be   pulled from.

receiver_account_type enum("checking", "savings")  Type of bank account that is receiving the ACH transfer.  Checking or Savings.
receiver_name string  Name of the receiving account holder.   String value representing the receiver's   name, i.e. "John Smith".
receiver_routing_number string  Routing number associated with the account number.   9 - Digit ABA routing number, identifying   the receiver financial institution.
return  object  In case of ACH failure or correction, this field will include NACHA return or correction     code.  This field will include the return failure   code and description. In case of   corrections, the field will include the   corrected value along with return code.
sec_code enum("ccd", "ppd", "web")  SEC code to be used for the ACH transfer. If not sure, contact your payment advisor for   the correct SEC code. 

 Standard Entry Class code, designates   how the ACH transfer was authorized by   the originator.

 ccd: Cash Concentration and   Disbursement

 ppd: Prearranged Payment and Deposit

 web: Internet-Initiated Entry

service enum("standard", "same-day")  Indicates whether this is a same-day or standard transfer.  Service and effective-date are important   fields to initiate same-day requests. For   a same-day request, enter service as   "same-day" and effective date as current   or tomorrow's date (depending on time   of day of request submission). 
status enum  The status of ACH payment. 

One of below:

 pending, processing, canceled,   successful, failed, hold, corrected.

 

Sandbox Testing/Simulating Failed Transfers

The following account numbers are reserved for testing returned ACH transfers. Creating an ACH transfer with the specific receiver_account_number will result in a failed status and a corresponding return_code, as shown above in the example of a returned transfer.

 

RECEIVER ACCOUNT NUMBER RETURN CODE
9000000000008201 R01
9000000000008202 R02