Merchant Onboarding (Manual flow)

This page describes the current onboarding flow for merchants on Djust Pay where merchant onboarding is handled manually by Djust.

⚙️ Overview

Djust currently manages merchant onboarding manually. This means Djust is responsible for:

• Creating the platform-level structure with the payment provider (account holders, accounts...)
• Generating onboarding links
• Pre-configuring payment settings and credentials

Merchants do not create their own accounts. Instead, Djust creates them on their behalf and provides them with a secure onboarding link.

flowchart LR
 subgraph subGraph0["Hosted Onboarding Flow"]
        D1["Client accesses<br> onboarding"]
        D2["Client fills KYC<br>& banking info"]
  end
    B["Contract & merchant <br>info collected"]
    B --> C["Djust creates<br> new merchant"]
    C --> D1
    C --> D2
    D1 --> E["PSP verifies<br>submitted data"]
    D2 --> E
    E --> F["Merchant ready<br>for payments"]

    D1@{ shape: rounded}
    D2@{ shape: rounded}
    B@{ shape: rounded}
    C@{ shape: rounded}
    E@{ shape: rounded}
    F@{ shape: rounded}
    subGraph0@{ shape: rounded}
     D1:::subphase
     D2:::subphase
     B:::phase
     C:::phase
     E:::phase
     F:::phase
    classDef phase fill:#0080ff,stroke:none,color:#ffffff,font-size:12px,border-radius:12px
    classDef subphase fill:#ffffff,stroke:none,color:#1A2A44,font-size:10px,border-radius:10px
    classDef startEnd fill:#FFAF40,stroke:none,color:#1A2A44,font-size:12px,border-radius:12px

🚶‍♂️Current Onboarding Flow (Manual)

1. Client signs with Djust and expresses intent to activate Djust Pay.
2. Djust creates the platform account structure with the payment provider:
   • accountHolderCode for the client
   • accountCode for the merchant account
   • Links API and webhook settings
3. Djust generates an onboarding link using the provider's hosted onboarding page.
4. The onboarding link is made available in the Djust backoffice.

📍Where to Find the Onboarding Link

Merchants can find their personal onboarding link in the Djust backoffice:

https://your.tenant.name.djust-app.com/pay/onboarding

This page displays the current onboarding status and provides access to the onboarding form hosted by the payment provider.

⚠️

This link is unique and should only be shared with the relevant internal teams completing the onboarding.

📋 What the Merchant Must Do

Once the onboarding link is opened:

• The merchant fills in their legal, business, and bank details in the provider's secure hosted form.
• The provider may request supporting documents for KYC verification.
• The onboarding process must be fully completed and verified before payments can be accepted.

📬 Support & Troubleshooting

If the merchant encounters issues with the onboarding form (e.g. link expired, validation errors), they should contact the Djust support team.

🧭 Next Steps After Onboarding

Once the merchant is verified:

• Djust will enable the account with the payment provider.
• Payment methods will be activated.
• The merchant can begin accepting payments through Djust Pay.

🔌 Onboarding Management via API

In addition to the manual flow described above, DJUST provides a set of API endpoints to monitor and manage onboarding processes programmatically.

Consulting onboarding processes

Available filters on the list endpoint: type, status, supplierId, supplierName.

The detail endpoint returns the full process state including organizationProfile, pspEntities, and steps.

⚠️

Supplier scoping: when using dj-client: SUPPLIER, a supplier can only view their own onboarding processes. Attempting to access another supplier's process returns a 404.

Managing the onboarding lifecycle

Five actions are available to manage the lifecycle of an onboarding process:

Status transitions are strictly controlled. An invalid transition returns the error code F-E-028. For a full list of error codes, see Error / Warning codes.

flowchart LR
    A["DRAFT"] -->|start| B["IN_PROGRESS"]
    B -->|suspend| C["SUSPENDED"]
    C -->|reactivate| B
    B -->|failure| D["FAILED"]
    D -->|retry| B
    B -->|complete| E["COMPLETED"]
    A -->|cancel| F["CANCELLED"]
    B -->|cancel| F
    C -->|cancel| F
    D -->|cancel| F