/api/v2/... paths as production on its own host, and it links the aggregators’ test banks instead of real ones: Finicity’s FinBank, MX’s MX Bank and FDE’s Ledgersync Bank. You sign in to them with test logins, then read the results back with the same calls you will use in production.
Sandbox:
https://staging.ledgersyncappv2.com · Production: https://ledgersyncappv2.com · The paths are the same on both hosts, for example POST https://staging.ledgersyncappv2.com/api/v2/public/authenticate.Get a sandbox account
1
Sign up in the sandbox
Create an account at staging.ledgersyncappv2.com/sign-up. The sandbox and production keep separate accounts and separate data, so signing up in one does not give you an account in the other.
2
Authenticate against the sandbox host
Call
POST /api/v2/public/authenticate on the sandbox host with that account, then send the authToken it returns in the Auth-Token header of every other call. See Authentication for the details. The examples on this page assume:3
Add a test client
The add, account list and transaction calls below all name the client by its
username. Add a client with POST /api/v2/client/add and use its username (here jane.client).The sandbox test banks
- Finicity reaches FinBank only. The sandbox registers its clients with Finicity as testing customers, and Mastercard lets testing customers use its FinBank test institutions only, never a real bank. The widget is Mastercard Connect on
connect2.finicity.com. - MX Bank is MX’s test bank. The sandbox uses MX’s integration environment: its widget runs on
int-widgets.moneydesktop.com, and MX Bank’s institution code there ismxbank. - FDE has no separate test environment. The sandbox uses the same FDE service as production, so link only Ledgersync Bank there, never a real bank login.
Avoid one client name: a client whose name has
Active as its second word (for example Jane Active) is registered with Finicity as a billable customer instead of a testing one, and billable customers cannot use FinBank.Link FinBank (Finicity)
1
Get a widget URL
2
Sign in to FinBank
Open
widgetUrl in a browser within two hours, which is how long Mastercard keeps the link valid. After Mastercard’s opening screens, search for FinBank and pick the row named exactly FinBank. The search also lists Mastercard’s FinBank variants for edge cases, and FinBank Billable is not open to testing customers.Sign in with demo / go (customer1 / go also works). No MFA question is asked. Choose the accounts to share and finish.3
Find the new connection
LedgerSync records the connection when Finicity reports it, so it can take a moment to appear after the user finishes. Then
GET /api/v2/account/jane.client lists it under banks with "source": "FINICITY", and each of its accounts[].id is an accountId for List Transactions.4
Read the transactions
pending and no posted date, so a request with from and to leaves them out: leave both dates off to see them. Dates come back as yyyy-MM-ddTHH:mm:ss in UTC, with no offset.
Link MX Bank (MX)
1
Get an MX widget URL
widgetUrl is now an MX Connect URL. With "institutionId": "mxbank" it opens on MX Bank and skips MX’s bank search; leave it out to search in the widget. MX does not use redirectUri.2
Sign in to MX Bank
Open
widgetUrl and sign in with mxuser / correct.3
Read it with source=MX
Once MX reports the new connection,
GET /api/v2/account/jane.client lists it with "source": "MX". Send source=MX to List Transactions for its accounts.POSTED or PENDING and dates in MM/dd/yyyy. from and to filter on the transaction date, and a pending row carries its transaction date in postedDate.
Ledgersync Bank (FDE)
FDE has no connect widget, soPOST /api/v2/account/add and POST /api/v2/account/add/lite answer 422 for "source": "FDE". The v2 API still reads FDE connections, so create the test connection in the sandbox web app and read it back through the API:
1
Add it in the web app
Sign in at staging.ledgersyncappv2.com with your sandbox account, open the client’s bank list, click Add Bank Connection and search for Ledgersync Bank. Follow the prompts: any username and password are accepted.
2
Find it through the API
GET /api/v2/account/jane.client lists it with "source": "FDE".Ledgersync Bank produces no transactions in the sandbox, so List Transactions with
source=FDE returns an empty list for its accounts. Use FinBank or MX Bank to test transaction reads.MFA questions
A v2 integration meets MFA questions in two places:- While linking a bank. The bank’s sign-in questions are asked and answered inside the Finicity or MX widget. Your app only handles the widget URL.
- While refreshing statements.
POST /api/v2/statements/refreshanswers203when a statement needs an answer first. Show the challenge to the user, then send the answer toPOST /api/v2/statements/refresh/mfawith the samebankAccountId,accountId,pullIndexandsource, plus themfaSessionfrom the 203 response. That call can answer203again with a new challenge. A challenge is atextquestion, animage(base64),choicesorimageChoices.
203.
Clean up
DELETE /api/v2/account/{bank_account_id} removes a test bank and its accounts. Send the bank’s source with it, for example ?source=MX: connection ids are numbered separately per source, and without source the call acts on the FINICITY connection with that id.
Authentication
Get the
Auth-Token every sandbox call needs.Transactions
How List Transactions reads each source.
