Table of Contents
Overview
ACH is a cost effective, simple way to make electronic payments in the United States. For more information on ACH payments, please visit SVB Learning Central.
The ACH API can be used to:
- Initiate ACH credits and debits, including Same Day ACH
- Submit payments for all supported NACHA types: PPD, CCD, and WEB
- Submit single ACH payments or a batch of ACH payments
- Retrieve status of payments submitted through the API
Postman Collection with examples
Key Features
- API allows for integration with variety of systems for automation of payment initiation
- ACH payments can be originated around the clock, to be processed during subsequent ACH batch processing windows
- Reduce costs of other payment origination methods such as paper checks or wire transmissions, with manual processes
- Automate reconciliation and error handling by subscribing to webhooks
Example Use Case
An Accounts Payable automation FinTech utilizes SVB’s ACH API to create an embedded payments workflow within their SaaS product that manages bill payments for their customers' suppliers and vendors. In real-time the integration facilitates:
- Origination of ACHs on behalf of their customers
- Get Status of each ACH
- Optional: Subscribe to Webhooks for status changes, including returns
- The FinTech provider’s platform is immediately updated with each status change, so that their customers have visibility throughout the ACH settlement lifecycle
cURL example for creating ACHs:
curl https://api.svb.com/v2/transfer/domestic-achs \ -X POST \ -H 'authorization': 'Bearer xxxxxxxxxxx' -H 'x-jws-signature: xxxxxxxxxxx' \ -H 'X-SVB-Correlation-ID: 123456' \ -H 'x-idempotency-key: 123456' \ -H 'prefer: RETURN_MINIMAL' \ -H 'content-type: application/json' \ -d '{ "batch_details": { "svb_account_number": "11111110", "direction": "CREDIT", "sec_code": "CCD", "settlement_priority": "STANDARD", "company_entry_description": "A123456789", "effective_entry_date": "2021-05-21", "currency": "USD" }, "transfers": [ { "amount": 55555, "identification_number": "000015234AB", "receiver_account_number": "2222220", "receiver_account_type": "CHECKING", "receiver_name": "George Washington", "receiver_routing_number": "321081669" }, { "amount": 255454, "identification_number": "000065234OP", "receiver_account_number": "7676766", "receiver_account_type": "SAVINGS", "receiver_name": "Michael Clarke", "receiver_routing_number": "321081669" } ] }'
Dependencies and restrictions
- Can originate ACH payments from US DDA accounts
- Not compatible with MCA, FCA, or UK accounts
- Direct channel integration, does not require SVB Go company ID/user ID
ACH Transfer Workflow
Typically ACH transfers take 1-2 business days to complete after specified effective date.
STATUS | DESCRIPTION |
---|---|
pending |
Accepted payments are immediately placed in pending status. Pending ACH transfers are queued for processing until the following settlement cutoff. An ACH transfer can be canceled as long as it remains in the pending state. Depending on when the API request is made and the effective entry data provided, a transfer may be in pending status for anywhere from a few minutes to a few hours. |
canceled |
ACH transfer was canceled prior to 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. |
processed | An ACH payment will move to processed after the ACH has been sent to clearing and the trace number has been assigned |
hold |
ACH transfer has been paused for further exception handling. |
succeeded |
ACH payment has processed through the network and 2 business days for potential returns have eclipsed. While ACH return rules vary based on SEC code and beneficiary account type, 2 business days is a conventional window by which the majority of ACH returns are processed by the receiving bank. There are edge cases a payment can move from Succeeded to Failed if the payment is returned after 2 business days. |
failed |
ACH transfer failed. Returns and rejects 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 transactions utilize a trace number assigned by the originating bank, which can be used to track the payment through clearing. Trace numbers will be assigned as the payment leaves the bank and will be provided with the Processed status webhook, or can be retrieved using the GET endpoint.
Return Codes
When an ACH is rejected, cannot be processed, or is processed with a change, there are a set of NACHA standard codes to describe the situation. Along with a failed or corrected status, the following codes may be present. For convenience, please see the descriptions here:
Return Code | Short Description | Change Code | Short Description |
---|---|---|---|
R01 | Insufficient Funds | C01 | Incorrect DFI Account Number |
R02 | Account Closed | C02 | Incorrect Routing Number |
R03 | No Account/Unable to Locate Account | C03 | Incorrect Routing Number and Incorrect DFI Account Number |
R04 | Invalid Account Number Structure | C05 | Incorrect Transaction Code |
R05 | Unauthorized Debit to Consumer Account Using Corporate SEC Code | C06 | Incorrect DFI Account Number and Incorrect Transaction Code |
R06 | Returned per ODFI's Request | C07 | Incorrect Routing Number, Incorrect DFI Account Number, and Incorrect Tranaction Code. |
R07 | Authorization Revoked by Customer | C08 | Incorrect Receiving DFI Identification (IAT Only) |
R08 | Payment Stopped | C09 | Incorrect Individual Identification Number/Incorrect Receiver Identification Number |
R09 | Uncollected Funds | C13 | Addenda Format Error |
R10 | Customer Advises Unauthorized, Improper, Ineligible, or Part of an Incomplete Transaction | C14 | Incorrect SEC Code for Outbound International Payment |
R11 | Check Truncation Early Return | ||
R12 | Account Sold to Another DFI | ||
R13 | Invalid ACH Routing Number | ||
R14 | Representative Payee Deceased or Unable to Continue in That Capacity | ||
R15 | Beneficiary or Account Holder (Other Than a Representative Payee) Deceased | ||
R16 | Account Frozen/Entry Returned per OFAC Instruction | ||
R17 | File Record Edit Criteria | ||
R18 | Improper Effective Entry Date | ||
R19 | Amount Field Error | ||
R20 | Non-Transaction Account | ||
R21 | Invalid Company Identification | ||
R22 | Invalid Individual ID Number | ||
R23 | Credit Entry Refused by Receiver | ||
R24 | Duplicate Entry | ||
R25 | Addenda Error | ||
R26 | Mandatory Field Error | ||
R27 | Trace Number Error | ||
R28 | Routing Number Check Digit Error | ||
R29 | Corporate Customer Advises Not Authorized | ||
R30 | RDFI Not Participant in Check Truncation Program | ||
R31 | Permissible Return Entry (CCD and CTX Only) | ||
R32 | RDFI Non-Settlement | ||
R33 | Return of XCK Entry | ||
R34 | Limited Participation DFI | ||
R35 | Return of Improper Debit Entry | ||
R36 | Return of Improper Credit Entry | ||
R37 | Source Document Presented for Payment | ||
R38 | Stop Payment on Source Document | ||
R39 | Improper Source Document/Source Document Presented for Payment |
End-to-end Reconciliation
The image below displays how key fields can be leveraged to pass information in the API request to create an ACH (Automated Clearing House) payment, that will show up in your OLB (Online Banking Portal). Scroll below the image for information on these and other important fields as well.
- company_name - The first value (test ac) in the online banking statement example above is the company_name. By default, this value will be populated with the account entity name used during the setup process for ACH settlement and clearing, and will show up on the bank statement. However, the “company_name” field can be added to the ACH POST request to override the default name and will appear in both – settlement clearing as well as the online banking statement.
- batch_id - The second value (A123456789) in the online banking statement example above. This is a unique ID indicating the batch this transfer was sent with. Can be used to reconcile with your SVB (SILICON VALLEY BANK) bank statements. Will be null until the transfer reaches processing status. This value is automatically generated by SVB.
- company_entry_description - The alternative second value (A123456789) in the online banking statement example above. An optional field specified by the originator applies to the batch header (so every transaction in the batch receives the same value). Typically, this is used for higher-level information about a group of transactions and could be as simple as "PAYROLL" or an ID for the payment run in your upstream payables system.
- passing the company_entry_description in the ACH API request, will override the batch_id value
- this will appear as the second value (A123456789) in the online banking statement example above, overriding the batch_id, if present within the ACH API request
- using a unique value within the batch details section of the ACH API request will produce separate headers in the NACHA file
Another field that does not appear in online banking, but that will be passed to the recipient of the ACH transaction:
- addenda - Addenda entry specified by the originator. Becomes an addenda row in the NACHA file for ccd, ppd and web payment types.
On Behalf Of (OBO) Payment
An OBO ACH payment can be made via the ACH API. When submitting the request, a different company name can be used. Example: ABC Company provides an Accounts Payable automation solution to Acme. ABC uses their own accounts to process the payments, but they want the beneficiary and statements to reflect that it was the end-customer Acme making the payment.
In order to process a payment on behalf of another company name, the "company_name" field will be required within the "batch_details" section of the request payload. The company name used in this field will appear on the SVB Online Banking (OLB) statement as well as the NACHA file. Below is a sample request payload for this scenario:
"batch_details": {
"settlement_priority": "STANDARD",
"sec_code": "CCD",
"company_entry_description": "A123456789",
"direction": "CREDIT",
"company_name": "Acme"
}
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 |