Plaid Core Exchange with Synctera

What is Plaid Core Exchange?

Plaid Core Exchange is a way for financial institutions to share customers account information
safely and securely with other financial institutions. This enables customers to effortlessly
link their accounts at your fintech to thousands of financial institutions. While Plaid estimates
Core Exchange integration typically takes 6-8 weeks, Synctera has done much of the integration
for you, greatly reducing your effort.

How does it work?

Plaid Core Exchange is a set of well-defined APIs and authentication methods which
together control access to a customer financial data (accounts, transactions, etc.) and provide
methods for Plaid to retrieve that data so it can be shared with the other financial institution.
Synctera helps by limiting our Fintech's integration scope to only the authentication piece.

At the highest level, Plaid Core Exchange works as follows:

1. A customer at another financial institution (FI) wants to link to their account at a Synctera hosted fintech
2. Plaid (via Synctera) makes an HTTP request to the fintech to authenticate the customer in their system
3. Synctera completes the linkage with Plaid
4. The FI receives the customer's fintech account information
5. The FI can then perform a transfer (e.g. ACH) to/from the fintech account

After a customer authenticates via your authentication endpoint (step 2), you will need to make a call to
Synctera granting authorization for Plaid to access the customer’s data. Behind the scenes Synctera will be
managing the rest of the authentication requirements with Plaid as well as orchestrating all the
data exchange between your customer and Plaid.

Comparison with External Accounts

Synctera's integration with Plaid Core Exchange is complementary to our External Accounts feature.
As a fintech on the Synctera platform, our external accounts feature enables a customer using your app to link
to their accounts on another financial institution, using either Plaid or Finicity.
Our Plaid Core Exchange integration enables linking in the other direction: the customer can use the other
financial institution's app to link to their accounts on your system.

Synctera's Plaid Core Exchange integration supports the thousands of financial institutions that use Plaid for
their outbound account linking, regardless of whether you use Plaid or Finicity for your outbound linking with our
external accounts feature.

Authentication Endpoint

To integrate with Synctera's Plaid Core Exchange feature, you need to implement an authentication endpoint.
You can choose the URL for this endpoint, and the Synctera operations team will record it in our platform,
as well as the exact name you want your fintech to be listed as.
This endpoint must handle a GET request that includes an auth_request_id query parameter.
Its purpose is to verify the customer's identity, using a login page, one time password or whatever other
method is appropriate for your service.

Upon successful authentication, the endpoint makes a POST request to the Synctera platform at /v1/fdx_auth_requests/authorize
to grant authorization to this auth_request_id, using the following schema:

{
  "auth_request_id": "0d35e262-5c75-4a53-baf3-e5cb3685b6e8",
  "customer_id": "1cef45db-3f45-4439-b79a-780ecfb5f113",
  "status": "GRANTED"
}

• auth_request_id: The unique identifier for this authentication attempt
• customer_id: The unique identifier for the authenticated customer within the Synctera platform
• status: The status of the authentication attempt. This can be either GRANTED, DENIED or ERROR

You can find the full documentation of this endpoint here.

The Synctera platform's response body will include a redirect_uri property. Your authentication endpoint must
then return a 302 Found response with this URI to the initial authentication request.
This will redirect the customer's app (browser or mobile) so it can continue the account linking flow with Plaid.

Authentication Failures and Error Handling

If a customer fails to authenticate, you must call /v1/fdx_auth_requests/authorize with a status of DENIED.
Similarly, if you encounter any errors, use a status of ERROR.
These will both provide you a redirect_uri for you to redirect the customer to the Plaid failure page, terminating the
auth flow.

In some error scenarios, the /v1/fdx_auth_requests/authorize response will not include a redirect_uri.
In such cases, your authentication endpoint should return a generic error message page instead of the redirect response.

Authentication Flow Sequence Diagram

The following gives a more detailed view of the flow. In this example, the fintech registered f.com/authorize as
their endopoint.

In this flow, Customer represents the customer using the initiating Financial Institution's app (browser or mobile).

📘

Note!

The urls used in the above diagram (Plaid.com/auth.html) are for illustrative
purposes only. Your system should treat them as generic
variables that are supplied by the Synctera platform.

Example React Function for Granting Access

The following React code provides an example that:

1. handles the initial GET request
2. displays a login page
3. calls Synctera with GRANTED or DENIED
4. redirects back to Plaid

The actual authentication of the customer, full error handling, etc., must still be implemented.

import { useState } from 'react';

interface AuthRequestParams {
    status: 'GRANTED' | 'DENIED';
    customer_id?: string;
    auth_request_id: string | null;
}

const authorizeRequest = async (params: AuthRequestParams) => {
    const response = await fetch(
        'https://api.synctera.com/v1/fdx_auth_requests/authorize',
        {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(params),
        }
    );

    const result = await response.json();
    window.location.replace(result.redirect_uri);
};

const loginRequest = async (email: string, password: string) => {
    const response = await fetch('http://yourapi.com/auth', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email, password }),
    });

    const result = await response.json();
    return result;
};

export function Login() {
    const searchParams = new URLSearchParams(window.location.search);
    const authRequestId = searchParams.get('auth_request_id');

    const [email, setEmail] = useState('');
    const [password, setPassword] = useState('');

    const grantAndRedirect = (customerId: string) => {
        authorizeRequest({
            status: 'GRANTED',
            customer_id: customerId,
            auth_request_id: authRequestId,
        });
    };

    const failAndRedirect = () => {
        authorizeRequest({
            status: 'DENIED',
            auth_request_id: authRequestId,
        });
    };

    const logIn = async () => {
        const result = await loginRequest(email, password);
        if (result.message === 'success') {
            grantAndRedirect(result.customer_id);
        } else {
            failAndRedirect();
        }
    };

    return (
        <div>
            <div>
                <div>Login</div>
            </div>
            <br />
            <div>
                <input
                    value={email}
                    placeholder='Enter your email here'
                    onChange={(e) => setEmail(e.target.value)}
                />
            </div>
            <br />
            <div>
                <input
                    value={password}
                    placeholder='Enter your password here'
                    onChange={(e) => setPassword(e.target.value)}
                />
            </div>
            <br />
            <div>
                <input type='button' onClick={logIn} value={'Log in'} />
            </div>
        </div>
    );
}

Using our Sandbox Test endpoint

Our sandbox test endpoint, allows you to get a mocked version of the request that would be initiated from Plaid
outlined in the sequence diagram from earlier. This allows you to test your implementation entirely encapsulated within the Synctera platform.

How to use the sandbox test endpoint

pre-requisites:

• You have a customer in your system that you want to test with
• Synctera support has registered your authentication endpoint in our platform.

The expected test flow is outlined in the sequence diagram below, the noted differences from the normal flow are:

• The customer's browser is not automatically redirected to your authentication page, instead the sandbox test endpoint will return the redirect url in the GET response body.
  • You can then copy/paste this url into your browser to simulate the customer's browser being redirected to your authentication page, or build a simple UI to simulate this.
• the final redirect will be to our sandbox success page, rather than the Plaid success page.

Example curl request from first step:

curl \
  -X GET \
  $baseurl/v1/fdx_auth_requests/authorization_test \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' 

Example response

{
  "redirect_url": "https://example.com/login?auth_request_id=0d35e262-5c75-4a53-baf3-e5cb3685b6e8"
}

📘

Note!

The urls and identifiers used in the above diagram and example requests (example.com) are for illustrative
purposes only. Your system should treat them as generic
variables that are supplied by the Synctera platform.

Access Management

Customers do not need to re-link their account if they change their password on your system.

For a customer to revoke access, they can submit a privacy request form to Plaid, or use Plaid's Portal to directly manage their connections.