ACH API follows the same conventions as SVB’s other APIs. Please see documentation on API conventions for more information.
Table of Contents
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.
| 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 |