Changelog
Back to All

Release Notes for Direct Debits: 07/10/2026

16 days ago

This release introduces Direct Debit for payer accounts, along with a new Direct Debit API Guide and API Reference documentation. A creditor can collect funds from a client or organization account under a standing authorisation (a mandate). The IF Platform represents each collection as a Direct Debit Payment and charges the account through a linked Outgoing Transfer.

Direct Debit is supported for the following schemes:

SchemeCurrencyService Providers
bacsGBPClearBank, Banking Circle
sepaEURBanking Circle

Direct Debit Mandate API changes:

Direct Debit Mandates are supported through the new Direct Debit Mandate API. See the Direct Debit API Guide Direct Debit Mandate for workflows, status transitions and payload examples.

New Direct Debit Mandate API endpoints

Supported workflows for Direct Debit Mandates:

  • client.direct — create or update a mandate owned by a client; clientId is required on create
  • organization.direct — create or update a mandate owned by the organization

Status updates:

  • A mandate is created as pending and becomes active once the service provider activates it. A pending mandate cannot be updated through the API.
  • An active mandate can be updated to:
    • cancelled, with a cancellationReason: user-requested, account-closed or organization-action
    • rejected, with a rejectionReason: user-requested, account-closed or other
  • cancelled and rejected are final.
  • A collection that arrives for a mandate that is not active is returned automatically with the reason mandate-not-active.

Webhooks: Direct Debit Mandate webhooks are sent with the module direct-debits. Direct Debit Mandate Webhooks

  • direct-debit-mandate-created
  • direct-debit-mandate-activated
  • direct-debit-mandate-cancelled
  • direct-debit-mandate-rejected

Changes of the mandate's connection at the service provider are sent as connection-created and connection-updated.

Direct Debit Payment API changes:

Direct Debit Payments are created from the service provider's collections; they cannot be created through the API. Each payment is linked to its mandate through mandateId. It is also linked through outgoingTransferId to the Outgoing Transfer that charges the payer account. See the Direct Debit API Guide Direct Debit Payment for the payment lifecycle and payload examples.

New Direct Debit Payment API endpoints

Supported update workflows for Direct Debit Payments:

  • client.direct — return a payment owned by a client
  • direct — return a payment owned by the organization

Payment statuses:

  • pending — the collection has been announced and is waiting for its settlement date
  • completed — the collection settled and the payer account was charged
  • failed — the payer account was not charged

Webhooks: Direct Debit Payment webhooks are sent with the module direct-debits. Direct Debit Payment Webhooks

  • direct-debit-payment-created
  • direct-debit-payment-completed
  • direct-debit-payment-failed
  • direct-debit-payment-returned

Changes of the payment's connection at the service provider are sent as connection-created and connection-updated.

Direct Debit Return Flow

Key Highlights

  • Added the returnContext object to the Direct Debit Payment response model.
  • Returns and refunds are triggered by PATCH /direct-debit-payments/{id}, by setting:
    • returnContext.status = processing
    • returnContext.reason = {valid_reason}
  • Returns raised by the service provider (for example insufficient-balance) are reflected on the same object.
  • When a return completes on a payment that charged the payer account, an Incoming Transfer credits the funds back. The Incoming Transfer is linked to the payment through incomingTransferId.

Return Context Fields

The returnContext object includes:

  • enabled – Indicates whether the service provider accepts a return at this stage (read-only).
  • cutOffDateTime – Last date-time (UTC) when a return can be initiated, according to the scheme rules (read-only).
  • status – Current return lifecycle status (processing, completed, failed). A failed return can be initiated again.
  • reason – Mandatory reason code for initiating a return.

Eligibility Conditions

A return can be initiated only when:

  • returnContext.enabled = true
  • cutOffDateTime has not passed
  • No return is processing or completed
  • Direct Debit Payment status is pending or completed, or failed after a failed return
  • A valid return reason is provided

Return Reasons

Supported return reason codes:

  • account-closed
  • advance-notice-disputed
  • amount-not-matched
  • amount-not-yet-due
  • insufficient-balance
  • mandate-not-active
  • no-account
  • no-mandate
  • presentation-overdue
  • service-user-not-match

For the full integration flow, see the Initiate a Return / Refund

Example Request for a Direct Debit Payment return:

{
  "workflow": {
    "code": "client.direct"
  },
  "data": {
    "directDebitPayment": {
      "returnContext": {
        "status": "processing",
        "reason": "advance-notice-disputed"
      }
    }
  },
  "connect": {},
  "metadata": {}
}

Documentation updates:

  • Added the Direct Debit API Guide, covering mandate and payment lifecycles, workflows, the return flow, webhooks and payload examples
  • Added the Direct Debit Mandates and Direct Debit Payments operations to the Outgoing Transfer API Reference, with request and response schemas