Link a bank account

Link a bank account to an existing Moov account.

To use this endpoint from the browser, you’ll need to specify the /accounts/{accountID}/bank-accounts.write scope when generating a token.
POST
/accounts/{accountID}/bank-accounts
cURL JavaScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
curl -X POST "https://api.moov.io/accounts/{accountID}/bank-accounts" \
  -H "Authorization: Bearer {token}" \
  --data-raw '{
    "account": {
      "holderName": "Jules Jackson",
      "holderType": "individual",
      "accountNumber": "0004321567000",
      "bankAccountType": "checking",
      "routingNumber": "123456789"
    }
  }'\
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
const moov = new Moov(credentialsObject);

const accountID = "accountID";
const bankAccountPayload = {
  bankAccount: {
    holderName: "Jules Jackson",
    holderType: "individual",
    accountNumber: "0004321567000",
    bankAccountType: "checking",
    routingNumber: "123456789"
  }
}

const response = await moov.bankaccounts.link(accountID, bankAccountPayload);
200 404 409 422 429
Bank account added.
Describes a bank account on a Moov account.
{
  "bankAccountID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
  "bankAccountType": "checking",
  "bankName": "Chase Bank",
  "exceptionDetails": {
    "achReturnCode": "R02",
    "description": "string",
    "rtpRejectionCode": "AC03 - Account Invalid"
  },
  "fingerprint": "9948962d92a1ce40c9f918cd9ece3a22bde62fb325a2f1fe2e833969de672ba3",
  "holderName": "Jules Jackson",
  "holderType": "individual",
  "lastFourAccountNumber": "7000",
  "routingNumber": "string",
  "status": "new",
  "statusReason": "bank-account-created",
  "updatedOn": "2019-08-24T14:15:22Z"
}
No Account with the specified accountID was found
  • Unable to get bank name for routing number
  • Duplicate bank account
The request body could not be processed.
Request was refused due to rate limiting.

X-Retry-In

string <duration>
How long (in milliseconds) to wait until able to retry the request.

Path parameters

accountID

string <uuid> required
ID of the account.

Body

application/json
Bank account Plaid Link Plaid Processor MX processor
Describes the account to link to the Moov account.

account

object
Describes the account to link to the Moov account.
right_key Show child attributes

accountNumber

string required

bankAccountType

string<enum> required
The bank account type.
Possible values: checking, savings, unknown

holderName

string required

holderType

string<enum> required
The type of holder on a funding source.
Possible values: individual, business

routingNumber

string required
Describes the account to link to the Moov account using a Plaid processor token.

plaid

object

The details of a Plaid processor integration for a linked funding source.

sandbox - When linking a bank account to a sandbox account using a Plaid processor token a default bank account response will be used. The following default data will be used to generate the bank account in this flow:

1
2
3
4
  RoutingNumber: "011401533",
  AccountNumber: "1111222233330000",
  AccountType:   "checking",
  Mask:          "0000"
right_key Show child attributes

token

string

Describes the account to link to the Moov account using a MX processor token.

sandbox - When linking a bank account to a sandbox account using an MX authorization token a default bank account routing number will be used. The following default data will be used to generate the bank account in this flow:

1
2
  RoutingNumber: "123456780",
  BankName: "Gringotts Bank"

mx

object
The authorization code of a MX account which allows a processor to retrieve a linked payment account.

sandbox - When linking a bank account to a sandbox account using a MX authorization code it will utilize MX’s sandbox environment. The MX authorization code provided must be generated from MX’s sandbox environment.
right_key Show child attributes

authorizationCode

string

Response

application/json
Describes a bank account on a Moov account.

bankAccountID

string<uuid> <=36 characters Pattern
UUID v4

bankAccountType

string<enum>
The bank account type.
Possible values: checking, savings, unknown

bankName

string

exceptionDetails

object
Reason for, and details related to, an errored or verificationFailed bank account status.
right_key Show child attributes

achReturnCode

string<enum>
The return code of an ACH transaction that caused the bank account status to change.
Possible values: R02, R03, R04, R05, R07, R08, R10, R11, R12, R13, R14, R15, R16, R17, R20, R23, R29, R34, R38, R39

description

string
Details related to an errored or verificationFailed bank account status.

rtpRejectionCode

string<enum>
The rejection code of an RTP transaction that caused the bank account status to change.
Possible values: AC03 - Account Invalid, AC04 - Account Closed, AC06 - Account Blocked, AC14 - Creditor Account Type Invalid, AG01 - Transactions Forbidden On Account, AG03 - Transaction Type Not Supported, MD07 - Customer Deceased

fingerprint

string <=100 characters
Once the bank account is linked, we don’t reveal the full bank account number. The fingerprint acts as a way to identify whether two linked bank accounts are the same.

holderName

string

holderType

string<enum>
The type of holder on a funding source.
Possible values: individual, business

lastFourAccountNumber

string

routingNumber

string

status

string<enum>
The bank account status.
Possible values: new, verified, verificationFailed, pending, errored

statusReason

string<enum>
The reason the bank account status changed to the current value.
Possible values: bank-account-created, verification-initiated, micro-deposit-attempts-exceeded, micro-deposit-expired, max-verification-failures, verification-successful, ach-debit-return, ach-credit-return, rtp-credit-failure, micro-deposit-return, admin-action, other

updatedOn

string<date-time> <=24 characters