ACH Account Verification

Finicity's ACH Account Verification Service includes services for downloading ACH data for customer accounts (institution routing number and full bank account number), including support for responding to MFA challenges.

(MFA means Multi-Factor Authentication, describing various styles of authentication challenges such as text questions, image matching, “captcha” images, etc.)

See Active Docs to experiment directly with the API.

Available services:

Get Customer Account Details

GET /v1/customers/{customerId}/accounts/{accountId}/details

Connect to the account's financial institution and retrieve the ACH data for the indicated account. This may be an interactive refresh, so MFA challenges may be required.

This service is supported only for accounts with type checkingsavings, or moneyMarket. Calling this service for other account types will return HTTP 400 (Bad Request).

This is a premium service. The billing rate is the variable rate for ACH Account Verification under the current subscription plan. The billable event is a successful call to this service.

HTTP status of 200 means both realAccountNumber and routingNumber were returned successfully in the body of the response.

HTTP status of 203 means the response contains an MFA challenge in XML or JSON format. Go to Get Customer Account Details (with MFA Answers).

HTTP status of 404 means that no ACH data is available for this account.

This service retrieves account data from the institution. This usually returns quickly, but in some scenarios may take a few minutes to complete, which can result in a timeout condition (usually HTTP 202, 408, or 504, but may show some other codes also). See Handling Timeouts for guidelines on handling this kind of error.

The recommended timeout setting for this request is 120 seconds.

JSON Implementation

Request Details

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header application/json
customerId path The ID of the customer who owns the account
accountId path The Finicity ID of the account

Example Request

GET https://api.finicity.com/aggregation/v1/customers/41442/accounts/2083/details

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/json" -X GET "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2083/details"

Response Details - HTTP 200 (OK)

Parameter Type Description
routingNumber JSON field The account's 9-digit Routing Transit Number 
realAccountNumber JSON field The full account number, assigned by the institution 

Example Response - HTTP 200 (OK)

{
"routingNumber": "123456789",
"realAccountNumber": "002345678901"

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header Session identifier. Must be copied directly to the subsequent request for Get Customer Account Details (with MFA Answers).
questions JSON parent MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

{
"questions": [
{
"text": "What was the last name of your favorite teacher?",
}
]

XML Implementation

Request Details

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header

application/xml

customerId path

The ID of the customer who owns the account

accountId path

The Finicity ID of the account

Example Request

GET https://api.finicity.com/aggregation/v1/customers/41442/accounts/2083/details

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/xml" -X GET "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2083/details"

Response Details - HTTP 200 (OK)

Parameter Type Description
account XML parent Root element
realAccountNumber XML element The full account number, assigned by the institution 
routingNumber XML element The account's 9-digit Routing Transit Number

Example Response - HTTP 200 (OK)  

<account>
<realAccountNumber>987654321</realAccountNumber>
<routingNumber>123456789</routingNumber>
</account> 

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header Session identifier. Must be copied directly to the subsequent request for Get Customer Account Details (with MFA Answers).
mfaChallenges XML element MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

<mfaChallenges>
  <questions>
    <question>
      <text>What was the last name of your favorite teacher?</text>
    </question>
  </questions>
</mfaChallenges> 

Get Customer Account Details (with MFA Answers)

POST /v1/customers/{customerId}/accounts/{accountId}/details/mfa

Send MFA answers for an earlier challenge while getting account details.

HTTP status of 200 means both realAccountNumber and routingNumber were returned successfully in the body of the response.

HTTP status of 203 means the response contains another MFA challenge. Call Get Customer Account Details (with MFA Answers) again to answer the new challenge.

This service is invoked only if a previous call to Get Customer Account Details or Get Customer Account Details (with MFA Answers) has returned HTTP 203. The response from that previous call is referred to as "the previous response" below.

The call itself is a replay of the previous call, with several changes:

  • Change the request method from GET to POST.
  • Append /mfa to the path.
  • Add a Content-Type header with the value application/json or application/xml
  • Copy the MFA-Session header from the previous response onto this request. 
  • Copy the MFA challenge from the previous response into the request body. 
  • Add the MFA answer inside the <question> element in the MFA challenge. 

The recommended timeout setting for this request is 120 seconds.

JSON Implementation

Request Details

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header

application/json

Content-Type HTTP header application/json
MFA-Session HTTP header

Copied directly from the previous response (the value will be different for each HTTP 203 response received)

customerId path

The ID of the customer who owns the account

accountId path

The Finicity ID of the account

questions JSON parent

MFA Challenge Segment

Example Request

POST https://api.finicity.com/aggregation/v1/customers/41442/accounts/2083/details/mfa
{
"questions": [
{
"text": "What was the last name of your favorite teacher?",
"answer": "Green"
}
]
}

Using curl:

curl -v -H "Content-Type:application/json" -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/json" -H "Content-Type:application/json" -H "MFA-Session:MFA_SESSION" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2083/details/mfa" -d '{ "questions": [ { "text": "What was the last name of your favorite teacher?", "answer": "Green" } ] }'

Response Details - HTTP 200 (OK)

Parameter Type Description
routingNumber JSON field The account's 9-digit Routing Transit Number
realAccountNumber JSON field The full account number, assigned by the institution  

Example Response - HTTP 200 (OK)

{
"routingNumber": "123456789",
"realAccountNumber": "002345678901"

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header Session identifier. Must be copied directly to the subsequent request for Get Customer Account Details (with MFA Answers).
questions JSON parent MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

{
"questions": [
{
"text": "Enter your first pet's name:",
}
]
}

XML Implementation

Request Details

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header

application/xml

Content-Type HTTP header application/xml
MFA-Session HTTP header

Copied directly from the previous response (the value will be different for each HTTP 203 response received)

customerId path

The ID of the customer who owns the account

accountId path

The Finicity ID of the account

mfaChallenges XML element

MFA Challenge Segment

Example Request

POST https://api.finicity.com/aggregation/v1/customers/41442/accounts/2083
<mfaChallenges> <questions> <question> <text>What was the last name of your favorite teacher?</text> <answer>Green</answer> </question> </questions> </mfaChallenges>

Using curl:

curl -v -H "Content-Type:application/xml" -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/xml" -H "Content-Type:application/xml" -H "MFA-Session:MFA_SESSION" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2083" -d '<mfaChallenges> <questions> <question> <text>What was the last name of your favorite teacher?</text> <answer>Green</answer> </question> </questions> </mfaChallenges>'

Response Details - HTTP 200 (OK)

Parameter Type Description
account XML parent Root element
realAccountNumber XML element  The full account number, assigned by the institution 
routingNumber XML element The account's 9-digit Routing Transit Number

Example Response - HTTP 200 (OK)  

<account>
<realAccountNumber>987654321</realAccountNumber>
<routingNumber>123456789</routingNumber>
</account>

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header Session identifier. Must be copied directly to the subsequent request for Get Customer Account Details (with MFA Answers).
mfaChallenges XML element MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

<mfaChallenges>
  <questions>
    <question>
      <text>Enter your first pet's name:</text>
    </question>
  </questions>
</mfaChallenges>
Have more questions? Submit a request

Comments

Powered by Zendesk