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 Adyen’s 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 given by Adyen

• 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
• Adyen 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 Adyen webhooks:

• AUTHORISATION: payment success or failure
• CAPTURE: confirmation of capture
• CANCEL, REFUND, CHARGEBACK: post-payment lifecycle events

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

---

🧠 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 Adyen 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

---