Connecting to shared accounts

This page is for the third party: an organisation that a Shuttle platform has given an OAuth client, to work with that platform’s merchants’ accounts. If you are the platform sharing its merchants, start with Account sharing.

You will have been given a client ID and a client secret, one pair for sandbox and one for live. Ask the merchant which environment they want to connect, and use that pair throughout.

Shuttle uses the OAuth 2.0 Authorization Code flow:

1. Send the merchant to Shuttle to grant access.
2. Shuttle sends them back to you with an authorisation code.
3. Exchange the code for an access token and a refresh token.
4. Call the API with the access token, and refresh it when it expires.

1. Send the merchant to Shuttle

Redirect the merchant to the authorisation endpoint:

https://merchant.shuttleglobal.com/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_url=https://yourapp.example/callback
  &state=RANDOM_VALUE

Parameter
response_type	Always code
client_id	Your client ID
redirect_url	Where to send the merchant afterwards
scope	Optional: space-separated scopes
state	A random value you check when the merchant comes back, to protect against cross-site request forgery; you can also use it to remember who started the flow

The merchant then:

1. Logs into the Merchant Portal, or creates a login
2. Chooses an organisation, if they have more than one
3. Chooses one of the accounts they have connected from the platform that gave you the client (accounts from other platforms aren’t offered)
4. Clicks Grant Access

2. Handle the redirect

Shuttle sends the merchant back to your redirect_url with a code:

https://yourapp.example/callback?code=AUTH_CODE&state=RANDOM_VALUE

Check that state matches what you sent.

Exchange the code within 15 minutes.

3. Exchange the code for tokens

POST https://merchant.shuttleglobal.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://yourapp.example/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

redirect_uri must be the same URL you sent as redirect_url in step 1. You can send the client ID and secret as HTTP Basic credentials (Authorization: Basic base64(client_id:client_secret)) instead of in the body. Use one or the other, not both.

{
  "token_type": "Bearer",
  "access_token": "at_1234_h480djs93hd8",
  "refresh_token": "rt_1234_8xLOxBtZp8",
  "expires_in": 3600
}

Store both tokens against the merchant’s account in your system, encrypted. Each pair works for that one account only.

4. Refresh the access token

Access tokens expire after an hour (expires_in, in seconds). Get a new one with the refresh token:

POST https://merchant.shuttleglobal.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=rt_1234_8xLOxBtZp8
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

The response has a new access_token and the same refresh_token. If refreshing fails, it usually means the merchant’s access has been removed (see Removing access): ask them to connect again.

The endpoints are in the API reference: Authorize, Get a token, Revoke a token, Introspect a token and Who am I.