No momento, esta página não está disponível em português
Developer-resource icon

Client-side authentication

Learn about the client key and how to generate it.

We use your client key to authenticate requests from your payment environment. For example, Web Drop-in and Web Component integrations need the client key to:

  • Render input fields to securely collect and encrypt card details.
  • Detect the card type from the number the shopper entered in the payment form.
  • Do server-side barcode or QR code rendering for payment methods such as Swish or Boleto Bancário.

The client key is not used when making requests to our APIs. For API requests, you need to get an API key.

With the client key, you have:

  • A single key for all your allowed origins in an environment.
  • Flexibility to add and remove origins without having to generate a new client key.
  • A human-readable prefix, test or live, so you can easily tell which environment a client key is linked to.

Availability and compatibility

The client key is available for the following:

Online payments integration Version
Web Drop-in and Components Available for 3.10.1 and later. Previous versions require origin keys for client-side authentication.
Starting 4.0.0 the client key is the only way to do client-side authentication.
iOS Drop-in and Components 3.7.0 and later.
Previous versions require client encryption public keys.
Starting 4.0.0 the client key is the only way to do client-side authentication.
Android Drop-in and Components 3.7.0 and later.
Previous versions require client encryption public keys.
Starting 4.0.0 the client key is the only way to do client-side authentication.
In-person payments integration Solutions
POS Mobile SDK for iOS Tap to Pay on iPhone
Card reader—iOS
POS Mobile SDK for Android Tap to Pay on Android
Card reader—Android

How it works

The client key is a public key that uniquely identifies an API credential. Each API credential has a list of allowed origins, or domains from which we expect to get your requests. We make sure data cannot be accessed by unknown parties by using Cross-Origin Resource Sharing.

A client key is linked to an API credential and its environment. The client key has two parts:

  • A 32-character string encoding the API credential
  • A human-readable environment prefix

For example, test_870be2854add4f56b86778353010f36c is a client key for the test environment. When you switch to your live environment, you need to generate a client key in your live Customer Area. The client key for your live environment will start with live_.

Allowed origins

Allowed origins are domains from which we expect to get your client-side requests.

The allowed origins:

  • Can include a wildcard, for example https://*.example.org includes both https://blue.example.org and https://red.example.org.
  • Can be either a local or https domain in the test environment.
  • Must have https in the live environment.

Allowed origins are linked to the API credential, so you can add or remove allowed origins without needing to generate a new client key.

Get your client key

  1. Log in to your Customer Area.
  2. Go to Developers > API credentials, and select the credential username for your integration, for example ws@Company.[YourCompanyAccount].
  3. Under Client settings > Authentication select the Client key tab.
  4. Select Generate client key.
  5. Select the copy icon and store your client key securely in your system.
  6. Under Add allowed origins, enter your domains and select Add.
  7. Select Save changes.

If you generated a new client key, the old one expires after 24 hours.

You now have a client key for your ws@Company.[YourCompanyAccount] API credential, which is linked to your test environment. To get a client key for your live environment, follow the same steps in your live Customer Area.

Manage allowed origins

You can add or remove allowed origins for an API credential without generating a new client key.

  1. Log in to your Customer Area .
  2. Go to Developers > API credentials, and select the API credential for your Web Drop-in or Web Components integration, for example ws@Company.[YourCompanyAccount].
  3. Under Allowed origins, enter a domain and select Add. To remove a domain select the remove origin icon next to it.
  4. Select Save changes. It takes a few seconds for new allowed origins to become available for your application.

See also