> For the complete documentation index, see [llms.txt](https://docs.ecommerce.seb.ee/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ecommerce.seb.ee/integration/hosted-checkout.md). # Hosted Checkout Accept online payments through a secure checkout page hosted by the Ecommerce Payment Gateway. Hosted Checkout provides a ready-to-use payment interface where customers can choose an available payment method, provide or confirm their payment details, and complete any required authentication. Your server creates a payment through the Merchant API and receives a Payment ID and checkout URL. You redirect the customer to that URL and confirm the payment result through callback notifications and the Merchant API. {% hint style="warning" %} **Do not treat the customer’s return to your website or application as payment confirmation.** Use the callback notification as a trigger, retrieve the current payment information from the Gateway, and fulfil the order only after confirming the required paid status. {% endhint %} ### Why use Hosted Checkout? Hosted Checkout is a good choice when you want to accept multiple payment methods without building and maintaining your own payment interface. | The Gateway handles | You implement | | -------------------------------------- | -------------------------------------------- | | The customer-facing payment page | Your order and checkout flow | | Payment-method selection | The create-payment API request | | Collection of payment credentials | Storing the Payment ID | | Customer authentication | Redirecting the customer | | Handover to banks and wallet providers | Processing callback notifications | | Responsive checkout experience | Confirming the status and updating the order | Hosted Checkout can reduce your integration effort and your systems’ exposure to sensitive cardholder data. Because the payment page is operated in the Gateway environment, payment credentials do not need to pass through your application. You remain responsible for your applicable PCI DSS obligations. #### Consider Hosted Checkout when you want * A ready-to-use payment page. * Multiple payment methods through one integration. * Authentication flows handled by the Gateway. * A responsive experience for desktop and mobile. * Configuration-based branding rather than a fully custom payment UI. #### Consider another integration when you need * Full control over the payment-page layout and behaviour. * To collect payment information within your own interface. * Bespoke checkout logic that is not available through Hosted Checkout configuration. See **Choose Your Integration** to compare Hosted Checkout with Merchant API, Web Plugins, and Mobile SDK. ### How ```mermaid sequenceDiagram participant C as Customer participant M as Merchant participant G as Ecommerce Payment Gateway participant P as Bank / Payment Provider C->>M: Starts checkout M->>G: Create payment G-->>M: Payment ID + Checkout URL M->>M: Store Payment ID M-->>C: Redirect to Hosted Checkout C->>G: Select payment method G->>P: Process payment / authentication P-->>G: Payment result G-->>C: Redirect back to Merchant G-->>M: Callback notification M->>G: Get payment information G-->>M: Current payment status M->>M: Update order ``` The flow consists of five main steps: 1. Your server creates a customer-initiated payment. 2. The Gateway returns a Payment ID and checkout URL. 3. You store the Payment ID and redirect the customer. 4. The customer completes the payment on Hosted Checkout. 5. Your backend confirms the result through a callback and the Merchant API. Hosted Checkout can present cards, digital wallets, Pay by Bank, and other methods enabled for the shop and applicable to the transaction. The exact customer journey depends on the selected payment method, but the merchant integration remains the same. ### Before you begin Make sure you have: * A Sandbox shop. * OAuth credentials for the shop. * The required payment methods enabled. * An HTTPS URL to which the customer can return. * An HTTPS Callback URL for payment notifications. * A merchant order that can be linked to the Gateway Payment ID. Configure Sandbox credentials, return URLs, Callback URLs, and payment methods before beginning development. Sandbox and Production configurations are managed separately. See: * **Quickstart** * **Integration checklist** * **Merchant Portal — Shop Settings** * **Authentication** * **Testing/Sandbox Guide** ### Integrate Hosted Checkout #### 1. Create the payment From your backend, use the Merchant API to create a customer-initiated payment. Provide the information required to identify and process the payment, including: * Your shop. * Your merchant order number. * The payment amount and currency. * The URL to which the customer should return. You can also provide additional order, customer, address, basket, locale, and token-setup information where applicable. The current Merchant API describes Hosted Checkout as one of the ways to continue a customer-initiated payment after it has been created. The API uses OAuth 2.0 Client Credentials and requires a unique request identifier. See **Merchant API — Create a customer-initiated payment** for the complete request schema, validation rules, and examples. {% hint style="info" %} Calculate the payment amount on your server. Do not trust an amount supplied only by browser or mobile client code. {% endhint %} #### 2. Store the Payment ID The create-payment response identifies the payment and provides the URL used to open Hosted Checkout. Before redirecting the customer, store the Payment ID against your merchant order. You will need it to: * Retrieve the current payment status. * Process callback notifications. * Find the payment in the Merchant Portal. * Reconcile the payment with the order. * Investigate the transaction with Support. {% hint style="info" %} **Store the Payment ID before redirecting the customer.** {% endhint %} Use a unique merchant order number or reference for each order to make reconciliation and troubleshooting easier. *** #### 3. Redirect the customer Redirect the customer’s browser to the checkout URL returned by the Gateway. Use the URL exactly as returned. Do not construct, modify, or reuse a Hosted Checkout URL for another order. On Hosted Checkout, the customer can: 1. Review the payment information. 2. Choose an available payment method. 3. Enter or confirm their payment details. 4. Complete authentication where required. 5. Return to your website or application. The page is hosted by the Gateway and is designed to work across supported desktop, tablet, and mobile devices. The payment methods shown to the customer can depend on: * The merchant agreement and shop configuration. * Currency and market. * Customer country. * Device and browser support. * Availability of the external bank, wallet, or provider. See **Payment Methods** for method-specific availability, authentication, statuses, and customer journeys. ### Handle the payment result Hosted Checkout uses two separate return paths. | Browser return | Callback notification | | --------------------------------------------------- | ----------------------------------------------------- | | Returns the customer to your website or application | Notifies your backend that the payment status changed | | Used for customer experience | Used to trigger order processing | | Depends on the customer’s browser | Delivered independently of the customer | | The customer may never return | Failed delivery is retried | | Not payment confirmation | Must be followed by a payment information lookup | The customer may close the browser, lose their connection, or leave the payment journey without returning to your website. Your order must therefore not depend on the browser redirect alone. #### When the customer returns Use the return page to show an appropriate message, such as: * Payment successful. * Payment is still processing. * Payment cancelled. * Payment failed. Your return page may ask your backend for the latest known order status. It must not independently fulfil the order merely because the customer reached the page. When the final status is not yet available, keep the order pending and tell the customer that confirmation is still in progress. #### When you receive a callback After receiving a callback: 1. Acknowledge the notification. 2. Retrieve the current payment information through the authenticated API. 3. Verify that the payment belongs to the expected order and shop. 4. Update the order from the confirmed payment status. 5. Ensure that fulfilment is performed only once. A callback identifies the payment and its new status. The Gateway documentation instructs merchants to retrieve the up-to-date payment details after receiving the notification. Unsuccessful callback deliveries are retried with increasing delays. Do not use the callback payload alone as the source of truth. Callback processing, retries, duplicate delivery, idempotency, and reconciliation are covered in **Callback Notifications**. ### Fulfil the order Fulfil the order only after retrieving and confirming the appropriate paid status. | Confirmed condition | Recommended action | | ------------------------------------------ | -------------------------------------- | | Card payment is captured | Treat the order as paid | | Pay by Bank payment is settled | Treat the order as paid | | Payment is still processing | Keep the order pending | | Payment is authorized but not captured | Do not treat it as fully paid | | Payment is cancelled, failed, or abandoned | Do not fulfil | | Payment is refunded | Update the order and financial records | The paid state differs between payment methods. For Pay by Bank, for example, the payment uses `SETTLED` rather than the card-specific `AUTHORIZED` and `CAPTURED` model. See: * **Payment Statuses** * **Cards** * **Pay by Bank** * **Callback Notifications** ### Customer experience and customization Hosted Checkout can be configured to reflect your visual identity within the options enabled for your shop. Depending on your configuration and access rights, customization can include: * Merchant logo. * Primary and secondary colours. * Supported fonts. * Button and corner styles. * Default language. * Payment-method visibility, ordering, and grouping. * Desktop and mobile preview. Customization is limited to the options provided by the Gateway. It does not allow changes to security controls, authentication flows, payment-processing logic, or provider-controlled interfaces. Hosted Checkout supports English, Latvian, Estonian, and Lithuanian in the initial solution scope. English is used as the fallback language. The page can select a supported language based on the configured preference or the customer’s browser or device locale. External screens can look different from Hosted Checkout. For example, a customer may be handed over to: * Their card issuer for a 3-D Secure challenge. * Their bank for Pay by Bank authentication. * A wallet provider such as PayPal, Apple Pay, or Google Pay. See **Merchant Portal — Checkout Page Builder** for the available configuration options. ### Test your integration Complete all development and validation in Sandbox before requesting Production activation. For Hosted Checkout, test at least: * A successful payment. * A declined or failed payment. * Customer cancellation. * Customer abandonment. * A customer who pays but does not return to your website. * Callback delivery and payment-status retrieval. * Every payment method enabled for your shop. * Desktop and mobile customer journeys. The general integration checklist also requires testing redirects, callback notifications, order confirmation, refunds, captures, reversals, and duplicate handling where applicable. Sandbox provides a limited hosted checkout experience and does not necessarily include every Production feature or payment method. See **Testing/Sandbox Guide** for: * Test payment data. * Supported Sandbox payment methods. * Authentication scenarios. * Expected statuses. * Error and cancellation cases. * Callback resilience testing. ### Go live Before processing live payments: * Complete the **Go-live checklist**. * Activate and configure the Production shop. * Generate Production credentials. * Configure the Production return and Callback URLs. * Confirm the enabled payment methods and currencies. * Review Hosted Checkout branding and languages. * Complete a controlled low-value Production payment. * Verify callback processing, order updates, and reconciliation. Do not use Sandbox credentials or endpoints in Production. ### Next steps Continue with the documentation relevant to your implementation: * **Merchant API** — create payments and retrieve payment information. * **Callback Notifications** — process payment-status changes reliably. * **Testing/Sandbox Guide** — test data and end-to-end scenarios. * **Payment Methods** — cards, wallets, and Pay by Bank. * **Payment Statuses** — understand payment lifecycle and merchant actions. * **Merchant Portal — Shop Settings** — credentials and technical URLs. * **Merchant Portal — Checkout Page Builder** — branding and checkout configuration. * **Security and Compliance** — PCI DSS and merchant security responsibilities. * **Go-live checklist** — prepare your integration for Production. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.ecommerce.seb.ee/integration/hosted-checkout.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.