v4.0.1

For v4.0.1 the following approach has been adopted for identifying changes:

• Known Issues - these are tagged with the KI identifier, e.g. [v40_KI45]
• Change Requests - these are tagged with the CR number used in the consultations, e.g. [CR4a]
• EAG/Consultation items - Items included in the consultations are tagged with an identifier representing the consultation period they were introduced, e.g. [v4.0.1 RC 1]
• Feedback remediation - Technical errata and other minor corrections identified by participants or OBL during the Advanced Information period for Release Candidates 1 and 2 with an appropriate identifier for internal OBL traceability e.g. [CDRW-5006]

Consultations:

• v4.x.x Consultation 1
• v4.0.1 Draft 1
• v4.0.1 Release Candidate 1
• v4.0.1 Release Candidate 2

v4.0.1 - 2026-04-01

Added

• [v40_KI45] Added LWMH, LXMH, & TWYR to Frequency Examples in PIS Domestic Standing Order consents & AIS Standing Orders
• [v40_KI45] Added Frequency Examples table to PIS International Standing Order Consents
• [CDRW-4937] Added example of query string date-time where only the Date is required.
• [CDRW-5038] Added text to Date Formats section advising on decimal precision limit of 5, as agreed in TDA Decision 284
• [CDRW-5039] Added new Days of the Week section to Date Formats advising of ISO-8601 alignment and providing a table of week days and ordinal values as discussed at TDA on 2026-03-04
• [CDRW-5057] Added OBRemittanceInformation2 definition and Data Dictionary to AIS Standing Orders page
• [v4.x.x Consultation 1] Added a note regarding the use of ExternalPaymentTransactionStatus1Code values in payment-details endpoints in
  PIS
  and Domestic VRPs
• [v4.x.x Consultation 1] Optional Rate Limit Headers added.
• [v40_KI29] NumberOfPayments has been restored to the following classes and guidance advising that TPPs should refer to ASPSP
  developer portals for further information on whether NumberOfPayments is supported has been added to the pages
  above the data dictionaries:
  • OBReadStandingOrder6/Data/StandingOrder/NumberOfPayments
  • OBDomesticStandingOrder3/NumberOfPayments
  • OBInternationalStandingOrder4/NumberOfPayments
• [v40_KI28] The following text has been added to OBMandateRelatedInformation1/Frequency/Type on the
  Account and Transaction API Profile and Payment Initiation API Profile pages:
  

  For compatibility with v3, an ASPSP may choose to optionally support legacy v3 regex patterns in this field.

  TPPs should refer to ASPSP developer portals for further information on whether legacy values are supported,
  alongside any additional information relevant to MandateRelatedInformation usage.

• [V4_KI1] OBCashAccountDebtorWithName has been added to:
  • Account and Transaction API Profile
  • Payment Initiation API Profile
  • Confirmation of Funds API Profile
• [CR7] Clarification on the usage of the term 'optional fields' in reference to Conditional fields.
• [v4.x.x Consultation 1] An overarching Events Release Management section has been introduced to the Event Notification API Profile
• [v4.x.x Consultation 1] OBReferredDocumentInformation has been split out from OBRemittanceInformation2 and added to the following pages:
  • Payment Initiation API Profile
  • AIS - Standing Orders
  • Variable Recurring Payments API Profile
• [v4.x.x Consultation 1] Added additional guidance to POST /file-payment-consents/{ConsentId}/file:
  • ASPSPs should document accepted file types on their developer portal.
  • ASPSPs who accept the UK.OBIE.PaymentInitiation.4.0 file type should specify which payload schemas they accept as payload structures vary across payment types.
    • E.g. An ASPSP accepting domestic, international and domestic standing orders via file payment should explicitly specify support for these 3 payload schemas on their developer portal.
• [v4.x.x Consultation 1] Added a Release Management section to the Variable Recurring Payments API Profile
• [CR2] Introduced a new OBIntermediaryAgent class which can appear up to 3 times in payload as IntermediaryAgent1, IntermediaryAgent2 andIntermediaryAgent3.
  • This is used in OBReadTransaction6/Data/Transaction
  • Returning these fields requires use of the ReadTransactionDetail permission and the Permission Codes table
    has been updated accordingly.
• [CR9] Added the following guidance to the Transactions notes:
  • TPPs should refer to ASPSP developer portals for information on whether individual Bacs transactions are available in the Transactions endpoint.
• [v4.x.x Consultation 1] Added the following note to File Payments:
  • TPPs should refer to ASPSP developer portals for information on which File Payment endpoints are available, specification of accepted file format(s) and information on File Payment statuses.
• [CR7] Clarified how Mandatory
  and Conditional
  fields are represented in the Data Dictionaries.
  • Mandatory fields are represented as 1..1 or 1..* in the Data Dictionary Occurrence column and UML diagrams.
  • Conditional fields are represented as 0..1 or 0..* in the Data Dictionary Occurrence column and UML diagrams
• [CR8] Added guidance to the Transaction page for returning Counterparty information in the TransactionInformation field.
• [v4.x.x Consultation 1] ReadStandingOrdersBasic and ReadStandingOrdersDetail added to overarching Permission Codes list

Change...

v4.0.1 - Release Candidate 2

Version History

v4.0.1 Release Candidate 2 - 2026-02-04

Added

• Added LWMH, LXMH, and TWYR to OBFrequency6Code in OBInternal
• Added SLCT to OBFrequency2Code in OBInternal
• Added legacy values to OBExternalPaymentContext1Code: Other, Bill Payment, EcommerceGoods, EcommerceServices, PartyToParty, PispPayee

Updated

• Updated ISO 20022 External Codeset files to Q3 2025 release.
• Enhanced the descriptions of current OBExternalPaymentContext1Code codes BillingGoodsAndServicesInAdvance, BillingGoodsAndServicesInArrears, EcommerceMerchantInitiatedPayment, FaceToFacePointOfSale, TransferToSelf, TransferToThirdParty

v4.0.1 Draft 1 - 2026-01-05

Added

• Added to OBInternalStatementFeeType1Code:
  • UK.OBIE.InstalmentPlan
  • UK.OBIE.ReturnedPayment
• Added to OBInternalStatementInterestType1Code:
  • UK.OBIE.InstalmentPlan
  • UK.OBIE.MoneyTransfer
• Added CRYP to ExternalPurpose1Code
• Introduced OBIntermediaryAgentStatus1Code in OB_Internal_Codeset. This is used for
  OBIntermediaryAgent/ProcessingStatus and has the following codes:
  • PDNG
  • RCVD
  • ACSP
  • ACSC
  • RJCT
  • UNKN
  • CANC
• Description of code value U037 updated to "Authorisation failed by one (or more) of the authenticators."
• Added NONE to OBFrequency2Code

Changed

• Separated OBInternalConsentStatus1Code into 3 codesets for certain contexts (#17):
  • Removed COND & AWUP from OBInternalConsentStatus2Code
  • Added OBInternalConsentStatus2Code to OB_Internal_Codeset.csv with the following values:
    • AWAU
    • RJCT
    • AUTH
    • COND
  • Added OBInternalConsentStatus3Code to OB_Internal_Codeset.csv with the following values:
    • AWAU
    • RJCT
    • AUTH
    • COND
    • AWUP
• Updated description of U037 in OBExternalStatusReason1Code (#7)
• Separated ExternalPaymentTransactionStatus1Code into 5 codesets for specific contexts (#16). New Codes look like:
  • ExternalPaymentTransactionStatus1Code (16 codes) for Domestic Standing Orders & International Standing Orders:
    • CANC
    • RCVD
    • ACTC
    • PATC
    • PDNG
    • RJCT
    • INFA
    • INCO
    • ACCP
    • ACFC
    • ACSP
    • ACWC
    • ACSC
    • BLCK
    • ACCC
    • ACWP
  • ExternalPaymentTransactionStatus2Code (14 codes) for Domestic Scheduled Payments and International Scheduled Payments:
    • CANC
    • RCVD
    • PDNG
    • ACTC
    • PATC
    • ACCP
    • ACFC
    • ACSP
    • ACWC
    • ACSC
    • BLCK
    • ACCC
    • ACWP
    • RJCT
  • ExternalPaymentTransactionStatus3Code (13 codes) for Domestic Payments and International Payments:
    • RCVD
    • PDNG
    • ACTC
    • PATC
    • ACCP
    • ACFC
    • ACSP
    • ACWC
    • ACSC
    • BLCK
    • ACCC
    • ACWP
    • RJCT
  • ExternalPaymentTransactionStatus4Code (3 codes) for File Payments:
    • PDNG
    • INFA
    • INCO
  • ExternalPaymentTransactionStatus5Code (12 codes) for Domestic VRPs:
    • RCVD
    • PDNG
    • ACTC
    • ACCP
    • ACFC
    • ACSP
    • ACWC
    • ACSC
    • BLCK
    • ACCC
    • ACWP
    • RJCT

Removed

• Removed duplicate ExternalMandateStatus1Code codes (#12)
• Removed deprecated OBExternalStatus3Code (#13)

Fixed

• codesets are now contiguous and organized alphabetically
• several descriptions have been moved out of the codeset name column and into the description column
• Corrected OBExternalStatusReason1Code 1180 description (#21)
• Moved the BusinessCurrentAccount code from OBInternalCardSchemeType1Code to OBInternalProductType1Code (#13)
• Corrected OBExternalAuthorisation1Code to OBInternalAuthorisation1Code (#14)
• Fix typo in ExternalPaymentGroupStatus1Code INFA description (#15)

Pull Requests

• CoP update by @OBPeteS in #217
• CoP update by @OBPeteS in #218
• CDRW-4714 Pt3 by @MikeBanyard1 in #228
• CDRW-4766 remap referred document amount from int32 to ob active currency and amount simple type by @cjrobbertse-ob in #277
• Fixed missing ` around OBRemittanceInformation2 by @OBPeteS in #279
• Added OBIntermediaryAgent1 class to OBReadTransaction6 by @OBPeteS in #248
• CDRW-4862 by @MikeBanyard1 in #232
• CDRW-4137 by @MikeBanyard1 in #230
• CDRW-4723 by @MikeBanyard1 in #225
• CDRW-4711 by @MikeBanyard1 in #229
• CDRW-4872 by @MikeBanyard1 in #231
• CDRW-4668 by @MikeBanyard1 in #240
• CR9 - Added clarifications by @OBPeteS in #251
• CDRW-4693v3 Changed status update to CANC from must to should by @MikeBanyard1 in #259
• CDRW-4774v2 remove Risk entry from Data Dictionary by @MikeBanyard1 in #258
• CDRW-4828v4 Added ref to negative numbers in PointInTime by @MikeBanyard1 in #260
• CDRW-4672v2 by @MikeBanyard1 in #261
• CDRW-4714v3 - Amended text re Permissions by @MikeBanyard1 in #262
• CDRW-4657 by @MikeBanyard1 in #275
• CDRW-4713 by @MikeBanyard1 in #276
• CDRW-4673 by @MikeBanyard1 in #246
• CDRW-4739v2 by @MikeBanyard1 in #245
• CDRW-4714 Pt2 by @MikeBanyard1 in #227
• CDRW-4806 by @MikeBanyard1 in #278
• CDRW-4871v2 Updated codeset location to OB_InternalCodeSet by @MikeBanyard1 in #257
• CDRW-4899 by @MikeBanyard1 in #285
• CDRW-4758 by @OBPeteS in #221
• Added guidance on how mandatory and conditional fields are represented by @OBPeteS in #250
• Updated payload signature guidance by @OBPeteS in #255
• Added NumberOfPayments to Standing Orders by @OBPeteS in #263
• Added guidance on legacy v3 values by @OBPeteS in #264
• Cdrw 4870 v40 ki1 by @OBPeteS in #266
• Updated guidance on optional fields by @OBPeteS in #267
• Updated File payments state model by @OBPeteS in #268
• Added VRP Release Management by @OBPeteS in #273
• Updated guidance on UK.OBIE.PaymentInitiation.4.0 by @OBPeteS in #274
• Updated Scheduled Payment state diagram by @OBPeteS in #269
• Updated Meta and Links to be conditional by @OBPeteS in #271
• Updated OBReferredDocumentInformation by @OBPeteS in #280
• Added Standing Order permission codes to main list by @OBPeteS in #282
• Update domestic-payments-usage-examples.md by @OBPeteS in #283
• Update payment-initiation-api-profile.md by @OBPeteS in #287
• Update file-payment-consents.md by @OBPeteS in #288
• Update read-write-data-api-profile.md by @OBPeteS in #289
• Updated v4.0 refs to v4.0.1 by @OBPeteS in #290
• CDRW-4674 by @MikeBanyard1 in #293
• CDRW-4865 Remove incorrect codeset reference by @cjrobbertse-ob in #281
• CDRW-4902 Fix OBExternalStatusReason1Code Typo by @cjrobbertse-ob in #292
• Fix PIS lost changes by @cjrobbertse-ob in #296
• CDRW-4671v2 by @MikeBanyard1 in #284
• CDRW-4764 Add OBInternalConsentStatus2Code & OBInternalConsentStatus3...

v4.0

v4.0 - 28th June 2024

Area	Changes
All	Enum/codeset repository created on GitHub. OBL enums have been removed from namespaced enumeration page and participants should refer to this respository for values. Note, OBExternal* enum names have been updated to OBInternal* New optional StatusReason array containing 0..*: StatusReasonCode Path StatusReasonDescription Sequence diagrams and consent status models updated with ISO values Usage examples updated
All	Alignment with ISO 20022: ISO code names replaced by code value (e.g. AcceptedWithoutPosting is now ACWP) Address fields aligned to ISO definition and rationalised into single address definition OBPostalAddress7. LEI added to Creditor/Debtor/CreditorAgent objects UltimateCreditor and UltimateDebtor added MandateRelatedInformation added to DirectDebit and StandingOrder, this object replaces some fields from v3.1.11 RemittanceInformation object updated to ISO format, this replaces ‘reference’ in payment requests. The object name has been updated to OBRemittanceInformation2. CreditorAccount & CreditorAgent now have the same (optional) fields across API endpoints Proxy added to CreditorAccount/DebtorAccount (across AISP, PISP & CBPII)
AISP	ISO 20022 changes AccountType (OBExternalAccountType1Code) renamed to AccountCategory (OBInternalAccountType1Code) AccountSubType renamed to AccountTypeCode MORT (Mortgage) and WALT (Wallet) added to OBExternalAccountSubType1Code Name added to Servicer in OBReadAccount6 StatementFrequencyAndFormat added to Account in OBReadAccount6 PaymentPurposeCode added to Transaction in OBReadTransaction6 CategoryPurposeCode added to Transaction in OBReadTransaction6
PISP	ISO20022 changes CategoryPurposeCode added to Risk object RemittanceInformation added to payments RegulatoryReporting added to payments
Errors	Simplified error object, top level Code and Message have been marked as optional and deprecated. Error codes now in ISO 20022 code value format (4 chars) in the OBExternalStatusReason1Code enum Additional guidance on errors experienced in the redirect flow or from PSU initiated changes
VRP	ContractPresentIndicator typo fixed Added guidance on dynamic reference information for VRP payments StatusReason now uses ExternalStatusReason1Code To assist with version migration: Introduced optional HTTP PUT/PATCH verbs for consents Added payload version header
Payments	Updated payment message types information to include ISO 20022 changes, CHAPS migration and CBPR+ Richer payment status information aligned to ISO 20022 ExternalTransactionStatus1code
Various	All 3.1.11 KI’s addressed
AISP	Added new ExtendedProprietaryBankTransactionCodes array to Transactions (TDA decision 264) Permission code table updated with UltimateCreditor, UltimateDebtor and StatementFrequencyAndFormat
Various	Frequency in OBMandateRelatedInformation1 object made mandatory
PISP	CreditorAgent added to Domestic Payment Consent Domestic Payment File payment Consents File payment

Version 3.1.8 RC1

Version 3.1.8 - RC1

• VRP Profile, Resources and Examples View Diff
• Decision 229 - Support for rejected transactions View Diff
• Update version numbers View Diff

Version 3.1.7 Final

No further changes from Version 3.1.7 - Draft 1

Version 3.1.7 RC1

Change Log

Version 3.1.7 - Draft1

• Decision 225 - Debtor account details following payment initiation View Diff
• Decion 226 - Optional fields for accounts that have been switched out View Diff
• Miscelleneous fixes to address Known Issues View Diff
  • OBSD-16647 - Fixed incorrect class name for CreditorAccount in domestic-standing-order-consents
  • OBSD-16818 - Corrected the txn specification for events to replace the reference to x-fapi-transaction-id with x-fapi-interaction-id
  • OBSD-16778 - Added description for post endpoints in file-payments
  • OBSD-15322 - Updated the account name field sizes for parties so that they are consistent
  • Add additional examples for message signing
  • OBSD-17345 - Corrected the description and length of ReferencePaymentOrderId
  • OBSD-17586 - In the Accounts resource, corrected UK.CASS.NotSwitced in description to UK.CASS.NotSwitched
  • OBSD-18538 - Inconsistent description of "CreationDate" in payment resources.
  • OBSD-18590 - Incorrect example for usage of CountrySubDivision
• Update version numbers View Diff

Version 3.1.6 Final

v3.1.6

Merge branch 'master' into release/v3.1.6

Version 3.1.6 RC1

Version 3.1.6 - RC1

Decision 222 - CASS View Diff
    Changes based on impact assessment
    Rolled back Option 2

Decision 223 - Change length of Account/Name fields View Diff

Errata
    Fix the multiplicity for CountrySubDivision
    Clarify error message for invalid ISO Date
    Clarify the use of txn for Event Notifications

Version 3.1.6 Draft1

https://github.com/OpenBankingUK/read-write-api-docs-pub#change-log

Version 3.1.5 Final

Final Release - https://github.com/OpenBankingUK/read-write-api-docs-pub#change-log