Frontend Integration

This section will help you integrate Stitch SafeLink into your application, site or platform. As there are a number of platforms and frameworks, we will first cover some general principles before delving into specifics. It is recommended that you complete the user token retrieval flow before you continue.

Broadly speaking, your integration will differ depending on whether your product is browser-based or a mobile application. However, both will require some form of backend (e.g. a webserver or cloud function) and database that can use the authorization code to retrieve and store the token.

Integrating a Web Application

The general flow for integrating a web application is as follows:

• Create a page that can be used to process the result of the authorization request, and register the URI with Stitch. The URI should ideally be distinct from the main pages as this reduces the danger of users getting stuck in a log-in loop.
• In your application, create some form of button or link that redirects the user to the /connect/authorize end point (using the appropriate query parameters as described in the user token retrieval flow).
• After the user has completed the authorization process, they'll be redirected back to your application, specifically to the redirect_uri supplied in the request. The query string will contain the authorization code needed to retrieve the actual token.
• POST the authorization code to your backend and use the backend to retrieve the access (and optionally refresh) tokens.
• Store the tokens in an appropriately secured database and use it to query the Stitch API.

note

Cookies must be enabled. We also recommend that browser local storage is enabled for the best user experience.

Library	Description	Platform/Language
salte-auth/salte-auth	💻🗝 OAuth 2.0 for the masses!	JavaScript
andreassolberg/jso	Easy to use OAuth 2.0 javascript library for use in your javascript application	JavaScript
zalando-stups/oauth2-client-js	A library to help you handle OAuth2 access and refresh tokens	JavaScript

Integrating a Web Application using an <IFRAME>

The general flow for integrating a web application with an <iframe> is as follows:

• Create a page used to process your applications business logic (i.e. digital wallet or cart etc), on submission to the backend, create a Payment Initiation Request, this will return an id and url.
• Return or redirect to the url in a <IFRAME>, remember to include your redirect_uri.
• During the payment process the following messages are sent to the browser window, PaymentCompletedEvent and PaymentQuitEvent. These messages may be used to inform the user flow in your application within the browser. See Handling Client-Side Messages
• After the user has completed the payment process, they'll be redirected back to your application, specifically to the redirect_uri supplied in the request. The query string will contain the id, status and optionally an externalReference if you supplied one. See Integration Process for more information.

Example of a PaymentInitiationRequest Response

{
  "id": "cGF5cmVxL2JlMTNhMzE1LTBjZDUtNGY5Mi04NDk4LTU4YmU0M2Y3YjAyNg==",
  "url": "https://secure.stitch.money/connect/payment-request/be13a315-0cd5-4f92-8498-58be43f7b026"
}

Rendering an <IFRAME>

Using HTML

<iframe
  name="paymentGatewayFrame"
  src="https://secure.stitch.money/connect/payment-request/0957174c-a600-4f7a-ac81-21a696338b0c?redirect_uri=https%3A%2F%2Fexample.com%2Fpayment"
  width="100"
  height="100"
>
</iframe>

Using React

Using react, where paymentRequestUrl and redirectUri are custom props on the component.

<iframe
  src={props.paymentRequestUrl + "?redirect_uri=" + props.redirectUri}
  width={100}
  height={100}
></iframe>

Handling Client-Side Messages

During the payment process the following messages are sent to the browser window, PaymentCompletedEvent and PaymentQuitEvent. These messages may be used to inform the user flow in your application within the browser.

Using HTML and JavaScript

Make sure to only add the Event Listener only once.

const handleMessage = (event: { origin: string, data: { type: any } }) => {
  if (event.origin !== "https://secure.stitch.money") return;

  switch (event.data.type) {
    case "PaymentCompletedEvent":
      console.log("User completed the payment process", event.data.type);
      break;
    case "PaymentQuitEvent":
      console.log("User exited the payment process", event.data.type);
      break;
  }
};

window.addEventListener("message", handleMessage, false);

Using React

useEffect(() => {
  const handleMessage = (event: { origin: string, data: { type: any } }) => {
    if (event.origin !== "https://secure.stitch.money") return;

    switch (event.data.type) {
      case "PaymentCompletedEvent":
        console.log("User completed the payment process", event.data.type);
        break;
      case "PaymentQuitEvent":
        console.log("User exited the payment process", event.data.type);
        break;
    }
  };

  window.addEventListener("message", handleMessage, false); // add event handler

  return () => {
    window.removeEventListener("message", handleMessage); // remove event handler
  };
}, []);

danger

The message field should not be used for any database operations. To secure yourself from attackers who can send a fake payload to your redirect or webhook endpoint, we recommend:

1. using the webhooks as the source of truth as they are secure and will always be sent from Stitch.
2. making use of signed webhooks since you'll be able to verify the signature of each incoming webhook's request payload.

Using the webhooks also ensures you'll still be able to know the final status of a payment request if for example the request times out due to a network issue.

note

Cookies must be enabled. We also recommend that browser local storage is enabled for the best user experience.

Ensure the <iframe> is sized appropriately for your application and the Stitch UI.

The redirection which takes place, does not replace the need to implement Webhooks.

Optional Configuration

If required you may request Stitch set the following attributes on the configuration of your client.

Name	Type	Description
RemovePadding	Boolean	Removes the padding within the iframe, this is useful if you are placing the page or frame within a specific UI/UX design.
HideQuitButton	Boolean	Removes the quit button from the iframe, this is useful if you already have a quit or close button within your UI/UX design.

Integrating a Mobile Application

The general flow for integrating a mobile application is as follows:

• Create a post authorization deep link to your application, and register this URI with Stitch.
• In your application, create some form of button, link, or action that opens a new tab in the user's mobile browser, redirecting them to the /connect/authorize endpoint (using the appropriate query parameters as described in the user token retrieval flow). Note that you'll also need to use the deeplink you created as the redirect_uri.
• After the user has completed the authorization process, they'll be redirected back to your application, specifically to the redirect_uri supplied in the request. The query string will contain the authorization code needed to retrieve the actual token.
• Retrieve the access token (and optionally refresh token) using the /connect/token endpoint.
• Store the tokens in an appropriately secured database and use it to query the Stitch API.

note

Cookies must be enabled when integrating with a WebView. We also recommend that WebView local storage is enabled for the best user experience.

Best Practises for Native Mobile Applications

RFC 8252 - OAuth 2.0 for Native Apps goes into more details about best practises when implementing OAuth 2 in native applications. It is a useful read in that it contains operating system specific advice for improving the SSO user experience without sacrificing security.

Library	Description	Platform/Language
openid/AppAuth-Android	Android client SDK for communicating with OAuth 2.0 and OpenID Connect providers	Android
openid/AppAuth-iOS	iOS and macOS SDK for communicating with OAuth 2.0 and OpenID Connect providers	iOS and MacOS
FormidableLabs/react-native-app-auth	React native bridge for AppAuth - an SDK for communicating with OAuth2 providers	React Native
xamarin/Xamarin.Auth	Xamarin.Auth helps developers authenticate users via standard authentication mechanisms (e.g. OAuth 1.0 and 2.0), and store user credentials. It's also straightforward to add support for non-standard authentication schemes	Xamarin (C#)