docs

Order Confirmation (hidden)

Introduction

The Order Confirmation endpoint starts the payment flow for the selected payment option and ongoing order. It should be called as the final step after collecting all necessary checkout data.

Prerequisites

Before calling this endpoint, ensure the following conditions are met:

  • 🛒 The order contains at least one item
  • 📦 A shipping address is set
  • 🧾 A billing address is set
  • 🚚 A shipping option has been selected
  • 💳 A payment option has been selected

Response Behavior

  • On success, the endpoint will return order confirmation data.
  • The client is responsible for processing this data, which typically includes:
    • Redirecting the customer to the order success page
    • Or redirecting the customer to an external payment page (depending on the PSP)

Referer Property

Referer property is used by external payment providers to redirect the customer back to the checkout page in case of errors. It must be set to the current checkout URL

PSP Redirect (External Payment Page)

For some payment methods, the customer must be redirected to an external payment service provider (PSP) page to complete the transaction.

This scenario depends on the integration type of the payment method.

Implementation Details

  • The response from the Order Confirmation endpoint contains an orderConfirmation object.
  • This includes:
    • The redirect URL
    • The HTTP method to use (typically GET or POST)

Post-Payment Behavior

  • Successful Payments:
    The customer is redirected to your order success page.
  • Failed or Cancelled Payments:
    The customer is redirected back to the checkout page, using the referer value sent during confirmation.
  • In this case, the next PUT /state call will:
    • Include a notification about the error
    • Optionally disable the failed payment method based on error type

OSP Redirect (On-Site Payment)

For on-site payment methods (e.g., credit card forms processed via a frontend SDK), the customer does not need to leave the checkout.

  • The Order Confirmation endpoint still returns an orderConfirmation object.
  • Instead of an external redirect, it includes:
    • A redirectUrl pointing to your configured order success page
    • The httpMethod set to GET

Error Handling

The Order Confirmation endpoint may fail in certain scenarios (e.g., risk checks, invalid data, or PSP errors).

  • A notification will be included in the state response.
  • This notification should be clearly presented to the customer (e.g., as an alert or inline error).
  • The related payment method may be disabled based on the type of error (e.g., fraud detection, payment rejection).