Developers

Build once, finalize on webhook, and go live safely.

Use backend session creation, redirect to hosted checkout, and trust webhook status as your paid-state source of truth.

Free / Starter

Hosted Checkout Flow

1. POST session from backend to `/gateway/session.php`.
2. Redirect buyer to `checkout_url`.
3. Receive return callback for UX only.
4. Mark order paid only after webhook signature verification.

Pro / Unlimited

Smart Routing by Method

1. Call `GET /gateway/me.php` to fetch available `methods`.
2. Show method list to buyer.
3. POST session with selected `method` value.
4. Do not pass provider slugs in merchant session payloads.

API Endpoints (Merchant)

Method	Endpoint	Purpose
POST	/gateway/session.php	Create checkout session
GET	/gateway/me.php	Read integration mode and method list
GET	/gateway/status.php?session_id=...	Read order/session status
POST	/api/webhook.php	Receive payment events

All merchant endpoints require Authorization: Bearer MERCHANT_API_KEY except inbound webhooks.

POST /gateway/session.php
Authorization: Bearer MERCHANT_API_KEY
Content-Type: application/json

{
  "domain": "merchant-store.example",
  "amount": "49.95",
  "currency": "USD",
  "order_id": "ORDER-10001",
  "return_url": "https://merchant-store.example/success",
  "cancel_url": "https://merchant-store.example/cancel",
  "customer_email": "buyer@example.com",
  "method": "card" // only for Smart Routing packages
}

Webhook verification: compute `hash_hmac('sha256', $rawPayload, $merchantWebhookSecret)` and compare using `hash_equals`. Update order state using webhook event, not return URL signal.

Webhook signature header: send/expect one of `X-Signature`, `X-Ecomtrade24-Signature`, or `X-Webhook-Signature`. Prefix `sha256=` is accepted.

Smart Routing behavior: read `integration_mode` from `GET /gateway/me.php`. If `integration_mode` is `hosted_checkout`, omit `method` and do not send `provider`.

Required payload rules for `POST /gateway/session.php`: `domain`, `amount`, `currency`, and `order_id`. Domain must match merchant approved domain exactly.

Status endpoint usage:

GET /gateway/status.php?session_id=SESSION_ID
Authorization: Bearer MERCHANT_API_KEY