Learning Central

Client Services

North America

clientsupport@svb.com
1.800.774.7390 | 408.654.4636
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

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 | 408.654.4636
clientservice@svb.com

More Support Contacts

ACH

The ACH API is currently in a limited beta.

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.

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. The status of an ACH transfer can take the following values:

  • 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 Transfers

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.
amount int Amount of money to transfer, specified in positive integral cents. Setting amount equal to zero will cause this to be a prenotification transaction.
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.
counterparty_id int ID of the counterparty resource used in place of receiver_* fields, if applicable.
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": "3333330", "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": "3333330", "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": "3333330", "return": {"code": "C02",
"corrected_data": "101015101", "description": "Incorrect transit/routing number"}, "sec_code": "ppd", "service": "standard", "status": "failed", "type": "ach", "url": "/v1/ach/124" }

 


Filters

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 (see above).
batch_id string Only show transactions with this batch_id.
receiver_account_number  string Only show transactions with this receiver account number.

 

Example request:

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

 


Create an ACH transfer

Request:

POST /v1/ach

Parameters:

NAME TYPE REQUIRED (?) DESCRIPTION
account_number string R SVB bank account number originating the ACH transfer.
amount int R Amount of money to transfer, specified in positive integral cents.
counterparty_id int   ID of the counterparty resource to use in place of receiver_ fields.
direction enum(“credit”, “debit”) R 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 string R Bank account number that is receiving the ACH transfer. Required if no counterparty_id is supplied.
receiver_account_type enum(“checking”, “savings”) R Type of bank account that is receiving the ACH transfer. Required if no counterparty_id is supplied.
receiver_name string R Name of the holder of the receiving account. Required if no counterparty_id is supplied.
receiver_routing_number string R ABA routing number associated with the receiver_account_number. Required if no counterparty_id is supplied.
sec_code enum(“ccd”, “ppd”, “web”) R 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": "3333330", "sec_code": "ppd", "service": "standard" } }'

Example response:

{
  "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": "3333330", "return": null, "sec_code": "ppd", "service": "standard", "status": "pending", "type": "ach", "url": "/v1/ach/127" } }

 


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": "3333330", "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 a PATCH update, any parameters not passed will remain unchanged.

NAME TYPE REQUIRED (?) DESCRIPTION
status enum(“canceled”) R 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": "3333330", "return": null, "sec_code": "ppd", "service": "standard", "status": "canceled", "type": "ach", "url": "/v1/ach/127" } }

 


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
  }
}

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".   

 

Example ach.status webhook payload:

{
  "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" } }
 

 

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