[PIMOB-4287]: adding base url prefix to Frames SDK for multi-region

[zane-smith-cko]

Issue

PIMOB-4287

Proposed changes

Added baseUrlPrefix as a parameter for Frames configuration

• Example app subdomain base url now uses 'global'
• If baseUrlPrefix's sub domain is not alphanumeric then we do not accept it and we use the standard environment set URL without a prefix.
• PK + SK has been updated.

Test Steps

1. Pay with via card or via CVV
2. Observe API call being made from global subdomain.

Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.

• Reviewers assigned
• I have performed a self-review of my code and manual testing
• Lint and unit tests pass locally with my changes
• I have added tests that prove my fix is effective or that my feature works
• I have added necessary documentation (if applicable)

Further comments

Screen.Recording.2026-03-09.at.14.20.32.mov

[Copilot]

Pull request overview

Adds support for an optional subdomain/base-URL prefix so tokenization requests can be routed via a regional/merchant-specific subdomain, and wires this through Frames + CVV flows with updated samples and tests.

Changes:

• Introduces baseUrlPrefix in Frames configuration/DI and propagates it down to CheckoutApiServiceFactory.
• Adds Environment.toBaseUrl(...) URL building with prefix validation and corresponding unit tests.
• Updates example apps and unit tests to pass the new prefix argument(s).

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
frames/src/test/java/com/checkout/frames/screen/paymentform/PaymentFormViewModelTest.kt	Updates test setup to include baseUrlPrefix when constructing the VM factory.
frames/src/test/java/com/checkout/frames/screen/paymentform/PaymentFormConfigTest.kt	Extends config test coverage to include baseUrlPrefix.
frames/src/test/java/com/checkout/frames/mock/PaymentFormConfigTestData.kt	Adds test data constant for baseUrlPrefix.
frames/src/test/java/com/checkout/frames/cvvinputfield/InternalCVVComponentApiTest.kt	Updates CVV API test to include baseUrlPrefix.
frames/src/test/java/com/checkout/frames/cvvinputfield/CVVComponentApiFactoryTest.kt	Updates factory test for new create(...) signature.
frames/src/main/java/com/checkout/frames/screen/paymentform/model/PaymentFormConfig.kt	Adds public config field baseUrlPrefix.
frames/src/main/java/com/checkout/frames/screen/paymentform/PaymentFormViewModel.kt	Threads baseUrlPrefix into injector creation.
frames/src/main/java/com/checkout/frames/screen/paymentform/PaymentFormScreen.kt	Passes config baseUrlPrefix into VM factory.
frames/src/main/java/com/checkout/frames/di/injector/FramesInjector.kt	Threads baseUrlPrefix into CheckoutApiServiceFactory.create(...) and DI builder.
frames/src/main/java/com/checkout/frames/di/component/FramesDIComponent.kt	Adds @BindsInstance baseUrlPrefix to Dagger builder.
frames/src/main/java/com/checkout/frames/cvvinputfield/api/InternalCVVComponentApi.kt	Threads baseUrlPrefix into CheckoutApiServiceFactory.create(...) for CVV tokenization.
frames/src/main/java/com/checkout/frames/cvvinputfield/CVVComponentApiFactory.kt	Extends CVV factory API to accept baseUrlPrefix.
example_app_frames/src/main/java/com/checkout/example/frames/ui/utils/Constants.kt	Adds demo constant for regional subdomain and updates demo keys.
example_app_frames/src/main/java/com/checkout/example/frames/ui/screen/MainActivity.kt	Passes regional subdomain into PaymentFormConfig.
example_app_frames/src/main/java/com/checkout/example/frames/ui/screen/HomeScreen.kt	Passes regional subdomain into CheckoutApiServiceFactory.create(...).
example_app_frames/src/main/java/com/checkout/example/frames/ui/screen/CVVTokenizationScreen.kt	Passes regional subdomain into CVVComponentApiFactory.create(...).
checkout/src/test/java/com/checkout/EnvironmentExtensionTest.kt	Adds unit tests for Environment.toBaseUrl(...) behavior.
checkout/src/test/java/com/checkout/CheckoutApiServiceFactoryTest.kt	Updates factory test for new signature.
checkout/src/main/java/com/checkout/logging/utils/EnvironmentExtension.kt	Adds Environment.toBaseUrl(...) and prefix validation helper.
checkout/src/main/java/com/checkout/base/model/Environment.kt	Refactors Environment enum to remove url field.
checkout/src/main/java/com/checkout/CheckoutApiServiceFactory.kt	Adds baseUrlPrefix parameter and uses Environment.toBaseUrl(...) for tokenization base URL.
app/src/main/java/checkout/checkout_android/DemoActivity.java	Updates demo to pass regional subdomain into PaymentFormConfig.
app/src/main/java/checkout/checkout_android/Constants.java	Adds regional subdomain constant and updates demo keys.
app/src/main/java/checkout/checkout_android/CVVTokenizationActivity.java	Updates demo to pass regional subdomain into CVVComponentApiFactory.create(...).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

A (sandbox) secret key is committed into source control via SECRET_KEY. Even sandbox secret keys should not be checked in; replace this with a placeholder and load it from a secure local/developer-only mechanism (e.g., gradle properties/env var), and rotate/revoke the exposed key.

Suggested change

	public static final String SECRET_KEY = "sk_sbox_cqc26o3haljkwuns6xcfcmf2vmu";
	private static String loadSecretKey() {
	String secretKey = System.getenv("CHECKOUT_SECRET_KEY");
	if (secretKey == null || secretKey.isEmpty()) {
	throw new IllegalStateException("Environment variable CHECKOUT_SECRET_KEY must be set with a valid secret key.");
	}
	return secretKey;
	}
	public static final String SECRET_KEY = loadSecretKey();

[zane-smith-cko]

This should be looked into in another ticket, have updated the keys for now so they are valid.

[Copilot]

Removing the public url property from Environment is a breaking API change for SDK consumers that may rely on Environment.url. Consider keeping a (possibly deprecated) url property (backed by the current default tokenization URL) or exposing a public replacement for retrieving the base URL.

Suggested change

	SANDBOX
	SANDBOX;
	@Deprecated(
	message = "Environment.url is deprecated. Use the appropriate configuration or tokenization URL accessor instead."
	)
	public val url: String
	get() = when (this) {
	PRODUCTION -> PRODUCTION_URL
	SANDBOX -> SANDBOX_URL
	}
	private companion object {
	private const val PRODUCTION_URL: String = "https://api.checkout.com/tokens"
	private const val SANDBOX_URL: String = "https://api.sandbox.checkout.com/tokens"
	}

[zane-smith-cko]

is this meant to be publicly exposed?