Domestic Payment Message Formats - v3.1

Version Control

VersionDateAuthorComments
3.0 OB R/W API TeamThis is the baseline version. No change from RC3.
3.1-draft1 OB R/W API Team

This is the initial draft version for 3.1.

Errata

  • Grammatical Fixes
3.1 RC1 OB R/W API Team

RC1 Changes:

  • Updated enumerations to use full UK.OBIE namespace.
3.1OB R/W API Team

Version 3.1 final release.

No changes from Version 3.1 RC1


ISO 20022

The Initiation section of the Payment API payloads is based on the ISO 20022 pain.001 XML standard and we have used ISO 20022 message elements or components where possible. However, has been adapted for APIs based as per our design principles. 

Deviations from the pain.001 XML standard are:

  • The pain.001 header section and trailer sections have been removed as these are not required for a RESTful API
  • Only required fields have been included in the Initiation objects. This has meant:
    • The separate CreditTransferTransactionInformation section in pain.001 which is a repeating group for multi-credit payments, has been removed and flattened.
    • PaymentInformationIdentification not required - we also have a InstructionIdentification.
    • PaymentMethod is not required as this is always immediate execution for the ASPSP.
    • RequestedExecutionDate is not required as this is always as soon as possible - which may differ between FPS and Bacs payments.
    • Debtor / DebtorAccount are optional as the debtor details are not always known to the PISP submitting the payment setup or submit.
  • The Payment Initiation team has requested a flatter structure for the payload:
    • InstructionIdentification and EndToEndIdentification moved to the top level (instead of embedding within Payment Order Identification).
    • DebtorAccount and CreditorAccount are simplified to only include the SchemeName and Identification.

ISO 8583

The ISO 8583 message format is used for the Faster Payments Scheme (FPS).

Execution:

  • The processing of payments via the FPS scheme is business as usual processing - i.e., no change.
  • FPS scheme requirements (are not formally part of the Open Banking API Specification, but are included for guidance):
    • The field 61.1 PAYMENT SUB-TYPE will be set by the FPS Institution with a A{**} prefix for any FPS transaction initiated by a PISP. Values within {**} will ordinarily be “00” unless the PISP initiated payment requires usage of other facilities (as indicated by the usage of an FPS sub-type code). 
    • There is also a requirement from the FPS scheme to identify the PISP via the field 122 REGULATORY REPORTING  

This is the mapping from the Payment API Initiation section to the relevant FPS scheme fields with the use of the "UK.OBIE.SortCodeAccountNumber" account identification SchemeName.

All required fields in the ISO 8583 message can be generated from the Initiation section of the payload or from the ASPSP, for domestic-payments and domestic-scheduled-payments.

Highlighted in red are the fields which are smaller in size than the corresponding ISO 20022 field.

In the case that a PISP sets up a payment-order consent with a larger field size (e.g., EndToEndIdentification, or InstructedAmount) than the eventual scheme field size - it will be up to the ASPSP to decide whether to reject the payment-order consent or truncate the field. 

Mapping

Name
XPath
Occurrence
Class
ISO8583 BIT
Field Name
Mandatory
Size
EndToEndIdentificationInitiation/EndToEndIdentification1..1Max35Text62END TO END REFERENCE 31
AmountInitiation/InstructedAmount/Amount1..1TotalDigits: 18, FractionDigits: 56AMOUNT 14
IdentificationInitiation/DebtorAccount/Identification1..1Max256Text

42

43

ORIGINATING CREDIT INSTITUTION

ORIGINATING CUSTOMER ACCOUNT NUMBER 

11

34

IdentificationInitiation/CreditorAccount/Identification1..1Max256Text

95

35

BENEFICIARY CREDIT INSTITUTION

BENEFICIARY CUSTOMER ACCOUNT NUMBER 

11

34

NameInitiation/CreditorAccount/Name1..1Max70Text118BENEFICIARY CUSTOMER ACCOUNT NAME 40
SecondaryIdentificationInitiation/CreditorAccount/SecondaryIdentification0..1Max34Text120REFERENCE INFORMATION 18
UnstructuredInitiation/RemittanceInformation/Unstructured0..1Max140Text121REMITTANCE INFORMATION 140
ReferenceInitiation/RemittanceInformation/Reference0..1Max35Text120REFERENCE INFORMATION 18

Notes

  • If the Initiation/CreditorAccount/SecondaryIdentification field is populated - this field must be mapped to field 120 REFERENCE INFORMATION as this will be used for the Creditor Agent to identify the account (i.e., the roll numbers in the building society context).
  • However, if the Initiation/CreditorAccount/SecondaryIdentification is not populated then field 120 REFERENCE INFORMATION must be populated with the Initiation/RemittanceInformation/Reference field.
  • If both Initiation/CreditorAccount/SecondaryIdentification and Initiation/RemittanceInformation/Reference are populated by the PISP, only the SecondaryIdentification will be mapped to field 120 REFERENCE INFORMATION. Whether the Initiation/RemittanceInformation/Reference is used in any other ASPSP systems is for the ASPSP to decide.
  • Field 116 ORIGINATING CUSTOMER ACCOUNT NAME must be populated from the ASPSP's system of record
  • Where the Initiation/DebtorAccount/SchemeName field is populated with "UK.OBIE.SortCodeAccountNumber", the Initiation/DebtorAccount/Identification field will be populated with a 14 digit field comprised of a 6 digit Sort Code (mapped to field 42 ORIGINATING CREDIT INSTITUTION) and 8 digit Account Number (mapped to field 43 ORIGINATING CUSTOMER ACCOUNT NUMBER)
  • Where the Initiation/CreditorAccount/SchemeName field is populated with "UK.OBIE.SortCodeAccountNumber", the Initiation/CreditorAccount/Identification field will be populated with a 14 digit field comprised of a 6 digit Sort Code (mapped to field 95 BENEFICIARY CREDIT INSTITUTION) and 8 digit Account Number (mapped to field 35 BENEFICIARY CUSTOMER ACCOUNT NUMBER)
  • CreditorPostalAddress is not supported in FPS .

BACS STD18

The BACS STD18 message format is used for the BACS scheme.

Execution:

  • The processing of payments via the Bacs scheme is business as usual processing i.e., no change
  • Expectation is that a Bank Grade user will be able to bulk up payments generated via the Payment API and create the appropriate file and submission structure (as per usual processing). None of these details will need to be generated via the Payment API.
  • The mapping below uses the Bacs Electronic Funds Transfer, File Structures (PN5011) document and the section on 2.6.1 CREDIT AND DEBIT PAYMENT INSTRUCTIONS (BANK GRADE USERS)

This is the mapping from the Payment API Initiation section to the relevant Bacs scheme fields with the use of the "UK.OBIE.SortCodeAccountNumber" account identification SchemeName.

All required fields in the BACS STD18 message can all be generated from the Initiation section of the payload or from the ASPSP for domestic-payments and domestic-scheduled-payments.

Highlighted in red are the fields which are smaller in size than the corresponding ISO 20022 field. 

In the case that a PISP sets up a payment-order consent with a larger field size (e.g., EndToEndIdentification, or InstructedAmount) than the eventual scheme field size, it will be up to the ASPSP to decide whether to reject the payment-order consent or truncate the field. 

Mapping

Name
XPath
Occurrence
Class
STD18 Field
Field Name
Mandatory ?
Size
AmountInitiation/InstructedAmount/Amount1..1TotalDigits: 18, FractionDigits: 58amount in penceM11
IdentificationInitiation/DebtorAccount/Identification1..1Max256Text

5

6

originating sorting code

originating account number

M

M

6

8

IdentificationInitiation/CreditorAccount/Identification1..1Max256Text

1

2

destination sorting code

destination a/c number

M

M

6

8

NameInitiation/CreditorAccount/Name1..1Max70Text11destination account nameM18
SecondaryIdentificationInitiation/CreditorAccount/SecondaryIdentification0..1Max34Text10service user’s referenceM18
ReferenceInitiation/RemittanceInformation/Reference0..1Max35Text10service user’s referenceM18

Notes

  • If the Initiation/CreditorAccount/SecondaryIdentification field is populated, this must be mapped to field 10 service user's reference as this will be used for the Creditor Agent to identify the account (i.e., the roll numbers in the building society context).
  • However, if the /CreditorAccount/SecondaryIdentification is not populated then 10 service user's reference must be populated with the Initiation/RemittanceInformation/Reference field.
  • If both Initiation/CreditorAccount/SecondaryIdentification and Initiation/RemittanceInformation/Reference are populated by the PISP, only the SecondaryIdentification will be mapped to field 10 service user's reference. Whether the Initiation/RemittanceInformation/Reference is used in any other ASPSP systems is for the ASPSP to decide.
  • Field 9 service user's name must be populated from the ASPSP's system of record.
  • Where the Initiation/DebtorAccount/SchemeName field is populated with "UK.OBIE.SortCodeAccountNumber", the Initiation/DebtorAccount/Identification field will be populated with a 14 digit field comprised of a 6 digit Sort Code (mapped to field 5 originating sorting code) and 8 digit Account Number (mapped to field 6 originating account number).
  • Where the Initiation/CreditorAccount/SchemeName field is populated with "UK.OBIE.SortCodeAccountNumber", the Initiation/CreditorAccount/Identification field will be populated with a 14 digit field comprised of a 6 digit Sort Code (mapped to field 1 destination sorting code) and 8 digit Account Number (mapped to field 2 destination a/c number)
  • CreditorPostalAddress is not supported in BACS.

MT103

The MT103 message format is used for the CHAPS scheme.

Execution:

  • The processing of payments via the CHAPS scheme is business as usual processing - i.e., no change

This is the mapping from the Initiation section to the relevant CHAPS scheme fields with the use of the "UK.OBIE.SortCodeAccountNumber" account identification SchemeName.

All required fields in the CHAPS MT103 message can all be generated from the Initiation section of the payload or from the ASPSP for domestic-payments and domestic-scheduled-payments.

Highlighted in red are the fields which are smaller in size than the corresponding ISO 20022 field. 

In the case that a PISP sets up a payment-order consent with a larger field size (e.g., EndToEndIdentification, or InstructedAmount) than the eventual scheme field size, it will be up to the ASPSP to decide whether to reject the payment-order consent or truncate the field. 

Mapping

Name
XPath
Occurrence
Class
MT103 Field
Field Name
Mandatory
Size
AmountInitiation/InstructedAmount/Amount1..1TotalDigits: 18, FractionDigits: 532AValue Date / Currency /  Interbank Settled AmountM15n
CurrencyInitiation/InstructedAmount/Currency1..1

ActiveOrHistoricCurrencyCode

"GBP"

32AValue Date / Currency / Interbank Settled AmountM3x
IdentificationInitiation/DebtorAccount/Identification1..1Max256Text

50K

Ordering Customer

34x

IdentificationInitiation/CreditorAccount/Identification1..1Max256Text

57

59

Account With Institution

Beneficiary Customer

6n

8n

NameInitiation/CreditorAccount/Name1..1Max70Text59Beneficiary CustomerM

35x

StreetNameInitiation/CreditorPostalAddress/StreetName0..1Max70Text59Beneficiary CustomerO35x
BuildingNumberInitiation/CreditorPostalAddress/BuildingNumber0..1Max16Text59Beneficiary CustomerO

35x

PostCodeInitiation/CreditorPostalAddress/PostCode0..1Max16Text59Beneficiary CustomerO35x
EndToEndIdentificationInitiation/EndToEndIdentification1..1Max35Text70Beneficiary ReferenceM35x
ReferenceInitiation/RemittanceInformation/Reference0..1Max35Text70Beneficiary Reference35x
UnstructuredInitiation/RemittanceInformation/Unstructured0..1Max140Text70Beneficiary Reference2*35x

Notes

  • The Value Date must be a valid BoE business day. It must be a valid date expressed as YYMMDD and is populated by the ASPSP.
  • Details for field 50K (Ordering Customer) relating to the Debtor's Name and Address must be populated from the ASPSP's system of record.
  • Where the Initiation/DebtorAccount/SchemeName field is populated with "UK.OBIE.SortCodeAccountNumber", the Initiation/DebtorAccount/Identification field will be populated with a 14 digit field comprised of a 6 digit Sort Code (mapped to field 50K Ordering Customer).
  • Where the Initiation/CreditorAccount/SchemeName field is populated with "UK.OBIE.SortCodeAccountNumber", the Initiation/CreditorAccount/Identification field will be populated with a 14 digit field comprised of a 6 digit Sort Code (mapped to field 57 Account With Institution) and 8 digit Account Number (mapped to field 59F Beneficiary Customer).
  • Beneficiary Customer Address (59) - there are only 3 fields of length 35 available in the MT103 message for the CreditorPostalAddress these will be mapped from:
    • Initiation/CreditorPostalAddress/StreetName.
    • Initiation/CreditorPostalAddress/BuildingNumber.
    • Initiation/CreditorPostalAddress/PostCode.
  • Beneficiary Reference (70) - this MT103 field has 4 fields of length 35 to be mapped with:
    • /ROC/ and EndToEndIndentification
      /RFB/ and RemittanceInformation/Reference (only 16 chars supported)
      RemittanceInformation/Unstructured