Get started
Welcome to Unified Services! This section explains how to get your clientId and clientSecret and how to generate your access token. Once you get access to these, you will be able to start processing requests.
clientId and clientSecret
Our standard integration uses the oAuth2.0 security protocol. This protocol allows you to authenticate your application towards the Unified API.
This protocol uses 2 parameters to authenticate you, namely a clientId and a clientSecret.
- The Client ID is a public identifier that identifies your application towards the Unified API. It is typically used in the initial authorization request towards the Unified API, so that it can know which application is making the request. The
clientIdis not a secret, and it can be safely included in client-side code or URLs. - The Client Secret, on the other hand, is a confidential string that is used to authenticate your application to the Unified API. It is used in the process of exchanging the authorization code for an access token. You should never share your
clientSecretwith anyone, as it is used to prove the identity of your application and could be used by someone else to impersonate your application.
Authentication process
Contact customer support
In order to get started with Unified Commerce services, please contact customer support. Through them, we will be able to provide you with a sign-on contract.
Please make sure to mention the channel you want to use. The clientId and the clientSecret are channel specific. You can use various channels, of course. But you'd need specific clientId and clientSecret for each channel you are going to use.
After the contract is signed, you will receive a welcome email with your channel-specific:
- clientId
- clientSecret
After you get the welcome email, you can create an access token that will allow you to use programming code to talk to the chosen channel using Unified Services.
To elaborate a bit more, an access token is a type of security token that is issued by an oAuth 2.0 provider when a user logs in to a website or app. The bearer token is essentially a unique identifier that represents the user's identity and grants them permission to access certain resources
Generate access token
In order to use programming code to communicate with our service, you must generate your access token using your clientId and clientSecret.
Unified Commerce services use an Identity Provider (IdP) to generate your personal access token.
In simple terms, an identity provider is like a trusted intermediary between a user and an application or service, verifying the user identity and enabling them to access different services without having to log in and out each time.
Generate access token
curl -k -d "grant_type=client_credentials" \ -H "Authorization: Basic Base64({your clientId}:{your clientSecret})" \ https://login.microsoftonline.com/2b8c81c1-69c3-4fcd-9de2-4579ced9d137/oauth2/v2.0/token
The response will contain your access token and it's expiration time. In the example below, the expiration time is 3599 seconds (almost an hour).
Generate access token response
{ "token_type": "Bearer", "expires_in": 3599, "ext_expires_in": 3599,
The access token is only valid for a certain time. After that, it expires and must be renewed.
Below are grant_type and scope details required to generate the access token for unified API.
Sandbox:
grant_type: client_credentials
scope: https://unifiedcommercesandbox.onmicrosoft.com/unifiedapi/paymentservice/.default
PRODUCTION:
grant_type: client_credentials
scope: https://unifiedcommerceprod.onmicrosoft.com/unifiedapi/paymentservice/.default
A grant type is a way for an application to obtain an access token that it can use to access our API.
Now that you have your access token, you should be able to send your first requests.