Crypto-first Payment API: create a session and redirect to checkout_url.

What the current API supports

Clear production integration flow

1. 1. Customer clicks Pay once

   Create or load the unpaid shop order first. Use one stable order ID for that order.

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

   Use JSON. Keep the API key on the server. Never call the Session API directly from frontend JavaScript.

3. 3. API returns checkout_url

   Save session_id. Treat checkout_url as an opaque URL and use it exactly as returned.

4. 4. Redirect the customer browser immediately

   Send the customer's browser to checkout_url. Do not fetch that URL from your backend and do not create another session before redirecting.

5. 5. Retry safely with the same order_id

   If your request is retried or the buyer clicks Pay again, reuse the same order_id. EcomTrade24 can return the existing open session with reused: true.

6. 6. Customer pays

   Direct crypto customers pay from their existing wallet or exchange. If the customer chooses an optional fiat-to-crypto route, the independent provider handles its own eligibility and verification steps.

7. 7. 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, detect the merchant plan and read the recommended payment-method order. New clients should use recommended_method, method_order and each method's group. Direct crypto is recommended when available; Smart Routing remains an optional fiat-to-crypto fallback for eligible Pro/Unlimited merchants. The shop 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",
  "recommended_method": "crypto",
  "method_order": ["crypto","card","paypal","revolut","ideal","klarna","bank","upi","interac","other"],
  "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, "min_amount": 46.0, "currency": "EUR"},
      "upi":    {"enabled": true, "configured": true, "available": false, "min_amount": 1600.0, "currency": "INR", "country": "IN"},
      "interac":{"enabled": true, "configured": true, "available": false, "min_amount": 100.0, "currency": "CAD", "country": "CA"},
      "crypto": {"enabled": true, "configured": true, "available": true},
      "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": "crypto",
    "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",
  "direct_url": null,
  "warmup_url": null,
  "selected_provider": null,
  "smart_route": false,
  "expires_at": "2026-04-29 12:30:00"
}

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

$data = json_decode($response, true);

if (empty($data['ok']) || empty($data['checkout_url'])) {
    // Handle the API error. Do not create a new order ID.
    exit;
}

// Send the CUSTOMER browser to the URL returned by EcomTrade24.
header('Location: ' . $data['checkout_url'], true, 303);
exit;

const response = await fetch('/your-server/create-payment', {
  method: 'POST'
});
const payment = await response.json();

if (payment.checkout_url) {
  window.location.assign(payment.checkout_url);
}

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