Guides
Start typing to search…

Pre-authorization check - PAY-502

What this page covers

  • Why PAY-502 gates authorization for P-Card L3
  • When to call it in the flow
  • Minimal request/response contract and typical errors

Quick facts

  • Mandatory before authorization (FR market): run PAY-502 and fix any missing identifiers before starting tokenization and payment.
  • What it validates (FR): presence of Market ID and Engagement ID in the order context.
  • If PAY-502 fails, do not proceed with P-Card; ask the buyer for the missing fields or fall back to another payment method.

Where PAY-502 fits

flowchart LR
  DRAFT[Draft order<br>ready to pay] --> PRE[Pre-auth check<br>PAY-502]
  PRE -->|OK| PAY101[Create PayPage token<br>PAY-101]
  PRE -->|KO| FIX[Ask for missing Market ID or 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,PRE,PAY101,OPEN touch
  class PB,AUTH djust
  class FIX warn

  style DRAFT rx:8,ry:8
  style PRE 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 FIX rx:8,ry:8

Reading guide

  • Call PAY-502 when the order is ready to pay.
  • Only if OK, proceed to PAY-101 (PayPage).
  • After PayPage postback, authorization is automatic (no public auth API).
  • Front-end must poll order/payment status after PayPage until a terminal state (return URLs are UX-only).

Where the identifiers live

The identifiers are stored as Custom Fields (CF) associated with roles of the same logical name:

ScopeCF role (logical name)Purpose
AccountMARKET_IDMarket Identifier used for Level 3 P-Card compliance
Order (commercial)ENGAGEMENT_IDEngagement Identifier used for Level 3 P-Card compliance

What PAY-502 does

  • Does not collect data — it only validates that these CFs are present and coherent for the current reference.
  • On failure, it returns missingFields with scope (ACCOUNT/ORDER) and field (MARKET_ID/ENGAGEMENT_ID).

How to fix a KO

  • Missing ENGAGEMENT_ID (Order): collect the value in the UI and persist it on the order (e.g., via ORDER-222), then re-run PAY-502.
  • Missing MARKET_ID (Account): the P-Card method must stay blocked until the account CF is completed by an admin/operator.

Request (minimal expectations)

Send enough context for Djust to validate the required identifiers for the order being paid.

Fields (illustrative)

  • orderId - ties the check to your order
  • identifiers
    • marketId - string
    • engagementId - string

Response (typical)

  • ready - true/false
  • missingFields - array when status=KO (e.g., ["marketId","engagementId"])
  • {
  "ready": false,
  "missingFields": [
    {
      "scope": "ORDER",
      "field": "ENGAGEMENT_ID",
      "path": "order.customFields.engagementIdCFExternalId",
      "source": "ORDER_CF"
    }
  ]
}

Behavior

  • ready=true → you may proceed to PAY-101.
  • ready=false → block the P-Card path; prompt for missing values or propose another payment method.

Operational tips

  • Run PAY-502 as close as possible to payment start (e.g., on the Payment step), and always before PAY-101.
  • If you cache form data, re-validate with PAY-502 after edits to avoid stale values.
  • On KO, suppress PayPage and guide the user to complete the missing fields.

🔗 API quicklinks

Updated 1 day ago