SSO (Single Sign-On) Integration Method
This resource is intended for a 3rd Party Integration/Partner who desires to be “Out of Scope” in regards to PCI compliance by allowing the partner to send customers to our API to handle all transactions.
This page describes how to pass new/existing contact data into the API.
Listed below is an overview of the process: A user of the partner will click a link from the partner system that will have an encrypted or hexed data string that can be sued in either a GET or POST request using the variables defined below. The request will contain a JSON message with data required as defined in this document. When a transaction has run, the API will in real time will POST transactions back to the Partner system. These POST calls will contain the data as defined in this document. Please send the URL you would like the POSTBACK to be sent to our developer support team so they can configure it.
Link Generation
The data being sent in the request can be sent in two ways:
- Encrypted
- Hexed
The data can be encrypted to prevent users from altering the data that is intended to be transmitted. This section will outline the method and encryption process to generate the link for the Partner’s users to click. It will also show how to simply hex the data if the full encryption method is not needed based on your security requirements.
The GET or POST request should be sent to the necessary URL, and the API will respond with a 302 request to redirect the user to the User Interface, and they will already be logged in.
Sending the Request
If Using GET:
The GET request sent to the API should look like one of the two following methods:
1) Encryption method sent with the “e_data” parameter
https://{domain}/custom/contactsso?developer-id=xxxxxxx&e_data=BD68908FB617CD45130B…
Note: The encoded string will be a LOT longer.
2) Hex method sent with the “data” parameter
https://{domain}/custom/contactsso?developer-id=xxxxxxx&data=A62B12C31FD34F…
Note: The hex string will be a LOT longer.
If Using POST:
The POST variables sent should be:
- developer-id
- data or e_data if using encryption
You will need to request an encryption key in order to utilize the encryption method. Using the hex method does not require a shared encryption key.
Standard SSO
Required data parameters
Fields | Type/Format | Length/Limit | Comments |
---|---|---|---|
contact_api_id | Varchar | 64 | This Field should contain your key for this record. There is a unique key on location_id and contact_api_id to prevent duplicates |
timestamp | timestamp | Timestamp when the link was created, Links expire after 15 minutes of being generated for security | |
first_name | varchar | 64 | First Name |
last_name | varchar | 64 | Last Name |
location_id | uuid | 36 | This is a unique id for each location (account) setup under a user. Users can have many locations |
user_id | uuid | 36 | API generated id that belongs to the user |
user_api_key | uuid | 36 | API generated “password” that belongs to the user_id |
Sample JSON
This sample JSON is for the standard “contactsso” endpoint and should include contact information so that when the contact is created, the user will be redirected to the UI and be placed on the contacts dashboard.
Transaction SSO
Optional data parameters
Fields | Type/Format | Length/Limit | Comments |
---|---|---|---|
account_number | Varchar | 32 | Account number for contact |
address | varchar | 64 | |
cell_phone | integer | 10 | Numbers only |
city | varchar | 64 | |
company_name | varchar | 64 | Company Name |
varchar | 64 | contact's email address | |
home_phone | integer | 10 | Numbers only |
office_ext_phone | varchar | 10 | Extension for office phone |
office_phone | integer | 10 | Numbers Only |
state | alpha | 2 | 2 character state identifier |
zip | varchar | 5-10 | nnnnn or nnnnn-nnnn or nnnnnnnnn (api doesn't enforce) |
Sample JSON
This sample JSON is for sending optional transaction data when using the “contactsso” endpoint. If optional transaction data is sent, then the contact will be created/updated and then the user will be redirected to the charge page with the description and amount fields already pre-filled.
Virtual Terminal SSO
Another option that is available is to be redirected to the Virtual Terminal page instead of contact page. In order to do this, there is a separate set of parameters that need to be submitted. The following table shows the parameters that are required in order to be redirected to the Virtual Terminal page from the contactsso endpoint.
If this is the desired method of input and you would like to be redirected to the virtual terminal instead of the contact page, then the values in the below table need to be submitted instead of the values in the above tables.
Data parameters
Fields | Type/Format | Length/Limit | Comments |
---|---|---|---|
location_id | varchar | 36 | A valid location_id that the transaction should be associated with. |
params | JSON | A JSON array containing any parameters that need to be set on the transaction. See below for fields that can be set. | |
route_name | Varchar | 32 | This value should be sent as “virtualterminal” if you want to be redirected to the virtualterminal UI page. It can however be any other valid route value like "contacts", "transactions", "dashboard", "accounts" |
route_id | VarChar | 32 | Optional. This is an optional value to go with the route_name. This value is only needed if the route contains an id for something like a specific contact or account vault. |
timestamp | integer timestamp | 10 | Timestamp when the link was created, Links expire after 15 minutes of being generated for security |
user_id | varchar | 36 | The user id of the user running the transaction. |
user-api-key | integer | 10 | The user api-key of the user running the transaction. |
Many fields that can be set on a transaction in the virtual terminal can be set using the above method. Here are the fields that can be set using the contactsso parameters field.
- account_holder_name
- advance_deposit
- billing_city
- billing_phone
- billing_state
- billing_street
- billing_zip
- checkin_date
- checkout_date
- clerk_number
- description
- no_show
- order_num
- product_transaction_id
- room_number
- room_rate
- subtotal_amount
- tags
- tax
- tip_amount
- transaction_amount
Sample JSON
Here is what the sample JSON data might look like before it is converted into HEX data:
Here is how the above JSON would be submitted in a GET request:
Sample Code for Hex Process
Encryption/Decryption Sample Code
Post Message
When SSO is used to open the UI in an iFrame, the following endpoints will have a postMessage event available:
- v2/transactions and all transactions endpoints/actions (run/void/refund/increment/etc.)
- v2/contacts
- v2/recurrings
- v2/accountvaults
All POST, PUT, and DELETE calls on these endpoints will cause a postMessage event to be triggered.
For more information about how to capture the response from the iFrame submission, take a look at Using Post Message.