Refunds

Introduction

DJUST PAY supports refunding payments on orders — either fully or partially. This page explains how refunds work, how they are funded, and their impact on commissions and supplier payouts.

Key Concepts

Full Refund

A full refund reimburses the entire order amount to the buyer. The payment status of the order transitions to REFUNDED.

Partial Refund

A partial refund reimburses a specific amount (less than the order total) to the buyer. Multiple partial refunds can be issued on the same order, up to the total order amount. The payment status of the order reflects the partial refund state until the full amount is refunded.

Refund Funding

Refunds are funded from the supplier balance account. If the supplier's balance is insufficient, the configured funding policy at the tenant level determines whether the marketplace balance account can cover the difference.

This mechanism is identical for both full and partial refunds.

Typical Workflow

flowchart LR
  %% 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 add      fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
  classDef remove   fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;
  classDef decision fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
  classDef place    fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
  classDef sys      fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;
  classDef ok       fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
  classDef stop     fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;

  A["📘 Operator triggers refund<br>POST /v1/orders/orderId/refund"]:::create
  B{{"💰 Amount specified?"}}:::decision
  C["🔄 Partial refund<br>Specified amount"]:::update
  D["🔄 Full refund<br>Total order amount"]:::update
  E{{"💳 Supplier BA<br>sufficient?"}}:::decision
  F["✅ Funded from<br>supplier BA"]:::place
  G{{"🏦 Marketplace<br>funding policy?"}}:::decision
  H["💰 Marketplace BA<br>covers difference"]:::add
  I["⚠️ Refund blocked<br>Insufficient funds"]:::stop
  J["✅ Refund processed<br>Commission recalculated"]:::place

  A --> B
  B -->|Yes| C
  B -->|No| D
  C --> E
  D --> E
  E -->|Yes| F --> J
  E -->|No| G
  G -->|Enabled| H --> J
  G -->|Disabled| I

  style A rx:8,ry:8
  style C rx:8,ry:8
  style D rx:8,ry:8
  style F rx:8,ry:8
  style H rx:8,ry:8
  style I rx:8,ry:8
  style J rx:8,ry:8

API Reference

Endpoint: POST /v1/orders/{orderId}/refund — operationId: ADM-ORDER-100

Header	Required	Description
`dj-client`	Yes	`OPERATOR`
`dj-api-key`	Yes	API key

Request body

Field	Type	Required	Description
`amount`	number	No	Amount to refund. If omitted, a full refund is performed.

Partial refund example

{
  "amount": 25.50
}

Full refund example

{}

Response

200 OK — refund successfully initiated.

Business Rules

Rule	Description
Partial refund	The `amount` field specifies the refund amount. Multiple partial refunds can be issued on the same order.
Cumulative limit	The total of all partial refunds cannot exceed the original order amount.
Commission adjustment	The marketplace commission is recalculated proportionally to the refunded amount.
Funding source	Refunds are funded from the supplier balance account. If insufficient, the marketplace balance account may cover the difference based on the tenant's funding policy.
Payout impact	A partially refunded order remains eligible for supplier payout, with the payout amount adjusted to account for the refund.

Sequence Diagram

sequenceDiagram
    participant Operator
    participant DJUST PAY
    participant PSP

    Operator->>DJUST PAY: POST /v1/orders/{orderId}/refund (dj-client: OPERATOR)
    DJUST PAY->>DJUST PAY: Validate refund amount against order total
    DJUST PAY->>DJUST PAY: Check supplier BA balance

    alt Sufficient funds in supplier BA
        DJUST PAY->>PSP: Trigger refund from supplier BA
    else Insufficient funds and marketplace funding enabled
        DJUST PAY->>PSP: Transfer from marketplace BA to supplier BA
        DJUST PAY->>PSP: Trigger refund from supplier BA
    end

    PSP-->>DJUST PAY: Webhook: refund confirmed
    DJUST PAY->>DJUST PAY: Update payment status and recalculate commission
    DJUST PAY-->>Operator: 200 OK

Best Practices

Start with partial refunds — if the buyer only needs a partial reimbursement, use the amount field to avoid refunding the full order.
Check the order's refund history — before issuing a new partial refund, verify the cumulative amount already refunded to avoid exceeding the order total.
Monitor funding policy — if your marketplace funding policy is disabled, ensure supplier balance accounts are adequately funded before triggering refunds.
Commission tracking — after a partial refund, the marketplace commission is proportionally reduced. Monitor your commission reports accordingly.

Common Mistakes

Mistake	Consequence	How to avoid
Omitting `amount` when intending a partial refund	A full refund is performed instead	Always specify `amount` for partial refunds
Issuing partial refunds exceeding the order total	The API rejects the request	Track cumulative refunded amounts per order
Not checking supplier BA balance before refunding	Refund may fail if marketplace funding is disabled	Enable marketplace funding policy or ensure supplier BAs are funded

Error Reference

For the complete list of DJUST error and warning codes, refer to the dedicated page: Error / Warning codes