The simple rule: create a session and redirect to checkout_url.

What the current API supports

Clear production integration flow

1. 1. Customer clicks Pay

   Your shop has an unpaid order with amount and currency.

2. 2. Your backend calls /gateway/session.php

   Use JSON. Keep the API key on the server. Do not call this from frontend JavaScript.

3. 3. API returns checkout_url

   Save the session_id on your order if possible.

4. 4. Redirect customer to checkout_url

   Do not change the URL. Do not append provider names.

5. 5. Customer pays

   Provider-side KYC/card checks, if triggered, are handled by the underlying payment/on-ramp provider.

6. 6. Your webhook receives final status

   Only then mark the order paid. Return pages are not proof of payment.

Authentication

Use your merchant API key from the merchant dashboard. The safest header is Authorization: Bearer YOUR_API_KEY. X-API-Key also works.

Authorization: Bearer YOUR_API_KEY

X-API-Key: YOUR_API_KEY

Use this endpoint to confirm the API key is valid and to detect the merchant plan before building optional method buttons. Free merchants use Hosted Checkout. Pro/Unlimited merchants can use Smart Routing when enabled. The shop still never sends a provider.

curl 'https://pay.ecomtrade24.com/gateway/me.php' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "ok": true,
  "merchant_id": 12,
  "email": "[email protected]",
  "package": "pro",
  "checkout_mode": "smart_router",
  "country": "DE",
  "smart_router": {
    "enabled_global": true,
    "allowed_for_package": true,
    "effective": true,
    "methods": {
      "card":   {"enabled": true, "configured": true, "available": true},
      "klarna": {"enabled": true, "configured": true, "available": false},
      "paypal": {"enabled": true, "configured": true, "available": true},
      "revolut":{"enabled": true, "configured": true, "available": true},
      "bank":   {"enabled": true, "configured": true, "available": true, "supported_bank_fiat": ["EUR", "USD"]},
      "ideal":  {"enabled": true, "configured": true, "available": false},
      "other":  {"enabled": true, "configured": true, "available": true}
    }
  }
}

This is the main endpoint for every merchant plan. Your backend sends order data and receives checkout_url. The API key decides whether this session becomes Hosted Checkout for a Free merchant or Smart Routing for a Pro/Unlimited merchant.

curl -X POST 'https://pay.ecomtrade24.com/gateway/session.php' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": "49.99",
    "currency": "EUR",
    "domain": "shop.example.com",
    "order_id": "ORD-10001",
    "email": "[email protected]",
    "country": "DE",
    "return_url": "https://shop.example.com/order/success",
    "cancel_url": "https://shop.example.com/checkout",
    "meta": {
      "source": "woocommerce"
    }
  }'

curl -X POST 'https://pay.ecomtrade24.com/gateway/session.php' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": "149.00",
    "currency": "EUR",
    "domain": "shop.example.com",
    "order_id": "ORD-10002",
    "email": "[email protected]",
    "country": "DE",
    "method": "card",
    "return_url": "https://shop.example.com/order/success",
    "cancel_url": "https://shop.example.com/checkout"
  }'

{
  "ok": true,
  "session_id": 1459,
  "checkout_url": "https://pay.ecomtrade24.com/hosted-checkout.php?session=1459",
  "checkout_mode": "hosted",
  "smart_route": false,
  "expires_at": "2026-04-29 12:30:00"
}

{
  "ok": true,
  "session_id": 1460,
  "checkout_url": "https://pay.ecomtrade24.com/checkout-continue.php?session=1460",
  "checkout_mode": "smart_router",
  "direct_url": null,
  "warmup_url": "https://pay.ecomtrade24.com/checkout-continue.php?session=1460",
  "selected_provider": null,
  "smart_route": true,
  "expires_at": "2026-04-29 12:30:00"
}

Smart Routing explained clearly

Use this as a fallback, not as your main payment confirmation. Look up by session_id, order_id, or number=session_1459.

curl 'https://pay.ecomtrade24.com/gateway/session_status.php?session_id=1459' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "ok": true,
  "session": {
    "id": 1459,
    "order_id": "ORD-10001",
    "status": "settled",
    "amount": "49.99",
    "currency": "EUR",
    "shop_domain": "shop.example.com",
    "payment_url": "https://pay.ecomtrade24.com/checkout.php?session=1459",
    "txid": "0x...",
    "txid_in": "0x...",
    "txid_out": "0x...",
    "last_error": null
  }
}

Webhooks: your real paid confirmation

Configure webhook URL and secret in the merchant dashboard. EcomTrade24 Pay sends a signed POST request. Your system must verify the signature and process the event idempotently.

{
  "event": "payment.completed",
  "session_id": 1459,
  "order_id": "ORD-10001",
  "status": "paid",
  "amount": "49.99",
  "currency": "EUR",
  "merchant_id": 12,
  "txid": "0x..."
}

<?php
$raw = file_get_contents('php://input');
$received = $_SERVER['HTTP_X_ECOMTRADE24_SIGNATURE']
    ?? $_SERVER['HTTP_X_SIGNATURE']
    ?? '';
$secret = 'YOUR_WEBHOOK_SECRET';
$expected = hash_hmac('sha256', $raw, $secret);

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('invalid signature');
}

$payload = json_decode($raw, true);
// 1. Check session_id/order_id
// 2. Process only once
// 3. Mark paid only for final paid statuses
http_response_code(200);
echo 'ok';

Payment links & hosted products

These are merchant dashboard features built on top of the same session engine. They are useful when a merchant does not want to integrate a shop plugin or custom API immediately.

Reseller / white-label API overview

Reseller endpoints are for approved reseller partners who run their own branded merchant platform. Normal merchants do not need these endpoints.

Common errors and how to fix them