Prerequisites & Setup

✅ Pre-flight checklists

What Djust Pay provides

Requirement	Details / Examples
PayPage integration profile	Redirect or iFrame; sandbox and production base URLs; supported locales and currencies.
Return and dropout URL policy	Accepted success, cancel, and error URLs; method is POST with tokenization outcome.
Postback contract	Fields returned after PayPage (token, status, correlation ids);
P-Card detection hooks	How the shop signals P-Card mode; catalog and checkout gating behavior.
Authorization behavior	Automatic S2S authorization executed by Djust backend after tokenization; mode is configured in Djust Pay.
Multi-authorization orchestration	Support for split shipments and partial captures; reconciliation guidelines.
Level 3 field dictionary	Business field catalog used at capture; kept provider-neutral.
Pre-capture check	Djust validates Level 3 completeness just before each capture and blocks if incomplete.
Error mapping	Normalized outcomes for tokenization and S2S steps; suggested UX.
Security & compliance	No PAN in your apps; TLS; allowlisted domains; PCI scope notes.

What you provide (merchant / frontend / backend)

Requirement	Details / Examples
URLs	Return and dropout URLs; environment matrix (sandbox, production); allowed origins for iFrame.
UX choice	Choose redirect or iFrame PayPage; container size, language, and theming.
P-Card gating	Business rule to enter P-Card flow: account policy, payment-method selection, or enterprise card flag.
Confirm auth configuration	Align with Djust on the configured authorization mode; you do not call auth yourself.
FR pre-authorization check	Call PAY-502 to register or validate required identifiers (e.g., Market ID and Commitment ID) before authorization.
Sandbox data	Test card numbers and flows; ensure the two FR identifiers are present for capture tests.

🧭 Integration surfaces

flowchart LR
  CFG[Configure<br>URLs and gating] --> PREAUTH[FR pre-auth check<br>call PAY-502]
  PREAUTH --> PP[Open PayPage<br>redirect or iFrame]
  PP --> PB[Handle postback<br>token and status]
  PB --> AUTH[Auto authorization<br>Djust backend]
  AUTH --> LOGI[Logistics flow<br>split or partials]
  LOGI --> PRECAP[Djust pre-capture check<br>L3 completeness]
  PRECAP --> CAP[Capture with Level 3<br>per shipped lines]

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

  class CFG,PREAUTH,PP,PB,CAP visible
  class AUTH,LOGI,PRECAP resp

  style CFG rx:8,ry:8
  style PREAUTH rx:8,ry:8
  style PP rx:8,ry:8
  style PB rx:8,ry:8
  style AUTH rx:8,ry:8
  style LOGI rx:8,ry:8
  style PRECAP rx:8,ry:8
  style CAP rx:8,ry:8

How to read this

Green = your touchpoints: PAY-502 pre-auth check, PayPage, postback handler, and captures.
Grey = Djust-managed: automatic authorization, logistics orchestration, and the pre-capture check.

Key clarifications

FR precheck before PayPage: ensure Market ID and Commitment ID are present before opening PayPage. If missing, block checkout or prompt the user to complete the information.
Auto authorization: after a successful PayPage postback, Djust backend runs authorization automatically. You do not call auth.
Logistics orchestration: handled by Djust (splits and partials).
Capture with Level 3: you may trigger capture manually or from shipment events. Djust assembles Level 3 at capture time.

🔐 PayPage setup

Choose the UX

Redirect: simplest to operate; page navigates to Djust PayPage and returns via your Return URL.
iFrame: embedded card form; configure allowed origins and size. Use clear Cancel and Back actions.

Configure URLs (tenant settings)

URLs are configured once at tenant level and used automatically by PAY-101:
- OnCompletionURL (success redirect) = computed from effectiveRedirectBaseUrl + onSuccessPath
- OnErrorURL (error redirect) = effectiveRedirectBaseUrl + onErrorPath
- PostbackResultURL (S2S postback to Djust backend)
- PayPageUrl (absolute HTTPS endpoint used by PAY-101)
Manage them via:
- GET settings - ADM-SETTINGS-500
- PUT settings - ADM-SETTINGS-201
Do not pass Return/Dropout URLs to PAY-101; returnPath is not used for PCard L3 payments.

Handle the postback

Expect a token and status on your configured PostbackResultURL (from tenant settings).
Run PAY-502 earlier in checkout (recommended just before opening PayPage) so the FR pre-auth check is complete by the time Djust runs authorization after postback.

🏁 P-Card detection and gating

Decide and document when the checkout uses P-Card flow, for example:

Payment method selection Purchasing Card
Account-level policy requiring P-Card
Enterprise card flag detected during sign-in or cart review

The storefront should gate UI and validation accordingly: available shipping modes, invoice options, and L3 completeness hints.

🧪 Choose your authorization mode

Mode	When to use	Pros	Considerations
Full-amount pre-auth	Single shipment or short fulfillment cycles	Reserves entire amount early	Ensure partial captures release unused funds correctly
Per-shipment auth	Frequent splits or long tails	Clean link between auth and shipment	More auths to manage; ensure retry and reconciliation strategy
Hybrid top-up	Amount changes or incremental adds	Flexibility as order evolves	Requires robust idempotency and careful shopper comms

Authorization is executed automatically by Djust backend after the PayPage postback. There is no public authorization API to call.

📦 Level 3 readiness for capture

For the FR market, Djust enforces a minimal precheck before any authorization:

Field	Purpose	Required
Market ID	Identifies the purchasing market context	✅
Commitment ID	Identifies the associated engagement or contract	✅

Other Level 3 fields are assembled by Djust at capture time from your order data. You do not need to pass a full L3 set in precheck.

🔗 API quicklinks

FR pre-authorization check — PAY-502
Create PayPage token (CIT) - PAY-101
Get PCard L3 settings - ADM-SETTINGS-500
Update PCard L3 settings - ADM-SETTINGS-201