Authentication

Introduction

We use OAuth with Microsoft Azure AD and Microsoft Azure AD B2C to manage user accounts, applications and authentication.

There are two forms of authentication in our implementation, these are:

• User Authentication - When a merchant logs in against our tenant using their username and password they are provided with a token which they can use to make API calls associated with their account. This is the authentication method used on our Merchant + Developer portals.

• Application Authentication - A merchant account has an Client Id and Client Secret associated with it. Using these two pieces of information it is possible to make authentication token requests programmatically. The only user input required for this method of authentication is the initial collection of Client Id and Client Secret from the user. You can store this values in your software long-term so you can make authentication token requests without user input.

As a developer you have the option to use one or both methods for fetching authentication tokens to make API calls. Although we believe that Application Authentication will be most suitable for integrations as it requires the least amount of user input.

User Authentication

User authentication in our implementation is standard OAuth login against our Azure AD B2C tenant. You can see this in action on the developer and merchant portals. Microsoft's official documentation can be found here.

You have the option to implement user-flow login on your implementation for the purpose of getting authentication tokens. Your application will need to be setup to support login against Azure AD B2C and fetch the token from the response.

Application Authentication

The easiest way for an application to request a token is by using a library, however the OAuth process is well documented so will not be covered in detail in this document.

OAuth credentials which will be provided to you as part of the signup process are:

• Client Id:                           A unique value for your merchant integration

• Client Secret:                   A unique value for your merchant integration

• Scope:                              A unique scope which allows access to your merchant details with your client id and secret.

You will pass these credentials to the token URL :

Production: https://login.microsoftonline.com/0bdad8b5-fe48-4ccd-b807-e6b2662a6d0c/oauth2/v2.0/token
Sandbox: https://login.microsoftonline.com/cf77fc4a-626b-46ff-bd3a-3400a727352f/oauth2/v2.0/token

Environment scopes

The scope will vary per environment. The {{Tenant}} placeholder in the C# code example below should be replaced with:

• Sandbox: takepaymentsintegrated.onmicrosoft.com

• Production:                     takepaymentsintegratedprod.onmicrosoft.com

Requesting a token with the IdentityModel library (C#)

The IdentityModel library is a lightweight nuget package which extends the standard http client providing a simple mechanism for requesting tokens.

An example request for a token is below.

You will need to substitute your client id and client secret into the placeholders. The default {{Tenant}} name is takepaymentsintegrated.

An example set of OAuth credentials for a merchant to be issued with a JWT token to access the production environment is shown below.

Please note that this client id for illustration purposes only and cannot be used for integration. Your unique client id and secret will be provided to you during the sign up process.

• Client Id and secret issued to merchant:

  • Client Id: 788715f8-2eef-421e-8cf0-e9f89fc91dea

  • Client Secret: 393a9cb3-4c66-4938-9749-3e883ea998c2

• Environment scope (Production):

  • Tenant: takepaymentsintegratedprod.onmicrosoft.com

  • Tenant Id: 0bdad8b5-fe48-4ccd-b807-e6b2662a6d0c

  Note that these values vary based on environment - you will receive the correct details in your onboarding email.

• OAuth credentials used to be issued with a JWT token for use against the API:

  • Client Id: 788715f8-2eef-421e-8cf0-e9f89fc91dea

  • Client Secret: 393a9cb3-4c66-4938-9749-3e883ea998c2

  • Scope: https://takepaymentsintegratedprod.onmicrosoft.com/
    788715f8-2eef-421e-8cf0-e9f89fc91dea/.default

API URLs

Once you have been issued with a JWT token it should be passed as a HTTP header in the format 'Authorization: Bearer {{JWT token}}' to the API URLs below:

• Sandbox:            https://takepayments-integrated-sandbox-apim.azure-api.net/

• Production:                     https://takepayments-integrated-prod-apim.azure-api.net/

The code sample below uses C# to pass the bearer token during an API call. The placeholder {{API URL}} should be replaced with either the sandbox or production URL.