Search

Are you looking for test card numbers?

Would you like to contact support?

User-management icon

Client-side authentication

Learn about the client key and how to generate it.

We use your client key to authenticate requests from your web 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 Web Drop-in and Web Components version 3.10.1 and above. Previous versions require origin keys for client-side authentication.

How it works

The client key is a public key that uniquely identifies a web service user. Each web service user 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 a web service user and its environment. The client key has two parts:

  • A 32-character string encoding the web service user
  • 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 have http in the test environment, for example http://localhost:8080.
  • Must have https in the live environment.

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

If you want to run more than one origin in the same browser session, you must disable your browser cache. For example, you might be developing a React and Java app, with the app running on localhost:8080 and a webpack live reload on localhost:3000. If you don't disable the browser cache, there will be an invalid client key error when the app requests the cached assets of the live reload.

Get your client key

  1. Log in to your test Customer Area.
  2. Go to Account > Users, and select the web service user for your Web Drop-in or Web Components integration, for example ws@Company.[YourCompanyAccount].
  3. Add your domains under Allowed origins. These are the domains from which you will be sending your client-side requests.
  4. Under Authentication, select Generate New Client Key. You can use your new client key immediately.

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] web service user, which is linked to your test environment. To get a client key for your live environment, follow the same steps in the live Customer Area.

Manage allowed origins

You can add or remove allowed origins for a web service user without needing to generate a new client key.

  1. Log in to your test Customer Area.
  2. Go to Account > Users, and select the web service user for your Web Drop-in or Web Components integration, for example ws@Company.[YourCompanyAccount].
  3. Under Allowed origins you can add or remove domains. These are the domains from which you will be sending your client-side requests.
  4. Select Save at the bottom of the page. It takes a few seconds for new allowed origins to become available for your application.

See also