Requirements

Before starting the integration, it is necessary to familiarize yourself with the Web Checkout SDK integration requirements. These requirements also include compliance with the rules for using the brand and visual elements according to the official brand manuals and integration guidelines of all affected platforms (Google Pay and Apple Pay).

Warning

Compliance with the stated conditions is essential for trouble-free payment operation.

General requirements

1. Active account in the Comgate client portal:
   • active contract,
   • activated payment methods (CARD_CZ_COMGATE or CARD_CZ_CSOB_2),
   • registered shop – the domain in the portal must exactly match the domain on which Checkout will operate (including subdomains).
2. HTTPS on the domain where Checkout will run.
3. Access to Google Pay Console (or the ability to set it up) with Admin permissions:
   • management of the payment profile and registration of the shop domain,
   • uploading materials for brand/UI review.
4. Experience in developing web applications using advanced JavaScript.

Technical requirements

1. Checkout must not be used in an iframe or in a WebView.
   • In these environments correct functionality cannot be guaranteed and unpredictable behavior may occur.
2. Content Security Policy (CSP)
   • Allowed scripts and styles from CDN; correctly configured directives.
   • SDK assets are downloaded from: https://checkout.comgate.cz/sdk/* (even when using the NPM package).
   • Network requests (XHR/fetch) go to: https://payments.comgate.cz/*.
   • General CSP recommendations:
     • default-src includes https://payments.comgate.cz, https://checkout.comgate.cz,
     • script-src includes https://checkout.comgate.cz,
     • style-src includes https://checkout.comgate.cz, https://fonts.googleapis.com,
     • style-src-elem includes https://checkout.comgate.cz, https://*.gstatic.com https://fonts.googleapis.com,
     • img-src includes https://checkout.comgate.cz,
     • connect-src includes https://payments.comgate.cz.
   • Google Pay:
     • script-src includes https://pay.google.com, https://*.gstatic.com
     • frame-src includes https://pay.google.com, https://*.gstatic.com
     • img-src includes https://pay.google.com, https://*.gstatic.com, https://*.googleusercontent.com, data:
     • font-src includes https://*.gstatic.com
     • connect-src includes https://pay.google.com, https://google.com/pay, https://*.gstatic.com, https://*.google.com
   • Apple Pay:
     • script-src includes https://applepay.cdn-apple.com
     • font-src includes https://applepay.cdn-apple.com
3. Ability to implement custom processes on the backend and create custom endpoints (e.g. creating a payment, getting status, handling notifications).
4. The domain and hosting must allow publishing static files in the /.well-known/ directory (e.g. https://your-shop.com/.well-known/apple-developer-merchantid-domain-association).

Danger

Using nonce or hash for Checkout SDK scripts is currently not supported. The reason is the continuous release of module updates and dynamic asset downloads from the CDN based on the currently published version, which does not allow stable maintenance of corresponding hash values.

Support for this functionality is planned for future versions; a specific date has not yet been set.

Payment requirements

Payer e-mail

Although the Comgate payment gateway unofficially allows creating a payment without the payer's e-mail and subsequently requests this information itself during the process, Checkout SDK does not support this functionality – if the e-mail is missing, the integration will not work correctly. Therefore, always ensure that a valid payer e-mail is provided when creating the payment.

Test environment and devices

Apple Pay

It is necessary to verify the test domain as well by placing the /.well-known/apple-developer-merchantid-domain-association file and to register the domain in the Comgate client portal as a test shop.

Device

To test Apple Pay payments, you must have access to one of the physical iPhone or iPad devices with Apple Wallet enabled.

Google Pay

Registration of the test domain in Google Pay Console is not required; it is done only before production deployment. Likewise, there is no need to have a registered test shop in the Comgate portal.

Device

For testing Google Pay payments, you do not need to own a physical device; a Google account with an active Google Wallet and an added payment method is sufficient.

It is always advisable to test the integration on an Android device.

Note

On localhost, the buttons can be displayed, provided the specific conditions are met.

Integration conditions

Compliance with the conditions below is essential for proper SDK functioning, maintaining payment security and compliance with the rules of payment networks.

Binding nature

Violation of some of the conditions below may lead to limitation or termination of the Checkout SDK service by Comgate.

Integrity of the payment form

Display of all elements

All elements of the card form — including fields for card number, expiration, CVV and the payment button — must remain visible, accessible and fully functional.

It is forbidden to:

• Hide parts of the form using display: none, visibility: hidden, opacity: 0 or other techniques.
• Overlap the form with other elements.
• Disable or break the payment button outside of SDK logic.
• Remove form elements from the DOM after initialization.

Prohibition of manipulating the SDK

It is forbidden to:

• Modify, decompile or perform reverse engineering of the SDK source code.
• Call internal (undocumented) methods or access internal data structures.
• Override or monkey-patch SDK functions.
• Intercept or modify SDK network communication with the payment server.

Warning

Use only the public API described in the implementation documentation. All other interfaces are internal, unsupported and may change without notice.

Payment processing

Required callbacks

The integrator must implement all required callbacks passed in the Core configuration:

Callback	Required	Purpose
onPaid	Yes	Handling a successful payment
onCancelled	Yes	Handling a cancelled payment
onPending	Yes	Handling an unsuccessful attempt (payment remains active)
onError	Yes	Handling a critical SDK error

The customer must always be informed of the payment result — whether successful, unsuccessful or cancelled.

Payer e-mail

When creating a payment via the Comgate Merchant API, a valid payer e-mail must always be provided. Without an e-mail, the payment cannot be processed via the Checkout SDK.

Verifying the payment on the backend

The onPaid callback is used to improve the user experience (immediate redirect to the thank-you page). Never rely solely on the frontend callback for payment confirmation. Always verify the actual payment state on your backend using the Comgate Merchant API.

Payment methods — network rules

Apple Pay

• The Marketing Guidelines and Human Interface Guidelines must be followed.
• The domain must be verified via the /.well-known/apple-developer-merchantid-domain-association file.
• The Apple Pay button must not be visually modified beyond the allowed configurations (type, color, style).

Google Pay

• The Brand Guidelines and UX best practices must be followed.
• The domain must be approved in Google Pay Console.
• A valid googlePayMerchantId must be provided for production operation.
• The Google Pay button must not be visually modified beyond the allowed configurations (type, color).

Operational requirements

Testing before deployment

Before production deployment, the integrator must verify:

• A successful payment with each implemented method.
• Correct handling of a failed payment and cancellation.
• Correct behavior of the 3D Secure flow.
• Correct display on mobile devices.

See the Integration checklist for a complete list of test scenarios.

SDK loader updates

The integrator should regularly check the availability of new SDK versions (primarily the NPM loader) and update it to the latest version within the major version in use. Comgate guarantees backward compatibility within a major version.

Liability

• Comgate is not responsible for errors caused by violation of the integration conditions, use of undocumented APIs or operation in an unsupported environment.