To authenticate to our API, follow the OAuth 2.0 Client Credentials flow to obtain access tokens.

In order to authenticate you will need:

1. Client ID
2. Client Secret
3. Scope
4. Token Endpoint URL

These can be found in your welcome email or in the Merchant Portal, which you will also have access to after onboarding.

The easiest way for an application to request an authentication token is by using an existing library. However, the OAuth process is already well documented and will not be covered in detail in this guide.

As part of the signup process, you will be provided with the following OAuth credentials:

• Client Id – A unique identifier for your merchant integration.
• Client Secret – A confidential value associated with your merchant integration.
• Scope – A unique scope that allows access to your merchant details using your Client ID and Client Secret.

These credentials should be supplied when making a request to the token endpoint URL.

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

In the code blocks below you will use one of these values for the tenant. Here are the tenants for each environment:

• Production Tenanttakepaymentsintegratedprod.onmicrosoft.com
• Sandbox Tenanttakepaymentsintegrated.onmicrosoft.com

You will substitute your Client ID and Client Secret into the placeholders.

static async Task GetAccessToken()
{
    using HttpClient client = new HttpClient();
    var response = await client.RequestClientCredentialsTokenAsync(
        new ClientCredentialsTokenRequest()
        {
            Address = "https://login.microsoftonline.com/{{TenantId}}/oauth2/v2.0/token",
            ClientId = "{{ClientId}}",
            ClientSecret = "{{ClientSecret}}",
            Scope = "https://{{Tenant}}.onmicrosoft.com/{{ClientId}}/.default"
        });

    return response.AccessToken;
}

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

• Example ClientId – 78871518-2eef-421e-8cf0-e9f89fc91dea
• Example ClientSecret – 393a9cb3-4c66-4938-9749-3e883ea998c2
• Example Production Tenant – takepaymentsintegratedprod.onmicrosoft.com
• Example Production TenantId – 0bdad8b5-fe48-4ccd-b807-e6b2662a6d0c

The above example values would produce the below code sample

static async Task GetAccessToken()
{
    using HttpClient client = new HttpClient();
    var response = await client.RequestClientCredentialsTokenAsync(
        new ClientCredentialsTokenRequest()
        {
            Address = "https://login.microsoftonline.com/0bdad8b5-fe48-4ccd-b807-e6b2662a6d0c/oauth2/v2.0/token",
            ClientId = "78871518-2eef-421e-8cf0-e9f89fc91dea",
            ClientSecret = "393a9cb3-4c66-4938-9749-3e883ea998c2",
            Scope = "https://takepaymentsintegratedprod.onmicrosoft.com.onmicrosoft.com/78871518-2eef-421e-8cf0-e9f89fc91dea/.default"
        });

    return response.AccessToken;
}

Once you have successfully requested your JWT token, it should be passed as an HTTP header in the format 'Authorization: Bearer {JwtToken}' to the API URLs below:

• Production API URLhttps://takepayments-integrated-prod-apim.azure-api.net/
• Sandbox API URLhttps://takepayments-integrated-sandbox-apim.azure-api.net/

The code sample below passes the bearer token during an API call. The placeholder {ApiUrl} should be replaced with either the sandbox or production URL.

static async Task GetAccessToken()
{
    using HttpClient client = new HttpClient();
 
        client.BaseAddress = new Uri("{ApiUrl}");
 
        client.DefaultRequestHeaders.Add("Authorization", $"bearer {token}");
 
        var saleRequest = await client.PostAsync($"/Terminal/{tid}/Sale/{amount}", null);
}