Link Token Flow

Technical overview of the desired 3rd-party integration installation process in Shift4 Marketplace

Reasoning

In order to increase the data cohesion between Shift4 Marketplace and the 3rd-party integration, a Link Token flow is being introduced as an improvement to its predecessor - Basic installation flow. By introducing several generic points of communication, the Link Token flow allow for better UX and faster system coordination by:

• Allowing the 3rd-party to create custom onboarding pages with Merchant and Location information.
• Passing over the process control over to the 3rd-party immediately after the installation has been initiated by Merchant.
• Providing an ability for the 3rd-party to confirm that the relevant Merchant account is successfully set up on the 3rd-party’s side.

Flow

The image below presents a simplified Link Token Flow sequence diagram.

The Link Token flow involves at least three system components:

• Shift4 Marketplace Frontend application - an entry point for the Merchant to discover and install integrations.
• Conecto API - the public API to extend the capabilities of a Merchant’s POS.
• 3rd-party system - a blackbox component representing the integration-oriented part of a 3rd-party system. Expected to include a User Interface to guide the Merchant and the capability to interact with Conecto API.

The “setup” part of the installation part is entirely according to the needs of a 3rd-party. Shift4 Marketplace does not have any specific recommendations or expectations on what the Merchant will need to be prompted to do, besides the authorization/registration.

The image below presents an example of the Merchant traverse through the Link Token flow.

Specification

When setting up the integration in Shift4 Marketplace, we ask the 3rd-party to provide an installation URL to redirect the Merchant to after the installation has been initiated. The 3rd-party server is expected to parse the query parameter “linkToken” from the invoked URL. For example, after clicking “Install” in Shift4 Marketplace, the Merchant would be redirected to “https://www.3rdparty.com/shift4?linkToken=uuidhashstring”. Please note that the “linkToken” expiration time is 15 minutes.

Methods

Retrieve the meta information of a specified link token

Provides the meta details of a specified link token

GET /marketplace/v2/links/{linkToken}

Response 200

Returns a link token meta info

{
  "user": {
    "email": "string"
  },
  "location": {
    "id": 0,
    "name": "string",
    "timeZone": "string",
    "merchantId": "string",
    "countryCode": "US",
    "currency": "USD",
    "language": "en",
    "brandRef": "string"
  },
  "salesRepContact": {
    "firstName": "string",
    "lastName": "string",
    "phone": "string",
    "phoneExt": "string",
    "email": "string"
  },
  "dealerContact": {
    "company": "string",
    "firstName": "string",
    "lastName": "string",
    "phone": "string",
    "phoneExt": "string",
    "email": "string"
  }
}

Finalize the app installation

Creates a location in the app's visibility scope as a final step of the installation/onboarding.

POST /marketplace/v2/locations

Request Body (required) Data that is necessary for finalizing the location installation

Content-Type: application/json

{
  "linkToken": "string"
}

Response 201

Installation finalized successfully

Definitions

• LinkToken
• UserMetaInfo
• LocationData
• LocationCreationPayload
• SalesRepContact
• DealerContact

LinkToken

UserMetaInfo

The user meta info

LocationData

Location data

LocationCreationPayload

SalesRepContact

Sales Rep contact information

DealerContact

Dealer contact information