Mobile Spreedly Tokenisation Component

Code Checks Release

A library that contains a React Native component that handles tokenisation of method payments with Spreedly.

Why

The main reason this library was created was to reduce the PCI compliance scope.

Solution

The solution we approached for this was the Spreedly Iframe Javascript API.

TLDR: In the form for collecting card information from the user Spreedly injects iframes in the cardNumber and CVV fields; and does this using the scripts they provide. For this we used a react-native-webview with an local html string as source.

Target

The main client of this library is UW's mobile client app, and should be used everywhere we collect card information from users and tokenise them as payment methods using Spreedly.

Scope

The library only takes care of tokenisation of the payment method; the rest of the payment flow will be handled by each team considering their use cases and particularities.

Installation

React Native

The component was tested in a React Native environment (UW's residential mobile app) and working as expected without additional development.

• yarn

yarn add @utilitywarehouse/mobile-spreedly-tokenisation-component

• npm

npm install @utilitywarehouse/mobile-spreedly-tokenisation-component

The package is private to the @utilitywarehouse npm org, so you need to be authenticated to npm to install it.

Peer dependencies

The library does not bundle React Native or the UW design system. Your app must provide the peer dependencies listed in package.json, including react-native-webview, react-native-unistyles and @utilitywarehouse/hearth-react-native.

Usage

With the props table below you can use and customise the component

| Prop Name | Optional/Mandatory | Type | Description | | ------------------------------------- | ------------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | spreedlyEnvironment | mandatory | 'Dev' / 'Prod' | Environment target in which we tokenise the payment method. Will fallback to 'Dev' if not provided or wrongly provided. | | onSpreedlyResponse | mandatory | (res) => void | Method that handles the Spreedly response when provided. The returned object from the component is an object with the following keys: token as string, saveCard as boolean and spreedlyResponse as object. | | onLoad | optional | () => void | Function that is invoked when the WebView has finished loading. | | backButtonLabel | optional | string | Label to be displayed in the secondary button, below the submit button; if not provided the second button will not be displayed, there is no "default" value for this label | | buttonLabel | optional | string | Label to be displayed in the submit button; defaults to "Continue" if prop not supplied | | colorScheme | optional | "dark" / "light" / "system" | Color scheme of the component, defaults to "light": will change the colors of the rendered components inside the webview. (Still needs dev work.) | | showSaveCardDetails | optional | boolean | If set to true the form will include a checkbox labeled Save card details and it's value will be returned in the "handleReturnSpreedlyResponse". | | showLoader | optional | boolean | If set to true a loading component will be rendered while the API calls are waiting for a response and until the webview has finished loading. | | webviewStyle | optional | StyleProp | StyleProp passed as style prop to the WebView; check WebView docs for more info. | | webviewContainerStyle | optional | StyleProp | StyleProp passed as containerStyle prop to the WebView; check WebView docs for more info. | | onSignatureError | optional | (e) => void | Error handler invoked when Spreedly returns the error message :"Missing or invalid required parameters for enhanced iframe security". | | onPaymentsApiError | optional | (e) => void | Error handler invoked when API call to back-end responsable for enhanced iframe security details fails. | | onBackButtonPress | optional | () => void | Function called when the secondary button is pressed |

Running

The library uses Storybook for local development.

Step 1: Start the Metro Server

First, you will need to start Metro, the JavaScript bundler that ships with React Native.

To start Metro, run the following command from the root of your React Native project:

# using the commands in the Makefile
make bundler

Step 2: Start your Application

Let Metro Bundler run in its own terminal. Open a new terminal from the root of your React Native project. Run the following command to start your Android or iOS app:

For Android

# using the commands in the Makefile
make android

For iOS

# using the commands in the Makefile
make ios

If everything is set up correctly, you should see your new app running in your Android Emulator or iOS Simulator shortly provided you have set up your emulator/simulator correctly.

This is one way to run your app — you can also run it directly from within Android Studio and Xcode respectively.

Releasing

Releases are automated with Changesets and published to npm from GitHub Actions using npm trusted publishing (no npm token is stored in the repo).

1. Run yarn changeset and commit the generated file with your change.
2. Merge to main. The Release workflow opens (or updates) a Version Packages PR.
3. Merge the Version Packages PR. The workflow publishes the new version to npm.