Skip to content
/
Authentication

Authentication

The Ratepay Payment API uses OAuth 2.0 client credentials to authenticate requests. The SDK automatically obtains, caches, and refreshes access tokens, so you don't need to manage tokens or authorization headers yourself.

How authentication works

  1. Initialize RatepayClient with your OAuth client ID, client secret, and target environment.
  2. When you make your first API request or call validateCredentials(), the SDK requests an access token from Ratepay's OAuth endpoint.
  3. The SDK caches the token and automatically refreshes it before expiration.
  4. Subsequent API requests include the access token in the Authorization: Bearer <token> header.

Authentication failures: If Ratepay rejects your credentials, the SDK throws RatepayAuthException. Authentication failures (HTTP 401/403) are not automatically retried. Check your credentials and environment configuration before retrying.

For more information, see Exception hierarchy.

You don't construct tokens, headers, or refresh logic yourself; the only two credentials you manage are the client ID and secret.

Environments

The Environment setting determines which Ratepay API and OAuth endpoints the SDK uses.

EnvironmentDescription
Environment.INTEGRATIONTest environment for developing and validating your integration without processing real payments.
Environment.PRODUCTIONProduction environment for processing live transactions.

Use separate OAuth credentials for each environment. Integration credentials cannot be used to authenticate production requests, or vice versa.

Credentials
Individual credentials will be provided by your Ratepay representative.

Client ID:snbFcxD4Rxt2O4YqeGqDls9yrGWYhmQ0

Client Secret:IHa7jiW0hMlH0VsoxDTZ03XH76NED7RwFvJLsmmUXg9fkowhiVQqp7EA84WoYT1Q

import com.ratepay.sdk.Environment;
import com.ratepay.sdk.RatepayClient;

RatepayClient sandboxClient = RatepayClient.builder()
    .clientId(clientId)
    .clientSecret(clientSecret)
    .environment(Environment.INTEGRATION)
    .build();

For more information about initializing and managing the client, see Client configuration.

Credential rotation

To rotate OAuth credentials, create a new RatepayClient instance with the updated client ID or secret.

The SDK does not support updating credentials on an existing client. Replace the existing instance with the newly configured client and close the old instance when it is no longer in use.

Multi-shop configurations

Ratepay supports different configurations for processing payments across multiple shops or shop profiles.

Marketplace configuration

A shop profile configured as a marketplace can process transactions involving multiple shops. Each shop is identified using partner_shop_id in the relevant transaction requests.

The marketplace configuration does not require separate OAuth credentials for each participating shop.

Single OAuth for multiple shop profiles

Single OAuth allows multiple Ratepay shop profiles to share one OAuth credential set, for example, when a company operates separate profiles for different countries or brands.

The :question_mark: identifies the relevant partner context for API requests using this configuration.

Previous page
Next page