Link a bank account
Link a bank account to an existing Moov account. Read our bank accounts guide to learn more.
To use this endpoint from the browser, you’ll need to specify the /accounts/{accountID}/bank-accounts.write
scope when generating a token.
It is strongly recommended that callers include the X-Wait-For
header, set to payment-method
, if the newly linked
bank-account is intended to be used right away. If this header is not included, the caller will need to poll the List Payment
Methods
endpoint to wait for the new payment methods to be available for use.
|
|
|
|
|
|
{
"bankAccountID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
"bankAccountType": "checking",
"bankName": "Chase Bank",
"exceptionDetails": {
"achReturnCode": "R02",
"description": "string",
"rtpRejectionCode": "AC03"
},
"fingerprint": "9948962d92a1ce40c9f918cd9ece3a22bde62fb325a2f1fe2e833969de672ba3",
"holderName": "Jules Jackson",
"holderType": "individual",
"lastFourAccountNumber": "7000",
"paymentMethods": [
{
"paymentMethodID": "9506dbf6-4208-44c3-ad8a-e4431660e1f2",
"paymentMethodType": "ach-debit-fund"
},
{
"paymentMethodID": "3f9969cf-a1f3-4d83-8ddc-229a506651cf",
"paymentMethodType": "ach-debit-collect"
}
],
"routingNumber": "string",
"status": "new",
"statusReason": "bank-account-created",
"updatedOn": "2019-08-24T14:15:22Z"
}
- Unable to get bank name for routing number
- Duplicate bank account
Response headers
Retry-After
number
Headers
X-Wait-For
string
Optional header to wait for certain events, such as the creation of a payment method, to occur before returning a response.
When this header is set to payment-method
, the response will include any payment methods that were created for the newly
linked card in the paymentMethods
field. Otherwise, the paymentMethods
field will be omitted from the response.
payment-method
,
rail-response
Path parameters
accountID
string
<uuid>
required
Body
account
object
Show child attributes
accountNumber
string
required
bankAccountType
string<enum>
required
checking
,
savings
,
general-ledger
,
loan
holderName
string
required
holderType
string<enum>
required
individual
,
business
routingNumber
string
required
plaidLink
object
This is used by Moov.js with a Plaid reseller relationship. The details of a Plaid link integration for a linked funding source.
You can simulate linking bank accounts with Plaid in test mode. See our test mode guide for more information.
Plaid’s sandbox
environment - (requires Plaid reseller setup with Moov). When linking a bank account to a sandbox
account using a Plaid public token it will utilize Plaid’s sandbox environment. The Plaid public token provided must be generated from Plaid’s sandbox environment. Please see Plaid’s sandbox documentation for more details.
Show child attributes
publicToken
string
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:
|
|
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:
|
|
mx
object
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.
Show child attributes
authorizationCode
string
Response
bankAccountID
string<uuid>
<=36 characters
bankAccountType
string<enum>
checking
,
savings
,
general-ledger
,
loan
bankName
string
exceptionDetails
object
errored
or verificationFailed
bank account status.
Show child attributes
achReturnCode
string<enum>
The return code of an ACH transaction that caused the bank account status to change.
Codes:
- R02 - Account Closed
- R03 - No Account/Unable to Locate Account
- R04 - Invalid Account Number
- R05 - Improper Debit to Consumer Account
- R07 - Authorization Revoked by Customer
- R08 - Payment Stopped
- R10 - Customer Advises Originator is Not Known or Authorized to Receiver and
- R11 - Customer Advises Entry Not in Accordance with the Terms of the Authorization
- R12 - Branch Sold to Another DFI
- R13 - RDFI not qualified to participate
- R14 - Representative payee deceased or unable to continue in that capacity
- R15 - Beneficiary or bank account holder
- R16 - Bank account frozen
- R17 - Entry with Invalid Account Number Initiated Under Questionable Circumstances
- R20 - Non-payment bank account
- R23 - Credit entry refused by receiver
- R29 - Corporate customer advises not authorized
- R34 - Limited participation RDFI
- R38 - Stop Payment on Source Document (Adjustment Entry)
- R39 - Improper Source Document
R02
,
R03
,
R04
,
R05
,
R07
,
R08
,
R10
,
R11
,
R12
,
R13
,
R14
,
R15
,
R16
,
R17
,
R20
,
R23
,
R29
,
R34
,
R38
,
R39
description
string
errored
or verificationFailed
bank account status.
rtpRejectionCode
string<enum>
The rejection code of an RTP transaction that caused the bank account status to change.
Codes:
- 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
AC03
,
AC04
,
AC06
,
AC14
,
AG01
,
AG03
,
MD07
fingerprint
string
<=100 characters
holderName
string
holderType
string<enum>
individual
,
business
lastFourAccountNumber
string
paymentMethods
array
Includes any payment methods generated for a newly created bank account, removing the need to call the List Payment Methods endpoint following a successful Create BankAccount request.
NOTE: This field is only populated for Create BankAccount requests made with the X-Wait-For
header.
Show child attributes
paymentMethodID
string<uuid>
<=36 characters
paymentMethodType
string<enum>
moov-wallet
,
ach-debit-fund
,
ach-debit-collect
,
ach-credit-standard
,
ach-credit-same-day
,
rtp-credit
,
card-payment
,
apple-pay
,
push-to-card
,
pull-from-card
routingNumber
string
status
string<enum>
new
,
verified
,
verificationFailed
,
pending
,
errored
statusReason
string<enum>
bank-account-created
,
verification-initiated
,
micro-deposit-attempts-exceeded
,
micro-deposit-expired
,
max-verification-failures
,
verification-attempts-exceeded
,
verification-expired
,
verification-successful
,
ach-debit-return
,
ach-credit-return
,
rtp-credit-failure
,
micro-deposit-return
,
admin-action
,
other
updatedOn
string<date-time>
<=24 characters