Overview

This document describes the migration from the legacy Direct Debit Payment Initiation endpoint to the new endpoint with a simplified structure and aligned with ISO20022 payment terminology and structure.

The new endpoint provides:

Simplified payload
Simplified response model
Explicit debtor and creditor sections
Higher degree of structured object (e.g.
ISO-aligned terminology
Date-only fields
No nested resource creation
No idempotency keys in payload

Deprecation Date & End-of-Life

Deprecation Date: To-be-announced

End-of-Life: To-be-announced

Legacy Endpoints

Instruction: (POST) https://sepaexpress-prod-fx.azurewebsites.net/api/services/v2/Payments

GET/Reporting:

New Endpoints

Introduction: Initiating Collections, Collection Status & Reconciling

New Instruction: (POST) https://www.bankingcircleconnect.com/api/v1/direct-debits

New GET/Reporting: Customer Payment Status Report https://docs.bankingcircleconnect.com/docs/customer-payment-status-report

High-level Changes

Category	Legacy Endpoint	New Endpoint	Impact
Mandate Management	Required to supply a reference to a self-managed- or Banking Circle managed Mandate	Required to supply reference to a self-managed Mandate. Banking Circle managed Mandate is no longer support	Banking Circle managed Mandate is no longer support
Idempotency key	Idempotency key is required (optionally) to supply in the request parameters Idempotency key is valid indefinitely.	Idempotency key is required (optionally) to supply in the request headers Idempotency key is valid for 10 days.	Idempotency must be supplied via request headers and has a limited validity period
Configuration & Reference Management	Management of Merchant, Connector, Customer, Bank Account and Hosted Page-objects	Relevant supported values are now provided explicitly in the payload.	Separate management of these objects are no longer required.

Mandate Management

Mandate management responsibilities reside with the creditor (merchant) as defined by the applicable scheme rulebook.

The following guidance outlines how mandate management can be integrated directly into the checkout or payment flow without reliance on external systems.

Mandate Data Requirements

A valid mandate must be created and stored with the following information:

Creditor (merchant) name and address
Creditor Identifier (CID)
Unique Mandate Reference
Customer name and IBAN
Payment type (one-off or recurring)
Customer consent (e.g., signature or digital confirmation), which may include:
- Checkbox or button confirmation (“click mandate”)
- Email confirmation
- Digital signature (e.g., signed PDF)

Mandate Creation Flow

The mandate creation process should follow these steps:

Collect customer details (e.g., name and IBAN)
Present the SEPA mandate text (in accordance with official scheme guidelines)
Capture customer consent (e.g., checkbox, digital confirmation, or signature)
Store the mandate securely for future reference
Reference the stored mandate (via mandateRelatedInformation.mandateId) when initiating Direct Debit collections

Structural Changes

ISO 20022 Data Model

The new endpoint follows an ISO 20022 style payment structure, introducing dedicated objects for:

Creditor
Debtor
Accounts
Agent banks
Mandate information
Remittance information

The legacy endpoint embedded many of these values within the mandate or bankAccount objects.

Debtor & Creditor Information

Creditor Information

Previously managed separate and referenced under bankAccountId

The new endpoint separates this into explicit entities.

//new structure
"creditor": {
  "name": "string",
  "personId": "string",
  "postalAddress": {...}
},
"ultimateCreditor": { 
	"name": "string", 
	"organisationId": "string" 
}

Debtor Information

The debtor (payer) is also now explicitly modeled.

//new structure
"debtor": {
  "name": "string",
  "postalAddress": {...}
}

//new structure
"debtorAccount": {
  "iban": "string"
}

Bank (Agent) Information

The debtor bank is now specified separately - this replaces earlier bank-related fields embedded in the account object.:

//new structure
"debtorAgent": {
  "bicFi": "string",
  "country": "string"
}

Field-by-field mapping - Instruction & Reporting

Legacy Field	New Field	Notes
accountNumber	❌ Removed	Not supported
amount	instructedAmount.amount	Now a string value in the amount object
approvalBy	❌ Removed	Not supported. Approval support planned
bankAccount	❌ Removed	Not supported
bankAccountId	❌ Removed	Not supported
bankCode	❌ Removed	Not supported
branchCode	❌ Removed	Not supported
connector	❌ Removed	Not supported
connectorId	❌ Removed	Not supported
countryCode (on bankAccount)	❌ Removed	Not supported
createdAt	acceptanceDateTime	Renamed
creditorBic	❌ Removed	BIC not required in new payload
creditorIban	creditorAccount.iban	Direct mapping
currencyCode	instructedAmount.currency	Moved inside structured amount object
custom1–custom5	❌ Removed	Not supported
customer	❌ Removed	Not supported
customerId	❌ Removed	Not supported
hostedPage	❌ Removed	Not supported
hostedPageId	❌ Removed	Not supported
id	instructionUetr	Renamed / semantic change
idempotencyKey (Header)	Idempotency-Key	Valid for 10 days
mandate.approvalDate	mandateRelatedInformation.dateOfSignature	Converted from timestamp to YYYY-MM-DD
mandate.bankAccount.*	❌ Removed	Not supported
mandate.connectorId	❌ Removed	Not supported
mandate.reference	mandateRelatedInformation.mandateId	Direct mapping
mandate.scheme	❌ Removed	Not supported
mandate.type	mandateRelatedInformation.sequenceType	Direct mapping
mandateId	mandateRelatedInformation.mandateId	Direct mapping
memo	❌ Removed	Not supported
merchant	❌ Removed	Not supported
paymentPreNotificationUrl	❌ Removed	Not supported
reasonCode	statusReasonInformation.reason	Renamed
reference	endToEndId	Max 35 chars; end-to-end payment identifier
refundAmount	❌ Removed	Not supported
refundCount	❌ Removed	Not supported
softDescriptor	remittanceInformation.line1-4	Payment reference text
state	transactionStatus	Renamed / enum change
submitAfter	requestedCollectionDate / transactionReference.requestedCollectionDate	Converted from timestamp to YYYY-MM-DD
validation*	❌ Removed	Not supported