Merchant API Documentation

Base URL & Authentication

https://pay.ecomtrade24.com

Your API key is available in the Merchant Dashboard. Keep it private and never expose it in browser-side JavaScript. Use server-to-server requests only.

Authorization: Bearer YOUR_API_KEY

Content-Type: application/json

1) Create a Checkout Session

POST /gateway/session.php

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "merchant": "yourshop.com",
  "merchant_ref": "YOUR_INTERNAL_ORDER_ID",
  "purchase_id": "OPTIONAL_PURCHASE_REFERENCE",
  "session_id": "OPTIONAL_EXTERNAL_SESSION_ID",
  "amount": "5.00",
  "currency": "EUR",
  "return_url": "https://yourshop.com/payment/return",
  "webhook_url": "https://yourshop.com/api/webhook/ecomtrade24",
  "customer": {
    "email": "[email protected]"
  },
  "meta": {
    "cart_id": "optional",
    "source": "optional"
  }
}

{
  "ok": true,
  "session_id": "SESSION_TOKEN",
  "checkout_url": "https://pay.ecomtrade24.com/pay.php?merchant=yourshop.com&merchant_ref=YOUR_INTERNAL_ORDER_ID&session_id=SESSION_TOKEN&amount=5.00¤cy=EUR&return_url=...&webhook_url=...",
  "expires_at": "YYYY-MM-DD HH:MM:SS"
}

2) Hosted Checkout via URL (Optional)

If you do not want to call the API first, you can start a hosted checkout directly by redirecting the customer to /pay.php. This method is commonly used for simple integrations.

GET /pay.php

merchant=yourshop.com
merchant_ref=YOUR_INTERNAL_ORDER_ID
session_id=YOUR_SESSION_TOKEN
purchase_id=OPTIONAL_PURCHASE_REFERENCE
amount=5.00
currency=EUR
return_url=https%3A%2F%2Fyourshop.com%2Fpayment%2Freturn
webhook_url=https%3A%2F%2Fyourshop.com%2Fapi%2Fwebhook%2Fecomtrade24

3) Get Session Status

GET /gateway/session_status.php?session_id=SESSION_TOKEN

Authorization: Bearer YOUR_API_KEY

{
  "ok": true,
  "session": {
    "session_id": "SESSION_TOKEN",
    "merchant": "yourshop.com",
    "merchant_ref": "YOUR_INTERNAL_ORDER_ID",
    "purchase_id": "OPTIONAL_PURCHASE_REFERENCE",
    "status": "created",
    "amount": "5.00",
    "currency": "EUR",
    "created_at": "YYYY-MM-DD HH:MM:SS",
    "updated_at": "YYYY-MM-DD HH:MM:SS",
    "meta": {
      "cart_id": "optional"
    }
  }
}

• created — session created, payment not completed yet
• pending — payment initiated, awaiting confirmation
• paid — payment completed successfully (final)
• failed — payment failed (final)
• expired — session expired before completion (final)
• canceled — customer canceled checkout (final)

4) Webhooks

Webhooks notify your system when a session changes state (e.g., paid). Configure a default Webhook URL and Webhook Secret in the Merchant Dashboard, or provide a per-session webhook_url.

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

• payment.session.created
• payment.session.updated
• payment.session.paid
• payment.session.failed
• payment.session.expired
• payment.session.canceled

{
  "event": "payment.session.paid",
  "sent_at": "YYYY-MM-DDTHH:MM:SSZ",
  "data": {
    "session_id": "SESSION_TOKEN",
    "merchant": "yourshop.com",
    "merchant_ref": "YOUR_INTERNAL_ORDER_ID",
    "purchase_id": "OPTIONAL_PURCHASE_REFERENCE",
    "status": "paid",
    "amount": "5.00",
    "currency": "EUR",
    "meta": {
      "cart_id": "optional"
    }
  }
}

<?php
// webhook.php
$secret = 'YOUR_WEBHOOK_SECRET';

$rawBody = file_get_contents('php://input');
$receivedSig = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$calculated  = hash_hmac('sha256', $rawBody, $secret);

if (!hash_equals($calculated, $receivedSig)) {
  http_response_code(401);
  echo 'invalid signature';
  exit;
}

$payload = json_decode($rawBody, true);
if (!is_array($payload)) {
  http_response_code(400);
  echo 'invalid json';
  exit;
}

$event = $payload['event'] ?? '';
$data  = $payload['data'] ?? [];

$sessionId   = $data['session_id'] ?? '';
$merchantRef = $data['merchant_ref'] ?? '';
$status      = $data['status'] ?? '';

// Important: Make your handler idempotent (webhooks may be retried).
// Always confirm final state by polling session_status if needed.

http_response_code(200);
echo 'ok';

Error Format

On errors, the API responds with an HTTP error status and a JSON body:

{
  "ok": false,
  "error": "error_code",
  "message": "Human readable explanation"
}

• 400 — invalid request (missing/invalid fields)
• 401 — unauthorized (missing/invalid API key)
• 403 — forbidden (domain not allowed, account disabled)
• 404 — endpoint not found
• 429 — rate limited
• 500 — server error

Quick cURL Examples

# Create session
curl -X POST "https://pay.ecomtrade24.com/gateway/session.php" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant":"yourshop.com",
    "merchant_ref":"YOUR_INTERNAL_ORDER_ID",
    "session_id":"YOUR_SESSION_TOKEN",
    "purchase_id":"OPTIONAL_PURCHASE_REFERENCE",
    "amount":"5.00",
    "currency":"EUR",
    "return_url":"https://yourshop.com/payment/return",
    "webhook_url":"https://yourshop.com/api/webhook/ecomtrade24",
    "customer":{"email":"[email protected]"},
    "meta":{"cart_id":"optional"}
  }'

# Poll status
curl "https://pay.ecomtrade24.com/gateway/session_status.php?session_id=YOUR_SESSION_TOKEN" \
  -H "Authorization: Bearer YOUR_API_KEY"

Integration Checklist

1. Generate a unique merchant_ref for each order and store it in your database.
2. Create a session via POST /gateway/session.php or build a /pay.php redirect URL.
3. Redirect the customer to checkout_url.
4. On return, call GET /gateway/session_status.php to confirm the final state.
5. Enable webhooks for instant updates and always verify X-Signature.
6. Mark orders as paid only when status is paid.