> 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/guides/sandbox/test-scenarios/integration-and-order-handling.md). # Integration & Order Handling Validate that the merchant’s own system handles payments correctly. ## Successful Payment Use Sandbox payment methods to verify that your integration handles successful payments correctly. Update orders and trigger fulfilment only once. Use the confirmed payment status as the source of truth. Do not rely on browser redirects or customer returns to your website. ### How Successful Payments Should Be Processed Consider a payment successful only after its final status is confirmed through the Payment API. 1. A **Webhook (also referred to as callback notifications)** is received. 2. The payment status is verified using the Payment API. 3. The order status is updated. 4. Fulfilment is triggered. Recommended flow: ``` Pending Order ↓ Customer Completes Payment ↓ Webhook Received ↓ GET /egw/v1/payments/{paymentId} ↓ Verify Final Payment Status ↓ Update Order Status ↓ Fulfil Order Once ``` If a Webhook cannot be delivered, reconcile pending payments through the Payment API. Do not leave a confirmed payment unprocessed because its Webhook was missed. ### Payment Statuses to Process Different payment methods can reach different successful statuses. | Payment method | Successful status | | -------------- | ----------------- | | Card | `Captured` | | Google Pay | `Captured` | | Apple Pay | `Captured` | | Click to Pay | `Captured` | | Pay by Bank | `Settled` | Verify the final status before updating the order. ### Card, Google Pay, Apple Pay, and Click to Pay The customer successfully completes the payment journey. #### Validation 1. Create a new order in Pending status. 2. Complete a successful payment. 3. Verify that a Webhook is received. 4. Retrieve the latest payment details. ```http GET /egw/v1/payments/{paymentId} ``` 5. Verify the payment status. 6. Update the order status. 7. Fulfil the order. Example: ```http GET https://sandbox-api.ecomm.api.tietoevry.com/egw/v1/payments/019fffc4-17c4-7922-8be4-23cc21348aa1 ``` #### Expected Result * The payment status is `Captured`. * A Webhook is received. * The payment ID is stored. * The order changes from Pending to Paid. * Fulfilment runs exactly once. * Duplicate fulfilment does not run. ### Pay by Bank The customer successfully completes a Pay by Bank payment. #### Validation 1. Create a new order in Pending status. 2. Complete a successful Pay by Bank payment. 3. Verify that a Webhook is received. 4. Retrieve the payment details using the Payment API. 5. Verify the final payment status. 6. Update the order status. 7. Fulfil the order. #### Expected Result * The payment status is `Settled`. * A Webhook is received. * The payment ID is stored. * The order changes from Pending to Paid. * Fulfilment runs exactly once. * Duplicate fulfilment does not run. ### Payment Verification Example Example successful payment response: ```json { "paymentId": "019fffc4-17c4-7922-8be4-23cc21348aa1", "paymentStatus": "CAPTURED", "orderNumber": "09a4efab-1365-409d-bb5f-a03a481c0b0d", "paidAmount": { "currency": "EUR", "amount": "38.00" } } ``` Verify that: * `paymentId` is present. * `paymentStatus` contains the expected successful status. * `paidAmount` matches the order amount. * `orderNumber` links to the merchant order. ### Merchant Validation Checklist Verify that: * Webhooks are received successfully. * The Payment API verifies the payment status: ```http GET /egw/v1/payments/{paymentId} ``` * The payment ID is stored. * The final payment status is stored. * The order changes from Pending to Paid. * Fulfilment runs exactly once. * Duplicate Webhooks do not cause duplicate fulfilment. * Duplicate Webhooks do not create duplicate shipments. * Duplicate Webhooks do not generate duplicate customer notifications. * Pending payments are reconciled when Webhook delivery fails. ## 3DS Authentication Use sandbox card payments to verify payment flows that require EMV 3DS authentication. ### How EMV 3DS affects payment status EMV 3DS does not have a separate payment status. A payment remains `Initialized` while the customer completes checkout and interacts with the 3DS challenge. The payment outcome is determined after authentication and issuer authorization complete. | Status | Description | | ------------ | ----------------------------------------------------------------------- | | `Authorized` | 3DS authentication succeeded and a two-step authorization was approved. | | `Captured` | 3DS authentication succeeded and a purchase payment was approved. | | `Failed` | Authentication or issuer authorization failed. | | `Abandoned` | The customer did not complete the 3DS challenge before it expired. | | `Cancelled` | The payment was cancelled before completion. | ### Successful authentication The customer completes the 3DS challenge and the payment is approved. #### Validation 1. Create a new order in Pending status. 2. Start a card payment that requires 3DS authentication. 3. Complete authentication successfully. 4. Verify that your Webhook endpoint receives a notification. 5. Retrieve the latest payment details: ```http GET /egw/v1/payments/{paymentId} ``` 6. Verify the final status, update the order, and fulfil it. #### Expected result * The payment changes from `Initialized` to `Captured`. * Your Webhook endpoint receives a notification. * The merchant system stores the payment ID. * The Payment API returns the final payment status. * The order changes from Pending to Paid. * Fulfilment runs exactly once. ### Successful authentication with two-step payments Some merchants use separate authorization and capture operations. Successful 3DS authentication results in an authorized payment. Keep the order Pending or reserve inventory until capture completes. Fulfil the order only after the payment reaches `Captured`. ``` Initialized ↓ 3DS authentication successful ↓ Authorized ↓ Capture payment ↓ Captured ``` #### Validation 1. Create a new order in Pending status. 2. Complete a card payment that requires 3DS authentication. 3. Verify that the payment reaches `Authorized`. 4. Keep the order Pending or reserve inventory. 5. Capture the payment: ```http PATCH /egw/v1/payments/{paymentId}/capture ``` 6. Retrieve the latest payment details. 7. Verify that the payment reaches `Captured`. 8. Update the order and fulfil it. #### Expected result * The payment changes from `Initialized` to `Authorized`. * The order remains Pending until capture succeeds. * The capture request succeeds. * The payment changes from `Authorized` to `Captured`. * The Payment API verifies the payment status. * The order changes from Pending to Paid. * Fulfilment runs exactly once. * Duplicate captures do not cause duplicate fulfilment. ### Authentication failed The customer fails the 3DS challenge, or the issuer declines authorization. #### Validation 1. Create a new order in Pending status. 2. Start a card payment that requires 3DS authentication. 3. Trigger a failed-authentication scenario. 4. Verify that your Webhook endpoint receives a notification. 5. Retrieve the latest payment details using the Payment API. 6. Verify the final payment status. #### Expected result * The payment changes from `Initialized` to `Failed`. * Your Webhook endpoint receives a notification. * The order remains Pending or Unpaid. * Fulfilment does not start. * No shipment or invoice is created. * The customer can retry the payment. ### Authentication abandoned The customer leaves the authentication flow before completing the challenge. The payment becomes `Abandoned` after the gateway applies its timeout or expiration handling. #### Validation 1. Create a new order in Pending status. 2. Start a card payment that requires 3DS authentication. 3. Close the browser or leave the authentication page. 4. Wait for the Webhook, or reconcile the pending payment after the applicable timeout. 5. Retrieve the latest payment details using the Payment API. 6. Verify that the final status is `Abandoned`. #### Expected result * The payment changes from `Initialized` to `Abandoned` after timeout or expiration handling. * The order remains Pending or Unpaid. * Fulfilment does not start. * No shipment or invoice is created. ### Payment cancelled The customer cancels the payment before completion. #### Validation 1. Create a new order in Pending status. 2. Start a card payment that requires 3DS authentication. 3. Cancel the payment. 4. Retrieve the payment using the Payment API. 5. Verify the final payment status. #### Expected result * The payment changes from `Initialized` to `Cancelled`. * The order remains Pending or Unpaid. * Fulfilment does not start. * No shipment or invoice is created. ### Merchant validation checklist Verify that: * The payment remains `Initialized` during the 3DS flow. * Webhooks are received and processed. * The Payment API verifies the final payment status: ```http GET /egw/v1/payments/{paymentId} ``` * Successful payments result in `Authorized` or `Captured`. * Failed authentication results in `Failed`. * Incomplete authentication results in `Abandoned`. * Cancelled payments result in `Cancelled`. * Orders are fulfilled only after successful payment confirmation. * Failed, abandoned, and cancelled payments never trigger fulfilment. {% hint style="warning" %} Use Webhooks with payment-status verification to determine the payment outcome. Never use a browser redirect as the sole indicator of payment success. {% endhint %} ## Failed payments Use Sandbox payment methods to verify failed, cancelled, and incomplete payment handling. Treat a payment as unsuccessful only after verifying its final status through the Payment API. Prevent order fulfilment for unsuccessful payments. Allow the customer to retry when appropriate. ### How failed payments should be processed Confirm payment failures through Webhooks and payment-status verification. Recommended flow: ``` Pending Order ↓ Payment Attempt ↓ Webhook Received ↓ GET /egw/v1/payments/{paymentId} ↓ Verify Final Payment Status ↓ Keep Order Unpaid ↓ Allow Retry ``` ### Failed payment The issuer rejects the payment, or processing fails. #### Validation 1. Create a new order in Pending status. 2. Trigger a failed payment scenario. 3. Verify that a Webhook is received. 4. Retrieve the payment details: ```http GET /egw/v1/payments/{paymentId} ``` 5. Verify the final payment status. 6. Review order processing. #### Expected result * The payment status is `Failed`. * The payment ID is available. * A Webhook is received. * The order remains Pending or Unpaid. * Fulfilment does not start. * No shipment or invoice is created. * The customer can attempt payment again. ### Cancelled payment The customer or merchant cancels the payment before completion. #### Validation 1. Create a new order in Pending status. 2. Start the payment flow. 3. Cancel the payment. 4. Retrieve the payment details using the Payment API. 5. Verify the final payment status. #### Expected result * The payment status is `Cancelled`. * The order remains Pending or Unpaid. * Fulfilment does not start. * No shipment is created. * The customer can start a new payment attempt. ### Abandoned payment The customer leaves the payment flow without completing it. #### Validation 1. Create a new order in Pending status. 2. Start the payment flow. 3. Leave the payment or authentication page before completion. 4. Retrieve the payment details using the Payment API. 5. Verify the final payment status. #### Expected result * The payment status is `Abandoned`. * The order remains Pending or Unpaid. * Fulfilment does not start. * No shipment or invoice is created. * The customer can start a new payment attempt. ### Payment verification example Verify the final payment state: ```http GET /egw/v1/payments/{paymentId} ``` Example unsuccessful payment response: ```json { "paymentId": "019fffc4-17c4-7922-8be4-23cc21348aa1", "paymentStatus": "FAILED" } ``` | Payment status | Merchant action | | -------------- | ------------------------ | | `Failed` | Do not fulfil the order. | | `Cancelled` | Do not fulfil the order. | | `Abandoned` | Do not fulfil the order. | ### Webhooks Webhooks inform your system when a payment status changes. Use each Webhook as a trigger to retrieve and process the latest payment state. This guidance applies to: * Unified Merchant API * API Client SDK * Hosted Checkout * Web Plugin * Mobile SDK Always retrieve the latest payment status through the Payment API before updating an order or triggering fulfilment. {% hint style="info" %} Web Plugins process Webhooks as part of their standard functionality. For other integrations, implement a Webhook endpoint. {% endhint %} #### Configure Webhooks Configure a Callback URL for each shop to receive automatic payment-status notifications. The endpoint must be publicly accessible over HTTPS. **Merchant Portal** 1. Sign in to the Merchant Portal. 2. Navigate to **Settings → Shop Settings**. 3. Select the required shop. 4. Select **Edit Agreement**. 5. Open **Technical Information**. 6. Enter the endpoint in **Callback URL**. 7. Submit the changes for approval. Example: ``` https://merchant.example.com/payment-callback ``` Configure Sandbox and Production Callback URLs separately. The gateway sends a notification whenever the payment status changes. #### Recommended Webhook processing flow ``` Webhook Received ↓ Extract Payment ID ↓ GET /egw/v1/payments/{paymentId} ↓ Verify Payment Status ↓ Update Order ↓ Trigger Business Actions ``` Treat the Webhook as a payment-verification trigger. Treat the Payment API response as the source of truth. --- # 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/guides/sandbox/test-scenarios/integration-and-order-handling.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.