Switchfly-PrimaryLogo-Reversed-WEB
Switchfly Loyalty API
API docs by Redocly

Switchfly Loyalty API (v2.5)

Download OpenAPI specification:Download

Switchfly uses OAuth 2 for the SSO authentication required to communicate with any 3rd party API in order to perform loyalty account actions. The grant types supported are:

  • client_credentials
  • authorization_code (with PKCE)

This flexibility allows clients to seamlessly integrate with our platform. For instance, some clients may already possess a form of Single Sign-On (SSO) "token" utilized internally for various actions concerning loyalty users, such as fetching profiles, redeeming rewards.

In such scenarios, adopting the client_credentials grant type flow could be a more logical choice for initiating Single Sign-On (SSO). This approach enables third parties to consolidate authorization by leveraging parameters such as client_id and client_secret to acquire an access token. This token operating as a Bearer token, can then be utilized alongside the internal "token" within any requests.

For this flow it will be required for the client to pass that token as a UserToken param into Switchfly's SSO endpoint.

If there is no such thing as a user token in the client internal SSO implementation authorization_code grant type will be the other option for the SSO integration.

After any of the OAuth2 flows is completed Switchfly will gain access to any the following credentials:

  • access_token
  • refresh_token (only required on Authorization Code grant)
  • UserToken (only required on Client Credentials Code grant, sent by 3rd party client in SSO request)

Once this SSO step is completed Switchfly will be able to communicate with a client hosted API capable providing traveler profile information and redeeming points.

Initiate SSO against Switchfly

In this section, we will outline the SSO shopping flow for each supported grant type, detailing the endpoints in place. Additionally, we will specify the circumstances under which each API call mentioned in this documentation will be utilized.

Authorization Code SSO

When a third party opts to integrate with Switchfly using the authorization code, our application must initially generate the code_challenge data to commence the OAuth2 flow. Consequently, it becomes necessary for the third party to initiate navigation to the Switchfly site.

This implies that within the third-party website, a redirect mechanism must be implemented. This implementation will initially transition the user to the Switchfly site at https://[domain].switchfly.com/.

After this Switchfly will detect that there is no loyalty session established yet and will generate a code_challenge and redirect the user to the specified client provided /authorize endpoint specifying the redirect_uri.

This redirect_uri will be the endpoint capable of receiving the authorization code, that's https://[domain].switchfly.com/apps/api/sso/oauth2

Following the user's login on the client login form, upon successful authentication, the third-party system is anticipated to send back the authorization code to the aforementioned redirect_uri.

Once Switchfly receives the authorization code it will be used to obtain access_token & refresh_token.

After being able to fetch the tokens Switchfly will perform a request to the provided /traveler-profile using the access_token as a Authorization Bearer token, which will provide back a TravelerProfile response back to our system which then will be parsed to SSO the customer into our system.

Switchfly will present the customer a search form from which the customer can proceed to look for any desired products.

During the checkout products process Switchfly will perform a request to the provided /redeem endpoint to send the 3rd party system the details about the points redemption performed by the customer and the products being purchased.

During the shopping flow on long sessions there will be some keep alive requests (grant_type=refresh_token) used to obtain new tokens to allow the user to book once they are ready.

Flow Steps

  • Navigate to the Switchfly site.
  • Redirect to the client's /authorize endpoint.
  • Log in with customer credentials.
  • Send the code to Switchfly's /apps/api/sso/oauth2.
  • Request a token from the client's /token endpoint.
  • Request a profile from the client's /traveler-profile endpoint.
  • During checkout, send a request to the client's /redeem endpoint.
  • Conditionally, refresh token requests to /token.

Client Credentials SSO

When a 3rd party chooses to integrate with Switchfly using client credentials the 3rd party is only required to perform a request to Switchfly OAuth2 endpoint providing the "token" as a parameter "userToken".

https://[domain].switchfly.com/apps/api/sso/oauth2 post parameter "userToken"=[internal_token]

Once Switchfly receives this token from the 3rd party it will obtain an access_token using the provided client_id & client_secret.

After being table to retrieve a token Switchfly will perform a request to the provided /traveler-profile endpoint sending the following headers:

  • Authorization: Bearer [access_token]
  • UserToken: [userToken send over to /oauth2 endpoint]

This should provide back a TravelerProfile response back to our system which then will be parsed to SSO the customer into our system.

Switchfly will present the customer a search form from which the customer can proceed to look for any desired products.

During the checkout products process Switchfly will perform a request to the provided /redeem endpoint to send the 3rd party system the details about the booking such as points used and products included.

Flow Steps:

  • The client submits the userToken to Switchfly's /apps/api/sso/oauth2.
  • A token is requested from the client's /token endpoint.
  • A profile is requested from the client's /traveler-profile endpoint.
  • During checkout, a request is sent to the client's /redeem endpoint.

OAuth 2 - SSO Authorize

Switchfly OAuth 2 SSO request to 3rd party

Endpoint for authentication

This is the token endpoint that will be used either to retrieve a token exchanging the authorization code when grant=authorization_code is used for the SSO.

Or retrieving a token using only the client_id and client_secret credentials provided by the 3rd party to Switchfly.

Authorization Code

When using the grant=authorization_code this endpoint need to return a response with both an access_token and refresh_token.

The refresh_token will be used to perform keep alive request using a grant=refresh_token to this same endpoint to retrieve a new set of tokens.

User
User
Switchfly
Switchfly
3rd party
Authorization service
3rd party...
3rd party
Redemption API
3rd party...
Login request
Login request
Login URL construct:
  • client_id
  • state
  • code_challenge
  • redirect_uri:Switchfly OAuth endpoint
 
Login URL const...
Authorization endpoint redirect
Authorization endpoint redirect
Login form Authentication
Login form...
Authorization Code
Authorization Code
Authorization Code Grant RQ
  • client_id + code
  • code_verifier
Authorization Code Grant RQ...
Validate
Code verifier
Challenge
Validate...
Authorization Code RS
  • id_token
  • access_token
  • refresh_token
Authorization Code RS...
Traveler Profile RQ + access_token
Traveler Profile RQ + access_token
Traveler Profile RS
Traveler Profile RS
Redemption RQ + access_token
Redemption RQ + access_token
Redemption Confirmation RS
Redemption Confirmation RS
Checkout Redeem Product
Checkout Redeem Product
Keep Alive - Refresh token grant
Keep Alive - Refresh token grant
Keep alive RS - Update Access token
Keep alive RS - Update Access token
Refresh 
Token 
Refresh...
1
1
2
2
3
3
4
4
5
5
Authentication
Authentication
6
6
7
7
8
8
9
9
10
10
11
11
12
12
13
13
14
14
15
15Text is not SVG - cannot display

Client Credentials

When using the grant=client_credentials this endpoint is only expected to return an access_token.

There will be no keep alive requests in this flow since the UserToken attribute cannot be refreshed and will require a new login from the customer to generate a new one. (consider giving the UserToken a larger expiration time so users can complete a booking in Switcfly platform without the need to re-login)

User
User
Switchfly
Switchfly
3rd party
Authorization service
3rd party...
3rd party
Redemption API
3rd party...
Redirect user to client login url.
 
Redirect user t...
Redirect to SWF SSO endpoint
 + userToken query param
Redirect to SWF SSO endpoint...
Client Credentials Grant RQ
  • client_id
  • client_secret
Client Credentials Grant RQ...
Client Credentials RS
  • access_token
Client Credentials RS...
Traveler Profile RQ + access_token
+ UserToken header property
Traveler Profile RQ + access_token...
Traveler Profile RS
Traveler Profile RS
Redemption RQ + access_token
+ UserToken header property
Redemption RQ + access_token...
Redemption Confirmation RS
Redemption Confirmation RS
Checkout Redeem Product
Checkout Redeem Product
1
1
2
2
Authentication with user
 credentials on client site
Authentication with user...
4
4
5
5
6
6
7
7
8
8
9
9
10
10
Create session
user specific
 "userToken"
 with expiration time
Create session...
3
3Text is not SVG - cannot display

This are the grants that should be supported by this endpoint:

  • authorization_code
    • refresh_token
  • client_credentials
Request Body schema: application/x-www-form-urlencoded
required

Token request body

One of
grant_type
required
string
Value: "authorization_code"

The type of grant being used in the request

client_id
required
string
code
required
string
code_verifier
required
string
scope
required
string
Value: "profile redeem"
redirect_uri
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "access_token": "string",
  • "token_type": "string",
  • "refresh_token": "string",
  • "expires_in": 0
}

Shopping Flow

Information about requests performed by Switchfly system to 3rd party service to fetch Loyalty profile data and redeem points from the customer account.

Retrieve Traveler Profile information

Request performed to 3rd party endpoint to fetch Traveler Profile information such as travelerProfileId, firstName, balancePoints, customerCurrency

  • Supported Currencies:

    • USD
    • AED
    • AUD
    • BBD
    • BRL
    • BSD
    • CAD
    • COP
    • CRC
    • DOP
    • EUR
    • GBP
    • GTQ
    • HNL
    • IDR
    • ILS
    • INR
    • JMD
    • JOD
    • JPY
    • MXN
    • MYR
    • NOK
    • NZD
    • PAB
    • PEN
    • PHP
    • PLN
    • SGD
    • THB
    • TTD
    • UYU
    • VND
    • XCD
    • ZAR

  • Supported Languages:

    • English
    • French
    • Spanish
    • LA Spanish
    • Chinese
    • Japanese
    • BR Portuguese
    • Thai
    • German
Authorizations:
bearerAuth
header Parameters
UserToken
string

Unique string token used to identify user session in case client_credential grant was used for OAuth 2 SSO.

Responses

Response samples

Content type
application/json
{
  • "travelerProfileId": "uniqueTravelerId",
  • "balancePoints": 150000,
  • "title": "Mr",
  • "firstName": "firstName",
  • "lastName": "lastName",
  • "email": "test@switchfly.com",
  • "phone": "7204909090",
  • "customerCurrency": "USD",
  • "langId": 1,
  • "companyCode": "goldtravel",
  • "address": {
    }
}

Redeem points from Traveler Points account

This API will allow Switchfly the capability of redeeming points from a customer loyalty profile account.

Switchfly will send a request to this API endpoint using a JSON payload which will describe the products the customer (booking components) is redeeming points on.

This will include the points and cash used for each component and will also include information whether or not a credit card payment top up was needed to complete the booking.

The only requirement for this endpoint is to return Switchfly a unique transaction id that represents the redemption transaction for this customer redemptionConfirmationId

This is important since this redemptionConfirmationId will be used by Switchfly if a points refund request is needed later to cancel a booking or individual components of it.

Authorizations:
bearerAuth
header Parameters
UserToken
string

Unique string token used to identify user session in case client_credential grant was used for SSO.

Request Body schema: application/json
required
bookingId
required
string

Switchfly unique identifier per type

createdDate
required
string <yyyy-MM-dd'T'HH:mm:ssX>

Date when the booking reservation was created

travelerProfileId
required
string

Unique Identifier for User Profile

points
required
string

Available points for User Profile. It is acceptable for this field to be 0 if the transaction was fully paid in cash

customerCurrency
required
string

Currency used for the cash display in the customer shopping flow

lang
required
number
Enum: 1 2 3 4 5 6 7 8 9

Number value which shares the language used in this booking, related to langId send on Profile Response or matches the default language configured on the system:

 1 - english
 2 - french
 3 - spanish
 4 - LA_Spanish
 5 - Chinese
 6 - Japanese
 7 - BR_portuguese
 8 - Thai
 9 - German
firstName
required
string

First name of the Lead traveler

lastName
required
string

Last name of the Lead traveler

country
required
string <ISO 3166 Alpha 2>

Two digits country code

email
required
string

Last name of the Lead traveler

phone
required
string

phone of the Lead traveler

mobilePhone
string

Sent only if present (Optional)

addressLine1
required
string

addressLine1 of the Lead traveler

addressLine2
string

Sent only if customer added extra address line

city
required
string

Traveler profile city

state
string

State Name

postalCode
required
string

Postal Code

required
object

Responses

Request samples

Content type
application/json
Example
{
  • "bookingId": "1234567",
  • "createdDate": "2023-07-0718:54:00Z",
  • "travelerProfileId": "uniqueId1234",
  • "points": 48300,
  • "customerCurrency": "USD",
  • "lang": 1,
  • "firstName": "Checkout",
  • "lastName": "Customer",
  • "country": "US",
  • "email": "checkout@test.com",
  • "phone": "3033121212",
  • "mobilePhone": "7204909090",
  • "addressLine1": "Test address Line",
  • "addressLine2": "More address details",
  • "city": "Denver",
  • "state": "Colorado",
  • "postalCode": "80249",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "redemptionConfirmationId": "string"
}

Machine to Machine (OAuth2 & Refund)

Describes authentication required (client_credentials OAuth 2) and refund requests performed by Switchfly application to 3rd party service to cancel redemption components.

Authentication Switchfly App against 3rd party API

This endpoint will be used to perform a OAuth 2 - client credentials token request.

The path in this endpoint can be the same as the /token path the only requirement is that a different set of client_id and client_secret credentials are shared by the 3rd party to Switchfly as this token request will be triggered to perform a machine to machine authentication which will then allow Switchfly to perform API requests to a secured /refund endpoint.

The generated token will be used by the /refund endpoint as a Bearer token.

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Value: "client_credentials"
client_id
required
string

The client ID associated with the client application.

client_secret
required
string

The client secret associated with the client application.

scope
required
string
Value: "refund"

Scope used to request token for /refund endpoint API requests.

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0
}

Cancel booking or individual components of a booking

This API will be used by Switchfly to perform points refund actions to a redemption booking from a loyalty customer.

Switchfly will include the redemptionConfirmationId in the body of the request, this will help the 3rd party API to identify which redemption booking is being refunded, it will also include the amount of points and cash refunded (susceptible to)

Refund could be of types BOOKING and COMPONENT which will describe if all the booking is being cancelled or if only an individual component will be cancelled.

Authorizations:
adminBearerAuth
Request Body schema: application/json
required
bookingId
required
string

Switchfly unique identifier

travelerProfileId
required
string

Unique Identifier for User Profile

redemptionConfirmationId
required
string

Confirmation Id/Code of the redemption to refund

pointsToRefund
required
string

Total points to refund after penalties

cancellationFeesInPoints
required
string

Cancellation penalty in points

cashToRefund
required
number

Cash to refund (matches customerCurrency)

currency
required
string

Currency in which the CC was charged for the amount (matches customerCurrency)

refundType
required
string
Enum: "BOOKING" "COMPONENT"

Supported refund types

object

Only sent when refundType is COMPONENT

Responses

Request samples

Content type
application/json
Example
{
  • "bookingId": 1234567,
  • "travelerProfileId": "uniqueId1234",
  • "redemptionConfirmationId": "123456",
  • "pointsToRefund": 68450,
  • "cancellationFeesInPoints": 0,
  • "cashToRefund": 100,
  • "currency": "USD",
  • "refundType": "BOOKING"
}