Merchant API Documentation

Create checkout sessions, query session status, and receive signed webhooks for payment updates. This API is designed for server-to-server integrations with EcomTrade24 Pay (custom checkouts, SaaS platforms, WooCommerce plugins, etc.).

Base URL & Authentication

Base URL (Gateway)

https://pay.ecomtrade24.com

⚠️ This is the Gateway domain. Do not use api.ecomtrade24.com for session creation.

API Key

Your API key is available in the Merchant Dashboard. Keep it secret and use it only in backend (server-to-server) requests.

Authorization Header

Authorization: Bearer YOUR_API_KEY

Content Type

Content-Type: application/json

1) Create a Checkout Session

Endpoint

POST /gateway/session.php

Request Body (JSON)

{
  "domain": "yourshop.com",
  "merchant_ref": "YOUR_INTERNAL_ORDER_ID",
  "amount": "5.00",
  "currency": "EUR",
  "return_url": "https://yourshop.com/payment/return",
  "cancel_url": "https://yourshop.com/payment/cancel",
  "customer_email": "[email protected]",
  "meta": {
    "cart_id": "optional",
    "source": "optional"
  }
}

domain (required) — must exactly match a domain registered in your Merchant Dashboard.
merchant_ref — your internal order ID (must be unique).
amount / currency — final order total.
return_url / cancel_url — customer redirect URLs.
customer_email — optional, recommended for reconciliation.
meta — optional metadata, returned in status & webhooks.

⚠️ The domain field is mandatory. If missing or invalid, the request will be rejected.

Response

{
  "ok": true,
  "session_id": 12345,
  "checkout_url": "https://pay.ecomtrade24.com/pay.php?session=12345",
  "expires_at": "YYYY-MM-DD HH:MM:SS"
}

2) Get Session Status

GET /gateway/session_status.php?session_id=SESSION_ID

Always treat paid as the only successful final state.

3) Webhooks

Webhooks notify your system when a payment session changes state. Always verify the signature.

X-Signature: HMAC-SHA256(raw_body, webhook_secret)

Quick cURL Example

curl -X POST "https://pay.ecomtrade24.com/gateway/session.php" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain":"yourshop.com",
    "merchant_ref":"ORDER_123",
    "amount":"5.00",
    "currency":"EUR"
  }'

Integration Checklist

Register your shop domain in the Merchant Dashboard.
Always send the domain field when creating a session.
Use server-to-server requests only.
Redirect customers to checkout_url.
Confirm final status via webhooks or session status polling.