Link with Bank Logins (Account Aggregation)

POST an ACH-US node with Bank Logins

After you Create a User and OAuth the User, you are ready to link a bank account.

To link an ACH account with bank logins (also known as account aggregation), submit a user's online banking credentials (ex: your Chase online banking username/password). This allows us to instantly connect and verify the account without account/routing number or micro-deposits. View the full list supported institutions for account aggregation. Don't see your bank? Link with account/routing instead.

Step 1: Submit Bank Logins

API ENDPOINT

https://uat-api.synapsefi.com/v3.1/users/:user_id/nodes

PATH PARAMETER

user_id :
required
string

The user ID of the user you wish to add the ACH-US node under

BODY PARAMETER

type :
required
string

Type of node you wish to add. In this case its always ACH-US

info.bank_id :
required
string

User's online banking username

info.bank_pw :
required
string

User's online banking password

info.bank_name :
required
string

This is the bank_code (i.e. "capone" for Capital One) available at here

Example Request: POST User Credentials

Submit the user's online banking username/password. Learn how to encrypt sensitive data.

POST /v3.1/users/5bb40f0faadcf0361c91345a/nodes HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_T1ohHB0zsAeWPYUb3Fc9QSKlfXuZa06x5EpgI42R|n38dj3h8NE393bv24ovoRY34kd62
Content-Type: application/json

{
  "type": "ACH-US",
  "info":{
    "bank_id":"synapse_good",
    "bank_pw":"test1234",
    "bank_name":"fake"
  }
}
body = {
  "type": "ACH-US",
  "info":{
    "bank_id":"synapse_good",
    "bank_pw":"test1234",
    "bank_name":"fake"
  }
}

user.create_node(payload: body)
const body = {
  "type": "ACH-US",
  "info":{
    "bank_id":"synapse_good",
    "bank_pw":"test1234",
    "bank_name":"fake"
  }
}

user.createNode(body);
body = {
  "type": "ACH-US",
  "info":{
    "bank_id":"synapse_good",
    "bank_pw":"test1234",
    "bank_name":"fake"
  }
}

user.create_node(payload: body)
$infoachus = (object)[
 "bank_id" => "synapse_good",
 "bank_pw" => "test1234",
 "bank_name" => "fake"
];
$body = (object) [
 "type" => "ACH-US",
 "info" => $infoachus
];

$user->create_node($body);
body := `{
  "type": "ACH-US",
  "info":{
    "bank_id":"synapse_good",
    "bank_pw":"test1234",
    "bank_name":"fake"
  }
}`

data, err := user.CreateNode(body)

Example Response: Determine whether MFA is Required

Multi-Factor Authentication (MFA) is determined by the user's bank account settings.

If there is "http_code":"200", no MFA is required. The accounts will link and an email notice will send to the email address listed on the bank account.

If there is "http_code":"202", MFA is required. Because there may be multiple MFAs in a row, please build your logic to always check for an HTTP code of 202, which means another MFA question was sent. Cycle through MFAs in this way until the HTTP code is 200.

{
    "error_code": "10",
    "http_code": "202",
    "mfa": {
        "access_token": "fake_cd60680b9addc013ca7fb25b2b704be324d0295b34a6e3d14473e3cc65aa82d3",
        "message": "I heard you like questions so we put a question in your question?",
        "type": "question"
    },
    "success": true
}
{
    "error_code": "0",
    "http_code": "200",
    "limit": 2,
    "node_count": 2,
    "nodes": [
        {
            "_id": "5bb40f5f9a835600b7fb45b0",
            "_links": {
                "self": {
                    "href": "https://uat-api.synapsefi.com/v3.1/users/5bb40f0faadcf0361c91345a/nodes/5bb40f5f9a835600b7fb45b0"
                }
            },
            "allowed": "CREDIT-AND-DEBIT",
            "client": {
                "id": "5ade26b4567a900029e2afd2",
                "name": "YY Test Account"
            },
            "extra": {
                "note": null,
                "other": {
                    "access_token": "5bb40f5d915131002b282554",
                    "updated_on": 1538541470000
                },
                "supp_id": ""
            },
            "info": {
                "account_num": "8901",
                "address": "PO BOX 85139, RICHMOND, VA, US",
                "balance": {
                    "amount": "800.00",
                    "currency": "USD",
                    "updated_on": 1538541470000
                },
                "bank_logo": "https://cdn.synapsepay.com/bank_logos/new/co.png",
                "bank_long_name": "CAPITAL ONE N.A.",
                "bank_name": "CAPITAL ONE N.A.",
                "class": "CHECKING",
                "match_info": {
                    "email_match": "match",
                    "name_match": "match",
                    "phonenumber_match": "no_match"
                },
                "name_on_account": " ",
                "nickname": "SynapsePay Test Checking Account - 8901",
                "routing_num": "6110",
                "type": "BUSINESS"
            },
            "is_active": true,
            "timeline": [
                {
                    "date": 1538527070659,
                    "note": "Node created."
                }
            ],
            "type": "ACH-US",
            "user_id": "5bb40f0faadcf0361c91345a"
        },
        {
            "_id": "5bb40f60e552da00a7ed9ea9",
            "_links": {
                "self": {
                    "href": "https://uat-api.synapsefi.com/v3.1/users/5bb40f0faadcf0361c91345a/nodes/5bb40f60e552da00a7ed9ea9"
                }
            },
            "allowed": "CREDIT-AND-DEBIT",
            "client": {
                "id": "5ade26b4567a900029e2afd2",
                "name": "YY Test Account"
            },
            "extra": {
                "note": null,
                "other": {
                    "access_token": "5bb40f5d915131002b282554",
                    "updated_on": 1538541470000
                },
                "supp_id": ""
            },
            "info": {
                "account_num": "8902",
                "address": "PO BOX 85139, RICHMOND, VA, US",
                "balance": {
                    "amount": "750.00",
                    "currency": "USD",
                    "updated_on": 1538541470000
                },
                "bank_logo": "https://cdn.synapsepay.com/bank_logos/new/co.png",
                "bank_long_name": "CAPITAL ONE N.A.",
                "bank_name": "CAPITAL ONE N.A.",
                "class": "SAVINGS",
                "match_info": {
                    "email_match": "match",
                    "name_match": "match",
                    "phonenumber_match": "no_match"
                },
                "name_on_account": " ",
                "nickname": "SynapsePay Test Savings Account - 8902",
                "routing_num": "6110",
                "type": "BUSINESS"
            },
            "is_active": true,
            "timeline": [
                {
                    "date": 1538527071627,
                    "note": "Node created."
                }
            ],
            "type": "ACH-US",
            "user_id": "5bb40f0faadcf0361c91345a"
        }
    ],
    "page_count": 1,
    "success": true
}

Step 2: Verify with MFA

Verify the account with Multi-Factor Authentication (MFA) if required.

PATH PARAMETER

user_id :
required
string

The user ID of the user you wish to add the ACH-US node under

BODY PARAMETER

access_token :
required
string

Access token returned from previous step

mfa_answer :
required
string

Answer to the MFA question

Example Request: Submit MFA Answer

Submit the MFA answer. MFAs can be in the form of a code or question.

POST /v3.1/users/5bb40f0faadcf0361c91345a/nodes HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_T1ohHB0zsAeWPYUb3Fc9QSKlfXuZa06x5EpgI42R|n38dj3h8NE393bv24ovoRY34kd62
Content-Type: application/json

{
    "access_token":"fake_cd60680b9addc013ca7fb25b2b704ba82d3",
    "mfa_answer":"test_answer"
}

Client Library Examples:

body = {
    "access_token":"fake_cd60680b9addc013ca7fb25b2b704ba82d3",
    "mfa_answer":"test_answer"
}

user.ach_mfa(body)
const accessToken: 'fake_cd60680b9addc013ca7fb25b2b704ba82d3';
const mfaAnswer: 'test_answer';

user.verifyAchMfa(accessToken, mfaAnswer);
body = {
    "access_token":"fake_cd60680b9addc013ca7fb25b2b704ba82d3",
    "mfa_answer":"test_answer"
}

user.ach_mfa(payload: body)
$body = (object)[
     "access_token" => "fake_cd60680b9addc013ca7fb25b2b70",
     "mfa_answer" => "test_answer"
];

$idempotency_key = 'your_idempotency_key';
$achusnodemfa = $user->submit_mfa($body, $idempotency_key);
body = `{
    "access_token":"fake_cd60680b9addc013ca7fb25b2b704ba82d3",
    "mfa_answer":"test_answer"
}`

data, err := user.Authenticate(body)

Example Response: Bank Accounts Linked

When a 200 HTTP code is returned, all bank accounts associated with the user's bank login credentials are automatically linked. In some cases this will link to multiple accounts (ex: checking and savings). Please ask the user to designate the preferred ACH-US node and delete extra nodes.

{
    "error_code": "0",
    "http_code": "200",
    "limit": 2,
    "node_count": 2,
    "nodes": [
        {
            "_id": "5bb40f5f9a835600b7fb45b0",
            "_links": {
                "self": {
                    "href": "https://uat-api.synapsefi.com/v3.1/users/5bb40f0faadcf0361c91345a/nodes/5bb40f5f9a835600b7fb45b0"
                }
            },
            "allowed": "CREDIT-AND-DEBIT",
            "client": {
                "id": "5ade26b4567a900029e2afd2",
                "name": "YY Test Account"
            },
            "extra": {
                "note": null,
                "other": {
                    "access_token": "5bb40f5d915131002b282554",
                    "updated_on": 1538541470000
                },
                "supp_id": ""
            },
            "info": {
                "account_num": "8901",
                "address": "PO BOX 85139, RICHMOND, VA, US",
                "balance": {
                    "amount": "800.00",
                    "currency": "USD",
                    "updated_on": 1538541470000
                },
                "bank_logo": "https://cdn.synapsepay.com/bank_logos/new/co.png",
                "bank_long_name": "CAPITAL ONE N.A.",
                "bank_name": "CAPITAL ONE N.A.",
                "class": "CHECKING",
                "match_info": {
                    "email_match": "match",
                    "name_match": "match",
                    "phonenumber_match": "no_match"
                },
                "name_on_account": " ",
                "nickname": "SynapsePay Test Checking Account - 8901",
                "routing_num": "6110",
                "type": "BUSINESS"
            },
            "is_active": true,
            "timeline": [
                {
                    "date": 1538527070659,
                    "note": "Node created."
                }
            ],
            "type": "ACH-US",
            "user_id": "5bb40f0faadcf0361c91345a"
        },
        {
            "_id": "5bb40f60e552da00a7ed9ea9",
            "_links": {
                "self": {
                    "href": "https://uat-api.synapsefi.com/v3.1/users/5bb40f0faadcf0361c91345a/nodes/5bb40f60e552da00a7ed9ea9"
                }
            },
            "allowed": "CREDIT-AND-DEBIT",
            "client": {
                "id": "5ade26b4567a900029e2afd2",
                "name": "YY Test Account"
            },
            "extra": {
                "note": null,
                "other": {
                    "access_token": "5bb40f5d915131002b282554",
                    "updated_on": 1538541470000
                },
                "supp_id": ""
            },
            "info": {
                "account_num": "8902",
                "address": "PO BOX 85139, RICHMOND, VA, US",
                "balance": {
                    "amount": "750.00",
                    "currency": "USD",
                    "updated_on": 1538541470000
                },
                "bank_logo": "https://cdn.synapsepay.com/bank_logos/new/co.png",
                "bank_long_name": "CAPITAL ONE N.A.",
                "bank_name": "CAPITAL ONE N.A.",
                "class": "SAVINGS",
                "match_info": {
                    "email_match": "match",
                    "name_match": "match",
                    "phonenumber_match": "no_match"
                },
                "name_on_account": " ",
                "nickname": "SynapsePay Test Savings Account - 8902",
                "routing_num": "6110",
                "type": "BUSINESS"
            },
            "is_active": true,
            "timeline": [
                {
                    "date": 1538527071627,
                    "note": "Node created."
                }
            ],
            "type": "ACH-US",
            "user_id": "5bb40f0faadcf0361c91345a"
        }
    ],
    "page_count": 1,
    "success": true
}

Timeout Windows

Bank Logins may take a while. We recommend a timeout window of 100 seconds. This is why most bank login interfaces are interactive to keep people engaged.

Testing Bank Login Credentials in Sandbox

Following are the sample bank login credentials that you can use to test out your bank login implementation.

Username
Password
MFA
Bank Name

synapse_good

test1234

again (to get multiple MFAs) or else test_answer

fake

synapse_good

test1234_one

again (to get multiple MFAs) or else test_answer

fake

synapse_good

test1234_checking

again (to get multiple MFAs) or else test_answer

fake

synapse_good

test1234_savings

again (to get multiple MFAs) or else test_answer

fake

synapse_good

test1234_random

again (to get multiple MFAs) or else test_answer

fake

synapse_nomfa

test1234

No multi-factor authentication ("MFA") is necessary

fake

synapse_code_mfa

test1234

123456

fake

Testing Login Sync Errors in Sandbox

When adding a new node, append any of these values to the end of the password. When doing a force_refresh on the node, it will trigger the corresponding error.

Appending “_needs_relink” to the password (e.g. “test1234_savings_needs_relink) will link a node that will return the 401/110 error message when you try doing a “force_refresh”. It falls in line with our current sandbox test values so you can add “_needs_relink” to the end of any of the passwords above.

HTTP_CODE
ERROR_CODE
Append to Password
Description

503

503

_sync_unavailable

Refresh unavailable.

400

410

_sync_not_allowed

Refresh not allowed.

401

110

_needs_relink

Bad credentials.

500

500

_sync_unknown_error

Unknown refresh error.

Sandbox Test Values

Test in sandbox with test values for bank login credentials and authentication errors.

Also test the force_refresh sync feature and sync errors.

Encrypting Data

If you wish to encrypt bank login info while transmitting the information from the client device, you can use the following encryption key.

The key works for bank_id, bank_pw and mfa_answer.

-----Begin Public Key-----

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxy7xFpupeVxgUiaPneI1WAioSIeL6+/NAIIjbvDOvdTCNUeI//ob4bfdGLYlXpXOor/5POqfheZnHzkTu6BhDQqGZBc2BLaARlqx0s+twIadPwzqOJETzmp7r5U5ZioluOGDw4CF+JKRL6sBOaYr5wJ3BemZOXqQE7SAqIsi6Sej2ijGzVFq4tR3gogAdMKjGhzDwthqzZViZN1Zhzb8jsX/aCY+OWq9IUp4iX41fYmpfI9klVKnneAuVAIOPhI5zMaZ7JiQ+88ZQngTi6IhieyGIjvfG7FTsLNoYEqu1OeKw3SRt+HSs+LpnO3P9wwWODZtr07H7oxNJDAIoXITPwIDAQAB

-----End Public Key-----

JSencrypt is an easy to use library to use for this purpose, the implementation would look something like this

// Encrypt with the public key...
var encrypt = new JSEncrypt();
encrypt.setPublicKey($('#pubkey').val());
var encryptedUsername = encrypt.encrypt($('#username').val());
var encryptedPassword = encrypt.encrypt($('#password').val());
var encryptedMFA = encrypt.encrypt($('#mfa').val());

Subscribe to Webhooks

We recommend that you subscribe to webhooks to stay updated on the status of nodes.

Link with Bank Logins (Account Aggregation)


POST an ACH-US node with Bank Logins

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.