Skip to main content

Authentication

In order to issue calls to Exact APIs, requests must be authenticated. As mentioned in the introduction, this can be done by adding an Authorization header to your requests with the value of the token.

It is important to note that our API accepts two token types for authentication. These are user tokens and application tokens.

User Tokens​

User tokens are for use with frontend applications. Exact's embedded payments APIs provides user management capabilities and allows users to access the API via their credentials. A user's capabilities are determined by their role and permissions.

User tokens are best used for frontend authentication as they expire after 2 hours of inactivity. They should not be used for servers or application backends unless authenticating on a user's behalf. For long living API access, see application tokens below.

User tokens are created by issuing the following request:

{
  "method": "post",
  "url": "https://api.exactpaysandbox.com/token",
  "body": {
    "email": "[email protected]",
    "password": "A rather secure password",
    "application": "harrison-widgets-app"
  }
}

This request includes email and user password as well as the application name. This field can be omitted in requests from a browser as the platform will use the origin url to detect your application.

Application Tokens​

Application tokens are for use with your application. Rather than authenticating as a user, use Application tokens to authenticate as an application. This is the most common form of authentication as these tokens will not expire but do require you to specify which permissions you wish to use upfront when creating the Application token.

You have the flexibility to add additional permissions or change existing permissions, which will require you to create a new application token for the changed permissions set to take effect.

To request an application to be created for your platform, please email [email protected] and our team will work with you to get it created.

It is recommended that you securely store the application token within your system as it is the primary identity and authorization key for the interactions of your application with Exactpay’s platform.

Application tokens do not expire and can be used by your systems as long as needed, or until someone with the permission to do so deletes the token. You can also replace the existing application tokens as needed (for example the previous token is compromised or lost). When making a request for a new application token, you will also need to provide your application name. The application ID provided determines what application settings, such as email templates, and CORS origins to use for this session. Please note that, at this time Exactpay only supports a single application per partner.

Application tokens for partner integrations (partner context) as well as merchant integrations (merchant context) as a self-service are created by issuing the following API request(see example below). To learn more about this API request please refer to our API Documentation

{
  "method": "post",
  "url": "https://api.exactpaysandbox.com/application/{applicationId}/token",
  "headers": {
    "Authorization": "<<Please replace this tag with your User Token>>"
  },
  "body": {
    "label": "My API Token",
    "permissions": [
      "accounts.read",
      "users.read"
    ]
  }
}

The above request creates a new application token with the accounts.read permission. The new application token will be associated with the same organization or account as the request authorization token.

Application tokens can created by a partner for merchants by issuing the following request: (see example below). Notice the added account/{accountId} part of the path.

{
 "method": "post",
 "url": "https://api.exactpaysandbox.com/application/{applicationId}/account/{accountId}/token",
 "headers": {
   "Authorization": ""
 },
 "body": {
   "label": "My API Token",
   "permissions": [
      "charges.read",
      "users.read"
   ]
 }
}

The following is the response for the POST request above for application token that includes the new application token that reflects any new requested permissions within the limits of the predefined permissions model for the persona (Partner admin or Merchant admin). Please note that the response also includes an array of merchant account IDs (“allowedAccounts”) that are in scope under the partner’s portfolio.

{
  "id": "64e77510274513721c9d9e12",
  "label": "My API Token",
  "type": "application",
  "token": "4dc52aeb677b594086da17755c053a3b3534a34509e6b3f3473be6abdc2fc387b5c7a4bf5dd1037d",
  "allowedPermissions": [
    "charges.create",
    "users.read"
  ],
  "allowedAccounts": [
    "6413fed0292672a72edd846c",
    "641dd9af58ddd61ef03dac06",
    "64c9799218b29fe5a41c3584",
    "6407965f0001c3bfa0d6a8dd",
    "64e684b9ea1ee1159e213436",
    "6413fcc6955720a73cb51fa0",
    "6404147e554aeb33cc45c9ed",
    "6414062a955720a73cb5208c"
  ]

}

While the creating a new application token guarantees the return of a list of all allowed accounts under a partner’s portfolio, it is advisable for partners to consume the account.create webhook event that includes the account ID created. Here is a sample payload you get with a account.create webhook event. The account field in the response holds the unique identifier created for the newly Onboarded account.

{
  "_id": "64e7e3706902d6352ee923aa",
  "createdAt": "2023-08-24T23:10:40.663Z",
  "updatedAt": "2023-08-24T23:10:41.318Z",
  "type": "account.create",
  "requestId": "31ec820a-bf44-47cc-81de-42caa301d685",
  "url": "/organization/57f424bb7e534ff71f6e5626/account",
  "isAuthenticated": true,
  "isInternal": true,
  "currentTokenType": "system",
  "currentAccount": "67f424bb7e534ff71f6e5626",
  "targetAccount": "67f424bb7e534ff71f6e5626",
  "currentApplication": "",
  "skip": 0,
  "limit": 100,
  "succeededAt": "2023-08-24T23:10:41.296Z",
  "expiresAt": "2030-08-22T18:02:18.854Z",
  "account": "64e7e3702794d3e606d24c9b",
  "parentAccount": "67f424bb7e534ff71f6e5626",
  "finishedAt": "2023-08-24T23:10:41.296Z",
  "isStarted": false,
  "isEnded": true,
  "status": "success",
  "id": "64e7e3706902d6352ee923aa"
}

Handling the account.create is a recommended method of being current on all the merchant accounts that are continuously added to the partner’s portfolio. To receive this event as a webhook, you need to subscribe to this event.

{
 "method": "post",
 "url": "https://api.exactpaysandbox.com/organization/{organizationId}/webhook",
 "headers": {
   "Authorization": ""
 },
 "body": {
    "event": "account.create",
   "url": "https://webhook.site/e5559b23-15d7-445e-8cff-9e5b4e30f69d",
   "headers": [
       {
           "key": "x-test-custom",
           "value": "eporer"
       },
       {
           "key": "x-another",
           "value": "keyvalyue"
       }
   ]
 }
}

NOTE:

If the implementation for the webhook handling is not possible, it is advisable to periodically request a new application token which is a convenient mechanism for the partners to fetch all the accounts in their portfolio and cache them on their side for easy reference.

For additional information on our API Conventions