Ask ChatGPTAsk Claude

Account configuration

To make use of the Checkout Components, the domains that you want to use the SDK on need to be added to your account or your sellers' accounts. If you're using the Deferred integration you will need to retrieve the accountPublishableKey of an account. For certain payment methods, like Apple Pay, additional account configuration is required.

Allowed domains

Depending on your model you need to add domains to your account or the account of your sellers. When your seller is the merchant of record and you use the processing_account_id in the payments request you need to add the domain(s) to your sellers account.

You can add multiple or a single domain to an account. We expect a Fully Qualified Domain Name, for example: "example.com" or "www.example.com". Domains are appended to the allowed list of the account and can be removed separately.

Important

On production all domains must be served over HTTPS.
On staging you can add localhost using HTTP.

Add multiple domains to an account

POST /v1/accounts/{account_id}/allowed-domains x-api-key: <your-api-key> rootline-version: 2024-04-23 Content-Type: application/json { "allowed_domains": [ "demoshop.example.com", "www.example.com" ] }

Add a single domain to an account

POST /v1/accounts/{account_id}/allowed-domains x-api-key: <your-api-key> rootline-version: 2024-04-23 Content-Type: application/json { "allowed_domain": "demoshop.example.com" }

Retrieve allowed domains of an account

GET /v1/accounts/{account_id}/allowed-domains x-api-key: <your-api-key> rootline-version: 2024-04-23
{ "allowed_domains": [ "demoshop.example.com", "www.example.com" ] }

Removing a domain from an account

DELETE /v1/accounts/{account_id}/allowed-domains/www.example.com x-api-key: <your-api-key> rootline-version: 2024-04-23

Retrieving the accountPublishableKey

To retrieve the accountPublishableKey from an account for the deferred flow you will need to make a GET /accounts/{account_id} request:

GET /v1/accounts/{account_id} x-api-key: <your-api-key> rootline-version: 2024-04-23
{ "id": "acc_3VfQsTP2lqnjR6IHnObpVe", "object": "account", "description": "SimulatorAccount", "legal_entity_id": "co_61OUixOkMWWeurILPXvJUM", "base_return_url": "https://rootline.com/", "created_at": "2026-01-14T12:15:37.904Z", "business_address": { "street_address": "IO street 1", "street_address2": "", "postal_code": "1212IO", "city": "Amsterdam", "state": "NH", "country": "NL" }, "publishable_keys": [ "apk_1aFvRxiyzgLjPXJAhOtVsY" ], "allowed_domains": [ "example.com" ], "payment_method_settings": [ { "payment_method": "applepay", "applepay_settings": { "merchant_url": "https://www.rootline.com/", "domains": [ "checkout.rootline.com", "rootline.com" ] } } ] }

Enable Apple Pay

Apple Pay requires a domain to be verified in order to use it. To verify your domain you need to take the following steps:

  1. Download the domain association file
  2. Upload the domain association file to each domain you want to offer Apple Pay and make sure it's accessible on the following path: /.well-known/apple-developer-merchantid-domain-association
  3. Make a PATCH request to /accounts/{account_id}/payment-method-settings/applepay with the domains you want to verify:
PATCH /v1/accounts/{account_id}/payment-method-settings/applepay x-api-key: <your-api-key> rootline-version: 2024-04-23 Content-Type: application/json { "applepay_settings": { "domains": ["test.com"] } }
info

The domain association file needs to be externally accessible. It cannot be password protected or behind a proxy or redirect. Ensure the file is served as Content-Type: text/plain.

Rootline always includes the checkout domain for the environment. An empty domain list keeps only that checkout domain. You cannot delete the checkout domain through the domains endpoint. Domain names are case-insensitive. Successful updates store and return lowercase domain names without duplicates. Adding a domain that differs only in case from an existing domain returns 422 if the request adds no other domains.

If Apple rejects domain verification, Rootline returns 422 with invalid_field on domain. The message names every domain sent to Apple, which can include the checkout domain:

Invalid value for request field 'domain' - Apple did not register test.com. Each domain must serve the domain association file at /.well-known/apple-developer-merchantid-domain-association over HTTPS, without a redirect, as text/plain.

A verification failure leaves the stored settings unchanged. Correct the file access problem, then repeat the PATCH request. Other Apple failures return 500. Apple can apply a change before Rootline receives an error. After the cause is resolved, repeat the PATCH request to reconcile Apple and the stored settings. Send updates for the same account one at a time. If updates overlap, repeat the desired PATCH after both finish.