Are you looking for test card numbers?

Would you like to contact support?

Payout icon

API credentials for Balance Platform

Generate and configure credentials for API requests related to the Balance Platform

To make API requests, you must have an API credential. When your Balance Platform account is set up, it includes:

  • An API credential for web services. This credential has a username in the format ws[_123456]@BalancePlatform.[YourBalancePlatform], and is used with the following APIs:
    • Configuration API: enables you to create a platform and manage platform resources, such as account holders, balance accounts, and business accounts.
    • Transfers API: enables you to perform and manage transfers in your platform, such as moving funds within your platform or sending funds to third-party bank accounts.
  • An API credential for legal entity management. This credential has a username in the format ws[_123456]@Scope.Company_[YourCompanyAccount], and is used with the following API:

In your Balance Platform Customer Area, you can manage your API credentials by:

This page explains how to create and configure your API credentials for web service and legal entity management (LEM) users.

Before you begin

Ensure that your user account has the following role:

  • BalancePlatform Merchant Admin role

Create an API credential

You can have multiple API credentials linked to your Balance Platform, and activate or deactivate those credentials at any moment. Before creating credentials, consider that having fewer credentials minimizes the number of API keys you must handle, making your operations easier. However, having more credentials provides better control over API permissions, increasing security. Some sample use cases are:

  • To separate web service users according to the permissions they have. For example, separating users that can create and configure accounts from users that can configure transfers.
  • To isolate a web service user that has access to important permissions, such as PIN reveal or payment instrument reveal.

The following tabs explain how to create API credentials for both web service and LEM users in your Balance Platform Customer Area.

Create an API credential for a web service user to make requests to the Configuration API and Transfers API.

To create the API credential:

  1. Log in to your Balance Platform Customer Area.
  2. Go to Developers > API credentials.
  3. Select Create new credential.
  4. In the Create API credential dialog, under Credential type, select Web service user.
  5. Optional. In the Description field, describe the purpose of the credential.
  6. Select Create credential.
    The configuration page for your new credential opens.

Your new API credential has a username with the following format: ws[_123456]@BalancePlatform.[YourBalancePlatform].

When switching to your live environment, you must create a new API credential in your live Balance Platform Customer Area.

The following sections explain how to configure your API credential.

Generate an API key

Use API keys to authenticate your requests. Every web service and LEM user has its own API key.

To generate an API key for a user:

  1. Log in to your Balance Platform Customer Area.
  2. Go to Developers > API credentials.
  3. Select the credential username.
  4. On the Configure API credential page, in the Server settings section, select API key.
  5. Select Generate API key.
  6. Select the copy icon and store your API key securely in your system.

    You cannot copy the API key again after you leave the page.

  7. Select Save changes.

When switching to your live environment, you must generate a new API key in your live Balance Platform Customer Area.

Change an API key

You can change an API key when needed, for example, when an API key is lost or compromised. To do this, follow the steps to generate an API key.

When you generate a new API key, it can be used immediately. However, the previous key also remains active for the following 24 hours.

Extend the time of a previous API key

To extend the time that a previous API key remains active:

  1. Log in to your Balance Platform Customer Area.
  2. Go to Developers > API credentials.
  3. Select the credential username.
  4. On the Configure API credential page, in the Server settings section, select API key.
  5. Under Expiring keys, see how much time is left until the previous key expires. You can either:
    • Select the reset icon to reset the expiry time to 24 hours.
    • Select the expire now icon to expire the previous key immediately.
  6. Select Save changes.

Generate a basic authentication password

Users can also use basic authentication for API requests. To generate a basic authentication password:

  1. Log in to your Balance Platform Customer Area.
  2. Go to Developers > API credentials.
  3. Select the credential username.
  4. On the Configure API credential page, in the Server settings section, select Basic auth.
  5. Select Generate password.
  6. Select the copy icon and securely store your basic authentication password in your system.

    You cannot copy the password again after you leave the page.

  7. Select Save changes.

When you generate a new basic authentication password, the previous password is deactivated immediately.

Instead of generating a new password for an existing API credential, you can create a new API credential. This enables you to use both your existing password and a new one until you have updated your systems.

When switching from your test to your live environment, use the basic authentication credentials from your live Balance Platform Customer Area.

Manage API permissions

Manage the permissions of a web service API credential by enabling or disabling its roles. To do this:

  1. Log in to your Balance Platform Customer Area.
  2. Go to Developers > API credentials.
  3. Select the username of the web service credential, for example: ws_[123456]@BalancePlatform.[YourBalancePlatform].
  4. On the Configure API credential page, under Permissions, expand the category accordions to see lists of available roles.
    You can also use the search bar to find specific roles.
  5. Select the checkboxes of the roles you want to enable for the API credential.
  6. Select Save changes.

An API credential must have at least one enabled role.

Deactivate an API credential

  1. Log in to your Balance Platform Customer Area.
  2. Go to Developers > API credentials.
  3. Select the credential username to open the Configure API credential page.
  4. Under General settings, turn off the toggle next to the Username to switch the status from Active to Inactive.
  5. Select Save changes.