Complete Ealyx SDK Integration Guide

This guide provides everything needed to integrate Ealyx trade-in payment solutions into your PHP e-commerce platform. Follow these steps sequentially for a complete implementation. Note that this guide does not enter into the details of error states, exception handling, logging, and other best practices.

1. Overview & Prerequisites

Ealyx lets merchants offer their customers the option to trade in used items as payment for new purchases. The integration involves four main phases which are covered in section 3, Shopper Journey Implementation:

1. Discovery - Display trade-in teasers across your site
2. Valuation - Customer values their device via Ealyx WebApp
3. Payment - Process payment with or without Ealyx Pay
4. Post-Purchase - Sync order status changes with Ealyx

System Requirements for PHP SDK

Requirement	Details
PHP Version	7.4.0 or newer
Database	MySQL / MariaDB (out of the box)
Extensions	PDO (MySQL), JSON, cURL
HTTPS	Required for production

2. Setup & Installation

Get Sandbox Credentials

Contact your Ealyx account manager or email info@ealyx.com with:

• Company name and technical contact
• Webhook base URL (staging/production)
• Integration timeline

You'll receive:

• Sandbox environment URL
• ClientId and ClientSecret
• Username and Password

Keep your credentials secure and do not expose them to the public. Once you have completed the integration, you can request production credentials from your Ealyx account manager.

Backend Installation

Step 1: Install PHP SDK

Extract the Ealyx SDK zip to your project root:

/my-project/
├── vendor/
├── composer.json
├── lib/                  <--- Extract SDK here
│   └── ealyx-php-sdk/

Add to composer.json (replace 1.2 with the version number of the SDK):

{
  "repositories": [
    {
      "type": "path",
      "url": "lib/ealyx-php-sdk",
      "options": { "symlink": false }
    }
  ],
  "require": {
    "ealyx/php-sdk": "1.2"
  }
}

Run: composer update ealyx/php-sdk

Step 2: Create Configuration

Create config/env.php (keep out of version control):

<?php
return [
  // Sandbox URLs (change for production)
  'ASSETS_URL' => 'https://cdn.stg.ealyx.tech',
  'API_BASE_URL' => 'https://api.stg.ealyx.tech',

  // Database
  'DB_HOST' => '127.0.0.1:3306',
  'DB_NAME' => 'your_database_name',
  'DB_USER' => 'username',
  'DB_PASS' => 'password',

  // Credentials (optional - can set via admin panel)
  'USERNAME' => 'your_username',
  'PASSWORD' => 'your_password',
  'CLIENT_ID' => 'your_client_id',
  'CLIENT_SECRET' => 'your_client_secret',
];

Step 3: Initialize SDK and Perform Initial Login

In your application bootstrap (src/BootstrapApp.php):

<?php

require_once __DIR__ . '/../vendor/autoload.php';

use EalyxSDK\Bootstrap;
use EalyxSDK\Models\LoginCredential;
use EalyxSDK\Exceptions\SDKException;
use EalyxSDK\Core\Config\EnvKeys;

$configPath = __DIR__ . '/../config/env.php';
$override = [Bootstrap::FILE_ENV_PATH_KEY => $configPath];

try {
    // SDK automatically creates ealyx_configuration table
    $serviceContainer = Bootstrap::init($override);
    $loginService = $serviceContainer->getLoginService();

    // Perform initial login (only needed once, during setup)
    $env = $serviceContainer->getEnv();
    $credential = new LoginCredential(
        $env->get(EnvKeys::CLIENT_ID),
        $env->get(EnvKeys::CLIENT_SECRET),
        $env->get(EnvKeys::USERNAME),
        $env->get(EnvKeys::PASSWORD)
    );

    $loginResult = $loginService->login($credential);
    echo "Ealyx SDK initialized and authenticated successfully!";

} catch (SDKException $e) {
    error_log("Ealyx authentication failed: " . $e->getMessage());
    die("Authentication error - check credentials");
} catch (\Exception $e) {
    error_log("SDK Init failed: " . $e->getMessage());
    die("System configuration error");
}

Important: The login() call should only be run once during initial setup, not on every page load, since it's deliberately slow. After successful login, tokens are stored in the database and automatically managed.

Frontend Installation

Add this to your base template before </body>:

<?php
use EalyxSDK\Bootstrap;
use EalyxSDK\Models\FrontEndConfiguration;

$serviceContainer = Bootstrap::init();
$shopConfig = new FrontEndConfiguration([
  'browserCallbackBase' => "https://yoursite.com/ealyx/callbacks",
  'confirmUrl' => "https://yoursite.com/order-success",
]);
echo $serviceContainer->getStaticAssets()->loadFrontEndSDK($shopConfig);

Alternative Manual Configuration:

<script>
  window.ealyxConfiguration = {
    merchantId: 'your_merchant_id',
    browserCallbackBase: 'https://yoursite.com/ealyx/callbacks',
    confirmUrl: 'https://yoursite.com/order-success',
    products: 'valuations+ep1' // Default is just 'valuations'
  };
  import('https://cdn.stg.ealyx.tech/v1/main.js')
    .then(module => { window.Ealyx = module.Ealyx; })
    .catch(err => console.error('Error loading Ealyx:', err));
</script>

3. Shopper Journey Implementation

Phase 1: Discovery - Display Teasers

Add teaser placeholders across your site:

<!-- Homepage banner -->
<div class="ealyx-teaser" data-type="banner"></div>

<!-- Product detail page -->
<div class="ealyx-teaser" data-type="product-widget"></div>

<!-- Cart page (both types) -->
<div class="ealyx-teaser" data-type="product-widget"></div>
<div class="ealyx-teaser" data-type="cart-summary"></div>

<!-- Checkout page -->
<div class="ealyx-teaser" data-type="cart-summary"></div>

<!-- Thank you page -->
<div class="ealyx-teaser" data-type="thank-you"></div>

Alternative 1: CSS Selector Injection

Without adding <div> tags to your HTML, you can display teasers using CSS selectors.

Configure selectors in EalyxSDK\Models\FrontEndConfiguration:

$shopConfig = new FrontEndConfiguration([
  ...
  'bannerCssSelector' => '#ealyx-banner-widget',
  'productWidgetCssSelector' => '#product-info-main .price-box',
  'cartSummaryCssSelector' => '#cart-summary .ealyx-discount-box',
  'thankYouCssSelector' => '#thank-you-page .ealyx-thankyou-widget'
]);
echo $serviceContainer->getStaticAssets()->loadFrontEndSDK($shopConfig);

The SDK automatically injects teasers into specified elements.

Alternative 2: CSS Selector Injection Manual

  window.ealyxConfiguration = {
    ...
    bannerCssSelector: "#ealyx-banner-widget",
    productWidgetCssSelector: "#product-info-main .price-box",
    cartSummaryCssSelector: "#cart-summary .ealyx-discount-box",
    thankYouCssSelector: "#thank-you-page .ealyx-thankyou-widget",
    ...
  };

Alternative 3: Targeted Placement

Use data-target to direct teasers into specific containers:

<!-- Teaser placeholder with target -->
<div class="ealyx-teaser"
     data-type="product-widget"
     data-target="#product-buybox-area">
</div>

<!-- Target container elsewhere on page -->
<div id="product-buybox-area">
  <!-- Teaser will be injected here -->
</div>

Phase 2: Valuation & Identification

When customers click "Calculate Discount", the valuation wizard opens in a modal window (iframe). If the shopper accepts the offer, the selected product and discount details are automatically reflected in the corresponding widget(s).

In case the shopper leaves the site without completing a purchase, the valuation can be used to try to reactivate the shopper, i.e. suggest to them that they should return to the site and complete the purchase. To be able to do so, the Ealyx frontend script will request some shopper data from your backend system.

Implement Shopper Data Endpoint

Create GET <browserCallbackBase>/shopper_data endpoint. This endpoint must return shopper session information if available. It must also return a session hash token, which is a unique string derived from the shopper's session identifier using a hash function, preferably with a salt.

Make sure to validate the request origin using a CORS policy, to prevent other sites from calling this endpoint and retrieving your shopper's personal data.

// Validate CORS origin
$origin = $_SERVER['HTTP_ORIGIN'] ?? '';
if (!isValidOrigin($origin)) { // Implement your own CORS policy!
    http_response_code(403);
    exit;
}

$sessionId = $_SESSION['session_id'] ?? null;
$hasSession = !empty($sessionId);

$response = [
    'customer' => null,
    'session_hash_token' => null
];

if ($hasSession) {
  if ($customer) {
      $response['customer'] = [
            'id' => $customer->getId(),
            'email' => $customer->getEmail(),
            'given_name' => $customer->getFirstName(),
            'family_name' => $customer->getLastName(),
            'phone' => $customer->getPhone(),
            // Optional additional fields:
            // date_of_birth
            // NIN
            // IBAN
            // street_address
            // street_address2
            // postal_code
            // region
            // country_code
            // city
            // country
            // mobile_phone
        ];
    }

    $response['session_hash_token'] = generateSessionHash($sessionId); // Never expose real session ID
};

header('Content-Type: application/json');
echo json_encode($response);

Alternatively, using the Ealyx PHP SDK you can simplify the integration with:

<?php

use EalyxSDK\Controllers\BrowserController;
use EalyxSDK\Models\Customer;

$browserController = new BrowserController(
    $serviceContainer->getEnv(),
    $serviceContainer->getSession(),
);

$sessionId = $_SESSION['session_id'] ?? null;

$ealyxCustomer = null;

if ($sessionId && $customer) {
  $ealyxCustomer = [
  'id' => $customer->getId(),
  'email' => $customer->getEmail(),
  'given_name' => $customer->getFirstName(),
  'family_name' => $customer->getLastName(),
  'phone' => $customer->getPhone(),
  // ... additional fields as needed
];
}

// Automatically outputs response using echo. NOTE: This starts a PHP session if not already started.
$browserController->handleShopperData($ealyxCustomer);

// Or, in case your framework doesn't support echo, retrieve the response and output it manually:
// $json = $browserController->shopperData($ealyxCustomer);
// $frameworkResponseManager->outputJson($json);

Note: The BrowserController uses PhpSessionHandler by default, but you can override it via:

use EalyxSDK\Bootstrap;
use YourNamespace\Session\CustomSessionHandler;

$serviceContainer = Bootstrap::init([
    Bootstrap::CLASS_SESSION_HANDLER_KEY => CustomSessionHandler::class
]);

using a custom class that extends EalyxSDK\Core\Session\AbstractSessionHandler.

Phase 3a: Payment via Ealyx Pay

Ealyx Pay is the "umbrella" or "abstract" payment method that allows the shopper to pay with their trade-in, through one of the concrete options that Ealyx offers. The Ealyx WebApp will guide the shopper through the payment process, and will offer the shopper the choice of one of the concrete options. You need to make a number of smallish integrations to make it all work: show the Ealyx Pay option at checkout, intercept the form submission to open the Ealyx WebApp, prepare the order for later confirmation (IPN), and handle the IPN. The necessary steps are described below.

Step 1: Show the Ealyx Pay option at checkout

You add the Ealyx Pay option to the payment methods list using the following code in the checkout page. Note that the data-module-name="ealyx" attribute is used to identify the Ealyx Pay option to the SDK.

<label>
  <input type="radio" name="payment_method" data-module-name="ealyx" value="ealyx_pay" />
  Pay with Ealyx
</label>

Step 2: Make the Ealyx Pay option show relevant information to the shopper

You listen for the Ealyx Pay option selection using the following code in the checkout page. Note that input[name="payment_method"] needs to refer to the name of the payment method input field. This listener allows the SDK to know when the Ealyx Pay option is selected and show relevant information to the shopper.

const paymentRadios = document.querySelectorAll('input[name="payment_method"]');
paymentRadios.forEach(radio => {
  radio.addEventListener("change", () => {
    const isEalyx = radio.value === "ealyx_pay";
    window.Ealyx?.updatePaymentSelected(isEalyx);
  });
});

Step 3: Intercept Form Submission to open the Ealyx Pay modal

You intercept the form submission to open the Ealyx Pay modal using the following code in the checkout page. Note that input[name="payment_method"] needs to refer to the name of the payment method input field. This interceptor allows the SDK to open the Ealyx Pay modal instead of submitting the form to the shop backend.

This code assumes that the form can only be submitted when all relevant T&C checkboxes are checked. If your submit button is always enabled, you need to modify the code to check for the T&C checkboxes.

document.querySelector("form").addEventListener("submit", function (e) {
  const selected = document.querySelector('input[name="payment_method"]:checked');
  const isEalyx = selected?.value === "ealyx_pay";

  if (isEalyx) {
    e.preventDefault();
    window.Ealyx?.openPayment(); // Launch Ealyx modal
    return false;
  }
});

Note: The window.ealyxConfiguration.confirmUrl property is used as the redirect URL after the Ealyx Pay payment is completed.

Step 4: Implement Purchase Data Endpoint

When the Ealyx Pay model opens, it needs to know the cart and purchase-related data to display to the shopper. To this end, you need to create a GET <browserCallbackBase>/purchase_data endpoint. This endpoint must return cart and purchase-related data and may include optional additional metadata via the available field.

Make sure to validate the request origin using your CORS policy to prevent other sites from calling this endpoint and retrieving your shopper's personal data and cart.

// Validate CORS origin — as before
// ...
$cart_id = $_SESSION['cart_id'] ?? null;
$hasCart = !empty($cart_id);

header('Content-Type: application/json');

if (!$hasCart) {
  echo json_encode(['purchase' => null]);
  die();
}

$response = [];
$response['purchase'] = [
  'cart' => [
    'id' => $cart->getId(),
    'currency' => 'EUR',
    'items' => [
        [
          'id' => 'ITEM_ID',
          'name' => 'ITEM_NAME',
          'description' => 'ITEM_DESCRIPTION',
          'url' => 'ITEM_URL',
          'quantity' => ITEM_QUANTITY,
          'price' => ITEM_PRICE * 100,     // Unit price without tax
          'tax' => ITEM_TAX * 100,         // Tax amount
          'total' => ITEM_TOTAL * 100      // price * quantity + tax
        ],
        // Additional items...
    ],
    'price' => $cart->getPrice() * 100, // Cart amount without discounts and without taxes
    'tax' => $cart->getTax() * 100, // Taxes only
    'discounts' => [
      [
        'id' => 'DISCOUNT_ID',
        'name' => 'DISCOUNT_NAME',
        'total' => DISCOUNT_AMOUNT * 100
      ],
      // Additional discounts...
    ],
    'total' => $cart->getTotal() * 100, // Price - discounts
  ]
];

if ($billing) {
    $response['purchase']['billing'] = [
      'given_name' => $billing->getFirstName(),
      'family_name' => $billing->getLastName(),
      'phone' => $billing->getPhone(),
      'address' => $billing->getAddress(),
      'city' => $billing->getCity(),
      'state' => $billing->getState(),
      'country_code' => $billing->getCountryCode(),
      'postal_code' => $billing->getPostalCode()
    ];
  }

if ($shipping) {
  $response['purchase']['shipping'] = [
    'address' => [
      'given_name' => $shipping->getGivenName(),
      'family_name' => $shipping->getFamilyName(),
      'phone' => $shipping->getPhone(),
      'address' => $shipping->getAddress(),
      'address2' => $shipping->getAddress2(),
      'city' => $shipping->getCity(),
      'state' => $shipping->getState(),
      'country_code' => $shipping->getCountryCode(),
      'country' => $shipping->getCountry(),
      'postal_code' => $shipping->getPostalCode(),
      'notes' => $shipping->getNotes(),
      'company' => $shipping->getCompany(),
      'vat_number' => $shipping->getVatNumber()
    ],
    'method' => [
      'name' => $shipping->getMethod(),
      'provider' => $shipping->getProvider(),
      'currency' => $shipping->getCurrency(),
      'price' => $shipping->getPrice() * 100,
      'tax' => $shipping->getTax() * 100,
      'total' => $shipping->getTotal() * 100 // 'price + tax'
    ]
  ];
}
if ($customer) {
  $response['purchase']['customer'] = [
      'id' => $customer->getId(),
      'email' => $customer->getEmail(),
      'given_name' => $customer->getFirstName(),
      'family_name' => $customer->getLastName(),
      'phone' => $customer->getPhone(),
      // ... optional fields
  ];
}
echo json_encode($response);

Alternatively, using the Ealyx PHP SDK you can simplify the integration with:

<?php

use EalyxSDK\Controllers\BrowserController;
use EalyxSDK\Models\BillingAddress;
use EalyxSDK\Models\Cart;
use EalyxSDK\Models\CartData;
use EalyxSDK\Models\CartDiscount;
use EalyxSDK\Models\CartItem;
use EalyxSDK\Models\Customer;
use EalyxSDK\Models\ShippingAddress;
use EalyxSDK\Models\ShippingInformation;
use EalyxSDK\Models\ShippingMethod;

$browserController = new BrowserController(
    $serviceContainer->getEnv(),
    $serviceContainer->getSession(),
);

$cart_id = $_SESSION['cart_id'] ?? null;
$hasCart = !empty($cart_id);

$cartData = null;

if ($hasCart) {
  $cartData = [
    'cart' => new Cart(
      'items' => [
        new CartItem(
          // populate cart item
        ),
        // Additional items...
      ]
      'discounts' => [
        new CartDiscount(
          // populate cart discount
        ),
        // Additional discounts...
      ]
      // populate cart data
    )
  ];
  if ($billing) {
    $cartData['billing'] = new BillingAddress(
      // populate billing data
    );
  }

  if ($shipping) { 
    $cartData['shipping'] = new ShippingInformation([
      'address' => new ShippingAddress([
        // populate address
      ]),
      'method' => new ShippingMethod([
        // populate method
      ])
    ]);
  }
  if ($customer) {
    $cartData['customer'] = new Customer(
      // populate customer info
    );
  }
}

// Automatically outputs response using echo.
$browserController->handlePurchaseData(
  new CartData($cartData),
  $available // Optional dynamic data
);

// Or, in case your framework doesn't support echo, retrieve the response and output it manually:
// $json = $browserController->purchaseData(new CartData($cartData), $available);
// $frameworkResponseManager->outputJson($json);

Step 5: Prepare order for later confirmation (IPN)

When (and if) the shopper completes the payment in the Ealyx Pay modal, the Ealyx backend will notify your backend via the POST <webhookBaseUrl>/order endpoint (as described in Step 6). You might need to prepare for this confirmation by creating a pending order on your backend system, and you might not want to do that too early. The Ealyx SDK will emit an event just before the request is sent to the payment gateway when the shopper completes the payment in the Ealyx Pay modal. Below is an example of how to listen for this event and create a pending order. Note that this is not mandatory from Ealyx's point of view, as long as you are able to handle the IPN.

window.addEventListener("ealyx-ready", () => {
    window.Ealyx.addReadyToPlaceOrderListener(() => {
      // Create pending order via AJAX
      fetch("/orders", {
        method: "POST",
        headers: { "Content-Type": "application/x-www-form-urlencoded" },
        // All other data will be picked up from the session
        body: new URLSearchParams({ payment_method: "ealyx_pay" })
      })
      .then(response => response.json())
      .then(data => {
        if (data.success) {
          console.log("Order created with pending status");
          // Ealyx SDK handles redirection
        }
      });
    });
});

Step 6: Handle IPN (Order Webhook)

As the final step in the Ealyx Pay payment process, the Ealyx backend will notify your backend via the POST <webhookBaseUrl>/order endpoint. This endpoint will receive the cart id from the Ealyx backend and you need to respond with the full order data. Below is an example of how to implement this endpoint.

use EalyxSDK\Services\ValidationService;

// Validate signature
$signature = $_SERVER[ValidationService::HEADER_KEY_EALYX_SIGNATURE] ?? '';
$body = file_get_contents('php://input');

$validationService = new ValidationService($serviceContainer->getConfig());
if (!$validationService->isValidSignature($signature, $body)) {
    http_response_code(401);
    exit;
}

$data = json_decode($body, true);
$cartId = $data['data']['cart_id'];
$status = $data['data']['status']; // pending, processing, payment_review, canceled

// Find and update order
$order = findOrderByCartId($cartId);
if (!$order) {
    // Handle case where the order is not found
    exit();
}

if ($status) {
    $order->updateStatus($status);
}

// Build cart, customer, and address objects
// This is the same data that you returned in the purchase_data endpoint

// Return order data
$response = [
    'result' => 'success',
    'message' => 'Order processed successfully',
    'order_ref' => $order->getId(),
    'purchase' => justLikeYouReturnedInThePurchaseDataEndpoint()
];

header('Content-Type: application/json');
echo json_encode($response);

Phase 3b: Payment via Other Methods

For non-Ealyx payments with active trade-ins, the shopper pays the full order value in the checkout, and Ealyx will follow up with a cashback/refund transaction to the shopper. For this to work, need to notify Ealyx after order completion. Below is an example of how to implement this.

use EalyxSDK\Models\PurchaseRegister;
use EalyxSDK\Enums\TradeInStatus;
use EalyxSDK\Models\BillingAddress;
use EalyxSDK\Models\Cart;
use EalyxSDK\Models\CartDiscount;
use EalyxSDK\Models\CartItem;
use EalyxSDK\Models\Customer;
use EalyxSDK\Models\ShippingAddress;
use EalyxSDK\Models\ShippingInformation;
use EalyxSDK\Models\ShippingMethod;

// Use the session hash token to query the Ealyx backend for the existence of an active trade-in
$sessionHash = generateSessionHash($_SESSION['session_id']); // Never expose real session ID
$tradeIn = $serviceContainer->getTradeinService()->getOneBySessionHash($sessionHash);
// If no active trade-in is found, do nothing
if (!$tradeIn || $tradeIn->status !== TradeInStatus::INITIATED) {
  return;
}

// Build cart, customer, and address objects -- just like you returned in the purchase_data endpoint
$cart = new Cart([
    'id' => $order->getCartId(),
    'currency' => 'EUR',
    'items' => $cartItems, // Array of CartItem objects
    'price' => $order->getTotalPrice() * 100, // cents
    'tax' => $order->getTotalTaxes() * 100,
    'discounts' => $discounts, // Array of CartDiscount objects
    'total' => $order->getTotalWithDiscounts() * 100,
]);

$billing = new BillingAddress(
  ...
);

$shipping = new ShippingInformation([
  'address' => new ShippingAddress([
    ...
  ]),
  'method' => new ShippingMethod([
    ...
  ])
]);

$cartData = [
  'cart' => $cart,
  'billing' => $billing,
  'shipping' => $shipping,
  'customer' => $customer
];

// The PurchaseRegister object contains the $cartData and the ID of the trade-in item
$purchaseRegister = new PurchaseRegister([
    'cart' => new CartData($cartData);
    'order_ID' => $order->getId(),
    'order_amount' => $order->getTotal() * 100,
    'order_tax_rate' => $order->getTaxRate() * 100,
    'order_total' => $order->getTotalWithTax() * 100,
    'tradein_item_id' => $tradeIn->tradein_id,
    'merchant_access_token' => $loginService->getValidAccessToken(),
    'consumer_email' => $customer->getEmail(),
    // ... other customer fields
    // consumer_given_name
    // consumer_family_name
    // consumer_nin
    // consumer_mobile_phone
    // consumer_street_address
    // consumer_street_address2
    // consumer_postal_code
    // consumer_region
    // consumer_country_code
    // consumer_city
    // consumer_country
]);

$response = $orderService->apiRegisterPurchase($purchaseRegister);
if (!$response || $response->status_code !== 200) {
  // Handle error
  return;
}

Phase 4: Post-Purchase Updates (Ealyx Pay Only)

If the order is paid with Ealyx Pay, you need to keep the order status synchronized with Ealyx Pay throughout its lifecycle (shipment, return, partial return, cart changes) in order to receive disbursements from Ealyx.

Below are examples of how to update the order status.

use EalyxSDK\Enums\UpdateType;
use EalyxSDK\Models\Cart;
use EalyxSDK\Models\CartItem;
use EalyxSDK\Models\CartDiscount;
use EalyxSDK\Models\OrderUpdateData;

$orderService = $serviceContainer->getOrderService();
$orderService->apiOrderUpdate(
    $orderId,     // The order ID you originally sent to Ealyx
    $updateType,  // One of the values from the UpdateType enum
    $data         // An OrderUpdateData object with additional data depending on the update type
);

// examples
$orderService->apiOrderUpdate($orderId, UpdateType::SHIPPED); // Full Shipment
$orderService->apiOrderUpdate($orderId, UpdateType::RETURNED); // Full Return

// Partial Shipment
$shippedItems = [
    new CartItem([
        // populate cart item
    ]),
    // more items...
];

$orderService->apiOrderUpdate(
    $orderId,
    UpdateType::PARTIAL_SHIPMENT,
    new OrderUpdateData(['shipped_items' => $shippedItems])
);

// Partial Return
$returnedItems = [
    new CartItem([
        // populate cart item
    ]),
    // more items...
];

$orderService->apiOrderUpdate(
    $orderId,
    UpdateType::PARTIAL_RETURN,
    new OrderUpdateData(['returned_items' => $returnedItems])
);

//Cart Update
$cart = new Cart([
    // populate cart fields
    'items' => [
      new CartItem([
        // populate cart item
      ]),
      // more items...

    ],
    'discounts' => [
      new CartDiscount([
        // populate discount
      ]),
      // more discounts...
    ]
]);

$orderService->apiOrderUpdate(
    $orderId,
    UpdateType::CART_UPDATE,
    new OrderUpdateData(['cart' => [$cart]])
);

4. Testing & Go-Live

End-to-End Testing Scenarios

Scenario 1: Ealyx Pay Flow

1. Complete valuation process
2. Add items to cart
3. Select Ealyx Pay at checkout
4. Complete payment in modal
5. Verify order webhook triggers
6. Check thank-you page display

Scenario 2: Other Payment Flow

1. Complete valuation process
2. Add items to cart
3. Pay with credit card
4. Verify apiRegisterPurchase() called
5. Check thank-you page display

Scenario 3: No Trade-in Flow

1. Complete standard purchase
2. Verify no Ealyx interference

Production Deployment

1. Request Production Credentials: Contact Ealyx after successful testing
2. Update Configuration:
   • Set production URLs: https://api.ealyx.tech, https://cdn.ealyx.tech
   • Update credentials in env.php or admin panel
3. Initial Production Login: Run authentication with production credentials
4. Go-Live Verification: Perform controlled test transaction
5. Monitor: Watch logs and maintain Ealyx support contact

5. Quick Reference

Key PHP Methods

// Authentication
$loginService->login($credential);           // Initial setup only
$loginService->getValidAccessToken();        // Auto-refreshing token

// Trade-in Management
$tradeinService->getOneBySessionId($sessionId);

// Order Management
$orderService->apiRegisterPurchase($purchaseRegister);
$orderService->apiOrderUpdate($orderId, $updateType, $data);

// Validation
$validationService->isValidSignature($body, $signature, $secret);

Frontend JavaScript API

// Event Listeners
window.addEventListener("ealyx-ready", handler);
window.Ealyx.addReadyToPlaceOrderListener(callback);
window.addEventListener("ealyx-valuation-updated", handler);

// Payment Control
window.Ealyx.updatePaymentSelected(isEalyxSelected);
window.Ealyx.openPayment();

Configuration Values

// Environment URLs
'API_BASE_URL' => 'https://api.stg.ealyx.tech',  // Sandbox
'API_BASE_URL' => 'https://api.ealyx.tech',      // Production
'ASSETS_URL' => 'https://cdn.stg.ealyx.tech',    // Sandbox
'ASSETS_URL' => 'https://cdn.ealyx.tech',        // Production

Teaser Types Location

• banner: Homepage / Category banners
• product-widget: Product detail pages
• cart-summary: Cart / Checkout summary
• thank-you: Order confirmation

Troubleshooting Checklist

• Teasers not appearing: Check frontend SDK loading and teaser placement
• Authentication failures: Verify credentials and check token storage in database
• Webhook errors: Validate signatures and check endpoint accessibility
• Payment modal issues: Ensure all three JavaScript components are implemented
• Order sync problems: Check apiRegisterPurchase() and apiOrderUpdate() calls

---

Support: For technical issues, contact your Ealyx account manager or info@ealyx.com