Capture & Level 3

What this page covers

• How captures are triggered (manual or status-driven) and decoupled from authorization
• The pre-capture check run by Djust (Level 3 completeness)
• Minimal Level 3 field expectations and common errors

Quick facts

• Authorization already happened at payment time (after PayPage postback).
• No top-up above the original order amount.
• Before each capture, Djust runs a Level 3 completeness check; if it fails, the capture is blocked with a clear error.

---

🕘 When and how captures run

• Triggering: captures are invoked later, per shipment (or group of lines), either manually by an operator or automatically on a status change (e.g., Shipped).
  • Endpoint ownership: capture is an admin operation; buyers never call it.
• Supported payment types: manual capture is available for both CREDIT_CARD and PCARD_L3 payment types, as long as the payment provider is DJUST_PAY and the payment status is AUTHORIZED.
• Mapping: each capture maps to the corresponding authorization created at payment time (per your mode: full amount vs per-shipment).

---

✅ Pre-capture check (Djust)

Djust validates Level 3 completeness from your order context right before executing each capture. If the data is incomplete or inconsistent, the capture is rejected with a clear error.

What Djust expects to be available (summary)

Header (capture scope)

• Currency, buyer reference (PO or similar), tax totals (if header-based), freight/duty (if applicable)

Per line (shipped items only)

• Product identifier (SKU or commodity code), description
• Quantity and UOM
• Unit price and extended amount
• Tax/discount/freight at line level if your setup requires per-line breakdown

Keep it consistent: line totals + header adjustments must equal the capture amount.

The pre-capture completeness check also relies on values sourced from the same CF roles: MARKET_ID (Account) and ENGAGEMENT_ID (Order). If either is missing or inconsistent with the capture scope, the capture is blocked until corrected.

Invoice number

The L3 capture standard requires an invoice number at capture time. The invoice number is resolved from a Custom Field with the role invoiceNumber (scope ORDER_LOGISTIC, type TEXT).

Validation rules:

• The invoice number is optional at order creation but mandatory at capture when the invoiceNumber role is configured.
• The value must not exceed 12 characters. Values longer than 12 characters are rejected at capture time.
• If the invoice number is missing when required, the capture is blocked with error F-E-001.

This validation applies only to L3 captures. Standard credit card captures are not affected by this check.

---

🔄 Capture flow

flowchart LR
  TRIG[Capture trigger<br>manual or status change] --> CALL[Call capture API<br>ADM-PAY-101]
  CALL --> CHECK[Djust pre-capture check<br>Level 3 completeness]
  CHECK -->|OK| CAP[Capture execution]
  CAP --> SETT[Settlement<br>acquirer]
  SETT --> STAT[Payment status updated<br>order context]
  CHECK -->|KO| ERR[Reject with error<br>fix Level 3 data then retry]

  %% 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 TRIG,CALL touch
  class CHECK,CAP,SETT,STAT djust
  class ERR warn

  style TRIG rx:8,ry:8
  style CALL rx:8,ry:8
  style CHECK rx:8,ry:8
  style CAP rx:8,ry:8
  style SETT rx:8,ry:8
  style STAT rx:8,ry:8
  style ERR rx:8,ry:8

---

🧠 Good practices

• Ship what you capture: include only shipped lines (or the subset actually fulfilled).
• Be explicit: ensure tax/freight/discounts follow your configured breakdown (header vs line).

---

🚨 Common errors & fixes

Capture errors occur in the ADM-PAY-101 flow after Djust’s pre-capture validation (e.g., missing Level 3 fields).

---

🔗 API quicklinks

• FR pre-authorization check - PAY-502
• Create PayPage token (CIT) - PAY-101
• Capture - ADM-PAY-101
• No public Authorization API — Djust runs authorization automatically after PayPage