Documentation

Getting StartedLinkIntroductionLink TokenJavascriptReact NativeAndroidiOSErrorsSitesAPI ReferenceWebhooksAPI Change ManagementChangelog

Link

Introduction

The Pinwheel Link opens up as a modal in your application. Through the modal, end-users can select their employer, authenticate with their payroll platform login credentials, and authorize the direct deposit change. The modal will take up the full screen for mobile SDKs and smaller web browsers.

To initialize Link, a short-lived link token will need to be generated first. Your server side code should generate the link token by sending a POST request to the /v1/link_tokens endpoint. DO NOT ever send this request from the client side and publicly expose your api_secret.

The link token returned is valid for 15 minutes, after which it expires and can no longer be used to initialize Link. The expiration time is returned as a unix timestamp.

Javascript

Installation

You have the option of adding the Pinwheel Link modal to your app using a script tag or, if you are using react, you can simply install our React package.

React

The React package can be found here.

npm install --save @pinwheel/react-modal

Then add it to your React app.

import PinwheelModal from '@pinwheel/react-modal'
const App = () => {
return <PinwheelModal
linkToken={token}
open={true}
onSuccess={console.log}
onEvent={console.log}
onExit={console.log}
/>
}

Script Tag

The Pinwheel Link modal is appended to the document body through an iframe that is loaded in the DOM via pinwheel-v1.js.

<!DOCTYPE html>
<html>
<head>
<script src="https://cdn.getpinwheel.com/pinwheel-v1.js"></script>
<script>
Pinwheel.open({ linkToken: "INSERT LINK TOKEN" });
</script>
</head>
<body></body>
</html>

Usage

Pinwheel Link is initialized and opened with a recently generated link token. Additionally, you can pass in callback functions that handle success, exit, and generic events.

Methods

Pinwheel.open()

This method opens the modal. It takes one parameter, params, of type InitializationParams.

type InitializationParams = {
linkToken: string;
onSuccess?: (result: { tokenId: string }) => void;
onExit?: (
error: { errorCode: string; errorMsg: string },
result: { tokenId: string }
) => void;
onEvent?: (
eventName: string,
params: {
modalSessionId?: string;
[key: string]: any;
}
) => void;
};

Initialization parameters

ParameterDescription
linkTokenThe link token retrieved using the create link token endpoint.
onSuccess (optional)Callback whenever a user completes a modal flow successfully. Note: This is simply a front end callback only. If a user begins a job, closes their browser tab or application, and the job completes successfully, this callback will not be called.
onExit (optional)Callback whenever a user exits the modal either explicitly or if an error occurred that crashed the modal. Error codes can be seen here.
onEvent (optional)The modal triggers events whenever a user interacts on a page (clicks or types) or whenever a user enters a new modal page. In order to audit these events, you can add an onEvent handler. The value of eventName is "Error" if the event is an error event.

See the summary for initialization arguments here.

Pinwheel.close()

This method closes the modal explicitly.

React Native

Installation

  1. Install react-native-webview as a peer dependency.
$ npm install --save react-native-webview
$ cd ios && pod install
  1. Install Pinwheel React Native SDK
$ npm install --save @pinwheel/react-native-pinwheel

You can find the package here.

Usage

The PinwheelLink component is a view that you can integrate into your app's flow like so:

import PinwheelLink from "react-native-pinwheel";
<PinwheelLink
linkToken={response.data.token}
onSuccess={onSuccess}
onExit={onExit}
onEvent={onEvent}
/>;

With the PinwheelLink component, end-users can select their employer, authenticate with their payroll platform login credentials, and authorize the direct deposit change. Throughout the authorization process, events will be emitted to the onEvent callback. Upon a successful authorization, the onSuccess callback will be called. The onExit callback will be called when it is time to close the dialog, and you should remove the PinwheelLink component from your view hierarchy.

The props used to initialize the component are listed here.

Android

You can find the source for the Android SDK here.

Installation

To get started, add the maven repository url to your project build.gradle file:

allprojects {
repositories {
...
maven {
url "https://underdog-technologies.bintray.com/pinwheel-android-sdk"
}
}
}

Then add the dependency in your build.gradle file:

implementation 'com.underdog_tech.pinwheel:pinwheel-android:1.0.1'

Make sure that the minimum Android SDK version, minSdkVersion, in your app is 22 or greater.

minSdkVersion 22

Usage

PinwheelFragment

The Pinwheel Android SDK provides the PinwheelFragment that takes linkToken as an argument. You can learn how to get the linkToken here. If linkToken is not present, an IllegalStateException error will be thrown.

PinwheelEventListener

To listen for the events coming from Link, implement PinwheelEventListener. Then simply provide the instance of the listener to PinwheelFragment by setting the pinwheelEventListener field.

val callbacks = object: PinwheelEventListener {
override fun onSuccess(successEvent: PinwheelSuccessEvent) {}
override fun onExit(exitEvent: PinwheelExitEvent) {}
override fun onEvent(actionEvent: PinwheelActionEvent) {}
}
val linkToken: String = getTheLinkTokenFunction()
val pinwheelFragment = PinwheelFragment.newInstance(linkToken)
pinwheelFragment.pinwheelEventListener = callbacks

You can find the type definitions here.

Errors

If there was an error before closing the PinwheelFragment, the onExit callback is called with an error object containing errorCode and errorMsg.

For more information on errors visit this page.

iOS

The Pinwheel iOS SDK's main interface is a UIViewController that you can integrate into your app as you would any UIViewController, e.g. presented as a modal, or used with a UINavigationController. Additionally, you can implement the PinwheelDelegate protocol to receive events throughout the PinwheelViewController's lifecycle.

Installation

The Pinwheel iOS SDK is available via CocoaPods.

To install the SDK with CocoaPods, add PinwheelSDK as one of your target dependencies in your Podfile:

use_frameworks!
target 'MyApp' do
pod 'PinwheelSDK'
end

Please be sure to run pod update and use pod install --repo-update to ensure you have the most recent version of the SDK installed.

Usage

To initialize the PinwheelViewController, a short-lived Link token will need to be generated first. Your mobile app should fetch the Link token from your server. DO NOT ever send this request from the client side, and publicly expose your api_secret.

PinwheelViewController

The PinwheelViewController is a UIViewController that you can integrate into your app's flow like so:

import PinwheelSDK
let pinwheelVC = PinwheelViewController(token: linkToken, delegate: self)
self.present(pinwheelVC!, animated: true)

With the PinwheelViewController, end-users can select their employer, authenticate with their payroll platform login credentials, and authorize the direct deposit change. Throughout the authorization process, events will be emitted to the onEvent callback. Upon a successful authorization, the onSuccess callback will be called. onExit will be called when it is time to close the dialog, and you should remove the PinwheelLink component from your view hierarchy.

PinwheelDelegate

onSuccess(_ event: PinwheelSuccessEvent)

Callback whenever a user completes a Link flow successfully. Note: This is simply a front end callback only. If a user begins a job, closes the app, and the job completes successfully this callback will not be called.

onExit(_ event: PinwheelExitEvent)

Callback whenever a user exits the modal either explicitly or if an error occurred that crashed the modal. Error codes can be seen here.

onEvent(_ event: PinwheelActionEvent)

Callback whenever a user interacts with the modal (e.g. clicks something or types something). The eventName can be used to gain insight into what the user is doing.

Errors

If there was an error before closing the PinwheelViewController, the onExit(_ event: PinwheelExitEvent) delegate method is called with a PinwheelExitEvent containing a PinwheelError.

For more information on errors visit this page.

Example

To run the example project, clone the repo, and run pod install from the Example directory first. Then, add your API secret to the top of the LinkToken.swift file. In your app, you should fetch the Link token from your server, and you should never include your API secret in your app.

Errors

If there was an error before closing the modal, Link's onExit callback is called with an error object containing errorCode and errorMsg. Link error codes (errorCode) are safe for developer use, whereas error messages (errorMsg) are liable to change.

If you want to react to an error at the moment the error occurs, you can use the onEvent callback with error name "Error".

Error codes and messages can be the following.

errorCodeerrorMsg
linkCrashThis is a generic error code that occurs if the front-end crashes. It will have the name, message, and stack of the error within it for debugging.
unhandledErrorUh oh! Something went wrong.