Tenant settings for PayPage & postbacks (ADM-SETTINGS-201/500)

What this page covers

• The tenant-level settings used by Djust Pay (PayPage, redirects, postback)
• How to read and update them via admin APIs
• Where these settings are used in the tokenization → authorization flow

Notes

• Return/iFrame URLs are settings-driven; they are not passed to PAY-101.
• Front-end must poll payment status after PayPage; redirects are UX-only.

⸻

🔑 What is configured

Return/iFrame URLs are settings-driven and not passed to PAY-101 (returnPath is not used with ITS).

Djust composes OnCompletionURL = effectiveRedirectBaseUrl + onSuccessPath and OnErrorURL = effectiveRedirectBaseUrl + onErrorPath.

🔁 Where settings are used in the runtime flow

flowchart LR
  CFG[Update tenant settings<br>ADM-SETTINGS-201] --> OKCFG[Settings active]
  OKCFG --> PAY101[Create PayPage token<br>PAY-101]
  PAY101 --> OPEN[Open PayPage<br>redirect or iFrame]
  OPEN --> PB[S2S postback to Djust<br>postbackUrl]
  PB --> AUTH[Auto authorization<br>Djust backend]

  %% Styles
  classDef touch fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
  classDef djust fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;

  class CFG,PAY101,OPEN touch
  class OKCFG,PB,AUTH djust

  style CFG rx:8,ry:8
  style OKCFG rx:8,ry:8
  style PAY101 rx:8,ry:8
  style OPEN rx:8,ry:8
  style PB rx:8,ry:8
  style AUTH rx:8,ry:8

Reading guide

• onSuccessPath, onErrorPath, postbackUrl, payPageUrl are tenant-level settings.
• effectiveRedirectBaseUrl is resolved from core store_view and is read-only here; it is used to compute preview URLs in GET only.
• PAY-101 uses payPageUrl; user redirects use the composed success/error URLs.
• Djust receives the postback on postbackUrl and runs authorization automatically.

📖 Read settings — ADM-SETTINGS-500

What you get (example)

Returns the four global ITS settings (tenant-level) and computed previews.

{
  "payPageUrl": "https://pay.example.com/page",
  "postbackUrl": "https://api.djust.com/payments/postback",
  "effectiveRedirectBaseUrl": "https://store.example.com",
  "onSuccessPath": "/checkout/success",
  "onErrorPath": "/checkout/error",
}

✍️ Update settings — ADM-SETTINGS-201

Request (example)

Required fields: onSuccessPath, onErrorPath, postbackUrl, payPageUrl

PUT is a full replacement of the four fields. Each change is audited (who, when, what) for diagnostics; audit data is not exposed.

{
  "payPageUrl": "https://pay.example.com/page",
  "postbackUrl": "https://api.djust.com/payments/postback",
  "onSuccessPath": "/checkout/success",
  "onErrorPath": "/checkout/error",
}

Validation tips

• All URLs must be HTTPS.
• allowedOrigins must include any host where the iFrame is embedded.
• Changing URLs impacts live checkouts; prefer a maintenance window.

🔐 Security & networking

• Allowlist outbound calls to the configured PayPage and postback hosts.
• Keep redirect paths relative to avoid accidental cross-site jumps.
• Never log PAN/CVC; log only opaque IDs (token, correlationId).

🧪 Minimal test plan

1. GET settings (ADM-SETTINGS-500) → confirm values.
2. PUT new values (ADM-SETTINGS-201) → verify persisted.
3. Run PAY-502 → PAY-101 → open PayPage (redirect/iFrame).
4. Confirm front receives redirects at the configured success/error paths.
5. Confirm Djust receives postback on postbackUrl, and authorization status updates backend.
6. Ensure the front polls backend status and does not rely on the redirect alone.

🚨 Common errors & fixes

🔗 API quicklinks

• Get settings - ADM-SETTINGS-500
• Update settings - ADM-SETTINGS-201
• Pre-authorization check - PAY-502
• Create PayPage token (CIT) - PAY-101
• No public Authorization API - Djust runs authorization automatically after PayPage