Overview

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):

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

Before You Start: Critical Integration Rules

Read This First

These three rules cause 90% of integration failures. Read them before writing any code.

1. All Monetary Values Are in Cents

All prices, taxes, and discounts must be integers in cents, not decimal values.

Price	Correct	Wrong
€99.99	`9999`	`99.99`
€1.50	`150`	`1.50`
€0.50	`50`	`0.50`

Using decimal values will cause cryptic API errors. Always multiply by 100.

2. Webhook Secret = `USER_ID-MERCHANT_ID`

The secret for validating webhook signatures is {USER_ID}-{MERCHANT_ID}.

Correct	Wrong
`user_12345-merchant_67890`	`your_client_secret`

You receive USER_ID and MERCHANT_ID in the authentication response
Using CLIENT_SECRET will reject all webhooks

3. Use Raw Body for Signature Validation

When validating webhook signatures:

Correct	Wrong
Raw request body bytes	Parsed JSON object
`request.body` (before parsing)	`JSON.stringify(parsedData)`

Different frameworks access raw body differently. Parsing and re-serializing changes the bytes and breaks validation.

Integration Architecture

Endpoints Overview

Understanding which endpoints you implement vs which you call is crucial:

Endpoints You Must Implement

These endpoints live on your server. The Ealyx SDK calls them:

Endpoint	Method	When Called	What It Returns
`{MERCHANT_CALLBACKS_BASE}/shopper_data`	GET	SDK loads on any page	Customer info + session hash
`{MERCHANT_CALLBACKS_BASE}/purchase_data`	GET	Customer reaches checkout	Full cart, billing, shipping
`{MERCHANT_WEBHOOK_BASE}/order`	POST	Ealyx Pay payment completes	Return HTTP 200 to confirm

Ealyx API Endpoints You Call

These endpoints live on Ealyx servers. Your backend calls them:

Endpoint	Method	When to Call	What You Get
`/oauth2/token/`	POST	Initial auth & token refresh	Access token, merchant_id, user_id
`/core/merchants/`	GET	During setup (optional)	Merchant configuration
`/core/sessions/{hash}/`	GET	Verify session exists	Session details
`/register-purchase`	POST	After payment (Other Methods only)	Purchase confirmation
`/payments/orders/update`	POST	Order status changes (Ealyx Pay only)	Update confirmation

Complete Flow Sequence

Ealyx Pay vs Other Payment Methods

There are two ways to offer trade-in benefits to your customers:

Ealyx Pay Integration: Integrate Ealyx Pay as a new payment method on checkout. Shoppers benefit from an instant discount based on the trade-in valuation, or
Other Payment Methods: Skip Ealyx Pay and let shoppers use your existing payment methods. They receive a payback (refund) once the trade-in process is completed.

Even if you integrate Ealyx Pay, shoppers can still choose to use other payment methods and benefit from the trade-in program.

Feature	Ealyx Pay	Other Payment Methods
Payment Processing	Ealyx processes payment	Your payment gateway
Instant Discount	Yes	No (refund after)
Webhook Integration	Yes	No
Order Status Updates	Yes (POST /payments/orders/update)	No
Integration Effort	Medium	Low
Testing Difficulty	Medium	Low

System Requirements

Requirement	Details
Programming Language	Any language with HTTP client support
HTTP Client	curl, httpx, axios, requests, fetch, etc.
OAuth 2.0 Support	Ability to make authenticated HTTP requests
Token Storage	Database or secure cache to store access tokens
HTTPS	Required for production (TLS 1.2 or higher)
Data Encoding	Support for JSON, URL-encoded form data, and Base64

Environment-Specific Configuration

All Ealyx integrations require configuration for a specific environment. Choose your environment and set the corresponding URLs:

Staging/Sandbox Environment

Use this environment for testing and development:

Service	Base URL
API	`https://api.stg.ealyx.tech`
Assets/SDK	`https://cdn.stg.ealyx.tech`
Credentials	Use sandbox test credentials from Ealyx

Production Environment

Use this environment for live transactions:

Service	Base URL
API	`https://api.ealyx.tech`
Assets/SDK	`https://cdn.ealyx.tech`
Credentials	Use your live production credentials

Configuration Setup

Define these base URLs in your environment or configuration file. Throughout this guide, examples use placeholders like {API_BASE_URL} which you replace with the appropriate value:

Option 1: Environment Variables (Recommended)

# staging/sandbox
export API_BASE_URL="https://api.stg.ealyx.tech"
export ASSETS_URL="https://cdn.stg.ealyx.tech"

# OR for production
export API_BASE_URL="https://api.ealyx.tech"
export ASSETS_URL="https://cdn.ealyx.tech"

Option 2: Configuration File

# ealyx-config.sh (source this file in your scripts)
API_BASE_URL="https://api.stg.ealyx.tech"
ASSETS_URL="https://cdn.stg.ealyx.tech"

# Source in your scripts:
source ealyx-config.sh

Option 3: Application Configuration

Store environment-specific URLs in your application's config (.env file, database, configuration management system, etc.):

EALYX_API_BASE_URL=https://api.stg.ealyx.tech
EALYX_ASSETS_URL=https://cdn.stg.ealyx.tech

Quick Switch: Staging → Production

When you're ready to move from staging to production, simply update your configuration:

Replace api.stg.ealyx.tech with api.ealyx.tech (remove .stg)
Replace cdn.stg.ealyx.tech with cdn.ealyx.tech (remove .stg)
Update your credentials to production credentials

That's it! No other code changes required.

Placeholder Reference

Throughout this guide, examples use placeholders in curly braces to represent values you need to fill in. This section explains what each placeholder means and how to use them.

Environment Configuration Placeholders

These are set once in your configuration and used in all examples:

Placeholder	Type	Value	Example
`{API_BASE_URL}`	Environment	Ealyx API base URL	`https://api.stg.ealyx.tech` (staging) or `https://api.ealyx.tech` (production)
`{ASSETS_URL}`	Environment	Ealyx Assets/CDN base URL	`https://cdn.stg.ealyx.tech` (staging) or `https://cdn.ealyx.tech` (production)

Merchant Configuration Placeholders

These are specific to your merchant account and application:

Placeholder	Type	Value	Purpose
`{CLIENT_ID}`	Credential	From Ealyx (merchant account)	OAuth Basic Auth
`{CLIENT_SECRET}`	Credential	From Ealyx (merchant account)	OAuth Basic Auth
`{USERNAME}`	Credential	From Ealyx (merchant account)	OAuth password grant
`{PASSWORD}`	Credential	From Ealyx (merchant account)	OAuth password grant
`{MERCHANT_WEBHOOK_BASE}`	Custom	Your webhook URL	e.g., `https://yoursite.com/ealyx/webhooks`
`{MERCHANT_CALLBACKS_BASE}`	Custom	Your callbacks base URL	e.g., `https://yoursite.com/ealyx/callbacks`
`{MERCHANT_SUCCESS_URL}`	Custom	Your order success page	e.g., `https://yoursite.com/order-success`

Dynamic Data Placeholders

These are obtained from API responses during integration:

Placeholder	Type	Value	Source
`{ACCESS_TOKEN}`	Auth Token	Bearer token for API requests	POST `/oauth2/token/` response
`{REFRESH_TOKEN}`	Auth Token	Token to refresh access token	POST `/oauth2/token/` response
`{USER_ID}`	Merchant ID	Your user identifier	POST `/oauth2/token/` response
`{MERCHANT_ID}`	Merchant ID	Your merchant identifier	POST `/oauth2/token/` response
`{SESSION_ID}`	Session Data	Your internal session identifier	Generated by your e-commerce platform
`{SESSION_HASH}`	Session Data	HMAC-SHA256 hash of session ID + salt	Computed before sending to Ealyx
`{SALT}`	Security	Random salt value for session hashing	Generated with each session for security
`{CUSTOMER_ID}`	Customer Data	Your internal customer identifier	From your e-commerce platform
`{TRADE_IN_ID}`	Trade-in Data	Identifier of trade-in item	From Ealyx API responses
`{ORDER_ID}`	Order Data	Your order identifier	Generated by your system

How to Use Placeholders

When you see an example like this:

curl -X POST '{API_BASE_URL}/oauth2/token/' \
  -H 'Authorization: Basic '$(echo -n "{CLIENT_ID}:{CLIENT_SECRET}" | base64) \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username={USERNAME}' \
  -d 'password={PASSWORD}'

Replace each placeholder with your actual value. If you set your configuration as environment variables (recommended), you can use them directly:

curl -X POST "$API_BASE_URL/oauth2/token/" \
  -H "Authorization: Basic $(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64)" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "username=$USERNAME" \
  -d "password=$PASSWORD"

Or replace them manually in your code:

curl -X POST 'https://api.stg.ealyx.tech/oauth2/token/' \
  -H 'Authorization: Basic '$(echo -n "your_client_id:your_client_secret" | base64) \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=your_username' \
  -d 'password=your_password'

Before You Start: Critical Integration Rules​

1. All Monetary Values Are in Cents​

2. Webhook Secret = USER_ID-MERCHANT_ID​

3. Use Raw Body for Signature Validation​

Integration Architecture​

Endpoints Overview​

Endpoints You Must Implement​

Ealyx API Endpoints You Call​

Complete Flow Sequence​

Ealyx Pay vs Other Payment Methods​

System Requirements​

Environment-Specific Configuration​

Staging/Sandbox Environment​

Production Environment​

Configuration Setup​

Quick Switch: Staging → Production​

Placeholder Reference​

Environment Configuration Placeholders​

Merchant Configuration Placeholders​

Dynamic Data Placeholders​

How to Use Placeholders​