Tokenization (CIT) - PAY-101

What this page covers

• How to start the PayPage flow and obtain a token (PAY-101)
• Redirect vs iFrame integration choices
• The postback contract and error handling
• Where this sits vs PAY-502 (pre-auth check) and auto-authorization

Quick facts

• Run PAY-502 first (FR pre-authorization check).
• Then call PAY-101 to create a PayPage token and display the secure card form.
• After the buyer completes the form, Djust receives the postback and will run automatic authorization (there is no public auth API).
• Card data never touches your app (PCI scope reduction).

---

🧭 Where tokenization fits

flowchart LR
  DRAFT[Draft order<br>ready to pay] --> PREAUTH[FR pre-auth check<br>call PAY-502]
  PREAUTH -->|OK| PAY101[Create PayPage token<br>PAY-101]
  PREAUTH -->|KO| STOP[Ask for missing Market ID / Engagement ID<br>or cancel P-Card]
  PAY101 --> OPEN[Open PayPage<br>redirect or iFrame]
  OPEN --> PB[Postback received<br>token and status]
  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;
  classDef warn  fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;

  class DRAFT,PREAUTH,PAY101,OPEN touch
  class PB,AUTH djust
  class STOP warn

  style DRAFT rx:8,ry:8
  style PREAUTH 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
  style STOP rx:8,ry:8

Reading guide

• PAY-502 must succeed before you initiate tokenization.
• PAY-101 returns a token you use to redirect to PayPage or render it in an iFrame.
• After postback, Djust authorizes automatically (per your configured mode).

Reminder: before calling PAY-101, ensure the required CFs exist: MARKET_ID on the Account and ENGAGEMENT_ID on the Order (validated by PAY-502).

---

🖥️ Integration options

Redirect

• Navigate the browser to PayPage; on completion, Djust posts back to your Return URL.
• Simple to operate and test; fewer browser constraints.

iFrame

• Render the PayPage inside your page.
• Configure allowed origins, sizing, and a clear cancel/back path.
• Use the same postback and dropout URLs as redirect.

---

🛰️ PAY-101 — what to send & what you get

Request essentials

• Correlation ID (your order reference)
• Optional UX context (locale, theming hints)
• Do not provide URLs to PAY-101. Djust composes OnCompletionURL, OnErrorURL and PostbackURL from tenant settings (ADM-SETTINGS-201/500).

Response

• A token for PayPage
• The PayPage URL (from settings payPageUrl) for redirect or iFrame initialization

Do not send PAN/CVC to Djust; PayPage collects all card data.

Next step

• On success, Djust runs authorization automatically (no public auth API).
• On canceled/error, present a safe retry or fallback payment method.

Settings-driven URLs

The PayPage URLs are configured once at tenant level:

• GET settings — ADM-SETTINGS-500
• PUT settings — ADM-SETTINGS-201

Djust composes OnCompletionURL, OnErrorURL (front redirects) and PostbackURL (S2S) from these settings. returnPath is not used with ITS.

---

🔄 Front-end status polling (mandatory)

• Why: Authorization is executed by Djust server-to-server after PayPage. Redirect/iFrame return URLs are not reliable indicators of success.
• What to do: After PayPage submission, poll your order/payment status endpoint until a terminal state is reached.

Recommended loop (example)

1. Start a spinner and poll every 2s for 60s.
2. If still pending, continue with exponential backoff (4s, 8s…) up to 2 minutes total.
3. Stop on: AUTHORIZED → proceed; REFUSED → display actionable error.

Status model (suggested)

• PENDING_AUTHORIZATION → keep polling
• AUTHORIZED → success
• REFUSED → stop and show guidance

Do not rely on the PayPage redirect/return to decide; it is UX-only. The order/payment status exposed by your backend is the source of truth.

---

🧪 Minimal test plan

1. PAY-502 succeeds; PAY-101 returns a token.
2. Redirect/iFrame shows PayPage; complete card entry.
3. Your Return URL receives the postback (success).
4. Confirm authorization status appears in your order context shortly after.
5. Exercise cancel, timeout, and error paths (verify dropout handling).

---

🔐 Security notes

• Always use TLS; allowlist the PayPage and postback domains.
• Log only opaque IDs (token, correlationId).
• Never store PAN/CVC; keep error messages generic.

---

🚨 Common errors & fixes

---

🔗 API quicklinks

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