Learning Central

Client Services

North America

clientsupport@svb.com
1.800.774.7390 
5:00 AM – 5:30 PM PT M-F

United Kingdom

ukclientservice@svb.com
0800.023.1441 | +44.207.367.7881
8:00 AM – 1:30 AM GMT

SVB PPP Care Team

SVBPPPCare@svb.com
1.833.450.5444
5:00 AM – 5:30 PM PT M-F


Contact the SVB PPP Care Team
for all PPP application questions or
view instructions here.


Bill Pay Classic

1.866.321.6563
4:30 AM PT - 11:00 PM PT M-F

Card Services

Cards Issued in the U.S.

cardservices@svb.com
1.866.553.3481
001.408.654.1039 (international)

Cards Issued in the UK
Support, lost, or stolen

0800.023.1062
+44.0.207.367.7852 (international)

Elite Cards

1.866.940.5920 | 408.654.7720

Lost or Stolen Cards

1.844.274.0771
001.408.654.1039 (international)

FX Trade Desk

North America

1.888.313.4029
IntFXT@svb.com
5:00 AM PT – 4:00 PM PT

United Kingdom

+1.44.0.207.367.7880
ukfxtraders@svb.com
8:00 AM BST – 5:OO PM BST

SVB Asset Management

1.866.719.9117
samoperations@svb.com

SVB Cash Sweep

1.800.774.7390 
clientservice@svb.com

More Support Contacts

ACH

This is the official reference documentation for the SVB ACH API. Please see the authentication documentation for access information.

The ACH API follows the same conventions as SVB’s other APIs. Please see the documentation on API conventions for more information.

ACH API
ACH Workflow
ACH Transfer Object
Create an ACH Transfer
Retrieve an ACH Transfer
Update an ACH Transfer
List ACH Transfers
ACH Webhooks
Testing failed ACH Transfers
 

Background

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.

Workflow and Status

Typically ACH transfers take 1-2 business days to complete. Below are the possible ACH status values.



STATUS
 DESCRIPTION
pending
The 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 pending for anywhere from a few minutes to a few hours.
canceled The 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 The ACH transfer has been sent for processing. The transfer is in transit to the clearinghouse and may no longer be canceled.
hold The ACH transfer has been paused for human review. This may happen infrequently for anti-fraud or compliance reasons.
succeeded The 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, according to SVB’s own best practices.
failed The ACH transfer failed. Failures can be for a variety of reasons, including incorrect account numbers or insufficient funds.
corrected The 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.

 

ACH Transfer Object

The ACH transfer object contains all the information needed to transfer money including bank account information, amount, and dates. It also provides the transfer’s current workflow status.

Attributes

NAME TYPE DESCRIPTION
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.
addenda string Addenda entry specified by the originator. Becomes an addenda row in the NACHA file for ccd, ppd and web payment types.
amount int Amount of money to transfer, specified in cents. Setting amount equal to zero will cause this to be a pre-notification transaction.

Example: 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.
company_entry_description
string Description of the transaction specified by the originator, applies to the batch header.
counterparty_id int ID of the counterparty resource used in place of receiver_* fields, if applicable.  Note that transfers created using the counterparty_id will not return the receiver_* fields.
currency enum(“usd”) Currency type to transfer. Currently supports only USD.
direction enum(“credit”, “debit”) Direction of the transfer. Credit means to push money to the receiver’s account and debit means to pull money from the receiver’s account.
effective_date date Date when the transfer should take place. Defaults to tomorrow’s date.
id string Uniquely identifies each ACH transfer object.
memo string Optional 15 digit alphanumeric string that can be used to pass data to the recipient bank.  Examples: an invoice number or transaction reference number.
metadata object Optional metadata to associate with the API resource.
receiver_account_number string Bank account number that is receiving the ACH transfer.
receiver_account_type enum(“checking”, “savings”) Type of bank account that is receiving the ACH transfer.
receiver_name string Name of the holder of the receiving account.
receiver_routing_number string ABA routing number associated with the receiver_account_number.
return object If the ACH transfer has been returned ("status": "failed"), or the transaction was corrected ("status": "corrected"), this field will be an object containing the NACHA return or correction code and description. For corrections, this will also contain the corrected value. 
sec_code enum(“ccd, "ppd”, “web”) SEC code to be used for the ACH transfer. Consult your banker if you’re not sure which is the correct value for your use case.
service enum(“standard”, “same-day”) Indicates whether this is a same-day or standard transfer.
status enum The status of the workflow (see above).

 

Example of a successful transfer:

{
  "account_number": "11111110",
  "amount": 55555,
  "batch_id": "1000010988",
  "currency": "usd",
  "direction": "credit",
  "effective_date": "2016-09-20",
  "id": 123,
"memo": "000015234AB", "metadata": {"foo": "bar"}, "receiver_account_number": "2222220", "receiver_account_type": "checking", "receiver_name": "George Washington", "receiver_routing_number": "321081669", "return": null, "sec_code": "ppd", "service": "standard", "status": "processing", "type": "ach", "url": "/v1/ach/123" }

Example of a returned transfer:

{
  "account_number": "11111110",
  "amount": 55555,
  "batch_id": "1000010988",
  "currency": "usd",
  "direction": "credit",
  "effective_date": "2016-09-20",
  "id": 124,
"memo": "000015234AB", "metadata": {"foo": "bar"}, "receiver_account_number": "2222220", "receiver_account_type": "checking", "receiver_name": "George Washington", "receiver_routing_number": "321081669", "return": {"code": "R01", "description": "Insufficient Funds"}, "sec_code": "ppd", "service": "standard", "status": "failed", "type": "ach", "url": "/v1/ach/124" }

Example of a corrected transfer:

{
  "account_number": "11111110",
  "amount": 55555,
  "batch_id": "1000010988",
  "currency": "usd",
  "direction": "credit",
  "effective_date": "2016-09-20",
  "id": 124,
"memo": "000015234AB", "metadata": {"foo": "bar"}, "receiver_account_number": "2222220", "receiver_account_type": "checking", "receiver_name": "George Washington", "receiver_routing_number": "321081669", "return": {"code": "C02",
"corrected_data": "101015101", "description": "Incorrect transit/routing number"}, "sec_code": "ppd", "service": "standard", "status": "failed", "type": "ach", "url": "/v1/ach/124" }

Create an ACH transfer

Request:

POST /v1/ach

Parameters:

NAME TYPE DESCRIPTION
account_number

                          required
string SVB bank account number originating the ACH transfer.

If 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.
amount

                          
                                required
int Amount of money to transfer, specified in cents.

Example: To pass in $10.55, use "1055" as the amount. No decimals should be used to represent amount. 
company_entry_description string 10 character transaction description field specified by the originator, applies to the batch header.
counterparty_id int ID of the counterparty resource to use in place of receiver_ fields.
currency enum("usd") If not provided, defaults to "USD".
direction

                          required
enum(“credit”, “debit”) Direction of the transfer.
effective_date date Date when the transfer should take place. Defaults to tomorrow’s date.
memo string Optional 15 digit alphanumeric string that can be used to pass data to the recipient bank.  Examples: an invoice number or transaction reference number.
metadata object Optional metadata to associate with the API resource.
receiver_account_number

        conditionally required
string Bank account number that is receiving the ACH transfer.

Required
if no counterparty_id is supplied.
receiver_account_type

        conditionally required
enum(“checking”, “savings”) Type of bank account that is receiving the ACH transfer.

Required if no counterparty_id is supplied.
receiver_name

        conditionally required
string Name of the holder of the receiving account. 

Required if no counterparty_id is supplied.
receiver_routing_number

        conditionally required
string ABA routing number associated with the receiver_account_number.

Required if no counterparty_id is supplied.
sec_code

                          required
enum(“ccd”, “ppd”, “web”) SEC code to be used for the ACH transfer.
service enum(“standard”, “same-day”) Service level. Defaults to standard service.

 

Response:

200 OK The new ACH transfer resource.

Example request:

curl "https://api.svb.com/v1/ach" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
          "data": {
            "account_number": "11111110",
            "amount": 55555,
            "currency": "usd",
            "direction": "credit",
            "effective_date": "2016-09-20",
"memo": "000015234AB", "receiver_account_number": "2222220", "receiver_account_type": "checking", "receiver_name": "George Washington", "receiver_routing_number": "321081669", "sec_code": "ppd", "service": "standard" } }'

Example response using receiver_* fields as above:

{
  "data": {
    "account_number": "11111110",
    "amount": 55555,
    "batch_id": null,
    "currency": "usd",
    "direction": "credit",
    "effective_date": "2016-09-20",
    "id": 127,
"memo": "000015234AB", "metadata": null, "receiver_account_number": "2222220", "receiver_account_type": "checking", "receiver_name": "George Washington", "receiver_routing_number": "321081669", "return": null, "sec_code": "ppd", "service": "standard", "status": "pending", "type": "ach", "url": "/v1/ach/127" } }

Example response using counterparty_id:

{
  "data": {
    "account_number": "11111110",
    "amount": 55555,
    "batch_id": null,
    "currency": "usd",
    "direction": "credit",
    "effective_date": "2016-09-20",
    "id": 127,
"memo": "000015234AB", "metadata": null, "counterparty_id": 12345, "return": null, "sec_code": "ppd", "service": "standard", "status": "pending", "type": "ach", "url": "/v1/ach/127" } }

Create ACH transfer endpoint supports idempotency to allow for safe retries and to prevent accidental duplication of transfers.

  • Clients can include "x-idempotency-key" in the request header to enable idempotency.
  • After the initial call to the create ACH transfer endpoint, if SVB receives the same idempotency key and request body again (from the same client), the endpoint will reply with the same response as the first call's response.
  • If SVB receives the same idempotency with another request body, the endpoint will respond with an error (422- Unprocessable Entity)
{
"error": "This X-Idempotency-Key header was used before with a
different payload"

}

Retrieve an ACH transfer

Request:

GET /v1/ach/:id

Response:

200 OK The ACH transfer resource.

Example request:

curl "https://api.svb.com/v1/ach/127" \
    -H "Authorization: Bearer YOUR_API_KEY"

Example response:

{
  "data": {
    "account_number": "11111110",
    "amount": 55555,
    "batch_id": "1000010988",
    "currency": "usd",
    "direction": "credit",
    "effective_date": "2016-09-20",
    "id": 127,
"memo": "000015234AB", "metadata": null, "receiver_account_number": "2222220", "receiver_account_type": "checking", "receiver_name": "George Washington", "receiver_routing_number": "321081669", "return": null, "sec_code": "ppd", "service": "standard", "status": "processing", "type": "ach", "url": "/v1/ach/127" } }

 

Update an ACH transfer

ACH transfers may only be updated while their status remains pending. Any other status indicates that the ACH has been sent for processing and may no longer be modified. 

Request:

PATCH /v1/ach/:id

Parameters:

Note: Since this is PATCH update only allows a change to the status, any parameters passed or not passed will remain unchanged.

NAME TYPE DESCRIPTION


status

        required
enum(“canceled”) To cancel a pending ACH transfer, pass "canceled" for status.

Response:

200 OK The updated ACH transfer resource.

Example request:

curl "https://api.svb.com/v1/ach/127" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -X PATCH \
    -d '{
          "data": {
            "status": "canceled"
          }
        }'

Example response:

{
  "data": {
    "account_number": "11111110",
    "amount": 55555,
    "batch_id": "1000010988",
    "currency": "usd",
    "direction": "credit",
    "effective_date": "2016-09-20",
    "id": 127,
"memo": "000015234AB", "metadata": null, "receiver_account_number": "2222220", "receiver_account_type": "checking", "receiver_name": "George Washington", "receiver_routing_number": "321081669", "return": null, "sec_code": "ppd", "service": "standard", "status": "canceled", "type": "ach", "url": "/v1/ach/127" } }
CODE ERROR MESSAGE DESCRIPTION
400
"Parameter status (\"pending\") must be: canceled"
Invalid value passed in status

List all ACH transfers

Request:

GET /v1/ach

Response:

200 OK List of ACH transfer resources.

Example request:

curl "https://api.svb.com/v1/ach" \
    -H "Authorization: Bearer YOUR_API_KEY"

Example response:

{
  "data": [
    {
      "id": 127,
      "type": "ach",
      "url": "/v1/ach/127"
    },
    {
      "id": 126,
      "type": "ach",
      "url": "/v1/ach/126"
    },
    {
      "id": 125,
      "type": "ach",
      "url": "/v1/ach/125"
    }
  ],
  "links": {
    "first": "/v1/ach",
    "next": null
  }
}

Filtering:

Filtering is supported by this endpoint. The results can be filtered by matching fields in the key portion of the ACH transfer.

  • To filter, use the the filter[key]=value parameter. Key is the name of the field that the user needs to filter by, and value is the string to match. For further information and examples on filtering, please refer to conventions page, filtering section.

  • For example, to find all pending ACH transfers, use the endpoint:

    /v1/ach?filter[status]=pending

The list route supports the following filters:

NAME TYPE DESCRIPTION
effective_date date Only show transactions with this effective date and after
status enum Only show transactions with this status
batch_id string Only show transactions with this batch_id
sec_code enum Only show transactions with this sec code
account_number string Only show transactions for this account number
counterparty_id int Only show transactions with this counterparty id
amount int Only show transactions with this amount
direction enum Only show transactions with this direction (credit/debit)
memo string Only show transactions with this memo
metadata object Key filter and key/value filter
receiver_account_number string Only show transactions with this receiver account number
receiver_account_type enum Only show transactions for this account type
receiver_name string Only show transactions for this receiver
receiver_routing_number string Only show transactions for this routing number
service enum Only show transactions with this service type (standard/same-day)


Example request with a filter:

curl -g "https://api.svb.com/v1/ach?filter[status]=pending" \
    -H "Authorization: Bearer YOUR_API_KEY"

ACH Webhooks

ACH webhook event types and payloads are listed here.

ACH Status Webhook Event Type

When an ACH transaction status changes to "failed" or "corrected", that event can be tracked using webhooks.  

Type Description
ach.status Triggered when an ach transfer status changes to "failed" or "corrected".   
ach.status.advice Triggered for all status updates other than "failed" or "corrected". 

 

Example ach.status webhook payload with 'failed' status:

{
  "data": {
    "date": "2017-08-21T16:34:26.330Z",
    "event-id": 101,
    "payload": {
      "id": 123,
      "memo": "000015234AB", "status": "failed", "return_code": "R01" }, "previous": { "id": 123,
      "memo": "000015234AB", "status": "processing", "return": null }, "type": "ach.status" } }

Example ach.status webhook payload with 'corrected' status:

{
  "data": {
    "date": "2017-08-21T16:34:26.330Z",
    "event-id": 101,
    "payload": {
      "id": 123,
      "memo": "000015234AB", "status": "corrected", "return_code":"C02",
"corrected_data": "053000219" }, "previous": { "id": 123,
      "memo": "000015234AB", "status": "processing", "return": null }, "type": "ach.status" } }
 

Testing 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