Terminals & Routing

A terminal is a configured connection between your platform and a payment provider. Each terminal has exactly one provider, one or more supported currencies, and a set of credentials. Smart routing selects the best terminal for each transaction automatically.

---

Terminal types

Type	Description
payment	Accepts incoming payments (pay-in)
payout	Sends outgoing payments (pay-out)
merchant	Notification-only — used for webhook delivery, not real payments

---

Creating a terminal

Via Admin Console

1. Admin Console → Terminals → New Terminal
2. Select provider from the catalog
3. Enter provider credentials (provider_params)
4. Set type, currencies, and geographic scope
5. Activate

Via Admin API

curl -X POST https://4pay.online/api/v1/terminal \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -d '{
    "name": "Stripe EUR Payments",
    "partner_id": 42,
    "provider": "stripe",
    "type": "payment",
    "is_active": true,
    "env": "prod",
    "provider_params": {
      "api_key": "sk_live_...",
      "webhook_secret": "whsec_..."
    },
    "merchant_adapter": "merchant_default",
    "notify_url": "https://partner.example.com/webhooks"
  }'

---

Provider credentials (provider_params)

Each provider requires different credentials. See the Provider Catalog for required provider_params per provider.

Common pattern:

Provider	Required params
Stripe	api_key, webhook_secret
Adyen	api_key, merchant_account, client_key
Checkout.com	secret_key, public_key
PayPal	client_id, client_secret

Full parameter reference: Provider Catalog

---

Merchant notifications (merchant_params)

Configure how the platform notifies you and the partner on transaction events:

{
  "merchant_params": {
    "tg_ids_to_notify": ["123456789", "987654321"]
  }
}

Param	Description
tg_ids_to_notify	Telegram user IDs to receive transaction notifications

---

Smart routing

Smart routing automatically selects the best terminal for each transaction based on rules you define.

How routing works

1. Transaction arrives with currency, amount, type, and optionally country
2. Routing engine evaluates all active terminals for the partner
3. Terminals are scored by your routing rules
4. Transaction is sent to the highest-scored terminal
5. If the terminal fails, the next terminal in the failover chain is tried

Routing factors

Factor	Description
Currency match	Terminal must support the transaction currency
Transaction type	Terminal type must match (payment / payout)
Geographic scope	Terminal can be restricted to specific countries or regions
Priority	Explicit priority number — lower = higher priority
Availability	Only active, non-degraded terminals are considered

Configuring routing rules

In Admin Console → Routing → Rules:

Rule: EUR payments in Europe
  currency = EUR
  region = Europe
  type = payment
  terminal_priority = [stripe_eur, adyen_eur, checkout_eur]

---

Failover

If a terminal fails (provider error, timeout, or network issue), the platform automatically retries on the next terminal in the failover chain.

Configure failover chains in Admin Console → Terminals → Failover:

Primary: stripe_eur
Failover 1: adyen_eur
Failover 2: checkout_eur

---

Multi-currency and FX

For transactions in a currency not natively supported by the terminal, automatic FX conversion can be enabled:

• Transaction arrives in USD
• Terminal supports EUR
• FX converts USD → EUR at the market rate + configured spread
• Transaction is processed in EUR
• Settlement is in EUR with the FX amount recorded

Configure FX spreads in Admin Console → FX → Rates.

---

Disabling a terminal

To temporarily take a terminal offline (e.g., provider maintenance):

1. Admin Console → Terminals → [Terminal] → Deactivate
2. Routing engine will automatically skip this terminal
3. Failover terminals will handle traffic

No data is lost. Reactivate at any time.