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)

Redirect vs. in-widget challenge: the bank decides

A common integration mistake is to assume that 3D Secure always happens inside the widget (an in-page challenge / iframe). This is not guaranteed.

Even when the integration is configured to rely on the Drop-in as much as possible, the issuing bank can require a full-page redirection instead of an embedded challenge. This is the bank's decision (based on its 3DS implementation, risk rules, or the card itself), and it cannot be forced back into the widget by the merchant or by Djust.

In practice, PAY-101 (or PAY-102) returns one of two action types depending on what the bank imposes:

⚠️

Attention

Your integration must handle both cases. Supporting only the in-widget challenge will silently break every payment whose bank requires a redirection — the shopper is sent to the bank, authenticates successfully, but the payment is never finalized because your return page does not exist or does not complete the flow.

Handling the return page after a redirection

When a redirection is required, the shopper leaves your site and is later sent back to the return page you declared. You must implement this page so the payment can be finalized.

1. Declare your return path in PAY-101. Set returnPath in the PAY-101 request — the path the shopper is redirected back to after 3DS authentication or any other external redirection (e.g. /payment-return).
2. Read the redirect result on the return page. When the shopper comes back, the URL carries the result returned by the bank (typically a redirectResult, or a threeDSResult depending on the flow).
3. Finalize via PAY-102. Submit these values to PAY-102 - POST /v1/shop/payments/details in the details object (keys redirectResult or threeDSResult, depending on the flow type). PAY-102 returns the final resultCode (Authorised, Refused, …).

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

    Frontend->>Backend_Djust: PAY-101 - Initiate payment (with returnPath)
    Backend_Djust-->>Frontend: resultCode = RedirectShopper + redirect action
    Frontend->>Banque: Full-page redirection to the bank
    Banque-->>Frontend: Return to returnPath with redirectResult in the URL
    Frontend->>Backend_Djust: PAY-102 - Submit details (redirectResult / threeDSResult)
    Backend_Djust-->>Frontend: Final resultCode (Authorised / Refused)

💡

Whether the bank imposes a redirection or an in-widget challenge, the payment is always finalized the same way: by submitting the authentication result to PAY-102. The only difference is where the result comes from — the URL of your return page (redirection) or the Drop-in callback (in-widget challenge).

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