Funding Transfers

Introduction

Funding transfers are internal movements of funds between balance accounts in DJUST PAY — for example, from a MARKETPLACE balance account to a SUPPLIER balance account, or vice versa. These transfers support key payment operations such as supplier payouts and refunds.

Two API endpoints allow operators and suppliers to list and inspect funding transfers for operational monitoring, financial reconciliation, and diagnostics.

Key Concepts

Balance Account Types

Transfer Statuses

Related Entity Types

Each funding transfer is linked to a business operation:

Scope and Visibility

Access follows the standard DJUST scoping rules:

• dj-client: OPERATOR — access to all funding transfers across the tenant. Can filter by supplier.
• dj-client: SUPPLIER — restricted to funding transfers that involve the connected supplier's balance account. This restriction is enforced server-side and cannot be bypassed by filters.

Key Endpoints

Both endpoints require dj-client and dj-api-key headers.

List Funding Transfers

GET /v1/payments/funding-transfers
dj-client: OPERATOR
dj-api-key: {{apiKey}}

Available Filters

Sorting

Sorting is supported via the sort query parameter in field:direction format:

✅

Tip: Invalid or malformed sort entries are silently ignored — no error is returned.

Example Request

GET /v1/payments/funding-transfers?createdAtFrom=2026-01-01T00:00:00Z&createdAtTo=2026-03-31T23:59:59Z&statuses=COMPLETED&sourceBalanceAccountType=MARKETPLACE&targetBalanceAccountType=SUPPLIER&sort=amount:desc
dj-client: OPERATOR
dj-api-key: {{apiKey}}

Example Response

{
  "data": [
    {
      "transferId": "ft-abc-123",
      "createdAt": "2026-02-15T10:30:00Z",
      "status": "COMPLETED",
      "amount": 1500.00,
      "currency": "EUR",
      "sourceBalanceAccountType": "MARKETPLACE",
      "targetBalanceAccountType": "SUPPLIER",
      "supplierExternalId": "supplier-456",
      "supplierName": "Acme Supplies",
      "reference": "PAY-2026-02-001",
      "relatedEntityType": "PAYOUT",
      "relatedEntityId": "payout-789",
      "failureReason": null
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 1,
    "totalPages": 1
  }
}

Get Transfer Detail

GET /v1/payments/funding-transfers/{transferId}
dj-client: OPERATOR
dj-api-key: {{apiKey}}

Returns the complete details of a single funding transfer, including amount, status, balance account types, supplier information, reconciliation reference, related entity, and failure reason (if applicable).

Example Response

{
  "transferId": "ft-abc-123",
  "createdAt": "2026-02-15T10:30:00Z",
  "status": "COMPLETED",
  "amount": 1500.00,
  "currency": "EUR",
  "sourceBalanceAccountType": "MARKETPLACE",
  "targetBalanceAccountType": "SUPPLIER",
  "supplierExternalId": "supplier-456",
  "supplierName": "Acme Supplies",
  "reference": "PAY-2026-02-001",
  "relatedEntityType": "PAYOUT",
  "relatedEntityId": "payout-789",
  "failureReason": null
}

Typical API Workflow

sequenceDiagram
    participant Client
    participant DJUST PAY

    Client->>DJUST PAY: GET /v1/payments/funding-transfers (ADM-PAY-553)
    DJUST PAY-->>Client: 200 OK (paginated list)
    Client->>DJUST PAY: GET /v1/payments/funding-transfers/{transferId} (ADM-PAY-503)
    DJUST PAY-->>Client: 200 OK (transfer detail)

Best Practices

1. Use date filters — always specify a date range to limit results and improve response time.
2. Combine filters for targeted queries — use sourceBalanceAccountType and targetBalanceAccountType to isolate specific flows (e.g. marketplace-to-supplier only).
3. Use relatedEntityType to correlate — filter by PAYOUT or REFUND to quickly identify transfers related to a specific business operation.
4. Check failureReason on FAILED transfers — this field provides diagnostic information about why a transfer did not succeed.
5. Leverage sorting — use sort=createdAt:desc for most recent transfers first, or sort=amount:desc to find the largest transfers.

Common Mistakes

Error Reference

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

Related Documentation

• Funding Transfers - Export
• Supplier Payout Lifecycle
• Marketplace Payout Lifecycle
• Introduction to Djust Pay