V4 Linking Flow

📘

This API is in BETA

Feedback is appreciated as we improve this flow. If there are any missing functionality that you're expecting reach out to our development team.

Live Demo

You can see a live demo of this at https://demo.slopepay.com/v4/link. To create a Slope user, you can use the tool at https://demo.slopepay.com/v4

Purpose

This new linking flow is designed for merchants where the user is already securely logged into your app and it is not expected to change their Slope account. This should reduce friction for customers as they would not be required to login to Slope anymore once their account has been linked to your app. The Slope customer may still revoke access to your app anytime from the Slope Buyer Portal.

Notes

Some important callout to be aware of:

• A linkToken may be revoked anytime by the user. Your app needs to graceful handle revokes and re-prompt them to re-link again.
• Your app must store a mapping based on userId and not only on customerId. For example, if you organization has 5 users, each user should independently link to Slope, each with their own linkToken. That way users are not sharing the same linkToken and our system can identify the end user performing each request.
• Once linked, you will still need to exchange the linkToken for an accessToken on the backend. This is the only foolproof way of ensuring the identity of userId and customerId
• accessToken are short-lived and expire within 4 hours. They should not be stored on your backend and instead generated on the fly when needed to open a Slope modal.
• There is currently no redirect flow option for the linking flow and can only be performed as an embedded iframe modal. If you'd like a redirect flow let us know and we can build that as needed!

How to use

1. Initiate the link flow by setting link as the flow param in Slope.js SDK. See Slope.js SDK API for details. If the user grants access, you will receive the linkToken response back from the onSuccess callback.

The publicKey is your public API Key that is found in your merchant dashboard's developer page

 window.SlopeJs.start({
   publicKey: 'YOUR_API_PUBLIC_KEY',
   flow: 'link',
   onSuccess: (resp) => {
     console.log('linkToken from Slope is:', resp.linkToken)
   },
   onFailure: (err) => {
   },
   onClose: () => {
   },
 })

2. Store the linkToken on your backend servers and you will need it indefinitely. The linkToken by itself is useless without your backend API secret to exchange for a short-lived accessToken
3. Exchange the linkToken for an accessToken by making a POST request to /v4/user-links/{linkToken}/access-token You can see https://developers.slopepay.com/reference/post_v4-user-links-linktoken-access-token for details. This will return data about the user including their userId and customerId in which both need to be stored properly.
4. Now, to bypass the login step for any future SlopeJs modal, simply add accessToken as a param like this:

 window.SlopeJs.start({
   code: '{{CHECKOUT_ORDER_CODE}}',
   accessToken: '{{ACCESS_TOKEN}}',
   onSuccess: (resp) => {
   },
   onFailure: (err) => {
   },
   onClose: () => {
   },
 })