Authorization Modes (CIT)

This page explains how Djust Pay runs CIT authorizations automatically after PayPage tokenization, what modes are available, and what you must do before that happens.

Heads-up

• No public Authorization API. Djust runs authorization automatically after PayPage postback.
• Two prechecks:
  1. Before authorization (your call): run PAY-502 (FR pre-auth check).
  2. Before capture (Djust): pre-capture Level 3 completeness check.
• No incremental top-up today. Authorizations are not increased above the order amount.
• Front-end polling required
  • After PayPage, Djust runs automatic authorization S2S. The storefront must poll the order/payment status until a terminal outcome is available.
  • Return URLs (redirect or iFrame) are UX-only and not reliable to infer success/failure.

  sequenceDiagram
    participant UI as Storefront UI
    participant DJ as Djust backend
    participant PP as PayPage
  
    UI->>PP: Open PayPage (token from PAY-101)
    PP-->>DJ: S2S postback (tokenization result)
    par Poll loop
      UI->>DJ: GET order/payment status
      DJ-->>UI: PENDING_AUTHORIZATION
    and Authorization
      DJ->>DJ: Run authorization (S2S)
      DJ-->>UI: AUTHORIZED / REFUSED
    end
    UI->>UI: Stop polling on terminal status

🔄 Runtime sequence

flowchart LR
	DRAFT[Draft order<br>ready to pay] --> PREAUTH[Pre-check FR<br>call PAY-502]
	PREAUTH -->|OK| INIT[Init payment<br>Create PayPage token<br>PAY-101]
	PREAUTH -->|KO| STOP[Request missing fields<br>Market ID or Engagement ID<br>or cancel P-Card]
	INIT --> FORM[Card entry<br>Djust PayPage]
	FORM --> PB[Postback received<br>token and status]
	PB --> AUTH[Auto authorization<br>Djust backend]
	AUTH --> LOGI[Logistics orchestration<br>splits and partials]
	LOGI --> PRECAP[Djust pre-capture check<br>Level 3 completeness]
	PRECAP --> CAP[Capture with Level 3<br>per shipped lines]

	classDef touch fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
	classDef djust fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;
	classDef warn  fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
	class DRAFT,PREAUTH,INIT,FORM,CAP touch
	class PB,AUTH,LOGI,PRECAP djust
	class STOP warn
	style DRAFT rx:8,ry:8
	style PREAUTH rx:8,ry:8
	style INIT rx:8,ry:8
	style FORM 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
	style STOP rx:8,ry:8

Reading guide

• Green nodes are your actions: handle PayPage postback, run PAY-502 before authorization, and trigger captures.
• Grey nodes are Djust-managed: authorization, logistics orchestration, and the pre-capture check.

About the data checked by PAY-502

PAY-502 validates Custom Fields (CF) tied to roles: MARKET_ID on the Account, and ENGAGEMENT_ID on the Order. If either is missing, authorization is rejected (you must fix the CFs and re-run PAY-502 before payment).

🧭 Authorization modes

Djust configures one of the following CIT authorization modes for your tenant or store. You never call an auth endpoint.

Mode selection is a Djust configuration. If you need to change it, align with your Djust contact.

Not supported now: incremental “top-up” above the original order amount.

🧩 Mode flows

A) Full amount pre-auth

flowchart TD
  DRAFT[Draft order<br>ready to pay] --> PRE[Pre-check - FR<br>call PAY-502]
  PRE -->|OK| INIT[Init payment<br>Create PayPage token<br>PAY-101]
  PRE -->|KO| FIX[Request missing fields<br>Market ID / Engagement ID<br>or cancel P-Card]
  INIT --> FORM[Card entry<br>Djust PayPage]
  FORM --> AUTH[Auto authorization<br>by Djust backend<br>full amount]
  AUTH --> SPLIT[Split by shipments]
  SPLIT --> C1[Capture 1<br>with Level 3]
  SPLIT --> C2[Capture 2<br>with Level 3]

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

  class DRAFT,PRE,INIT,FORM,C1,C2 touch
  class AUTH,SPLIT djust
  class FIX warn

  style DRAFT rx:8,ry:8
  style PRE rx:8,ry:8
  style INIT rx:8,ry:8
  style FORM rx:8,ry:8
  style AUTH rx:8,ry:8
  style SPLIT rx:8,ry:8
  style C1 rx:8,ry:8
  style C2 rx:8,ry:8
  style FIX rx:8,ry:8

Step summary

• Draft order ready to pay
• Pre-check with PAY-502
  • OK → proceed
  • KO → prompt for Market ID / Engagement ID or cancel P-Card
• Init payment (PAY-101) to display PayPage
• User enters card
• Auto authorization by Djust for the total amount
• Shipments & captures (multiple captures possible, each with L3)

B) Per-shipment authorization

flowchart TD
  DRAFT[Draft order<br>ready to pay] --> PRE[Pre-check - FR<br>call PAY-502]
  PRE -->|OK| INIT[Init payment<br>Create PayPage token<br>PAY-101]
  PRE -->|KO| FIX[Request missing fields<br>Market ID or Engagement ID<br>or cancel P-Card]
  INIT --> FORM[Card entry<br>Djust PayPage]
  FORM --> PB[Postback received<br>token and status]

  %% Authorizations happen now (payment time)
  PB --> PLAN[Planned shipments<br>or line groups]
  PLAN --> A1[Auto authorization<br>group 1 amount]
  PLAN --> A2[Auto authorization<br>group 2 amount]

  %% Captures occur later, independently
  A1 --> T1[Capture trigger 1<br>manual or by status change]
  A2 --> T2[Capture trigger 2<br>manual or by status change]

  T1 --> PRECAP1[Djust pre-capture check<br>Level 3 completeness]
  PRECAP1 --> C1[Capture 1<br>with Level 3]

  T2 --> PRECAP2[Djust pre-capture check<br>Level 3 completeness]
  PRECAP2 --> C2[Capture 2<br>with Level 3]

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

  %% Your touchpoints
  class DRAFT,PRE,INIT,FORM,T1,T2,C1,C2 touch
  %% Djust-managed
  class PB,PLAN,A1,A2,PRECAP1,PRECAP2 djust
  %% Error branch
  class FIX warn

  style DRAFT rx:8,ry:8
  style PRE rx:8,ry:8
  style INIT rx:8,ry:8
  style FORM rx:8,ry:8
  style PB rx:8,ry:8
  style PLAN rx:8,ry:8
  style A1 rx:8,ry:8
  style A2 rx:8,ry:8
  style T1 rx:8,ry:8
  style T2 rx:8,ry:8
  style PRECAP1 rx:8,ry:8
  style PRECAP2 rx:8,ry:8
  style C1 rx:8,ry:8
  style C2 rx:8,ry:8
  style FIX rx:8,ry:8

• Authorizations (A1, A2, …) are created right after payment (postback), potentially days/weeks before any capture.
• Captures are decoupled from shipment readiness: each has its own trigger node (manual or by status change).
• Authorization per shipment still happens automatically by Djust, and pre-capture checks are done by Djust right before executing each capture.

Responsibilities

You (integrator)

• Run PAY-502 (FR pre-auth check) before payment.
• Start payment via PAY-101, show PayPage, and trigger captures when each shipment is ready.
• Keep capture triggers idempotent and store only opaque references (no PAN/CVC).

Djust

• Handles PayPage postback and performs automatic authorizations at T0 for shipment groups.
• Runs pre-capture Level 3 checks just before each capture and attaches the L3 addendum.
• Re-authorizes if a hold has expired, following this mode’s rules (Roadmap).

Timeline & windows (typical expectations)

Capture triggers

• Manual: an operator triggers capture from back-office once items ship.
• Status-driven: your OMS/WMS sets a status (e.g., Shipped → capture).
• For each trigger, Djust runs the pre-capture L3 check; if incomplete, the capture is blocked with a clear error.

Error handling (common cases)

🔗 API quicklinks

• FR pre-authorization check - PAY-502
• Create PayPage token (CIT) - PAY-101
• No public Authorization API - authorization is executed by Djust automatically at payment time (after postback)