{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars/sdk_sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["code-group","admonition"]},"type":"markdown"},"seo":{"title":"Client configuration","description":"The specifications of Ratepay's APIs for easy payment transactions.","siteUrl":"https://docs.ratepay.com","keywords":"Ratepay developer portal, Ratepay api portal, Ratepay api reference docs","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"client-configuration","__idx":0},"children":["Client configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayClient"]}," is the main interface for interacting with the Ratepay SDK. It manages HTTP connections and OAuth access tokens, and supports concurrent requests."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create one client per credential set and reuse it throughout your application's lifecycle. For multi-shop integrations where each shop uses separate OAuth credentials, create a dedicated client for each credential set."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"initialize-the-client","__idx":1},"children":["Initialize the client"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To initialize a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayClient"]},", provide your OAuth client ID, client secret, and target ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/client/authentication#environments"},"children":["environment"]},"."]},{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"tabs"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","data-title":"Java","header":{"title":"Java","controls":{"copy":{}}},"source":"import com.ratepay.sdk.Environment;\nimport com.ratepay.sdk.RatepayClient;\n\nRatepayClient client = RatepayClient.builder()\n    .clientId(System.getenv(\"RATEPAY_CLIENT_ID\"))\n    .clientSecret(System.getenv(\"RATEPAY_CLIENT_SECRET\"))\n    .environment(Environment.INTEGRATION)\n    .build();\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","data-title":"Kotlin","header":{"title":"Kotlin","controls":{"copy":{}}},"source":"import com.ratepay.sdk.Environment\nimport com.ratepay.sdk.RatepayClient\n\nval client = RatepayClient {\n    clientId(System.getenv(\"RATEPAY_CLIENT_ID\"))\n    clientSecret(System.getenv(\"RATEPAY_CLIENT_SECRET\"))\n    environment(Environment.INTEGRATION)\n}\n","lang":"kotlin"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Kotlin supports the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayClient { ... }"]}," configuration syntax shown above. Alternatively, you can use the standard Java-style builder."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK manages HTTP transport, timeouts, and token refresh behavior internally. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/getting-started/compatibility#configuration-limitations"},"children":["Configuration limitations"]}," for details."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"validate-your-credentials","__idx":2},"children":["Validate your credentials"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Creating a client with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["build()"]}," does ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," initiate a network request. It validates the required configuration and throws ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayConfigurationException"]}," if the client ID, client secret, or environment is missing or invalid."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authentication occurs automatically when the client makes its first API request."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To validate your credentials before processing payments, call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validateCredentials()"]},". This method obtains or reuses an OAuth access token without initiating a payment."]},{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"tabs"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","data-title":"Java","header":{"title":"Java","controls":{"copy":{}}},"source":"try {\n    client.validateCredentials();\n} catch (RatepayAuthException e) {\n    // Credentials are wrong or revoked, fail startup instead of on\n    // the first customer's checkout.\n    throw new IllegalStateException(\"Ratepay credentials rejected\", e);\n}\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","data-title":"Kotlin","header":{"title":"Kotlin","controls":{"copy":{}}},"source":"try {\n    client.validateCredentials()\n} catch (e: RatepayAuthException) {\n    // Credentials are wrong or revoked, fail startup instead of on\n    // the first customer's checkout.\n    throw IllegalStateException(\"Ratepay credentials rejected\", e)\n}\n","lang":"kotlin"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validateCredentials()"]}," during application startup is optional but recommended. It helps detect authentication issues before processing payments and populates the SDK's token cache for subsequent requests."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/client/authentication"},"children":["Authentication"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"thread-safety-and-reuse","__idx":3},"children":["Thread safety and reuse"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A built ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayClient"]}," is thread-safe and can be shared across concurrent requests."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["However, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayClient.Builder"]}," is not thread-safe and should only be used once. Create a new builder for each client instance rather than sharing or reusing an existing builder."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Note: For applications serving multiple shop profiles, initialize a separate client for each credential set."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reusing client instances allows the SDK to maintain pooled HTTP connections and cached OAuth tokens, avoiding unnecessary initialization and authentication overhead."]},{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"tabs"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","data-title":"Java","header":{"title":"Java","controls":{"copy":{}}},"source":"// Do this once, at startup, and keep the reference.\nprivate static final RatepayClient CLIENT = RatepayClient.builder()\n    .clientId(clientId)\n    .clientSecret(clientSecret)\n    .environment(Environment.PRODUCTION)\n    .build();\n\n// Every request thread can safely call CLIENT.authorize(...), CLIENT.capture(...), etc.\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","data-title":"Kotlin","header":{"title":"Kotlin","controls":{"copy":{}}},"source":"// Do this once, at startup, and keep the reference — e.g. as a singleton bean.\nval client: RatepayClient = RatepayClient {\n    clientId(clientId)\n    clientSecret(clientSecret)\n    environment(Environment.PRODUCTION)\n}\n\n// Every request thread can safely call client.authorize(...), client.capture(...), etc.\n","lang":"kotlin"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"manage-the-client-lifecycle","__idx":4},"children":["Manage the client lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayClient"]}," implements ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AutoCloseable"]},". Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["close()"]}," when the client is no longer needed, typically during application shutdown, to release its HTTP connections."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Close the client at shutdown:"]}," Avoid closing it after individual payment operations."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Do not reuse a closed client:"]}," Create a new instance if additional requests are required."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use application-managed lifecycle hooks:"]}," In frameworks such as Spring, register the client as a singleton bean and configure it to close during shutdown."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For applications that manage resources explicitly, use Java's try-with-resources or Kotlin's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["use"]}," function."]},{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"tabs"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","data-title":"Java","header":{"title":"Java","controls":{"copy":{}}},"source":"// close() declares no checked exception\npublic static void main(String[] args) {\n    try (RatepayClient client = RatepayClient.builder()\n            .clientId(clientId)\n            .clientSecret(clientSecret)\n            .environment(Environment.PRODUCTION)\n            .build()) {\n        client.validateCredentials();\n        // ... run your application using `client` for its whole lifetime ...\n    }\n    // connections released here\n}\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","data-title":"Kotlin","header":{"title":"Kotlin","controls":{"copy":{}}},"source":"RatepayClient {\n    clientId(clientId)\n    clientSecret(clientSecret)\n    environment(Environment.PRODUCTION)\n}.use { client ->\n    client.validateCredentials()\n    // ... run your application using `client` for its whole lifetime ...\n}\n// connections released here\n","lang":"kotlin"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"extend-or-wrap-the-client","__idx":5},"children":["Extend or wrap the client"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayClient"]}," is an interface, allowing you to create custom wrappers for logging, metrics, circuit breaking, or testing without subclassing the SDK's internal implementation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For implementation examples, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/operations/logging-and-observability"},"children":["Logging and observability"]}," and ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/testing/testing-overview"},"children":["Testing overview"]},"."]}]},"headings":[{"value":"Client configuration","id":"client-configuration","depth":1},{"value":"Initialize the client","id":"initialize-the-client","depth":2},{"value":"Validate your credentials","id":"validate-your-credentials","depth":2},{"value":"Thread safety and reuse","id":"thread-safety-and-reuse","depth":2},{"value":"Manage the client lifecycle","id":"manage-the-client-lifecycle","depth":2},{"value":"Extend or wrap the client","id":"extend-or-wrap-the-client","depth":2}],"frontmatter":{"seo":{"title":"Client configuration"}},"lastModified":"2026-11-04T11:12:53.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/developer/sdk/client/client-configuration","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}