NAV
curl

← Home

ACH

Introduction

Disclaimer: This documentation is currently in Alpha and is subject to drastic change.

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:

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.

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.

The ACH transfer has been sent for processing. The transfer is in transit to the clearinghouse and may no longer be canceled.

The ACH transfer has been paused for human review. This may happen infrequently for anti-fraud or compliance reasons.

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.

The ACH transfer failed. Failures can be for a variety of reasons, including incorrect account numbers or insufficient funds.

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

Example of a sucessful transfer:

{
  "account_number": "11111110",
  "amount": 55555,
  "batch_id": "1000010988",
  "currency": "usd",
  "direction": "credit",
  "effective_date": "2016-09-20",
  "id": 123,
  "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,
  "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"
}
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.
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"), this field will be an object containing the NACHA return code and description. In all other cases it will be null.
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).

Filters

The list route supports the following filters:

Example request:

curl -g "https://api.svb.com/v1/ach?filter[status]=pending" \
    -H "Authorization: Bearer YOUR_API_KEY"
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.

Create an ACH transfer

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

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

Retrieve an ACH transfer

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

Request:

GET /v1/ach/:id

Response:

200 OK The ACH transfer resource.

Update an ACH transfer

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

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.

List all ACH transfers

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

Request:

GET /v1/ach

Response:

200 OK List of ACH transfer resources.

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