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
- Does not work with FCA, MCA, 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. 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. |
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 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 (2 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.
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
- identification_number - The optional third value (000015234AB) in the online banking statement example above is 15-digit alphanumeric string that be used to pass data to the recipient bank. For examples: an invoice number or transaction reference number. This field is mandatory for WEB credits.
- receiver_name - The fourth value (TEST) in the online banking statement example above is the ACH Company ID. This is the receiver's name in the ACH API request. This field can be modified in the ACH API POST request.
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 |