{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars/sdk_sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["credential-value","code-group"]},"type":"markdown"},"seo":{"title":"Authentication","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":"authentication","__idx":0},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-authentication-works","__idx":1},"children":["How authentication works"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Initialize RatepayClient with your OAuth client ID, client secret, and target ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#environments"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["environment"]}]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When you make your first API request or call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validateCredentials()"]},", the SDK requests an access token from Ratepay's OAuth endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The SDK caches the token and automatically refreshes it before expiration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Subsequent API requests include the access token in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer <token>"]}," header."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authentication failures:"]}," If Ratepay rejects your credentials, the SDK throws ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayAuthException"]},". Authentication failures (HTTP 401/403) are not automatically retried. Check your credentials and environment configuration before retrying."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/errors-and-resilience/exception-hierarchy"},"children":["Exception hierarchy"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You don't construct tokens, headers, or refresh logic yourself; the only two credentials you manage are the"," ","client ID and secret."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"environments","__idx":2},"children":["Environments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Environment"]}," setting determines which Ratepay API and OAuth endpoints the SDK uses."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Environment"},"children":["Environment"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Environment.INTEGRATION"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Test environment for developing and validating your integration without processing real payments."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Environment.PRODUCTION"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Production environment for processing live transactions."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use separate OAuth credentials for each environment. Integration credentials cannot be used to authenticate production requests, or vice versa."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"rp-credentials"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"rp-credentials__title"},"children":["\n      Credentials\n   "]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"rp-credentials__note"},"children":["\n      Individual credentials will be provided by your Ratepay representative.\n   "]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"rp-credentials__switcher"},"children":[{"$$mdtype":"Tag","name":"select","attributes":{"id":"env","aria-label":"API environment","className":"rp-credentials__select"},"children":[{"$$mdtype":"Tag","name":"option","attributes":{"value":"test"},"children":["Test"]},{"$$mdtype":"Tag","name":"option","attributes":{"value":"live"},"children":["Live"]}]}]},{"$$mdtype":"Tag","name":"div","attributes":{"id":"block-test","className":"rp-credentials__panel"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"rp-credentials__divider"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"rp-credentials__fields"},"children":[{"$$mdtype":"Tag","name":"CredentialValue","attributes":{"label":"Client ID","value":"snbFcxD4Rxt2O4YqeGqDls9yrGWYhmQ0"},"children":[]},{"$$mdtype":"Tag","name":"CredentialValue","attributes":{"label":"Client Secret","value":"IHa7jiW0hMlH0VsoxDTZ03XH76NED7RwFvJLsmmUXg9fkowhiVQqp7EA84WoYT1Q"},"children":[]}]}]},{"$$mdtype":"Tag","name":"div","attributes":{"id":"block-live","className":"rp-credentials__panel","style":{"display":"none"}},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"rp-credentials__divider"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"rp-credentials__fields"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{"className":"rp-credentials__field"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client ID:"]},{"$$mdtype":"Tag","name":"span","attributes":{"className":"rp-credentials__note"},"children":["\n         You will receive this via your Ratepay representative.\n         "]}]},{"$$mdtype":"Tag","name":"p","attributes":{"className":"rp-credentials__field"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client Secret:"]},{"$$mdtype":"Tag","name":"span","attributes":{"className":"rp-credentials__note"},"children":["\n         You will receive this via your Ratepay representative.\n         "]}]}]}]}]},{"$$mdtype":"Tag","name":"HtmlScript","attributes":{},"children":["\ndocument.getElementById('env').addEventListener('change', function() {\n  const isTest = this.value === 'test';\n  document.getElementById('block-test').style.display = isTest ? 'block' : 'none';\n  document.getElementById('block-live').style.display = isTest ? 'none' : 'block';\n});\n"]},{"$$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 sandboxClient = RatepayClient.builder()\n    .clientId(clientId)\n    .clientSecret(clientSecret)\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 sandboxClient = RatepayClient {\n    clientId(clientId)\n    clientSecret(clientSecret)\n    environment(Environment.INTEGRATION)\n}\n","lang":"kotlin"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information about initializing and managing the client, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/client/client-configuration"},"children":["Client configuration"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"credential-rotation","__idx":3},"children":["Credential rotation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To rotate OAuth credentials, create a new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayClient"]}," instance with the updated client ID or secret."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"multi-shop-configurations","__idx":4},"children":["Multi-shop configurations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ratepay supports different configurations for processing payments across multiple shops or shop profiles."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"marketplace-configuration","__idx":5},"children":["Marketplace configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A shop profile configured as a marketplace can process transactions involving multiple shops. Each shop is identified using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partner_shop_id"]}," in the relevant transaction requests."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The marketplace configuration does not require separate OAuth credentials for each participating shop."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"single-oauth-for-multiple-shop-profiles","__idx":6},"children":["Single OAuth for multiple shop profiles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The :question_mark: identifies the relevant partner context for API requests using this configuration."]}]},"headings":[{"value":"Authentication","id":"authentication","depth":1},{"value":"How authentication works","id":"how-authentication-works","depth":2},{"value":"Environments","id":"environments","depth":2},{"value":"Credential rotation","id":"credential-rotation","depth":2},{"value":"Multi-shop configurations","id":"multi-shop-configurations","depth":2},{"value":"Marketplace configuration","id":"marketplace-configuration","depth":2},{"value":"Single OAuth for multiple shop profiles","id":"single-oauth-for-multiple-shop-profiles","depth":2}],"frontmatter":{"seo":{"title":"Authentication"}},"lastModified":"2026-11-04T16:00:18.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/developer/sdk/client/authentication","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}