# Embedded Referral

## Introduction

Core Bank and Increase support financial technology developers by:

1. Allowing fintechs to refer customers to Core Bank;
2. If both the fintech’s customer and Core Bank consent, onboarding that customer as Core Bank depositor; and
3. Allowing the fintech developer to connect to the depositor’s Core Bank account.

The main technology used to power this product is [OAuth](https://en.wikipedia.org/wiki/OAuth).

## Sending the referral

Your users who choose to opt-in to banking products should be redirected to your unique URL. Your unique registration URL is available on [dashboard.increase.com](https://dashboard.increase.com/referral_program). There are 3 parameters to this URL:

- `client_id=<fixed>`. This is assigned by Increase.
- `state=<unique ID in your database>`. This should probably be a pointer to a “user id” in your application.
- `redirect_uri=<redirect URI for your application>`. This URI must be pre-registered on the [Dashboard](https://dashboard.increase.com/referral_program).

After the User completes the Core Bank onboarding, they’ll be redirected to your application through the provided `redirect_uri`.

When the User is redirected back to your site, they’ll have the URL query parameter `code`. Using the parameter `code` and your `client_secret`, you can request a long-lived Bearer Credential using [`POST /oauth/tokens`](https://increase.com/documentation/api/oauth-tokens#create-an-oauth-token).

## Working with a connected account

That Bearer Credential will provide read-write access to all of the Increase API endpoints. From there, you can create [Accounts](https://increase.com/documentation/api/accounts), [Transfers](https://increase.com/documentation/transactions-transfers#transactions-and-transfers) and [Cards](https://increase.com/documentation/api/cards).

Because each end-User has their own API key, one User is always silo’ed from the actions of another User.

As much as possible, the Increase API supports the standard OAuth 2.0 specification. Details about Increase’s flavor of OAuth are [documented](https://increase.com/documentation/oauth#building-an-oauth-application).

The OAuth program is fully compatible with the rest of the Increase API. Once you have the User’s API Key, you can use the [Software Development Kits](https://increase.com/documentation/software-development-kits) or create your own bindings to access the User’s data.

## Sandbox

All of the Increase features exist in the Sandbox, too. You can find your unique Sandbox URL in the [Dashboard](https://dashboard.increase.com/referral_program).

To test your implementation, you can simulate a User completing the referral onboarding flow. Using the [Sandbox API](https://increase.com/documentation/api/simulated-referral-oauth-codes#simulated-referral-oauth-code-object), you can receive a short-lived OAuth code as if a User had been redirected to your frontend. [Exchange](https://increase.com/documentation/api/oauth-tokens#create-an-oauth-token) that code to create a long-lived API token.

## Prepopulating data with the referral

If your customer has already provided some information in your application, you can prefill the data in the referral webform. The data should be passed as query parameters, just like `client_id` and `state`. These fields should be nested under `referral` as form-encoded key-value pairs.

As an example, you’d format your URL like this:

```plaintext
?client_id=<fixed>
  &referral[email_address]=hello@world.com
  &referral[address][line1]=1%20Main%20Street
  &referral[leadership][address][line1]=1%20Second%20Street
```

The following values can be configured via URL:

- Information about the business itself:

  - `email_address`
  - `name`
  - `incorporation_state`
  - `address`; with the child keys `line1`, `line2`, `city`, `state`, and `zip`.

- Information about the person in a leadership position. This data should be passed under the key `referral[leadership]`

  - `name`
  - `date_of_birth`
  - `address`; with the child keys `line1`, `line2`, `city`, `state`, and `zip`.