Skip to main content

Integration checklist

The checklist guides the developer through the entire useCheckout() integration — from account activation to production deployment.

Tip

Checked items are saved to the browser's local storage and remain preserved even after the page is refreshed.

SymbolMeaning
🔜Must be met before production deployment (not necessarily in order).
⚠️Critical — without it the SDK will not work correctly.
❔Optional.

1. Prerequisites​

Comgate account is active.
At least one of the following methods is activated (depending on planned payment methods):
Card only — CARD_CZ_COMGATE method activated.
Apple Pay / Google Pay only — CARD_CZ_COMGATE or CARD_CZ_CSOB_2 method activated.
Card + Apple Pay / Google Pay — CARD_CZ_COMGATE method activated.
Shop is registered with Comgate with the correct domain / subdomain.
🔜 HTTPS is available on the production domain.
⚠️ The SDK is not running in an iframe or WebView.
❔ If CSP is used — domains checkout.comgate.cz, payments.comgate.cz, pay.google.com, applepay.cdn-apple.com are allowed.
❔ File uploads to /.well-known/ on your domain must be allowed (for Apple Pay).

2. Configuration in the Comgate portal​

A shop connection with activated services (Card, Apple Pay, Google Pay) has been created in the portal.
The checkoutId has been obtained from the connection settings.

❔ Domain verification — Apple Pay​

Only if you integrate Apple Pay.

🔜 The /.well-known/apple-developer-merchantid-domain-association file has been uploaded to your domain.
🔜 The file content matches the value from the /v2.0/appleDomainAssociation endpoint (ASCII/UTF-8, no trailing newline).
🔜 Domain + subdomains verified in the Comgate client portal.
🔜❔ Automatic file content refresh implemented.

❔ Domain verification — Google Pay​

Only if you integrate Google Pay.

🔜 Domain + subdomains approved in Google Pay Console.
🔜 Integration screenshots ready for Google review.

3. Implementation of useCheckout()​

[Link to documentation] · [Examples]

Payment creation (backend)​

⚠️ Payment is created via Merchant API — transactionId obtained.
⚠️ The payer e-mail is always provided when creating the payment.

Preparing HTML elements​

❔ For Apple Pay: <div> with a defined size (min. 240×45 px).
❔ For Google Pay: <div> with a defined size (min. 240×45 px).
❓ For card: container with a unique ID, inner elements #{id}-ibox and #{id}-button > button, min. size 280×250 px.
⚠️ The elements exist in the DOM before useCheckout() is called.

Calling useCheckout()​

checkoutId and transactionId are passed.
⚠️ All required callbacks are implemented: onPaid, onCancelled, onPending, onError.
In onPaid the user sees a success confirmation (or is redirected).
In onCancelled / onPending the user sees an understandable message and can repeat the action.
In onError the error is logged and the user is informed.

Processing the result (result)​

result.applepay?.success is checked — if false, the element is hidden.
result.googlepay?.success is checked — if false, the element is hidden.
The state where useCheckout() rejects (the SDK failed to load) is handled.

4. SPA — lifecycle​

Required for applications with client-side routing (Vue, React, Next.js, Nuxt, …).

Warning

Without proper cleanup, old instances remain in memory and cause conflicts when the payment page is loaded again.

⚠️ When leaving the page, destroy() is called on the Apple Pay, Google Pay and Card instances.
⚠️ destroy() is not called on Core — it is a singleton managed by the SDK.
⚠️ Cleanup is performed in the correct lifecycle hook (onUnmounted / useEffect cleanup).
⚠️ For a new payment, useCheckout() is called again — the old instance is not used.

5. Backend — payment verification​

Danger

Never rely solely on frontend callbacks (onPaid). Always verify the payment state server-to-server.

⚠️ The backend verifies the payment state via the Merchant API (endpoint /v1.0/status) after receiving the notification.
⚠️ The order is marked as paid only after confirmation from the backend, not based on onPaid.

6. Test scenarios​

Before deploying to production, verify the following scenarios for each implemented method:

❔ Apple Pay​

Successful payment → onPaid was called, user sees confirmation.
Declined payment (insufficient funds) → onPending, user is informed.
User closed Apple Pay sheet → onPending, application behaves correctly.
❔ Preauthorization payment → onPaid.
❔ Initial recurring payment → onPaid.

❔ Google Pay​

Successful payment → onPaid was called, user sees confirmation.
Declined payment (insufficient funds) → onPending, user is informed.
User closed Google Pay dialog → onPending, application behaves correctly.
❔ Preauthorization payment → onPaid.
❔ Initial recurring payment → onPaid.

❔ Card payment​

Successful payment → onPaid was called, user sees confirmation.
Declined payment (insufficient funds) → onPending, user is informed.
3D Secure verification took place (iframe modal) and the payment was completed.
Invalid card details → user sees a validation error.
❔ Preauthorization payment → onPaid.

7. Production deployment​

🔜 Apple Pay — domain verified in the Comgate portal (production).
🔜 Google Pay — domain approved in Google Pay Console (production).
checkoutId matches the production connection.
⚠️ SDK elements are not programmatically hidden, overlaid or modified.
Payment tested on a real device (iOS for Apple Pay, Android for Google Pay).
All implemented payment methods (card, Apple Pay, Google Pay) are functional in the production environment.