Other Payment Methods Integration

This path covers Phase 3b only. Choose this path if you want to use your existing payment gateway and let Ealyx send a cashback to the customer after the trade-in is completed.

Prerequisites

Complete Common Phases (1-2) before implementing this path.

Simpler Integration

This path requires less integration effort than Ealyx Pay - no webhook handling needed. Just one API call after order completion.

Phase 3b: Payment via Other Methods

Flow Diagram:

For non-Ealyx payments (credit card, PayPal, etc.) with active trade-ins, the shopper pays the full order value in the checkout. Ealyx will follow up with a cashback/refund transaction to the shopper.

To enable this, you must notify Ealyx after order completion. This involves:

Checking if an active trade-in exists for the customer
Registering the purchase with Ealyx using the POST /register-purchase endpoint
Providing complete order details for Ealyx to process the cashback

Step 1: Check for Active Trade-in

Query Ealyx for an active trade-in using the session hash:

# Get session hash (same as used in shopper_data endpoint)
SESSION_HASH="{SESSION_HASH}"
ACCESS_TOKEN="{ACCESS_TOKEN}"

curl -X GET "{API_BASE_URL}/core/sessions/$SESSION_HASH" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json"

# Response:
{
  "session_id": "uuid",
  "tradein_item": "tradein_item_id"
}

Important: If the returned session_id differs from your queried $SESSION_HASH, the session was redirected on the server:

Use the returned session_id directly (no re-hashing needed)
Re-query: GET /core/sessions/{response.session_id}
Use the returned data to validate the trade-in

The returned session_id is Ealyx's internal identifier - use it as-is for the retry.

If no tradein_item is returned, skip the trade-in steps and proceed with normal order processing.

✓ Verification

Test the endpoint:

curl -X GET "$API_BASE_URL/core/sessions/$SESSION_HASH" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Check	Expected	If it fails
HTTP status	`200 OK`	Token may be expired - refresh it
`session_id`	UUID string	Session hash may be incorrect
`tradein_item`	UUID string or `null`	`null` means no active trade-in (skip remaining steps)

Step 2: Get Trade-in Details

If a trade-in exists, retrieve its details:

TRADE_IN_ID="{TRADE_IN_ID}"
ACCESS_TOKEN="{ACCESS_TOKEN}"

curl -X GET "{API_BASE_URL}/core/tradeinitems/$TRADE_IN_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json"

# Response:
{
  "tradein_item_id": "uuid",
  "merchant_user_ref": "ref",
  "description": "iPhone 12 Pro",
  "pre_valuation": 45000,
  "valid_until": "2024-12-31T23:59:59Z",
  "valuation_status": "accepted"
}

✓ Verification

Check	Expected	If it fails
HTTP status	`200 OK`	Trade-in ID may be invalid or token expired
`tradein_item_id`	UUID string	Check the ID from Step 1 response
`pre_valuation`	Integer (cents)	Trade-in value to apply as cashback
`valuation_status`	`"accepted"`	Only `accepted` valuations can be used
`valid_until`	Future date	Expired valuations cannot be used

Step 3: Register Purchase

Register the purchase with Ealyx using a POST request to the /register-purchase endpoint. This endpoint takes all purchase data in the request body:

# Prepare cart data (JSON)
CART_DATA='{
  "customer": {
    "id": "customer_123",
    "email": "john@example.com",
    "given_name": "John",
    "family_name": "Doe"
  },
  "cart": {
    "id": "cart_123",
    "currency": "EUR",
    "items": [...],
    "price": 89999,
    "tax": 18900,
    "discounts": [...],
    "total": 74999
  },
  "billing": {...},
  "shipping": {...}
}'

# Base64 encode cart data
CART_DATA_B64=$(echo -n "$CART_DATA" | base64)

# Call register-purchase endpoint with JSON body
curl -X POST "{API_BASE_URL}/register-purchase" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cart": "'$CART_DATA_B64'",
    "order_amount": 89999,
    "order_tax_rate": 18900,
    "order_total": 108899,
    "tradein_item_id": "'$TRADEIN_ID'",
    "merchant_access_token": "'$ACCESS_TOKEN'",
    "order_ID": "ORD-123456",
    "consumer_email": "john@example.com",
    "consumer_given_name": "John",
    "consumer_family_name": "Doe",
    "consumer_mobile_phone": "+1234567890",
    "consumer_street_address": "123 Main St",
    "consumer_street_address2": "Apt 4B",
    "consumer_postal_code": "10001",
    "consumer_region": "NY",
    "consumer_country_code": "US",
    "consumer_city": "New York",
    "consumer_country": "United States"
  }'

Required Parameters:

Parameter	Type	Description
`cart`	string (base64)	URL-encoded JSON of cart data
`order_amount`	string	Order subtotal in cents
`order_tax_rate`	string	Tax rate in cents
`order_total`	string	Total including tax in cents
`tradein_item_id`	string	ID from trade-in query
`merchant_access_token`	string	Your current access token
`order_ID`	string	Your order ID
`consumer_email`	string	Customer email

Important: At least consumer_email is required. Other consumer fields are optional but highly recommended to improve cashback delivery.

Optional Parameters:

consumer_given_name - Customer first name
consumer_family_name - Customer last name
consumer_nin - National ID number (format varies by country)
consumer_mobile_phone - Customer phone number
consumer_street_address - Street address
consumer_street_address2 - Additional address line (apartment, suite, etc.)
consumer_postal_code - Postal/ZIP code
consumer_region - State or region
consumer_country_code - ISO 3166-1 alpha-2 country code (e.g., "US", "DE", "GB")
consumer_city - City name
consumer_country - Full country name

Pseudo-code Implementation:

# 1. Generate session hash (same as shopper_data)
session_hash = HMAC_SHA256(session_id, salt)  # NOT SHA256(session_id + salt)

# 2. Query for active trade-in
response = GET /core/sessions/{session_hash}
if not response.tradein_item:
    return  # No active trade-in, skip

tradein_id = response.tradein_item

# 3. Register purchase with Ealyx
cart_json = {
    'customer': get_customer_data(),
    'cart': get_cart_data(),
    'billing': get_billing_address(),
    'shipping': get_shipping_info()
}

response = POST /register-purchase with body:
    cart: base64_encode(json_encode(cart_json))
    order_amount: order.subtotal * 100
    order_tax_rate: order.tax * 100
    order_total: order.total * 100
    tradein_item_id: tradein_id
    merchant_access_token: access_token
    order_ID: order.id
    consumer_email: customer.email
    ...

if response.status == 200:
    # Purchase registered successfully
    # Ealyx will process cashback automatically
else:
    # Handle error

✓ Verification

Test the endpoint:

curl -X POST "$API_BASE_URL/register-purchase" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cart":"...", "order_amount":"89999", ...}'

Check	Expected	If it fails
HTTP status	`200 OK`	Check required fields and token
Response	Registration confirmation	Ealyx will process cashback
HTTP 400	-	Missing required field (check `consumer_email`, `order_ID`, `tradein_item_id`)
HTTP 401	-	Token expired - refresh it
HTTP 422	-	Invalid cart data or amounts not in cents

After successful registration: Ealyx processes the cashback automatically (1-5 business days). No further action required from your backend.

Phase 3b: Payment via Other Methods​

Step 1: Check for Active Trade-in​

Step 2: Get Trade-in Details​

Step 3: Register Purchase​

Phase 3b: Payment via Other Methods

Step 1: Check for Active Trade-in

Step 2: Get Trade-in Details

Step 3: Register Purchase