EcomTrade24 Pay Merchant API Docs

Integration model by merchant plan

Free merchants

Use the normal hosted checkout.

Your backend creates a session with POST /gateway/session.php.
Redirect the buyer to the returned checkout_url.
The payment choice and provider routing happen inside the EcomTrade24 checkout flow.
Mark the order paid only after the webhook arrives. Use polling only as fallback.

Important: for Free merchants, do not build your own provider selection around internal provider names. The safe integration is always: create session → redirect to checkout_url.

Pro / Unlimited merchants

Build Smart Routing with `method`, not `provider`.

Your backend calls GET /gateway/me.php with the merchant API key.
Your frontend shows only methods where smart_router.methods.{method}.available is true.
When the buyer chooses a method, your backend creates the session with method.
Redirect to the checkout_url returned by that exact session response. Do not reconstruct the URL yourself and do not hardcode provider URLs.
Finalize the order when the signed webhook arrives.

Smart Routing is only really active when all three are true: the merchant package allows it, global Smart Routing is enabled, and checkout_mode on /gateway/me.php is smart_router.

Authentication

Preferred

Authorization: Bearer YOUR_API_KEY

Alternative

X-API-Key: YOUR_API_KEY

Query-string API keys are legacy fallback only and should not be used for new integrations.

Create checkout session

POST /gateway/session.php

Create the session on your server, then redirect the buyer to the returned checkout_url. This endpoint accepts JSON only.

Required fields

Field	Type	Notes
amount	string / number	Positive value like `10.00`
currency	string	Fiat code like `EUR` or `USD`
domain	string	Must match one of your merchant shop domains

Common optional fields

Field	Type	Notes
order_id	string	Your own order reference
email	string	Recommended, and required for some immediate provider redirects
return_url	string	HTTPS return URL
cancel_url	string	HTTPS cancel URL
meta	object	Stored as JSON metadata
method	string	Buyer-facing Smart Routing hint for Pro/Unlimited
bank_fiat_currency	string	Optional only when `method=bank`

Correct Free merchant example

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]",
    "return_url": "https://shop.example.com/checkout/success",
    "cancel_url": "https://shop.example.com/checkout/cancel"
  }'

Free merchants normally omit method and redirect to the returned checkout_url.

Correct Pro Smart Routing example

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]",
    "method": "paypal",
    "return_url": "https://shop.example.com/checkout/success",
    "cancel_url": "https://shop.example.com/checkout/cancel"
  }'

For Pro, pass the buyer-facing method, not an internal provider name, and redirect to the returned checkout_url from that same response.

Do not build against internal provider slugs

Avoid values like moonpay, epv2_paypal or other internal provider names in your public checkout UI. For Pro Smart Routing, use method values only.

Typical success response

{
  "ok": true,
  "session_id": 1459,
  "checkout_url": "https://pay.ecomtrade24.com/pay.php?session=1459&method=paypal&provider=moonpay",
  "direct_url": "https://pay.ecomtrade24.com/pay.php?session=1459&method=paypal&provider=moonpay",
  "selected_provider": "moonpay",
  "smart_route": true,
  "expires_at": "2026-03-19 09:22:38"
}

checkout_url

Main redirect target. For Free it usually points to hosted checkout. For Pro with a chosen method it points to the correct pay handoff including method and provider context.

direct_url

Compatibility mirror of the immediate pay handoff when Smart Routing already resolved the method. You normally do not need to prefer it over checkout_url.

Supported method values

Use these only when you are on Pro/Unlimited and Smart Routing is active.

Method	Meaning	Notes
card	Credit/debit card style flow	Aliases like `credit_card` are tolerated, but use `card` in new code
paypal	PayPal style flow	Buyer-facing method only
revolut	Revolut style flow	Buyer-facing method only
bank	Bank transfer or open banking	May use `bank_fiat_currency`
ideal	iDEAL	Usually only available for NL buyers when configured
other	Fallback bucket	Use only if your UI intentionally offers a generic alternative method

Check merchant capabilities

GET /gateway/me.php

Use this endpoint before rendering a method selector. It tells you the merchant package, checkout mode and which methods are actually available.

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},
      "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","CHF","USD"]},
      "ideal":  {"enabled": true, "configured": true, "available": false},
      "other":  {"enabled": true, "configured": true, "available": true}
    }
  }
}

Use smart_router.effective

Only treat Smart Routing as active when this is true.

Use method availability

Only show buyer-facing methods where available is true.

Check session status

GET /gateway/session_status.php

Look up a session by session_id, order_id, or number=session_<id>.

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

Webhooks

Configure your webhook URL and secret in merchant settings. When the gateway confirms a payment, your endpoint receives a signed POST request. Use the webhook as your paid-state source of truth.

Example payload

{
  "event": "payment.completed",
  "session_id": 1459,
  "order_id": "ORD-10001",
  "status": "paid",
  "amount": "49.99",
  "currency": "EUR",
  "merchant_id": 12,
  "created_at": "2026-04-06T07:10:12Z"
}

Verify the signature

<?php
$raw = file_get_contents('php://input');
$received = $_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);
// process idempotently
?>

Webhook rule

Process webhooks idempotently and trust the webhook before any frontend return URL or success page signal.

Go-live checklist

Free merchant launch

• Add and verify your merchant domain.
• Set webhook URL and webhook secret.
• Create sessions on your backend only.
• Redirect buyers to checkout_url.
• Confirm paid webhook handling before live traffic.

Pro Smart Routing launch

• Confirm package is Pro or Unlimited.
• Confirm GET /gateway/me.php returns smart_router.effective=true.
• Show only methods where available=true.
• Create sessions with buyer-facing method values only.
• Still redirect to checkout_url as the default integration target.

Manage domains & webhooks Open go-live checklist Upgrade to Pro

Quick answers

What is the correct Free merchant flow?

Create the session on your backend with POST /gateway/session.php and redirect the buyer to checkout_url. Do not build your own provider selection UI for Free.

What is the correct Pro merchant flow?

Call GET /gateway/me.php, show only methods where smart_router.methods.{method}.available is true, then create the session with method=card, paypal, revolut, bank, ideal or other and redirect to the returned checkout_url from that same response.

Should I redirect to direct_url?

Normally redirect to checkout_url. When method is supplied, checkout_url already contains the real pay.php handoff. direct_url is only an optional mirror for debugging or compatibility.

Should I trust polling or the webhook?

Trust the webhook first. Use status polling only as a fallback if your webhook delivery is delayed or unavailable.

Merchant API docs that match the real gateway flow.