Current Situation¶

sequenceDiagram
    autonumber
    participant U as User
    participant B as Prestashop Backend


    %% Pre-Checkout
    U ->   B: <a href="pre-checkout-add-to-cart-flow">📋 Pre-Checkout - Add to cart flow</a> 
    activate B

    U ->>  B: Go to Checkout - Redirect to /checkout?isPaymentStep=true
    B ->>  B: Is User logged in? - (FrontControllerCore 'is_logged' => $this->context->customer->isLogged())
    B -->> U: Response checkout isPaymentStep=true page
    note over B: 📊 <a href="MT-31">MT-31</a>: page_views - checkout_step_login_guest

    %% Checkout Step 1: Authentication
    U ->   B: <a href="checkout-step-1-authentication-flow">📋 Checkout step 1 - Authentication flow</a>

    %% Checkout Step 2: Payment Selection
    U ->   B: <a href="checkout-step-2-payment-selection">📋 Checkout step 2 - Payment selection</a>

    %% Checkout Step 3: Payment
    alt Checkout step 3 - Payment
        note over U, B: User selected Bank transfer
        U ->  B: <a href="bank-transfer">📋 Payment method - Bank transfer</a>
    else
        note over U, B: User selected IDEAL
        U ->  B: <a href="ideal">📋 Payment method - IDEAL</a>
    else
        note over U, B: User selected PayPal
        U ->  B: <a href="paypal">📋 Payment method - PayPal</a>
    else
        note over U, B: User selected Maestro
        U ->  B: <a href="maestro">📋 Payment method - Maestro (TODO)</a>
        note right of U: TODO: Flow needs verification!
    else
        note over U, B: User selected Klarna
        U ->  B: <a href="klarna">📋 Payment method - Klarna</a>
    else
        note over U, B: User selected Creditcard (Visa & MasterCard)
        U ->  B: <a href="creditcard-visamastercard-card-selection">📋 Payment method - Creditcard - Card Selection</a>
        U ->  B: <a href="creditcard-visamastercard-payment-flow">📋 Payment method - Creditcard - Payment Flow</a>
    else
        note over U, B: User selected Mistercash (Bancontact)
        U ->  B: <a href="mistercash-bancontact">📋 Payment method - Bancontact - Card Selection & Order</a>
        U ->  B: <a href="bancontact-qr-desktop">📋 Payment method - Bancontact - QR Code (Desktop)</a>
        U ->  B: <a href="bancontact-app-mobile">📋 Payment method - Bancontact - App (Mobile)</a>
        U ->  B: <a href="bancontact-card-payment">📋 Payment method - Bancontact - Card Flow</a>
    else
        note over U, B: User selected Apple Pay & Google Pay
        note right of U: To be Implemented!
    end

    %% Checkout Step 4: Validation & Completion
    U ->  B: <a href="checkout-step-4-proceed-validation-and-confirmation">📋 Checkout step 4 - Proceed, Validation and Confirmation</a>


    deactivate B

sequenceDiagram
    autonumber
    participant U as User
    participant B as Prestashop Backend

    %% Pre-Checkout
    alt Add to cart
        note over U,B: Add to cart - using PDP or PLP

        U ->> B: Add to Cart - Ajax POST Request to /?rand=X -> (cart controller add)
        activate B
        note over B: 📊 <a href="MT-9">MT-9</a>: cart - add
        B -->> U: Response with updated cart
        U ->>  B: Go to Cart - Redirect to /checkout (or like /winkelwagen)
        B -->> U: Response cart page
        note over B: 📊 <a href="MT-34">MT-34</a>: page_views - cart
        U ->>  B: Get cart details - Ajax POST Request to /?rand=X -> (cart controller)
        B -->> U: Response cart details
    else
        note over U,B: Add to cart - using My account reorder
        U ->>  B: Go to My account - Redirect to /mijn-account#account
        B -->> U: Response My account page and data
        U ->>  B: Go to My account Order History - AccountManagment.vue uiTabActive from 'account' -> 'order-history'
        U -->> U: Show 'order-history' tab
        U ->>  B: Reorder add to cart - Ajax POST Request /module/brekz_reorder/ajax containing the product
        note over B: 📊 <a href="MT-92">MT-92</a>: ajax: cart - add
        B -->> U: Response success
        U ->>  B: Get cart details - GET Request to /module/brekz_my_account_api/cart?action=get
        B -->> U: Response cart details
    end

sequenceDiagram
    autonumber
    participant U as User
    participant B as Prestashop Backend

    %% Checkout Step 1: Authentication


    alt Authentication - only if Not Logged In
        B -->> U: Show Authentication method options
        note over B: 📊 <a href="MT-13">MT-13</a>, <a href="MT-89">MT-89</a>: page_views - login_register_form
        activate B
        alt Authentication methods
            note over U,B: Authentication methods - Log In

            U ->>  B: Fill in e-mail address and password
            U ->>  B: Press login button - Send Ajax POST request to /authentication?rand=X (or like /aanmelden) with email and passwd

            break
                note right of U: Login attempt - Failed
                note over B: 📊 <a href="MT-58">MT-58</a> to <a href="MT-63">MT-63</a>: login - failed
                B -->> U: Response Error (example. 'The conmbination of username and password is not valid.')
                B -->> U: Show error on screen
                U -->  B: Go back to -> Checkout Step 1: Authentication
            end

            break
                note right of U: Login attempt - Succeeded
                note over B: 📊 <a href="MT-64">MT-64</a>: login - success
                B ->>  B: TODO - Combine carts in extra flow
                B -->> U: Redirect to /checkout - with new cart
                U -->  B: Go back to -> <a href='main-flow'>📋 Main flow - Go to Checkout - Redirect to /checkout?isPaymentStep=true</a>
            end
        else
            note over U,B: ROUGH: Authentication methods - Register new customer

            U ->>  B: Press register button - Send POST request to /authentication (or like /aanmelden)
            B -->> U: Response success
            B -->> U: Show register form with password (and country selector if the country is Netherlands, France or Luxembourg)
            U ->>  B: Fill in registration form
            U ->>  B: Submit registration form - Send Ajax POST request to /authentication?rand=X (or like /aanmelden) with all the registration data
            note over B: 📊 <a href="MT-65">MT-65</a> to <a href="MT-88">MT-88</a>: register - failed (various)
            note over B: 📊 <a href="MT-69">MT-69</a>, <a href="MT-86">MT-86</a>: register - success
            note over B: 📊 <a href="MT-140">MT-140</a>: registration - attempt
            note over B: 📊 <a href="MT-141">MT-141</a>, <a href="MT-142">MT-142</a>: registration - failed (Turnstile)
            note over B: 📊 <a href="MT-143">MT-143</a>, <a href="MT-144">MT-144</a>: registration - turnstile_success/success
            B ->>  B: ROUGH: Create Customer and set correct context for cart, customer etc.
            B -->> U: ROUGH: Response success - set static token
            B -->> U: ROUGH: Send Ajax POST request to /checkout?rand=X with getAddressBlockAndCarriersAndPayments and static token
            B ->>  B: ROUGH: Check if customer has an address and return some html and tpl blocks
            B -->> U: ROUGH: Response success - Reload page while being logged in - location.reload()
            B -->> U: Show payment method selection step
        else
            note over U,B: ROUGH: Authentication methods - Register guest customer

            U ->>  B: Press register button - Send POST request to /authentication (or like /aanmelden)
            B -->> U: Response success
            B -->> U: Show register form without password (and country selector if the country is France or Luxembourg)
            U ->>  B: Fill in registration form
            U ->>  B: Submit registration form - Send Ajax POST request to /authentication?rand=X (or like /aanmelden) with all the registration data
            note over B: 📊 <a href="MT-65">MT-65</a> to <a href="MT-88">MT-88</a>: register - failed (various)
            note over B: 📊 <a href="MT-69">MT-69</a>, <a href="MT-86">MT-86</a>: register - success
            note over B: 📊 <a href="MT-140">MT-140</a>: registration - attempt
            note over B: 📊 <a href="MT-141">MT-141</a>, <a href="MT-142">MT-142</a>: registration - failed (Turnstile)
            note over B: 📊 <a href="MT-143">MT-143</a>, <a href="MT-144">MT-144</a>: registration - turnstile_success/success
            B ->>  B: Create Guest Customer and set correct context for cart, customer etc.
            B -->> U: Response success - set static token
            B -->> U: Send Ajax POST request to /checkout?rand=X with getAddressBlockAndCarriersAndPayments and static token
            B ->>  B: Check if customer has an address and return some html and tpl blocks
            B -->> U: Response success - Reload page while being logged in - location.reload()
            B -->> U: Show payment method selection step
        else
            note over U,B: Authentication methods - Forgot password

            U ->>  B: Go to forgot password - Redirect to /password-recovery (or like /wachtwoord-vergeten)
            B -->> U: Response password reset page
            note over B: 📊 <a href="MT-57">MT-57</a>: page_views - password_recovery
            U ->>  B: Fill in e-mail address
            U ->>  B: Send request for password reset - Form POST request to /password-recovery (or like /wachtwoord-vergeten) with email
            note over B: 📊 <a href="MT-44">MT-44</a> to <a href="MT-56">MT-56</a>: password_forgotten - failed/success
            B -->> U: Send e-mail to filled in e-mail address
            U ->>  B: Open mailbox and open link - Open to https://{brekz url}/password-recovery?reset_token={reset_token}&id_customer={id_customer}
            B -->> U: Response change password page
            U ->>  B: Put in new password twice
            U ->>  B: Send request for new password - Form POST request to /password-recovery (or like /wachtwoord-vergeten) with reset_token, id_customer and new_password
            note over B: 📊 <a href="MT-52">MT-52</a>: password_forgotten - success-password-sent
            B -->> U: Response password has changed page
            break
                U -->  B: Go back to -> Checkout Step 1: Authentication
            end
        end
    end

    deactivate B

sequenceDiagram
    autonumber
    participant U as User
    participant B as Prestashop Backend

    activate B
    B ->>  B: Get active payment methods - (OrderOpcController -> docdatapayments->getActivePaymentMethods)
    B -->> U: Response checkout page with payment methods - (order-opc.tpl -> CheckoutPaymentStep.vue -> CheckoutSelectPayment.vue)
    note over B: 📊 <a href="MT-33">MT-33</a>: page_views - checkout_step_payment_methods

    U -->> U: Select payment method - (CheckoutSelectPayment.vue)

    alt Klarna - phone number required
        note over U,B: Klarna selected and no phone number on delivery address
        U -->> U: Submit button greyed out - (CheckoutPaymentStep.vue removes js-hook-submit-checkout class)
        U ->>  U: Click submit button - (order-opc.js blocks submit, shows error)
        U -->> U: Show phone number modal - (CheckoutPhoneNumberRequiredModal.vue)
        U ->>  B: Update address with phone - PUT /module/brekz_my_account_api/address?action=update
        B -->> U: Response success
        U -->> U: Submit button enabled - (CheckoutPaymentStep.vue adds js-hook-submit-checkout class)
    end

    U ->>  B: Submit checkout form - Form POST to /checkout with submitCheckout=true (order-opc.js)
    note over B: 📊 <a href="MT-35">MT-35</a>, <a href="MT-91">MT-91</a>: button_submit - to_payment
    B ->>  B: Store payment preferences in cookie - (OrderOpcController)

    alt Redirect to payment
        note over U,B: Creditcard selected
        B -->> U: Redirect to card payment page - /checkout?isPaymentStep=true&paymentMethod=creditcard
    else
        note over U,B: Bancontact selected
        B -->> U: Redirect to card payment page - /checkout?isPaymentStep=true&paymentMethod=bancontact
    else
        note over U,B: Other payment method selected
        B -->> U: Redirect to payment module - /module/docdatapayments/payment?pname=X
    end

    deactivate B

sequenceDiagram
    autonumber
    participant U as User
    participant B as Prestashop Backend
    participant CMS as CM SOAP Order/Payment API

    U ->>  B: Redirect to /module/docdatapayments/payment?pname=BANK_TRANSFER
    activate B
    B ->>  B: Validate order - (payment.php -> validateOrder)
    note over B: 📊 <a href="MT-43">MT-43</a>: order_as - customer
    B ->> CMS: Create payment - SOAP {soapBaseUrl} → create() with customer email (DocDataPaymentApi->createPayment)
    activate CMS
    CMS -->> B: Response with payment_cluster_key
    B ->> CMS: Start payment - SOAP {soapBaseUrl} → start() with email address (DocDataPaymentApi->startPaymentWithoutToken)
    note over B: 📊 <a href="MT-98">MT-98</a> to <a href="MT-118">MT-118</a>: cm - start_payment (various)
    note over B: 📊 <a href="MT-137">MT-137</a> to <a href="MT-139">MT-139</a>: StartPaymentResponse metrics
    CMS -->> B: Response with status AUTHORIZED
    deactivate CMS
    B -->> U: Redirect to /module/docdatapayments/proceed?key={payment_cluster_key}
    deactivate B

    U ->>  B: Redirect to Proceed - /module/docdatapayments/proceed?key={payment_cluster_key}

sequenceDiagram
    autonumber
    participant U as User
    participant B as Prestashop Backend
    participant CMR as CM REST API
    participant P as iDEAL

    U ->>  B: Redirect to /module/docdatapayments/payment?pname=IDEAL
    activate B
    B ->>  B: Validate and create shop order - (payment.php -> validateOrder)
    note over B: 📊 <a href="MT-43">MT-43</a>: order_as - customer
    B ->> CMR: Create payment order for shop order - POST {restBaseUrl}/orders (DocDataTokenRestApi->createOrder)
    activate CMR
    CMR -->> B: Response with order_key
    B ->> CMR: Start payment - POST {restBaseUrl}/orders/{order_key}/payments (DocDataTokenRestApi->startPayment)
    CMR -->> B: Response with redirect URL
    deactivate CMR
    B -->> U: Redirect to iDEAL

    U ->>  P: Pay the amount in iDEAL
    activate P
    P -->> U: Redirect to /module/docdatapayments/validation?key={order_key}
    deactivate P

    U ->>  B: Redirect to Validation - /module/docdatapayments/validation?key={order_key}
    deactivate B

sequenceDiagram
    autonumber
    participant U as User
    participant B as Prestashop Backend
    participant CMR as CM REST API
    participant P as PayPal

    U ->>  B: Redirect to /module/docdatapayments/payment?pname=PAYPAL
    activate B
    B ->>  B: Validate order - (payment.php -> validateOrder)
    note over B: 📊 <a href="MT-43">MT-43</a>: order_as - customer
    B ->> CMR: Create order - POST {restBaseUrl}/orders (class DocDataTokenRestApi->createOrder())
    activate CMR
    CMR -->> B: Response with order_key
    B ->> CMR: Start payment - POST {restBaseUrl}/orders/{order_key}/payments (class DocDataTokenRestApi->startPayment())
    CMR -->> B: Response with redirect URL
    deactivate CMR
    B -->> U: Redirect to PayPal

    U ->>  P: Pay the amount in PayPal
    activate P
    P -->> U: Redirect to /module/docdatapayments/validation?key={order_key}
    deactivate P

    U ->>  B: Redirect to Validation - /module/docdatapayments/validation?key={order_key}
    deactivate B

sequenceDiagram
    autonumber
    participant U as User
    participant B as Prestashop Backend
    participant CMS as CM SOAP Order/Payment API

    U ->>  B: Redirect to Proceed - /module/docdatapayments/proceed?key={payment_cluster_key}
    activate B

    B ->>  B: Validate payment key (32-char alphanumeric)
    B ->>  B: Load DDP_Transaction by payment_cluster_key
    B ->>  B: Load Order from transaction

    alt Order already paid
        B -->> U: Skip proceed, redirect to validation?key={key}&success=1
    end

    alt Payment method specific handling
        note over U,CMS: Creditcard / Bancontact (with 3DS data)
        note right of U: Returns with PaRes and MD from 3D Secure
        B ->>  B: Validate PaRes (Base64, max 5000 chars) and MD (0-10 digits)
        B ->> CMS: SOAP {soapBaseUrl} → proceedPayment() with threeDomainSecureAuthenticationResult
        note over B: 📊 <a href="MT-121">MT-121</a> to <a href="MT-136">MT-136</a>: cm - proceed_payment (various)
        activate CMS
        CMS -->> B: Payment authorization result
        deactivate CMS
    else
        note over U,CMS: Bank Transfer
        note right of U: No authentication data needed
        B ->>  B: Payment already AUTHORIZED at start
        B -->> U: Redirect to /module/docdatapayments/validation?key={key}&success=1
        U ->>  B: Redirect to Validation - /module/docdatapayments/validation?key={key}&success=1
    end

    B ->>  B: Check proceedPayment response

    alt Response validation
        note over U,CMS: proceedSuccess with AUTHORIZED status
        B ->> CMS: SOAP {soapBaseUrl} → status() - verify payment status
        activate CMS
        CMS -->> B: Response with confidenceLevel
        deactivate CMS

        alt Confidence level check
            note over U,B: confidenceLevel == ACQUIRER_APPROVED
            B -->> U: Redirect to /module/docdatapayments/validation?key={key}&success=1
            U ->>  B: Redirect to Validation - /module/docdatapayments/validation?key={key}&success=1
        else
            note over U,B: Payment not approved
            B -->> U: Redirect to /module/docdatapayments/validation?key={key}&canceled=1
            U ->>  B: Redirect to Validation - /module/docdatapayments/validation?key={key}&canceled=1
        end
    else
        note over U,CMS: proceedErrors or no response
        B ->> CMS: SOAP {soapBaseUrl} → status() - check if already AUTHORIZED
        activate CMS
        CMS -->> B: Response with authorization status
        deactivate CMS
        alt Already authorized
            B -->> U: Redirect to /module/docdatapayments/validation?key={key}&success=1
            U ->>  B: Redirect to Validation - /module/docdatapayments/validation?key={key}&success=1
        else
            B -->> U: Redirect to /module/docdatapayments/validation?key={key}&error=1&reason={reason}
            U ->>  B: Redirect to Validation - /module/docdatapayments/validation?key={key}&error=1&reason={reason}
        end
    end

    deactivate B

    U ->  B: <a href="validation-flow-all-payment-methods">📋 Continue to Validation Flow</a>

sequenceDiagram
    autonumber
    participant U as User
    participant B as Prestashop Backend
    participant P as Klarna

    note over U,P: User returns from Klarna hosted checkout
    P -->> U: Redirect to /module/docdatapayments/proceed?key={payment_cluster_key}
    U ->>  B: Redirect to Proceed - /module/docdatapayments/proceed?key={payment_cluster_key}

    loop Until (order->hasBeenPaid() && order->valid) == true
        note over U,B: Proceed (proceed.php)
        activate B
        B ->>  B: Validate payment key, load DDP_Transaction and Order
        alt Proceed check
            note over U,B: Order already paid (proceed.php:67)
            B -->> U: JSON { redirect_url: /module/docdatapayments/validation?key={key}&success=1 }
            U ->>  U: JavaScript handles redirect
            note right of U: Break loop
        else
            note over U,B: Order not yet paid (proceed.php:270)
            B ->>  B: Sleep 3 seconds
            B -->> U: JSON { redirect_url: /module/docdatapayments/proceedWaiting?key={key} }
            U ->>  U: JavaScript handles redirect
            U ->>  B: Redirect to ProceedWaiting - /module/docdatapayments/proceedWaiting?key={key}
        end
        deactivate B

        note over U,B: ProceedWaiting (proceedWaiting.php)
        activate B
        B ->>  B: Validate payment key, load DDP_Transaction and Order
        alt ProceedWaiting check
            note over U,B: Order already paid (proceedWaiting.php:89)
            B -->> U: Redirect to /module/docdatapayments/validation?key={key}&success=1
            note right of U: Break loop
        else
            note over U,B: Order not yet paid
            B -->> U: Display waiting page (proceed_waiting.tpl)
            U ->>  U: JavaScript auto-submits form
            U ->>  B: Redirect to Proceed - /module/docdatapayments/proceed?key={key}
        end
        deactivate B
    end

    U ->>  B: Redirect to Validation - /module/docdatapayments/validation?key={key}&success=1

    U ->  B: <a href="validation-success">🔄 Validation: Success</a>

sequenceDiagram
    autonumber
    participant U as User
    participant B as Prestashop Backend
    participant CMS as CM SOAP API

    U ->>  B: Redirect to Validation - /module/docdatapayments/validation?key={key}
    activate B

    B ->>  B: Validate payment key, load DDP_Transaction and Order
    B ->> CMS: SOAP {soapBaseUrl} → status() - get payment report (validation.php)
    note over B: 📊 <a href="MT-94">MT-94</a>, <a href="MT-95">MT-95</a>: cm - validation
    activate CMS
    CMS -->> B: Payment report with confidenceLevel, totalRegistered, totalCaptured
    deactivate CMS
    note right of B: If multiple payments, find first non-CANCELED with confidenceLevel set

    alt Route by URL parameter or payment method
        note over U,B: success=1
        U ->  B: <a href="validation-success">🔄 Validation: Success</a>
    else
        note over U,B: canceled=1 OR authorization.status == CANCELED
        U ->  B: <a href="validation-canceled">🔄 Validation: Canceled</a>
    else
        note over U,B: error=1
        U ->  B: <a href="validation-error">🔄 Validation: Error</a>
    else
        note over U,B: Payment method: BANK_TRANSFER
        U ->  B: <a href="validation-bank-transfer">🔄 Validation: Bank Transfer</a>
    else
        note over U,B: No parameter (direct REST return: iDEAL, PayPal)
        U ->  B: <a href="validation-rest">🔄 Validation: REST (iDEAL, PayPal)</a>
    end

    deactivate B