Managing Card Payments

This documentation provides a comprehensive overview of how card payments are handled within the Djust Pay module. It details the user flow, API interactions, 3D Secure (3DS) handling, webhook management, capture and refund logic, and chargeback processing.

💳 Supported Card Types

Djust Pay supports a wide range of international and local card schemes.

Natively integrated and supported schemes :

• Visa and Mastercard (credit, debit, Electron, Maestro).
• Cartes Bancaires (CB)
• American Express

Additional schemes such as:

• Discover
• JCB
• Diners Club
• UnionPay (China)
• Bancontact (Belgium)
• Dankort (Denmark)

are included in our roadmap and can be enabled progressively based on client demand.

Card support may vary depending on your merchant configuration and the markets you operate in. For a complete and up-to-date list of supported card types, please refer to your Customer Support Manager.

🧾 Business & Purchase Cards

In a B2B context, business cards (also known as commercial, corporate, or company cards) and purchase cards (P-Cards) are commonly used by professionals to track company-related expenses.

Djust Pay supports these cards. Please note:

• Business card detection is automatic and available in Djust Pay platform.
• Level 2/3 data enrichment is not required but may be configured for merchants needing detailed reporting or integration with expense systems.
• Some purchase cards may require additional configuration with card providers for tax and invoice matching.

If your clients frequently use business or P-Cards, we recommend verifying with Djust that these are enabled on your account and fully supported in your target regions.

🧭 Overview of the Payment Workflow

The Djust Pay module leverages a hosted Drop-in component to offer a secure, branded, and compliant card payment experience. Here's a simplified flow of the interaction between systems:

sequenceDiagram
    participant User
    participant Drop-in
    participant Djust PAY

    User->>Drop-in: Starts payment
    Drop-in->>Djust PAY: PAY-501 - Get available payment methods
    Djust PAY-->>Drop-in: Send methods

    User->>Drop-in: Enters card info
    Drop-in->>Djust PAY: PAY-101 - Initiate credit card payment

    Djust PAY-->>Drop-in: Final result displayed to user (authorised or refused)

🔁 Full Card Payment Lifecycle

1. Initialize Drop-in

sequenceDiagram
    participant Frontend as Drop-in
    participant Backend_Djust as Djust PAY

    %% Etape 1: Starts payment
    Frontend->>Backend_Djust: PAY-501 - Get available payment methods
    Backend_Djust-->>Frontend: Returns the list of payment methods configured to be displayed

    %% Etape 2: User interaction with Drop-in
    Note right of Frontend: The Drop-in widget loads the available payment methods

• Fetch available payment methods via PAY-501 - GET /v1/shop/payments/payment-methods
• Drop-in is configured with methods supported by the merchant
• Saved cards (if enabled) are included

2. Card Information Entry & Payment Initiation

sequenceDiagram
    participant Frontend as Drop-in
    participant Backend_Djust as Djust PAY

    %% Etape 2: User interaction with Drop-in
    Note right of Frontend: The Drop-in widget loads the available payment methods
    Frontend->>Frontend: Credit card details entered by the user
    Frontend->>Backend_Djust: PAY-101 - Initiation of credit card payment
    Backend_Djust-->>Backend_Djust: Order payment status set to `AUTHORIZATION_PENDING`

    %% Etape 4: Finalizing payment
    Backend_Djust-->>Frontend: Transmission of the final result to the customer - accepted/refused/challenged

    %% Webhook for updating payment status
    Backend_Djust-->>Backend_Djust: Update payment status AUTHORIZED/REFUSED returned by the PSP

• User enters card details in Drop-in

⚠️

Attention

The value of the transaction amount must comply with the standard ISO-4217 : https://en.wikipedia.org/wiki/ISO_4217

For example, for the euro currency EUR, the expected amount must be in centimes.

• Payment is initiated via PAY-101 - POST /v1/shop/payments
• The PSP may return a 3DS action if the transaction is challenged

3. 3D Secure Authentication (if required)

sequenceDiagram
    participant Frontend as Drop-in
    participant Backend_Djust as Djust PAY
    participant Banque as Issuing bank

    %% Etape 2: User interaction with Drop-in
    Note right of Frontend: The Drop-in widget loads the available payment methods
    Frontend->>Frontend: Credit card details entered by the user
    Frontend->>Backend_Djust: PAY-101 - Initiation of credit card payment
    Backend_Djust-->>Frontend: Transmission of the 3DS action to Drop-in when challenge is asked

    %% Etape 3: 3D Secure Challenge
    Frontend->>Banque: Redirection to the bank for 3DS authentication
    Banque-->>Frontend: Authentication validation or rejection

    %% Etape 4: Finalizing payment
    Frontend->>Backend_Djust: PAY-102 - Transmission of the result of the 3DS challenge
    Backend_Djust-->>Frontend: Payment accepted/refused. Final result displayed to customer

• Drop-in redirects user to the issuing bank for 3DS challenge
• Result is returned to Djust via PAY-102 - POST /v1/shop/payments/details
• Payment is either:
  • Authorised (go to capture)
  • Refused (error returned to user)

4. Webhook Management

Djust receives notifications via PSP webhooks:

• AUTHORISATION: payment success or failure
• CAPTURE: confirmation of capture
• CANCEL, REFUND, CHARGEBACK: post-payment lifecycle events (see Refunds for full and partial refund details)

All webhooks:

• Are acknowledged by Djust
• Update the transaction status in Djust database
• Are visible via the Djust Backoffice and APIs

5. Capture Workflow

After a credit card payment is authorized, Djust Pay allows for either immediate or delayed capture of funds, depending on your operational needs.

Capture Modes

Note: Only full captures are supported. Partial captures are not currently available.

Failures during manual capture trigger:

• Error notification
• Status update
• Manual intervention workflow if needed

Commission Splits at Capture

When a card payment is captured, Djust Pay automatically calculates and applies commission splits based on the configured rates. This ensures that each capture reflects the correct financial distribution between all parties.

How it works

• Commissions are calculated exclusively server-side — no rate or split information is passed in the capture request.
• Two optional commission rates are used:
  • Platform commission rate — configured at the tenant level
  • Marketplace supplier commission rate — configured per supplier in the marketplace matrix
• If a rate is not configured, the corresponding commission line is simply omitted from the split.
• The supplier share always equals the captured amount minus all applicable commissions.

Split structure

Each capture includes a split with up to three lines:

✅

Tip: The API contract for ADM-PAY-101 does not change. Commission splits are applied transparently based on the rates configured in your tenant settings and marketplace matrix.

For the full algorithm — including how rates are loaded, how cent corrections are applied to the supplier share, and worked examples — see Commission Split Calculation. To configure the per-supplier marketplace commission rates, see Marketplace Commissions Matrix.

flowchart LR
  AUTH[Payment authorized] --> CAP[Capture triggered<br>manual or auto]
  CAP --> LOAD[Load commission rates<br>platform + supplier]
  LOAD --> CALC[Calculate splits<br>commissions + supplier share]
  CALC --> VALID{Amounts valid}
  VALID -->|Yes| SEND[Send capture with splits<br>ADM-PAY-101]
  VALID -->|No| BLOCK[Capture blocked<br>functional error]
  SEND --> OK[Capture confirmed<br>splits recorded]

  %% Styles (Readme)
  classDef create   fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#0b3d91;
  classDef read     fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#1e1b4b;
  classDef update   fill:#e0f7fa,stroke:#06b6d4,stroke-width:2px,color:#0c4a6e;
  classDef decision fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
  classDef place    fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
  classDef stop     fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;

  class AUTH,CAP create
  class LOAD,CALC read
  class VALID decision
  class SEND update
  class BLOCK stop
  class OK place

  style AUTH rx:8,ry:8
  style CAP rx:8,ry:8
  style LOAD rx:8,ry:8
  style CALC rx:8,ry:8
  style VALID rx:8,ry:8
  style SEND rx:8,ry:8
  style BLOCK rx:8,ry:8
  style OK rx:8,ry:8

Key Business Rules & Notes

• Drop-in component handles both card data entry and 3DS flows, ensuring PCI compliance.
• All transaction statuses are tracked in Djust and synchronized with PSP events.
• All webhook events are idempotent and acknowledged.
• Errors are displayed to users and logged for support analysis.

🧩 Related APIs

• PAY-501 - GET /v1/shop/payments/payment-methods
• PAY-101 - POST /v1/shop/payments
• PAY-102 - POST /v1/shop/payments/details
• ADM-PAY-101 - POST /v1/payments/captures