- 1 -
- 1 -
Request to Pay
Message Specification
Issued: May 2020
Version: 1.0
Copyright 2020 Pay.UK Limited. Pay.UK Limited is a company limited by guarantee, incorporated in England.
Company Number 10872449. Pay.UK Limited's registered office is 2 Thomas More Square, London, E1W 1YN.
- 2 -
- 2 -
Document Version History
Version Date Author Comments v0.3.0 May 2018 Initial draft version.
v0.4.0 October 2018 Version with changes related to the community
comments from the first cycle consultation.
v0.5.0 20/12/2018 Version with changes related to the community
comments from the second cycle consultation.
v0.6.0 28/02/2019 Version with changes related to the community
comments from the third cycle consultation.
V0.7.0 30/04/2019 Updated with changes to be delivered in version
v0.7.
V0.7.1 22/08/2019 Update to rqtp.006, change NotetoBiller and
NotetoPayer message type to be aligned with
Swaggers
V0.7.2 16/10/2019 Rob Moore Minor updates
V0.8.0 22/01/2020 Carlos Mu Document reviewed for to be inline with
Swaggers v0.8.0
V0.8.1 3/2/2020 Carlos Mu Added Pre-Authorisation Message section
V0.8.2 23/3/2020 Carlos Mu Updated wording of document
- 3 -
- 3 -
Table of Content
Document Version History ................................................................................................. 2
Table of Content ............................................................................................................... 3
Table of Figures ................................................................................................................ 7
1. Request to Pay Overview ........................................................................................... 8
1.1 Introduction ......................................................................................................................................... 8
1.2 Scope .................................................................................................................................................... 8
1.3 Out of scope ......................................................................................................................................... 8
2. Message Structure .................................................................................................... 9
2.1 envelope ............................................................................................................................................... 9 2.1.1 threadHeader ...................................................................................................................................................... 10
2.1.1.1 profile ........................................................................................................................................................ 10 2.1.1.2 subject ....................................................................................................................................................... 11 2.1.1.3 threadId ..................................................................................................................................................... 11 2.1.1.4 originatorPid ............................................................................................................................................. 11 2.1.1.5 respondentPid ........................................................................................................................................... 11 2.1.1.6 threadDateTime ........................................................................................................................................ 12 2.1.1.7 threadPriority ............................................................................................................................................ 12
2.1.2 messageHeader ................................................................................................................................................... 12
2.1.2.1 messageId ................................................................................................................................................. 12 2.1.2.2 senderName .............................................................................................................................................. 13 2.1.2.3 senderPid .................................................................................................................................................. 13 2.1.2.4 recipientPid ............................................................................................................................................... 13 2.1.2.5 messageDateTime ..................................................................................................................................... 13
2.1.3 messageBody ...................................................................................................................................................... 13
2.1.4 errorBody ............................................................................................................................................................ 14
2.1.4.1 referenceMessageId .................................................................................................................................. 14 2.1.4.2 code ........................................................................................................................................................... 14 2.1.4.3 message ..................................................................................................................................................... 15 2.1.4.4 failureReason ............................................................................................................................................ 15 2.1.4.5 Errors description ...................................................................................................................................... 15
2.1.4.5.1 Delivery errors ........................................................................................................................................ 15 2.1.4.5.2 Message validation errors ...................................................................................................................... 16
2.2 messageMeta ..................................................................................................................................... 17 2.2.1 deliveryPath ........................................................................................................................................................ 17
2.2.1.1 fromId ........................................................................................................................................................ 17 2.2.1.2 senderCert ................................................................................................................................................. 17 2.2.1.3 timestamp ................................................................................................................................................. 18 2.2.1.4 toId ............................................................................................................................................................ 18
2.2.2 numMessages ...................................................................................................................................................... 18
2.2.3 signature.............................................................................................................................................................. 18
2.3 attachments ....................................................................................................................................... 18 2.3.1 fileName .............................................................................................................................................................. 19
2.3.2 contentType ........................................................................................................................................................ 19
2.3.3 signature.............................................................................................................................................................. 19
2.3.4 path ..................................................................................................................................................................... 20
- 4 -
- 4 -
2.3.5 content ................................................................................................................................................................ 20
2.4 Flexibility in parsing message fields .................................................................................................. 20
3. Request to Pay Messages ......................................................................................... 21
3.1 List of messageBody objects .............................................................................................................. 21
3.2 rqtp.001 RequestToPay Message Body ............................................................................................. 22 3.2.1 messageType....................................................................................................................................................... 23
3.2.2 endToEndIdentification ...................................................................................................................................... 23
3.2.3 creditor ................................................................................................................................................................ 23
3.2.3.1 name .................................................................................................................................................................... 23
3.2.4 paymentOptions ................................................................................................................................................. 24
3.2.4.1 paymentMethod ........................................................................................................................................ 24 3.2.4.2 creditorAgent ............................................................................................................................................ 24
3.2.4.2.1 financialInstitutionId .............................................................................................................................. 25 3.2.4.2.1.1 BICFI ................................................................................................................................................ 25 3.2.4.2.1.2 clearingSystemMemberId ............................................................................................................... 25
3.2.4.2.1.2.1 clearingSystemId ..................................................................................................................... 25 3.2.4.2.1.2.1.1 code ................................................................................................................................. 26
3.2.4.2.1.2.2 memberId ................................................................................................................................ 26 3.2.4.3 creditorAccount ........................................................................................................................................ 26
3.2.4.3.1 identification .......................................................................................................................................... 26 3.2.4.3.1.1 IBAN ................................................................................................................................................. 27 3.2.4.3.1.2 other ................................................................................................................................................ 27
3.2.4.3.1.2.1 id .............................................................................................................................................. 27 3.2.4.3.2 currency .................................................................................................................................................. 28 3.2.4.3.3 name ....................................................................................................................................................... 28
3.2.4.4 creditorPortal ............................................................................................................................................ 28 3.2.4.4.1 basketId .................................................................................................................................................. 28 3.2.4.4.2 electronicAddress ................................................................................................................................... 28
3.2.5 dueDate ............................................................................................................................................................... 29
3.2.6 amount ................................................................................................................................................................ 29
3.2.6.1 dueAmount ................................................................................................................................................ 29 3.2.6.2 currency ..................................................................................................................................................... 29
3.2.7 remittanceInformation ....................................................................................................................................... 30
3.2.7.1 unstructured.............................................................................................................................................. 30 3.2.7.2 structured .................................................................................................................................................. 30
3.2.7.2.1 billName ................................................................................................................................................. 30 3.2.7.2.2 creditorReferenceInformation ............................................................................................................... 30
3.2.7.2.2.1 reference ......................................................................................................................................... 31 3.2.7.2.3 billingPeriod ........................................................................................................................................... 31
3.2.7.2.3.1 billingPeriodFrom ........................................................................................................................... 31 3.2.7.2.3.2 billingPeriodTo ................................................................................................................................ 31
3.2.8 relatedRemittanceInformation........................................................................................................................... 32
3.2.8.1 remittanceIdentification ........................................................................................................................... 32 3.2.8.2 remittanceLocationDetails ....................................................................................................................... 32
3.2.8.2.1 electronicAddress ................................................................................................................................... 32 3.3 rqtp.002 Pay Message Body ............................................................................................................... 32
3.3.1 messageType....................................................................................................................................................... 33
3.3.2 endToEndIdentification ...................................................................................................................................... 33
3.3.3 requestedExecutionDate .................................................................................................................................... 33
3.3.4 amount ................................................................................................................................................................ 34
3.3.4.1 instructedAmount ..................................................................................................................................... 34
- 5 -
- 5 -
3.3.4.2 currency ..................................................................................................................................................... 34 3.3.5 transactionId ....................................................................................................................................................... 34
3.3.6 acceptanceDateTime .......................................................................................................................................... 35
3.3.7 transactionStatus ................................................................................................................................................ 35
3.3.8 additionalInformation ........................................................................................................................................ 35
3.4 rqtp.003 Requested Payment Extension Message Body ................................................................... 36 3.4.1 messageType....................................................................................................................................................... 36
3.4.2 endToEndIdentification ...................................................................................................................................... 36
3.4.3 requestedExtensionDate .................................................................................................................................... 36
3.4.4 additionalInformation ........................................................................................................................................ 37
3.5 rqtp.004 Extension Response Message Body .................................................................................... 37 3.5.1 messageType....................................................................................................................................................... 38
3.5.2 endToEndIdentification ...................................................................................................................................... 38
3.5.3 referenceMessageId ............................................................................................................................................ 38
3.5.4 additionalInformation ........................................................................................................................................ 38
3.6 rqtp.005 Decline Message Body ......................................................................................................... 38 3.6.1 messageType....................................................................................................................................................... 39
3.6.2 endToEndIdentification ...................................................................................................................................... 39
3.7 rqtp.006 Note Message Body ............................................................................................................. 39 3.7.1 messageType....................................................................................................................................................... 40
3.7.2 endToEndIdentification ...................................................................................................................................... 40
3.7.3 note...................................................................................................................................................................... 40
3.8 rqtp.007 Acknowledge in Full Message Body .................................................................................... 40 3.8.1 messageType....................................................................................................................................................... 41
3.8.2 endToEndIdentification ...................................................................................................................................... 41
3.9 rqtp.008 Acknowledge Payment Message Body ............................................................................... 41 3.9.1 messageType....................................................................................................................................................... 42
3.9.2 endToEndIdentification ...................................................................................................................................... 42
3.9.3 amount ................................................................................................................................................................ 42
3.9.3.1 paidAmount ............................................................................................................................................... 42 3.9.3.2 currency ..................................................................................................................................................... 43
4. Simple Message ...................................................................................................... 43
4.1 messageBody ..................................................................................................................................... 43 4.1.1 messageBody ...................................................................................................................................................... 43
5. Request to Pay Business Processes ........................................................................... 43
5.1 Request to Pay communication messages ....................................................................................... 45
5.2 Business Roles and Participants ........................................................................................................ 47 5.2.1 Business Roles and Participants definitions ...................................................................................................... 47
5.2.2 Business Roles and Participants table ................................................................................................................ 48
5.3 Business Processes and Business Activities ...................................................................................... 48 5.3.1 Business Process and Business Activities definitions ........................................................................................ 48
5.3.2 Business Processes description .......................................................................................................................... 48
5.3.3 Business Activities description ........................................................................................................................... 49
5.3.3.1 E2E process for sending and receiving Request to Pay message............................................................. 49
- 6 -
- 6 -
5.3.3.1.1 Process Overview - Create and send Request to Pay message ............................................................. 50 5.3.3.1.2 Process Overview – Validate message ................................................................................................... 51 5.3.3.1.3 Process Overview – Receive Request to Pay message........................................................................... 51
5.3.3.2 E2E process for responding to Request to Pay message.......................................................................... 52 5.3.3.2.1 Process Overview – Retrieve message ................................................................................................... 52 5.3.3.2.2 Process Overview – Respond to request ................................................................................................ 53
5.3.3.3 E2E process for response option – Request extension ............................................................................. 53 5.3.3.3.1 Process Overview – Request extension.................................................................................................. 54
5.3.3.4 E2E processes for response option – Make payment (PayAll and PayPartial) ......................................... 55 5.3.3.4.1 Process Overview – Make payment through PSP .................................................................................. 55
5.3.3.5 E2E processes for response option – Decline Request to Pay and block Biller (Decline and
DeclineBlock) ................................................................................................................................................................ 56 5.3.3.5.1 Process Overview – Decline Request to Pay .......................................................................................... 56 5.3.3.5.2 Process Overview – Block Biller ............................................................................................................. 56
5.3.3.6 E2E process for updating request status .................................................................................................. 57 5.3.3.6.1 Process Overview – Update request status ........................................................................................... 57
5.4 Business Transactions ....................................................................................................................... 58 5.4.1 Business Transactions definitions ...................................................................................................................... 58
5.4.2 Payer makes full payment to a Request to Pay .................................................................................................. 59
5.4.3 Payer makes partial payments to a Request to Pay ........................................................................................... 59
5.4.4 Payer asks for extension ..................................................................................................................................... 59
5.4.5 Payer declines ..................................................................................................................................................... 60
5.4.6 Payer & Biller exchange information on a Request to Pay ................................................................................. 61
6. Pre-Authorisation Messages .................................................................................... 63
6.1 Pre-Authorisation Message (PAM) definition .................................................................................... 63 6.1.1 Application to Repository API’s .......................................................................................................................... 64
6.1.1.1 AR1 - Request for Authorisation ................................................................................................................ 64 6.1.1.1.1 Authorization .......................................................................................................................................... 64 6.1.1.1.2 pamId ...................................................................................................................................................... 65 6.1.1.1.3 requestMessage ...................................................................................................................................... 65 6.1.1.1.4 billerName .............................................................................................................................................. 65 6.1.1.1.5 billerId ..................................................................................................................................................... 65 6.1.1.1.6 payerId .................................................................................................................................................... 65 6.1.1.1.7 status ...................................................................................................................................................... 66
6.1.1.2 AR2 – Retrieve Authorisation Requests .................................................................................................... 66 6.1.1.2.1 Authorization .......................................................................................................................................... 67 6.1.1.2.2 role .......................................................................................................................................................... 67 6.1.1.2.3 status ...................................................................................................................................................... 67 6.1.1.2.4 pid ........................................................................................................................................................... 68
6.1.1.3 AR3 – Retrieve Single Authorisation Request ........................................................................................... 68 6.1.1.3.1 Authorization .......................................................................................................................................... 69 6.1.1.3.2 pamId ...................................................................................................................................................... 69
6.1.1.4 AR4 – Update Authorisation ...................................................................................................................... 69 6.1.1.4.1 Authorization .......................................................................................................................................... 70 6.1.1.4.2 status ...................................................................................................................................................... 70 6.1.1.4.3 pamId ...................................................................................................................................................... 70
6.1.1.5 AR5 – Request for More Info ...................................................................................................................... 70 6.1.1.5.1 Authorization .......................................................................................................................................... 71 6.1.1.5.2 pamId ...................................................................................................................................................... 71 6.1.1.5.3 mimId ...................................................................................................................................................... 71 6.1.1.5.4 moreInfoMessage ................................................................................................................................... 72
6.1.1.6 AR6 – Update with More Info (PATCH) ...................................................................................................... 72 6.1.1.6.1 Authorization .......................................................................................................................................... 72 6.1.1.6.2 pamId ...................................................................................................................................................... 73
- 7 -
- 7 -
6.1.1.6.3 mimId ...................................................................................................................................................... 73 6.1.1.6.4 moreInfoReply ........................................................................................................................................ 73
6.1.2 Repository to Repository API’s............................................................................................................................ 74
6.1.2.1 RR1 - Request for Authorisation ................................................................................................................ 74 6.1.2.1.1 pamId ...................................................................................................................................................... 74 6.1.2.1.2 requestMessage ...................................................................................................................................... 75 6.1.2.1.3 billerName .............................................................................................................................................. 75 6.1.2.1.4 billerId ..................................................................................................................................................... 75 6.1.2.1.5 payerId .................................................................................................................................................... 75 6.1.2.1.6 status ...................................................................................................................................................... 75
6.1.2.2 RR2 - Update Authorisation ...................................................................................................................... 76 6.1.2.2.1 status ...................................................................................................................................................... 76 6.1.2.2.2 pamId ...................................................................................................................................................... 76
6.1.2.3 RR3 - Request for More Info....................................................................................................................... 77 6.1.2.3.1 pamId ...................................................................................................................................................... 77 6.1.2.3.2 mimId ...................................................................................................................................................... 77 6.1.2.3.3 moreInfoMessage ................................................................................................................................... 78
6.1.2.4 RR4 – Update with More Info..................................................................................................................... 78 6.1.2.4.1 pamId ...................................................................................................................................................... 78 6.1.2.4.2 mimId ...................................................................................................................................................... 79 6.1.2.4.3 moreInfoReply ........................................................................................................................................ 79
6.1.2.5 RR5 - Sync Authorisations (POST) ............................................................................................................. 79 6.1.2.5.1 pamId ...................................................................................................................................................... 79
7. Glossary ................................................................................................................ 81
7.1 Terms and definitions ........................................................................................................................ 81
7.2 Acronyms ............................................................................................................................................ 81
7.3 References .......................................................................................................................................... 81
8. Change log ............................................................................................................. 83
Table of Figures
Figure 1 E2E process for sending and receiving Request to Pay message ................................................. 50
Figure 2 E2E process for responding to Request to Pay message .............................................................. 52
Figure 3 E2E process - Request extension ................................................................................................... 53 Figure 4 E2E process for Make Payment ..................................................................................................... 55
Figure 5 E2E process - Decline a request and block a Biller ....................................................................... 56
Figure 6 E2E process for update request status ......................................................................................... 57 Figure 7 Payer makes full payment towards Request to Pay ..................................................................... 59
Figure 8 Payer makes partial payments towards Request to Pay ............................................................. 59
Figure 9 Biller approves Payer's request for extension .............................................................................. 60
Figure 10 Biller declines Payer's request for extension .............................................................................. 60
Figure 11 Payer declines a Request to Pay ................................................................................................. 61 Figure 12 Payer blocks a Biller ................................................................................................................... 61 Figure 13 Payer & Biller exchange information on a Request to Pay ......................................................... 62
- 8 -
- 8 -
1. Request to Pay Overview
1.1 Introduction
Request to Pay is one of the “End User Needs” initiatives identified through the Payments Strategy Forum (PSF) activity to offer end-users more flexibility and control over their finances. The initiative aims to address the lack of control, flexibility and transparency in payments.
The Request to Pay ecosystem will include diverse types of Third-Party Participants (TPP), for example consumer, businesses, financial institutions, app developers, etc. This document defines the set of messages to be exchanged between the participants to support the functionalities of the Request to Pay Framework.
The Payment Strategy Forum and the Payment Systems Regulator have set out the following response options that must be supported within the Request to Pay Framework:
Pay all, Pay part,
Request extension (of the payment period),
Decline, Contact biller.
Additionally, the framework must support a “Block” feature to ensure end users can stop receiving
further requests from a particular sender. These options must be presented to the end user in a
manner which makes them visible and easily accessible.
This document should be used as a reference by Providers as they develop their systems to exchange
Request to Pay messages.
1.2 Scope
A key characteristic of the Request to Pay Framework is that the communication mechanism is independent of any payment mechanism users can select to make a payment. For that purpose, the messaging mechanism is segregated from the payment mechanisms in the solution design.
This approach provides more flexibility to both payers and billers on the payment mechanisms
through which they make and collect payments, as well as fostering competition for both the messaging component and the payment mechanism of Request to Pay, which could be provided by different service providers.
1.3 Out of scope Standard OAuth (Open Authorization) protocol is used for authentication and authorisation of the
end user and is not elaborated in this document.
- 9 -
- 9 -
2. Message Structure All JSON objects and fields names in this document follow the lowerCamelCase notation.
The message object is a structured JSON object and contains the following elements.
Field Name Field Description M/O1 Data Type
envelope This is the envelope of the message core
objects which can optionally be signed by the message sender and verified by
message recipient. Either object messageBody or errorBody must be present.
M Object
messageMeta This is the meta object for each message object. It holds the static/dynamic information for a message thread. This is
unique/same info for each message in a
thread.
M Object
attachments This is an array of attachments that are either base64-encoded attachment
content or download paths to where the attachments are stored.
O Array
2.1 envelope The envelope object of the message may be digitally signed by the sender’s Application Provider
signing certificate and the signature is sent within the messageMeta object of the message. For clarity,
the digital signing of the envelope is optional.
The envelope object contains the following elements.
Field Name Field Description M/O Data Type
threadHeader This encapsulates static information for the message thread. It is included in each
message and remains unchanged for each subsequent message linked to the initial thread message.
M Object
messageHeader This encapsulates static information for a
message. It is included in each message
and data varies to uniquely identify each message.
M Object
messageBody This encapsulates static information for a
message. It is included in each message except when errorBody is present.
O Object
errorBody This contains all possible errors that could
be raised during message transmission from sender to recipient causing a
O Object
1 M/O stands for Mandatory or Optional fields.
- 10 -
- 10 -
Field Name Field Description M/O Data Type
message delivery failure. It is included in
the message when messageBody is not present.
2.1.1 threadHeader
Information contained in the threadHeader is included unchanged in all subsequent messages within
the thread. Note that the threadHeader object does not contain any Request to Pay specific fields and is independent to the content of the messageBody object.
The threadHeader object contains the following elements.
Field Name Field Description M/O Data Type
profile This value defines the messageBody object structure.
M Max 35 chars
subject This is the subject of the thread sent by the
originator and displayed to the
respondent.
M Max 140
chars
threadId This is the unique identifier of the thread. M Max 1024
chars
originatorPid This is the payment address of the originator of the thread.
M Max 300 chars
respondentPid This is the payment address of the
respondent.
M Max 300
chars
threadDateTime This is the date and time of the thread
creation.
M Date
threadPriority This provides a routing prioritisation hint to repositories.
O Max 35 chars
2.1.1.1 profile Definition: Field profile defines fields, as well as semantics of the fields, in the messageBody object that carries the message payload.
Usage: Possible values are:
“requestToPay” Refer to section Request to Pay Messages for further details on the associated message
structure and content. “simpleMessage”
Refer to section
Simple Message for further details on the associated message structure and content.
Additional profile values with their corresponding messageBody structure may be defined in the
future.
- 11 -
- 11 -
Data type: String of maximum 35 characters.
Presence: Mandatory field.
2.1.1.2 subject
Definition: Field subject contains a readable description of the thread as defined by the originator
of the thread.
Usage: N/A Data type: String of maximum 140 characters. Presence: Mandatory field.
2.1.1.3 threadId Definition: Field threadId contains a unique identifier. This is generated in the original message by the originator’s Application Provider and passed on unchanged in all subsequent messages related to this
specific thread.
Usage: The format of threadId is user1pid-user2pid-timestamp_nano-64_bitsrandom, where: user1pid is the payment address of the thread originator in lowercase,
user2pid is the payment address of the thread respondent in lowercase, timestamp_nano is the epoch time in nanoseconds,
64_bitsrandom is a BASE64-encoded value. Data type: String of maximum 1024 characters.
Presence: Mandatory field.
2.1.1.4 originatorPid Definition: Field originatorPid contains the payment address of the originator (end user who sent the
initial message) of the thread. Usage: Payment address originatorPid format is username#domain as described in the Request to Pay Service Overview document (section 5.4 End User). This field must be in lowercase.
Data type: String of maximum 300 characters. Presence: Mandatory field.
2.1.1.5 respondentPid Definition: Field respondentPid contains the payment address of the respondent (end user who
received the initial message) to the thread. Usage: Payment address respondentPid format is username#domain as described in the Request to
Pay Service Overview document (section 5.4 End User). This field must be in lowercase. Data type: String of maximum 300 characters.
Presence: Mandatory field.
- 12 -
- 12 -
2.1.1.6 threadDateTime
Definition: Field threadDateTime contains the date and time of creation of the initial message of the thread. Usage: Format YYYY-MM-DDTHH:MM:SSZ.
Data type: ISODateTime 8601. Presence: Mandatory field.
2.1.1.7 threadPriority
Definition: Field threadPriority provides a routing prioritisation indication to repositories. Usage: List of possible values:
“high”: messages should be prioritised for delivery over “normal”, “low” or no priority,
“normal”: messages should be prioritised for delivery over “low” or no priority,
“low”.
Rules to be applied to this field will be implemented in future releases.
Data type: String of maximum 35 characters. Presence: Optional field.
2.1.2 messageHeader
Information contained in the messageHeader is included in all messages. Note that the messageHeader object does not contain any Request to Pay specific fields and is
independent to the content of the messageBody object. The messageHeader object contains the following elements.
Field Name Field Description M/O Data Type
messageId This is the unique identifier of the
message.
M Max 105
chars
senderName This is the name of the message sender. M Max 70 chars
senderPid This is the payment address of the message sender.
M Max 300 chars
recipientPid This is the payment address of the message recipient.
M Max 300 chars
messageDateTime This is the date and time of the message
creation.
M Date
2.1.2.1 messageId Definition: Field messageId contains a unique identifier generated by the sender’s Application Provider for each message.
- 13 -
- 13 -
Usage: The format of messageId is timestamp_nano-64_bitsrandom, where:
timestamp_nano is the epoch time in nanoseconds, 64_bitsrandom is a BASE64-encoded value.
Data type: String of maximum 105 characters.
Presence: Mandatory field.
2.1.2.2 senderName Definition: Field senderName contains the name of the sender of the message. Usage: N/A
Data type: String of maximum 70 characters. Presence: Mandatory field.
2.1.2.3 senderPid
Definition: Field senderPid contains the payment address of the sender of the message.
Usage: Payment address senderPid format is username#domain as described in the Request to Pay
Service Overview document (section 5.4 End User). This field must be in lowercase.
Data type: String of maximum 300 characters. Presence: Mandatory field.
2.1.2.4 recipientPid
Definition: Field recipientPid contains the payment address of the receiver of the message.
Usage: Payment address recipientPid format is username#domain as described in the Request to Pay Service Overview document (section 5.4 End User). This field must be in lowercase.
Data type: String of maximum 300 characters. Presence: Mandatory field.
2.1.2.5 messageDateTime
Definition: Field messageDateTime contains the date and time of creation of the message.
Usage: Format YYYY-MM-DDTHH:MM:SSZ. Data type: ISODateTime 8601. Presence: Mandatory field.
2.1.3 messageBody
- 14 -
- 14 -
Object messageBody contains the framework provided to the end users. Information contained in the
messageBody is included in all messages except when errorBody is present.
The messageBody object contains the following elements.
Field Name Field Description M/O Data Type
MessageBodyRequestToPaySpecific
This is the specific message body object for
profile “requestToPay”. Content is
described in section Request to Pay
Messages.
O One-off object
MessageBodyGeneric This is the specific message body object for
profile “simpleMessage”. Content is
described in section
Simple Message.
O One-off object
2.1.4 errorBody
Information contained in the errorBody object is included only when messageBody is not present in
the envelope object.
Note that errorBody object does not contain any Request to Pay specific fields.
The errorBody object contains the following elements.
Field Name Field Description M/O Data Type
referenceMessageId This field refers to the messageId of the
original message.
M Max 105
chars
code This contains the message delivery failure code.
M Max 3 chars
message This is the message matching the failure code.
M Max 70 chars
failureReason This is the user readable description of the
reason for failure to deliver a message.
O Max 300
chars
2.1.4.1 referenceMessageId Definition: Field contains a copy of messageId from the message which could not be delivered due to
an error.
Usage: N/A Data type: String of maximum 105 characters.
Presence: Mandatory field.
2.1.4.2 code Definition: Field code contains the message delivery failure code which represents a specific error
during the message delivery.
- 15 -
- 15 -
Usage: Refer to section 2.1.4.5 Errors description for the list of code values.
Data type: String of maximum 3 characters. Presence: Mandatory field.
2.1.4.3 message Definition: Field message contains a short description matching the failure codes.
Usage: Refer to section 2.1.4.5 Errors description for the list of message values.
Data type: String of maximum 70 characters. Presence: Mandatory field.
2.1.4.4 failureReason
Definition: Field failureReason contains the user readable description of the reason for failure to deliver a message.
Usage: Refer to section 2.1.4.5 Errors description for the list of failureReason values. Data type: String of maximum 300 characters.
Presence: Optional field.
2.1.4.5 Errors description
2.1.4.5.1 Delivery errors
Delivery errors occur in transmitting messages from sender’s Repository Provider to recipient’s Repository Provider.
In certain cases, a “TemporaryDeliveryError” notification message in the errorBody should be returned
to the EAP indicating that the server should attempt to retry the delivery. An example would be where a repository receives a synchronous error response from the receiving repository where the error
code relates to a problem that is potentially temporary in nature, e.g. a 500 Internal Server Error, or a 503 Service Unavailable error. These ‘inter-repository’ errors should ‘map’ to the asynchronous 001
TemporaryDeliveryError, to make the error more meaningful to the EAP.
Field
Code Field message Field failureReason
001 “TemporaryDeliveryError” A temporary delivery error has occurred and a retry may be
required.
If a message cannot be delivered, despite retries, a terminal error message is returned to sender with
one of the following error codes.
Field Field message Field failureReason
- 16 -
- 16 -
Code
002 “RecipientNotFound” Recipient is not found in the
Repository Provider (user not registered or deleted).
003 “SenderIsBlocked” Sender is blocked by the recipient.
004 “StorageFull” Recipient's inbox is full.
005 “RepositoryNotFound” Recipient's Repository Provider
domain name is not found
(Repository Provider domain name is not registered or deleted).
006 “RepositoryCertificateInvalid” Recipient’s Repository Provider does not have a valid certificate.
007 “RepositoryUnavailable” Recipient's Repository Provider is
unavailable (due to planned or
unplanned downtime).
008 “InternalServerError” Internal server error.
Error codes 002, 003 and 004 do not need to be mapped before collection by the EAP, as they make
sense natively and already represent a terminal status. Inter-repository synchronous error codes 404 server not found or 401 Unauthorized should map to 005 and 006 to make the error more meaningful
to the EAP. Where retry attempts as a result of a 001 error have been exhausted, terminal error codes 007 and 008 can be mapped to make inter-repository errors 503 and 500 more meaningful to the EAP.
2.1.4.5.2 Message validation errors
Message validations performed by receiving Repository Provider may indicate that a message, or any
part of the message, has been compromised in transit. In this case, repository may send a failure
message with the following codes.
Field
code Field message Field failureReason
009 “MessageSemanticValidationFailed” Message semantics are incorrect. This can happen at sender or receiver's
Repository Provider.
010 “MessageAttachmentLimitExceeded” Attachment limit is exceeded.
011 “MessageIntegrityVerificationFailed” Message integrity is compromised.
012 “MessageAttachmentsIntegrityVerificationFailed” Message attachment(s) compromised.
013 “MessageSigningCertificateNotFound” Message signing certificate of the
sender or recipient is not found.
014 “MessageSigningCertificateInvalid” Invalid signing certificate is used by either sender or recipient.
015 “BillerPaymentOptionsInvalid” Payment options data in the request does not match payment options data initially on-boarded by the biller’s Repository Provider.
For codes “009” to “015” i.e. for message validation errors, no retry is attempted for delivery failure, since these failures are permanent in nature.
- 17 -
- 17 -
2.2 messageMeta The messageMeta object contains a meta object for each message. This holds the static/dynamic information for a message thread. The same format exists for every message within a thread, however
the data within is unique to that message in the thread.
Note that the messageMeta object does not contain any Request to Pay specific fields and is independent to the content of the messageBody object.
The messageMeta object contains the following elements.
Field Name Field Description M/O Data Type
deliveryPath This is the delivery path of the message. M Object
numMessages This is the message number that defines the position this message exists within the order of a specific thread.
M Number
signature This is the digital signature signed with the sender’s signing certificate for the
Envelope object
O Max 1025 chars
2.2.1 deliveryPath The deliveryPath object contains the following element.
Field Name Field Description M/O Data Type
fromId This is the Request to Pay domain name of
the message sender.
M Chars
senderCert This is the sender's certificate fingerprint. O Chars
timestamp This is the ISODateTime8601 timestamp of transmission.
M Date
toId This is the Request to Pay domain name of the message receiver.
M Chars
2.2.1.1 fromId
Definition: Field fromId contains the Request to Pay domain name of the message sender.
Usage: domain name format, e.g. ‘requesttopay.mydomain.co.uk’
Data type: String of characters. Presence: Mandatory field.
2.2.1.2 senderCert Definition: Field senderCert contains the sender's certificate fingerprint. Usage: N/A
- 18 -
- 18 -
Data type: String of characters. Presence: Optional field.
2.2.1.3 timestamp Definition: Field timestamp contains the ISODateTime8601 timestamp of transmission.
Usage: Format YYYY-MM-DDTHH:MM:SSZ.
Data type: ISODateTime8601. Presence: Mandatory field.
2.2.1.4 toId
Definition: Field toId contains the Request to Pay domain name of the message receiver.
Usage: domain name format. e.g. ‘requesttopay.mydomain.co.uk’
Data type: String of characters.
Presence: Mandatory field.
2.2.2 numMessages Definition: Field numMessages contains the message number that defines the position this message
exists within the order of a specific thread. Usage: N/A
Data type: Number.
Presence: Mandatory field.
2.2.3 signature Definition: Field signature contains the digital signature of the envelope object signed with the
sender’s signing certificate using Cryptographic Message Syntax (PKCS#7).
Usage: Encrypted signature hash and public keys to be encapsulated within CMS (PKCS#7) block in
Base64 format
Data type: String of maximum 1025 characters. Presence: Optional field.
2.3 attachments Attachments is a JSON array having a list of attachments objects. The content field of each attachment
can be signed by the sender’s Application Provider with the signing certificate and signature to be
sent within the unsigned part of the attachments JSON.
- 19 -
- 19 -
The attachment can be added as either a path or as an object (Base64 format) but the total of all attachments in the array should not exceed 10M chars (7 MB).
Note that the attachments object does not contain any Request to Pay specific fields and is
independent to the content of the messageBody object.
The attachments object contains the following fields.
Field Name Field Description M/O Data Type
fileName This is the name of the attachment. M Max 35 chars
contentType This is the type of the file content. M 4 chars
signature This is the digital signature of the attachment content (only) signed with the
sender’s signing certificate.
O Max 1025 chars
path This is the API path to download the
content.
O Max 2048
chars
content This is the contents of the attachment in
Base64 format
O Max 10M
chars (~7MB)
2.3.1 fileName Definition: Field fileName contains the name of the attachment.
Usage: N/A
Data type: String of maximum 35 characters.
Presence: Mandatory field.
2.3.2 contentType Definition: Field contentType contains the type of the file content, and is defined as per ISO 20022 message Standards.
Usage: Possible values are:
“DPDF” for PDF document format, “DXML” for XML document format, “SDSH” for Spreadsheet document format,
“WORD” for Word document format,
“XSLT” for XSLT document format.
“URID” for Uniform Resource Identifier Data type: String of 4 characters. Presence: Mandatory field.
2.3.3 signature Definition: Field signature contains the digital signature of the attachment content (only) field signed with the sender’s signing certificate using Cryptographic Message Syntax (PKCS#7).
- 20 -
- 20 -
Usage: Encrypted signature hash and public keys to be encapsulated within CMS (PKCS#7) block in Base64 format
Data type: String of maximum 1025 characters.
Presence: Optional field.
2.3.4 path Definition: Field path contains API path to download the attachment content.
Usage: This field must be populated with the path to download content if the field content in
attachments is left blank. Application of using path as opposed to content would be for example where an EAP retrieves a message without downloading the attachments from the RSP.
Data type: String of maximum 2048 characters. Presence: Optional field.
2.3.5 content
Definition: Field content contains the content of the file in Base64 format.
Usage: This field must be populated with the content of the attachment if the field path in attachments is left blank. Application of using content as opposed to path would be for example
where an EAP sends a message with attachments to the RSP.
Data type: String of maximum 10M chars (~7MB) in Base64 format Presence: Optional field.
2.4 Flexibility in parsing message fields In order to support future features, all software processing messages (e.g. end user’s Application
Provider, Repository Provider) MUST ignore any fields that are not recognised.
RtP service providers are entitled to define vendor-specific message fields. Any such fields should be
prefixed by string “x-“ (without quotation marks), to be easily distinguishable from fields defined in this specification.
For example x-avScanResult may be a field vendor defines to track Anti-Virus scan results of attachments.
- 21 -
- 21 -
3. Request to Pay Messages
This section describes Request to Pay specific message semantics, that is message types and fields
required to facilitate communications needed between biller and payer.
3.1 List of messageBody objects
The following table lists all possible messageType values for the Request to Pay framework. This determines structure and content of fields in the corresponding messageBody objects.
Message Identifier
Field messageType Definition
rqtp.001 RequestToPay
The RequestToPay message is the first message of
every request thread, sent by the biller to the payer. It
contains information sufficient for the payer to
understand the context of the payment request. It also
contains the biller’s payment options where the
payment should be credited if the payer decides to
pay either in full or in part.
rqtp.002
PayAll
The PayAll message is sent by the payer when the
payer accepts the biller’s RequestToPay message and
pays the entire outstanding amount on a request. If
the payment is successful then the request is closed.
PayPartial
The PayPartial message is sent by the payer when the
payer accepts the biller’s RequestToPay message but
pays only a part of the outstanding amount on a
request. The original request sent by the biller remains
open until the full amount is paid in by the payer.
rqtp.003 ReqPayExtension
The ReqPayExtension message is sent by the payer to
the biller suggesting a new due date in the future for
the biller’s payment request. The biller then must
grant or decline the extension. The payer cannot
request another extension until the previous request
has been granted or declined by the biller.
rqtp.004
ExtensionGranted
A biller sends an ExtensionGranted message to a payer
when they approve the payer’s ReqPayExtension
message with the new due date for the payment.
ExtensionDeclined
A biller sends an ExtensionDeclined message to a payer
when the payer’s ReqPayExtension message is
declined.
rqtp.005
Decline
The Decline message is sent by the payer in response
to a biller’s RequestToPay message when the payer
does not want to make any payment towards that
request.
DeclineBlock In addition to declining a RequestToPay message from
a biller the payer can also block the biller if the payer
- 22 -
- 22 -
does not want to receive any future requests from the
biller. In this scenario the payer sends a DeclineBlock
message to the biller. payer will no longer receive
RequestToPay messages from the same biller until the
block is lifted.
rqtp.006
NoteToBiller
NoteToBiller is a message sent by the payer to the
biller when the payer requires further information
regarding a specific RequestToPay message.
NoteToPayer
NoteToPayer is a message sent by the biller to the
payer when the biller requires further information
regarding a specific RequestToPay message.
rqtp.007 AcknowledgeInFull
A biller sends the AcknowledgeInFull message to the
payer when the payer has paid the full amount
requested by the biller. The payer can pay the full
amount either as one payment transaction or as
multiple partial payment transactions.
rqtp.008 AcknowledgePayment
AcknowledgePayment message is sent by the biller
when the latter wants to acknowledge any payment
received from a payer, whether within or outside of the Request to Pay communication channel.
3.2 rqtp.001 RequestToPay Message Body
The RequestToPay message is the first message of every request thread, sent by the biller to the
payer.
The messageBody object contains the following elements.
Field Name Field Description M/O Data Type
messageType This is the message type populated with
“RequestToPay” for rqtp.001.
M Max 35 chars
endToEndIdentification This is a unique identifier provided by the
biller.
M Max 35 chars
creditor This contains information on the biller. M Object
paymentOptions This array contains information related to
the list of payment options offered by the biller to the payer to process payments.
M Array
dueDate This is the date by which the full due
amount must be paid by the payer.
M Date
amount This contains information on the payment amount that is requested by the biller to
the payer.
M Object
remittanceInformation This contains information on the remittance information, passed on by the
biller to the payer, which should be
provided to any of the agents in the payment processing chain.
M Object
relatedRemittanceInformation This contains information on the handling O Object
- 23 -
- 23 -
Field Name Field Description M/O Data Type
of the remittance information, passed on
by the biller to the payer, which should be provided to any of the agents in the payment processing chain.
3.2.1 messageType
Definition: Field messageType indicates the specific type of message when profile in the thread header is populated with “requestToPay”. Usage: messageType must be populated with “RequestToPay” for message rqtp.001.
Data type: String of maximum 35 characters.
Presence: Mandatory field.
3.2.2 endToEndIdentification Definition: Field endToEndIdentification is an identifier generated by the biller, which can be used for
reconciliation purpose and to link a payment to the original bill (defined as per ISO 20022 message
Standards).
Usage: endToEndIdentification is provided by the biller and should be:
A unique identifier in the biller’s system that will be used to link the request to the payment
received, Stored in the payer’s repository,
Carried unchanged throughout the payment system chain.
Note the current size constraints to endToEndIdentification: Faster Payments Scheme can access a maximum of 31 characters (field 62 from the ISO8583
specification),
BACS Scheme can access a maximum of 18 characters (field 10 from the STD18 specification).
Data type: String of maximum 35 characters. Presence: Mandatory field.
3.2.3 creditor The creditor object contains the following element.
Field Name Field Description M/O Data Type
name This is the name of the biller. M Max 70 chars
3.2.3.1 name Definition: Field name contains the name of the biller.
- 24 -
- 24 -
Usage: This field can be defaulted with same value as the biller’s account name in field name of the
creditorAccount object and specifically populated when biller’s name is different from the biller’s account name.
This field must correspond to the biller’s name provided during the Repository Provider’s on-boarding process. If content of this field name in rqtp.001 Request to Pay does not match the biller’s
name stored in the biller’s Repository Provider, the Request to Pay message will be declined by the Repository Provider (see section 2.1.4.5 Errors description).
Data type: String of maximum 70 characters. Presence: Mandatory field.
3.2.4 paymentOptions The paymentOptions section is a JSON array having a list of paymentOptions objects. One or more of
the below objects must be offered by the biller to the payer as a payment option, which must correspond to the payment details the biller provided in the Repository Provider’s onboarding process. If payment details in rqtp.001 Request to Pay message do not match the payment details stored in the
biller’s Repository Provider, the Request to Pay message will be declined by the Repository Provider
(see section 2.1.4.5 Errors description).
The paymentOptions object contains the following elements.
Field Name Field Description M/O Data Type
paymentMethod This is code that identifies the type of payment option allowed by the biller.
M 3 chars
creditorAgent This contains the biller’s agency details. O Object
creditorAccount This contains the biller’s account details. O Object
creditorPortal This contains the biller’s portal details. O Object
3.2.4.1 paymentMethod Definition: Field paymentMethod contains a code that identifies the type of payment option allowed
by the biller. Field paymentMethod is defined as per ISO 20022 message Standards.
Usage: Value “TRF” indicates that payment option is via bank transfer and biller provides:
Either UK sort code and bank account number, Or BIC and IBAN.
Value “PRT” indicates that payment option is via a payment portal and biller provides information to
log in. Note that code “TRF” is as per ISO 20022 message Standards whilst code “PRT” is not.
Data type: String of 3 characters.
Presence: Mandatory field.
3.2.4.2 creditorAgent The creditorAgent object contains the following element.
- 25 -
- 25 -
Field Name Field Description M/O Data Type
financialInstitutionId This is an intermediate component as per
ISO20022 Standards.
O Object
3.2.4.2.1 financialInstitutionId
This object contains details of the biller's bank agency (be it with a UK sort code or a BIC) and
populated only when the field paymentMethod is valued with “TRF”. Object creditorAgent contains elements as per ISO 20022 message Standards.
The financialInstitutionId object contains the following elements.
Field Name Field Description M/O Data Type
BICFI This is the biller’s BIC. O Max 11 chars
clearingSystemMemberId This is an intermediate component as per ISO20022 Standards.
O Object
3.2.4.2.1.1 BICFI Definition: Field BICFI contains the BIC of the biller's agency. Field BICFI is defined as per ISO 20022
message Standards.
Usage: This field is populated with a BIC only when the field code in creditorAgent (\financialInstitutionId\clearingSystemMemberID\clearingSystemId) is not populated. When the field code is populated with “GBDSC”, field BICFI must not be populated.
The BIC must correspond to the account details established for the biller when they were on-boarded
to the Repository Provider. Valid BICs for financial institutions are registered and published by the ISO 9362 Registration
Authority in the ISO directory of BICs, and consist of 8 or 11 contiguous characters.
Data type: String of maximum 11 characters.
Presence: Optional field.
3.2.4.2.1.2 clearingSystemMemberId This object contains details of the biller's bank agency and populated only when the field
paymentMethod is valued with “TRF”. Object creditorAgent contains elements as per ISO 20022
message Standards.
The clearingSystemMemberId object contains the following elements.
Field Name Field Description M/O Data Type
clearingSystemId This is an intermediate component as per
ISO20022 Standards.
O Object
memberId This is the biller’s UK sort code. O Max 35 chars
3.2.4.2.1.2.1 clearingSystemId
- 26 -
- 26 -
The clearingSystemId object contains the following element.
Field Name Field Description M/O Data Type
code This field is as per ISO20022 Standards. O 5 chars
3.2.4.2.1.2.1.1 code
Definition: Field code is defined as per ISO 20022 message Standards. Usage: This field must be populated with value "GBDSC" when biller's payment details are UK sort
code and bank account. Otherwise, code object must not be populated.
Data type: String of 5 characters. Presence: Optional field.
3.2.4.2.1.2.2 memberId Definition: Field memberId contains the biller's sort code. Field memberId is defined as per ISO 20022
message Standards.
Usage: This field must be populated with a 6 digit UK sort code only when the field code in
creditorAgent (\financialInstitutionId\clearingSystemMemberID\clearingSystemId) is specified as “GBDSC”. Otherwise, clearingSystemMemberId object and subsequently memberId field must not be
populated. The UK sort code must correspond to the account details established for the biller when they were on-boarded to the Repository Provider.
Data type: String of maximum 35 characters. Presence: Optional field.
3.2.4.3 creditorAccount
This object contains details of the biller's bank account and populated only when the field paymentMethod is valued with “TRF”. Object creditorAccount contains elements as per ISO 20022 message Standards.
The creditorAccount object contains the following element.
Field Name Field Description M/O Data Type
identification This is an intermediate component as per
ISO20022 Standards.
O Object
currency This is the currency in which the biller's account is held.
O Max 3 chars
name This is the name of the biller's bank account.
M Max 70 chars
3.2.4.3.1 identification
- 27 -
- 27 -
This object must be displayed and contain either IBAN or other populated. When the field code in
creditorAgent (\financialInstitutionId\clearingSystemMemberID\clearingSystemId) is populated with “GBDSC”, other must be populated. If the ‘code’ field is not populated, then IBAN must be populated.
In summary, IBAN and other are mutually exclusive.
The identification object contains the following elements.
Field Name Field Description M/O Data Type
IBAN This is the IBAN of the biller's account. O Max 34 chars
other This is an intermediate component as per ISO20022 Standards.
O Object
3.2.4.3.1.1 IBAN
Definition: Field IBAN contains the International Bank Account Number of the biller's account.
Usage: This field is populated only when field code in creditorAgent (\financialInstitutionId\clearingSystemMemberID\clearingSystemId) is not populated. When code is populated with “GBDSC”, IBAN must not be populated.
The IBAN must correspond to the account details established for the biller when they were on-
boarded to the Repository Provider.
A valid IBAN format consists of all three of the following components: country code, check digits and BBAN.
Data type: String of maximum 34 characters. Presence: Optional field.
3.2.4.3.1.2 other The other object contains the following elements.
Field Name Field Description M/O Data Type
id This is the biller’s UK bank account
number.
O Max 34 chars
3.2.4.3.1.2.1 id
Definition: Field id contains the biller's UK bank account.
Usage: This field must be populated with an 8 digit UK account number only when the field code in creditorAgent (\financialInstitutionId\clearingSystemMemberID\clearingSystemId) is specified as
“GBDSC”. Otherwise, the field must not be populated and field IBAN must be used instead. The UK account number must correspond to the account details established for the biller when they were on-boarded to the Repository Provider. Data type: String of maximum 34 characters.
Presence: Optional field.
- 28 -
- 28 -
3.2.4.3.2 currency
Definition: Field currency contains the currency associated to the account identification. Usage: Field currency is defaulted to “GBP”. Valid active currency codes are registered with the ISO 4217 Maintenance Agency, and consist of 3 contiguous letters.
Data type: String of maximum 3 characters. Presence: Optional field.
3.2.4.3.3 name Definition: Field name contains the name of the biller's bank account, as assigned by the biller's bank
as an additional means of identification of the account. Usage: This field must correspond to the biller’s account name provided during the Repository Provider’s on-boarding process.
If content of field name in rqtp.001 Request to Pay does not match biller’s account name stored in the
biller’s Repository Provider, Request to Pay message will be declined by the Repository Provider (see
section 2.1.4.5 Errors description).
Data type: String of maximum 70 characters.
Presence: Mandatory field.
3.2.4.4 creditorPortal Payer selects payment method directly on the biller’s portal.
The creditorPortal object contains the following elements.
Field Name Field Description M/O Data Type
basketId This is the identifier of the basket to be
displayed on the biller's portal.
O Max 35 chars
electronicAddress This is the biller’s portal URL. M Max 2048 chars
3.2.4.4.1 basketId
Definition: Field basketId contains the identifier of the basket to be displayed on the biller's portal and paid by the payer.
Usage: N/A
Data type: String of maximum 35 characters. Presence: Optional field.
3.2.4.4.2 electronicAddress
- 29 -
- 29 -
Definition: Field electronicAddress contains the URL allowing the payer to access the biller's portal.
Usage: The URL must be in a valid format.
Data type: String of maximum 2048 characters.
Presence: Mandatory field.
3.2.5 dueDate
Definition: Field dueDate contains the chosen date sent by the biller by which the full due amount of the requested payment must be paid by the payer.
Usage: Good practice is to display dueDate to the payer in format DD-MM-YYYY or in a similar format.
Data type: ISODateTime 8601, format YYYY-MM-DDTHH:MM:SSZ. Presence: Mandatory field.
3.2.6 amount
The amount object contains the following elements.
Field Name Field Description M/O Data Type
dueAmount Payment amount that is requested by
biller to the payer.
M Numeric 14,2
currency This is the currency of the due amount
requested by the biller.
M 3 chars
3.2.6.1 dueAmount Definition: Field dueAmount contains amount that is requested by biller to the payer.
Usage: Value 0.00 is allowed.
Faster Payments amount format is numeric 14,2 (readable version is 999,999,999,999.99).
Data type: Numeric 14,2 Presence: Mandatory field.
3.2.6.2 currency
Definition: Field currency contains the currency associated to dueAmount.
Usage: Field currency is defaulted to “GBP”. Valid active currency codes are registered with the ISO 4217 Maintenance Agency, and consist of 3
contiguous letters.
Data type: String of 3 characters.
Presence: Mandatory field.
- 30 -
- 30 -
3.2.7 remittanceInformation The remittanceInformation object contains the following elements.
Field Name Field Description M/O Data Type
unstructured This is the biller’s unstructured remittance information to be passed unchanged through the payment system chain.
O Max 140 chars
structured This is the biller’s structured remittance information.
M Object
3.2.7.1 unstructured
Definition: Field unstructured contains the biller’s remittance information.
Usage: unstructured is provided by the biller and should be: Stored in the payer’s repository, Carried unchanged throughout the payment system chain.
Data type: String of maximum 140 characters.
Presence: Optional field.
3.2.7.2 structured The structured object contains the following elements.
Field Name Field Description M/O Data Type
billName This is the name of the bill for which
payment is requested by the biller.
M Max 70 chars
creditorReferenceInformation This is an intermediate component as per
ISO20022 Standards.
O Object
billingPeriod This is the period of service for which
payment is requested by the biller.
O Object
3.2.7.2.1 billName
Definition: Field billName contains name of the bill for which payment is requested by the biller.
Usage: N/A
Data type: String of maximum 70 characters. Presence: Mandatory field.
3.2.7.2.2 creditorReferenceInformation
The creditorReferenceInformation object contains the following elements.
Field Name Field Description M/O Data Type
- 31 -
- 31 -
Field Name Field Description M/O Data Type
reference This is a reference information provided by
the biller to the payer.
M Max 35 chars
3.2.7.2.2.1 reference
Definition: Field reference may contain a Building Society Roll Number, Credit Card Number, or Utility
Customer Account Number, etc. that the biller wishes to pass on to the payer to make payment. Usage: This corresponds to the optional FPS field 120 and BACs field 10.
Note that field reference is defined as per the Faster Payments Standards Library Specifications (see section 7.3 References).
Data type: String of maximum 35 characters.
Presence: Mandatory field.
3.2.7.2.3 billingPeriod
The billingPeriod object contains the following elements.
Field Name Field Description M/O Data Type
billingPeriodFrom This is the start date of service for which
payment is requested by the biller.
M Date
billingPeriodTo This is the end date of service for which
payment is requested by the biller.
M Date
3.2.7.2.3.1 billingPeriodFrom Definition: Field billingPeriodFrom contains the start date of the billing period for which payment is
requested by the biller.
Usage: Good practice is to display billingPeriodFrom to the payer in format DD-MM-YYYY or in a similar
format. Data type: ISODateTime 8601, format YYYY-MM-DDTHH:MM:SSZ. Presence: Mandatory field.
3.2.7.2.3.2 billingPeriodTo
Definition: Field billingPeriodTo contains the end date of the billing period for which payment is
requested by the biller. Usage: Good practice is to display billingPeriodTo to the payer in format DD-MM-YYYY or in a similar
format.
Data type: ISODateTime 8601, format YYYY-MM-DDTHH:MM:SSZ. Presence: Mandatory field.
- 32 -
- 32 -
3.2.8 relatedRemittanceInformation The relatedRemittanceInformation object contains the following elements.
Field Name Field Description M/O Data Type
remittanceIdentification This is the identifier of the biller’s bill. O Max 35 chars
remittanceLocationDetails This is an intermediate component as per
ISO20022 Standards.
O Object
3.2.8.1 remittanceIdentification Definition: Field remittanceIdentification contains the identifier of the biller’s bill.
Usage: N/A
Data type: String of maximum 35 characters. Presence: Optional field.
3.2.8.2 remittanceLocationDetails The relatedLocationDetails object contains the following elements.
Field Name Field Description M/O Data Type
electronicAddress This is the URL of the biller’s bill. O Max 2048
chars
3.2.8.2.1 electronicAddress
Definition: Field electronicAddress contains the URL of the biller’s bill.
Usage: Note that when this field is passed on to an ISO 20022 payment format, field method should be populated with “URID” to specify the method used to deliver the remittance information as per
ISO20022 Code Set RemittanceLocationMethod2Code (see section 7.3 References ). Data type: String of maximum 2048 characters.
Presence: Optional field.
3.3 rqtp.002 Pay Message Body The Pay message is originated by a payer against a biller’s RequestToPay message to:
Either pay full due amount in a PayAll single payment, Or pay parts of the due amount in several PayPartial payments.
The messageBody object contains the following elements.
Field Name Field Description M/O Data Type
messageType This is the message type populated with
“PayAll” or “PayPartial” for rqtp.002.
M Max 35 chars
- 33 -
- 33 -
Field Name Field Description M/O Data Type
endToEndIdentification This is a unique identifier provided by the
biller.
M Max 35 chars
requestedExecutionDate This is the date of payment execution instructed by the payer to their payment
service provider.
M Date
amount This contains information on the payment amount that is paid by the payer to the
biller.
M Object
transactionId This is a unique identification as assigned by the payer’s payment service provider to
unambiguously identify the payment
transaction submitted by the payer.
O Max 35 chars
acceptanceDateTime This is the date and time at which a
payment instruction was submitted by the payer’s payment service provider.
O Date
transactionStatus This specifies the transaction status returned by the payer’s payments service
provider on submission of a payment transaction by the payer.
O 4 chars
additionalInformation This is additional information in free text
form to complement the transaction status.
O Max 140
chars
3.3.1 messageType
Definition: Field messageType indicates the specific type of message when profile is populated with “requestToPay”.
Usage: messageType must be populated with “PayAll” or “PayPartial” for message rqtp.002.
Data type: String of maximum 35 characters. Presence: Mandatory field.
3.3.2 endToEndIdentification
Definition: Field endToEndIdentification is an identifier generated by the biller, which can be used for
reconciliation purpose and to link a payment to the original bill (defined as per ISO 20022 message Standards).
Usage: Refer to the field usage in section 3.2.2 endToEndIdentification.
Data type: String of maximum 35 characters.
Presence: Mandatory field.
3.3.3 requestedExecutionDate Definition: Field requestedExecutionDate is the date of payment execution instructed by the payer to
their payment service provider.
- 34 -
- 34 -
As per ISO20022 message Standards definition, this field carries the following data: “Date at which
the initiating party (i.e. payer) requests the clearing agent payer (i.e. payer’s payment service provider) to process the payment.”
Usage: Good practice is to display requestedExecutionDate to the payer in format DD-MM-YYYY or in a
similar format. Data type: ISODateTime 8601, format YYYY-MM-DDTHH:MM:SSZ. Presence: Mandatory field.
3.3.4 amount
The amount object contains the following elements.
Field Name Field Description M/O Data Type
instructedAmount This is the amount instructed to be paid by the payer through the payer’s payment system.
M Numeric 14,2
currency This is the currency of the payment made
by the payer.
M 3 chars
3.3.4.1 instructedAmount
Definition: Field instructedAmount contains the amount instructed to be paid by the payer.
Usage: Minimum allowed value is 0.01. Faster Payments amount format is numeric 14,2 (readable
version is 999,999,999,999.99). Data type: Numeric 14,2
Presence: Mandatory field.
3.3.4.2 currency Definition: Field currency contains the currency associated to the instructedAmount. Usage: Field currency is defaulted to “GBP”.
Valid active currency codes are registered with the ISO 4217 Maintenance Agency, consist of 3
contiguous letters.
Data type: String of 3 characters.
Presence: Mandatory field.
3.3.5 transactionId Definition: Field transactionId captures any type of confirmation code returned by the payer's bank or
payment portal in the payment response to the payer to identify the payment instruction submitted by the payer.
- 35 -
- 35 -
Usage: N/A
Data type: String of maximum 35 characters.
Presence: Optional field.
3.3.6 acceptanceDateTime
Definition: Field acceptanceDateTime specifies the transaction date returned by the payer’s payments service provider on submission of a payment transaction by the payer.
As per ISO20022 message Standards definition, this field carries the following data: “Point in time
when the payment order from the initiating party (i.e. payer) meets the processing conditions of the
account servicing agent (i.e. payer’s payments service provider). This means that the account servicing
agent (i.e. payer’s payments service provider) has received the payment order and has applied checks such as authorisation, availability of funds.”
Usage: Good practice is to display acceptanceDateTime to the payer in format DD-MM-YYYY hh:mm:ss
(payer’s local time) or in a similar format.
Data type: ISODateTime 8601, format YYYY-MM-DDTHH:MM:SSZ. Presence: Optional field.
3.3.7 transactionStatus
Definition: Field transactionStatus contains the payment status as returned by the payer's bank or
payment vehicle.
Usage: Only successful transaction should be passed on to the biller in PayAll or PayPartial messages. Where payments made by the payer are executed via transfer or a portal, the transaction status returned by the payer’s PISP can have one of the following values (non-exhaustive list):
ACCC – AcceptedSettlementCompleted, ACSC – AcceptedSettlementCompleted,
ACSP – AcceptedSettlementInProcess, APPR – Approved.
This list of values for transactionStatus is defined as per the ISO20022 Code Set
ExternalPaymentTransactionStatus1Code for PISP payments.
Data type: String of maximum 4 characters. Presence: Optional field.
3.3.8 additionalInformation
Definition: Field additionalInformation contains additional information in free text form to complement the transaction status. Usage: If the payer’s PISP either returns any other status than listed in section 3.3.7 transactionStatus
or provides additional information, that information should be populated in the additionalInformation field.
- 36 -
- 36 -
Data type: String of maximum 140 characters.
Presence: Optional field.
3.4 rqtp.003 Requested Payment Extension Message Body The Request to Pay framework provides the payer with the flexibility to ask the biller for an extension
of the payment due date. In such circumstances the payer can respond to the biller’s RequestPayment message with a ReqPayExtension message.
The messageBody object contains the following elements.
Field Name Field Description M/O Data Type
messageType This is the message type populated with
“ReqPayExtension” for rqtp.003.
M Max 35 chars
endToEndIdentification This is a unique identifier provided by the biller.
M Max 35 chars
requestedExtensionDate This is the new date requested by the payer to the biller by which payer intends
to make payments towards the biller’s request.
M Date
additionalInformation This is additional information in free text form for the payer to complement their requested payment extension.
O Max 140 chars
3.4.1 messageType
Definition: Field messageType indicates the specific type of message when profile is populated with
“requestToPay”. Usage: messageType must be populated with “ReqPayExtension” for message rqtp.003.
Data type: String of maximum 35 characters.
Presence: Mandatory field.
3.4.2 endToEndIdentification Definition: Field endToEndIdentification is an identifier generated by the biller, which can be used for
reconciliation purpose and to link a payment to the original bill (defined as per ISO 20022 message
Standards). Usage: Refer to the field usage in section 3.2.2 endToEndIdentification.
Data type: String of maximum 35 characters. Presence: Mandatory field.
3.4.3 requestedExtensionDate Definition: Field requestedExtensionDate is the new due date requested by the payer to the biller.
- 37 -
- 37 -
Usage: It is the date-time of the extended due date requested and not the number of days of extension. Good practice is to display requestedExtensionDate to the biller in format DD-MM-YYYY or in
a similar format.
Data type: ISODateTime 8601, format YYYY-MM-DDTHH:MM:SSZ. Presence: Mandatory field.
3.4.4 additionalInformation
Definition: Field additionalInformation contains additional information in free text form should the payer wish to complement their payment extension request to the biller.
Usage: N/A
Data type: String of maximum 140 characters. Presence: Optional field.
3.5 rqtp.004 Extension Response Message Body The Request to Pay framework allows the biller to either accept or decline a payer’s request for
extension of payment due date. Whether the biller decides to approve or decline the payer’s ReqPayExtension message, the biller can respond to the payer with the ExtensionResponse message
with either “ExtensionGranted” or “ExtensionDeclined” values. Note
It is the competitive space for the biller to decide on a case by case basis the length of extension they
would grant to a specific payer as well as under what circumstances they would decline an extension request from a payer.
The messageBody object contains the following elements.
Field Name Field Description M/O Data Type
messageType This is the message type populated with either “ExtensionGranted” or
“ExtensionDeclined” for rqtp.004.
M Max 35 chars
endToEndIdentification This is a unique identifier provided by the
biller.
M Max 35 chars
referenceMessageId This field contains messageId of rqtp.003
Requested Payment Extension message.
M Max 105
chars
additionalInformation This is additional information in free text form for the biller to complement their
response to the payer’s requested payment extension.
O Max 140 chars
- 38 -
- 38 -
3.5.1 messageType Definition: Field messageType indicates the specific type of message when profile is populated with “requestToPay”.
Usage: messageType must be populated with either “ExtensionGranted” or “ExtensionDeclined” for message rqtp.004.
Data type: String of maximum 35 characters. Presence: Mandatory field.
3.5.2 endToEndIdentification Definition: Field endToEndIdentification is an identifier generated by the biller, which can be used for
reconciliation purpose and to link a payment to the original bill (defined as per ISO 20022 message
Standards). Usage: Refer to the field usage in section 3.2.2 endToEndIdentification.
Data type: String of maximum 35 characters.
Presence: Mandatory field.
3.5.3 referenceMessageId Definition: Field referenceMessageId contains a copy of messageId from the rqtp.003 Requested Payment Extension message in order to identify which message this Extension Response relates to.
Usage: N/A
Data type: String of maximum 105 characters. Presence: Mandatory field.
3.5.4 additionalInformation
Definition: Field additionalInformation contains additional information in free text form should the biller wish to complement their response to the payer’s extension request.
Usage: N/A
Data type: String of maximum 140 characters.
Presence: Optional field.
3.6 rqtp.005 Decline Message Body
- 39 -
- 39 -
The Request to Pay framework offers to the payer the options:
To decline a biller’s RequestToPay message for a specific payment by responding with a Decline message,
To block payment requests from the biller.
The messageBody object contains the following elements.
Field Name Field Description M/O Data Type
messageType This is the message type populated with “Decline” or “DeclineBlock” for rqtp.005.
M Max 35 chars
endToEndIdentification This is a unique identifier provided by the biller.
M Max 35 chars
3.6.1 messageType Definition: Field messageType indicates the specific type of message when profile is populated with
“requestToPay”.
Usage: messageType must be populated with “Decline” to decline the initial RequestToPay sent by the Biller.
If the payer does not want to receive any further request from a specific biller, the payer must reply with messageType populated with “DeclineBlock”. The payer will not receive any future request from the biller until the block is lifted by the payer.
Note that a declineBlock must also update the Authorisation Request status for the sender and receiver to blocked as well
Data type: String of maximum 35 characters.
Presence: Mandatory field.
3.6.2 endToEndIdentification
Definition: Field endToEndIdentification is an identifier generated by the biller, which can be used for
reconciliation purpose and to link a payment to the original bill (defined as per ISO 20022 message Standards).
Usage: Refer to the field usage in section 3.2.2 endToEndIdentification.
Data type: String of maximum 35 characters. Presence: Mandatory field.
3.7 rqtp.006 Note Message Body The Request to Pay framework provides end users with the opportunity to engage in a conversation
with each other, the payer to the biller and vice versa.
If a payer requires further information on a biller’s RequestToPay message before either making the payment or declining the request, the payer can send a NoteToBiller message to the biller.
If a biller wants to provide further information following their RequestToPay message or a
payer’s NoteToBiller message, the biller can send a NoteToPayer message to the payer.
- 40 -
- 40 -
The messageBody object contains the following elements.
Field Name Field Description M/O Data Type
messageType This is the message type populated with “NoteToBiller” or “NoteToPayer” for
rqtp.006.
M Max 35 chars
endToEndIdentification This is a unique identifier provided by the biller.
M Max 35 chars
note This contains the text exchanged between payer and biller.
M Max 300 chars
3.7.1 messageType Definition: Field messageType indicates the specific type of message when profile is populated with
“requestToPay”. Usage: messageType must be populated with “NoteToBiller” or “NoteToPayer” for message rqtp.006.
Data type: String of maximum 35 characters. Presence: Mandatory field.
3.7.2 endToEndIdentification
Definition: Field endToEndIdentification is an identifier generated by the biller, which can be used for
reconciliation purpose and to link a payment to the original bill (defined as per ISO 20022 message
Standards).
Usage: Refer to the field usage in section 3.2.2 endToEndIdentification.
Data type: String of maximum 35 characters. Presence: Mandatory field.
3.7.3 note Definition: This contains the text exchanged between payer and biller.
Usage: Field note is sent:
By the biller to the payer when messageType is populated with “NoteToPayer”, By the payer to the biller when messageType is populated with “NoteToBiller”.
Data type: String of maximum 300 characters. Presence: Mandatory field.
3.8 rqtp.007 Acknowledge in Full Message Body
- 41 -
- 41 -
AcknowledgeInFull message can be sent by the biller to acknowledge they have received the full due
payment requested to the payer.
Full payment was received by the biller: Through a one-off payment or a series of payments through the Request to Pay communication
channel via either rqtp.002 PayAll or PayPartial messages, As well as through external payment methods such as cash2 for example.
The messageBody object contains the following elements.
Field Name Field Description M/O Data Type
messageType This is the message type populated with “AcknowledgeInFull” for rqtp.007.
M Max 35 chars
endToEndIdentification This is a unique identifier provided by the
biller.
M Max 35 chars
3.8.1 messageType Definition: Field messageType indicates the specific type of message when profile is populated with “requestToPay”.
Usage: messageType must be populated with “AcknowledgeInFull” for message rqtp.008.
Data type: String of maximum 35 characters. Presence: Mandatory field.
3.8.2 endToEndIdentification Definition: Field endToEndIdentification is an identifier generated by the biller, which can be used for
reconciliation purpose and to link a payment to the original bill (defined as per ISO 20022 message Standards).
Usage: Refer to the field usage in section 3.2.2 endToEndIdentification.
Data type: String of maximum 35 characters. Presence: Mandatory field.
3.9 rqtp.008 Acknowledge Payment Message Body
AcknowledgePayment message can be sent by the biller to acknowledge each payment they received from the payer, independently of whether the received amount is under, equal or above of the due
amount.
Payment can be done by the payer:
Through the Request to Pay communication channel via either rqtp.002 PayAll or PayPartial messages,
2 Note that payment by cash can be acknowledged by the biller via an rqtp.008 Acknowledge Payment message
described in this document.
- 42 -
- 42 -
Or outside of the Request to Pay communication channel, i.e. electronic or non-electronic funds.
The messageBody object contains the following elements.
Field Name Field Description M/O Data Type
messageType This is the message type populated with
“AcknowledgePayment” for rqtp.008.
M Max 35 chars
endToEndIdentification This is a unique identifier provided by the biller.
M Max 35 chars
amount This represents the amount acknowledged by the biller as paid by the payer.
M Object
3.9.1 messageType Definition: Field messageType indicates the specific type of message when profile is populated with
“requestToPay”. Usage: messageType must be populated with “AcknowledgePayment” for message rqtp.008.
Data type: String of maximum 35 characters. Presence: Mandatory field.
3.9.2 endToEndIdentification
Definition: Field endToEndIdentification is an identifier generated by the biller, which can be used for
reconciliation purpose and to link a payment to the original bill (defined as per ISO 20022 message
Standards).
Usage: Refer to the field usage in section 3.2.2 endToEndIdentification.
Data type: String of maximum 35 characters. Presence: Mandatory field.
3.9.3 amount The amount object contains the following elements.
Field Name Field Description M/O Data Type
paidAmount This is the amount acknowledged as paid
by the biller when a payment from the payer has been reconciled.
M Numeric 14,2
currency This is the currency of the amount paid. M 3 chars
3.9.3.1 paidAmount Definition: Field paidAmount indicates the payment amount paid by the payer to the biller.
- 43 -
- 43 -
Usage: Minimum allowed value is 0.01. Faster Payments amount format is numeric 14,2 (readable
version is 999,999,999,999.99).
Data type: Numeric 14,2 Presence: Mandatory field.
3.9.3.2 currency Definition: Field currency contains the currency associated to paidAmount.
Usage: Field currency is defaulted to “GBP”. Valid active currency codes are registered with the ISO 4217 Maintenance Agency, consist of 3
contiguous letters.
Data type: String of 3 characters. Presence: Mandatory field.
4. Simple Message
Simple Message is a communication mechanism that allows two end users (government, business, charity and consumer) to communicate via messages sent to each other. These messages are independent from the Request to Pay framework.
4.1 messageBody
The messageBody object contains the following elements.
Field Name Field Description M/O Data Type
messageBody This contains text exchanged by end users. M Max 65536
chars
4.1.1 messageBody
Definition: Field messageBody contains plain text exchanged between end users.
Usage: Used when the field profile in threadHeader is populated with “simpleMessage” and when the
errorBody object is not present. Data type: String of maximum 65536 characters. Presence: Mandatory field.
5. Request to Pay Business Processes
This section describes the Business Processes and underlying message set for the Request to Pay framework.
- 44 -
- 44 -
The section sets: The Business Process scope (business processes addressed or impacted by the project),
The Business Roles involved in these Business Processes.
- 45 -
5.1 Request to Pay communication messages
The table below summarises the Request to Pay message types along with typical response options as well as originator and receiver of the
messages and responses.
Message type Originator Description Typical response Allowed customer
responses
RequestToPay Biller First message of every request thread, sent from biller to payer.
PayAll PayPartial
Decline DeclineBlock
ReqPayExtension NoteToBiller
No response at all
PayAll Payer Pay the entire outstanding amount on a request. If payment is successful then the request is closed.
AcknowledgeInFull NoteToPayer No response at all
PayPartial Payer Pay a portion of the total amount of a request. The request is not closed until full amount or more is paid.
AcknowledgePayment
NoteToPayer
No response at all
ReqPayExtension Payer Suggest a new “due date” in the future. Biller then must grant or decline the extension. Payer cannot request another extension until previous has been granted or declined.
ExtensionGranted ExtensionDeclined
NoteToPayer No response at all
Decline Payer Decline the request. NoteToPayer No response at all
DeclineBlock Payer Decline the request and block the biller. Payer will no longer receive requests from this biller until block is lifted.
NoteToBiller Payer Send a message to the biller or request further information. NoteToPayer
No response at all
NoteToPayer Biller Send a message to the payer or request further information. NoteToBiller
No response at all
ExtensionGranted Biller Grant the extension amendment.
ExtensionDeclined Biller Decline the extension amendment.
- 46 -
Message type Originator Description Typical response Allowed customer
responses
AcknowledgeInFull Biller Biller’s response when a request is paid in full.
AcknowledgePayment Biller Biller’s response when a payment made for a request outside
Request to Pay communication channel.
- 47 -
-
5.2 Business Roles and Participants
Description Definition
Business Role A Business Role represents an entity (or a class of entities) of
the real world, physical or legal, a person, a group of persons, a corporation. Examples of Business Roles: “Consumer”, “Business”, “Financial Institution”, “App Developer”.
Participant A Participant is a functional role performed by a Business Role in a particular Business Process or Business Transaction: for example the “user” of a system, a “biller”, a
“payer”, etc.
5.2.1 Business Roles and Participants definitions The relationship between Business Roles and Participants is many-to-many. One Business Role
(that is, a person) can be involved as different Participants at different moments in time or at the
same time: "user", "biller”, "payer", etc. Different Business Roles can be involved as the same
Participant.
In the context of Request to Pay the high-level Business Roles and typical Participants can be
represented as follows.
Business Roles
Description Definition
Request to Pay End User Entity involved in initiating or receiving Request to Pay
messages.
Repository Provider Organisation enabling storing and exchange of Request to Pay messages.
Application Provider Organisation providing front-end application to send and retrieve messages.
Payments Service Provider (PSP) Organisation established primarily to provide payments services.
Participants
Description Definition
Biller Entity that creates a Request to Pay for a service provided to a payer.
Payer Entity that consumes a service from a biller and is required
to make payment against that.
Biller’s Application Provider Entity that offers a front-end channel for biller to send and receive Request to Pay messages and request payments
Payer’s Application Provider Entity that offers a front-end channel for payer to send and receive Request to Pay messages and make payments. Payer’s Application Provider must offer all Request to Pay
- 48 -
-
Description Definition
response options (Pay all, Pay partial, Request extension,
Decline, Contact biller).
Biller’s Repository Provider Entity that plays a role in storing and forwarding Request to Pay messages of a biller.
Payer’s Repository Provider Entity that plays a role in storing and forwarding Request to Pay messages of a payer.
Biller’s PSP Biller’s financial institution.
Payer’s PSP Payer’s financial institution.
5.2.2 Business Roles and Participants table
Participants Request to
Pay End User
Repository Provider
Application Provider
Payment
Service Provider (PSP)
Biller X
Payer X
Biller’s Application Provider X
Payer’s Application Provider X
Biller’s Repository Provider X
Payer’s Repository Provider X
Biller’s PSP X
Payer’s PSP X
5.3 Business Processes and Business Activities
5.3.1 Business Process and Business Activities definitions
The main objectives of this section are: To explain what Business Processes and Business Activities these Message Specifications
have addressed,
To give a high-level description of Business Processes and the associated Business Roles.
Description Definition
Business Process Unrealised definition of the business activities undertaken
by Business Roles within a Business Area whereby each
Business Process fulfils one type of business activity and whereby a Business Process may include and extend other
Business Processes.
5.3.2 Business Processes description
# Process Name Description
1 Create and send Request to Pay
The process of generating a new Request to Pay message or creating a response message and sending it. This process is similar
- 49 -
-
# Process Name Description
messages for Payer and Biller.
2 Validate message The process of verifying message formats, message security and business rules by Payer’s or Biller’s Repository Provider.
3 Receive Request to Pay
messages
The process of receiving a Request to Pay message or response
messages from another user. This process is similar for Payer and Biller.
4 Retrieve messages The process of retrieving Request to Pay messages from one’s message store. This process is similar for Payer and Biller.
5 Respond to request The mechanism of responding to a request. This process is similar for Payer and Biller.
6 Request extension The process of requesting extension of payment due date by Payer
and subsequent response by Biller.
7 Make payment The process of initiating a payment against a request by the Payer to the Biller.
8 Decline and/or block Biller
The process for Payer to decline a Request to Pay from Biller and block it.
9 Update request status The process of updating or closing a request based on responses received from recipient.
Note that the following processes are out of scope of this document: Onboarding end users,
Payments execution, Reconciliation.
5.3.3 Business Activities description
This section presents the different Business Activities within each Business Process. The Business
Activities of a process are described with activity diagrams.
5.3.3.1 E2E process for sending and receiving Request to Pay message
The diagram below illustrates the sequences of business activities to be performed when a Biller
creates and sends a Request to Pay message to a Payer. The business processes remain same when
the Payer creates and sends a response to the Biller.
- 50 -
-
Figure 1 E2E process for sending and receiving Request to Pay message
The key business processes for sending and receiving Request to Pay message are:
# Process Name Description
1 Create and send
Request to Pay
messages
The process of generating a new Request to Pay message or creating
a response message and sending it. This process is similar for Payer
and Biller.
2 Validate message The process of verifying message formats, message security and
business rules by Payer’s or Biller’s Repository Provider.
3 Receive Request to Pay
messages
The process of receiving a Request to Pay message or response
messages from another user. This process is similar for Payer and Biller.
5.3.3.1.1 Process Overview - Create and send Request to Pay message
Step Description Initiator
Create message The Biller prepares the outgoing Request to Pay message.
Biller
Send message The Biller submits outgoing Request to
Pay message to its Biller’s Repository Provider.
Biller
Validate message Business Process is same than Validate
message.
Biller’s Repository
Provider
Store message If all validations and verifications are successful, the Biller’s Repository
Provider saves a copy of the Request to Pay message in the Biller’s message
box.
Biller’s Repository Provider
Forward message If all validations and verifications are
successful, the Biller’s Repository Provider forwards the message to the
Payer’s Repository Provider.
Biller’s Repository
Provider
- 51 -
-
5.3.3.1.2 Process Overview – Validate message
Step Description Initiator
Message technical validation
Biller’s Repository Provider performs technical validation of the submitted message.
Biller’s Repository Provider
Message integrity
verification
Biller’s Repository Provider performs
integrity checks on the submitted message.
Biller’s Repository
Provider
Business validation Biller’s Repository Provider may apply additional validation (such as on-
boarded biller’s payment options) to check if the message is within arrangements agreed with the user.
Biller’s Repository Provider
Accept message If all validations and verifications are successful, the Biller’s Repository
Provider accepts the message.
Biller’s Repository Provider
Reject message If any validation or verification fails, the
Biller’s Repository Provider rejects the
request.
Biller’s Repository
Provider
5.3.3.1.3 Process Overview – Receive Request to Pay message
Step Description Initiator
Receive message The Payer’s Repository Provider receives Request to Pay messages sent
by a Biller’s Repository Provider.
Payer’s Repository Provider
Validate message Business Process is same than Validate message.
Payer’s Repository Provider
Store message If the validations and verifications are
successful, the Payer’s Repository Provider stores a copy of the Request to
Pay message in the Payer’s message
box.
Payer’s Repository
Provider
Error notification The Payer’s Repository Provider sends a
notification to the Biller’s Repository
Provider in case it rejects a request.
Payer’s Repository
Provider
Note that this business process is also applicable when the Biller receives a message from the Payer.
- 52 -
-
5.3.3.2 E2E process for responding to Request to Pay message
Figure 2 E2E process for responding to Request to Pay message
Note that the processes outlined above show the business activities that need to be performed to
respond to Request to Pay messages. Depending on the specific type of Request to Pay response
option selected by the user, additional steps may be required to be performed.
The key business processes for sending and receiving Request to Pay messages are:
# Process Name Description
4 Retrieve messages The process of retrieving Request to Pay messages from one’s
message store. This process is similar for Payer and Biller.
5 Respond to request The mechanism of responding to a Request to Pay. This process is similar for Payer and Biller.
5.3.3.2.1 Process Overview – Retrieve message
Step Description Initiator
Request access Payer accesses its Request to Pay messages from its Payer’s Repository
Provider.
Payer
Authenticate user Payer’s Repository Provider authenticates Payer.
Payer’s Repository Provider
Reject access request If authentication is unsuccessful Payer’s
Repository Provider rejects Payer’s access request.
Payer’s Repository
Provider
Accept access request If authentication is successful, Payer’s
Repository Provider accepts Payer’s access the request.
Payer’s Repository
Provider
Retrieve messages Payer’s Repository Provider retrieves messages.
Payer’s Repository Provider
Note that this business process is also applicable when the Biller retrieves a message.
- 53 -
-
5.3.3.2.2 Process Overview – Respond to request
Step Description Initiator
Retrieve messages Business Process is same than Retrieve
message.
Payer’s Repository
Provider
Create response message Payer prepares response message using
Request to Pay response options.
Payer
Send message The Payer submits response message to its Payer’s Repository Provider.
Payer
Validate message Business Process is same Validate message.
Payer’s Repository Provider
Store response message If all validations and verifications are
successful, the Payer’s Repository Provider saves a copy of the response in the Payer’s message box.
Payer’s Repository
Provider
Forward response message
If all validations and verifications are successful, the Payer’s Repository Provider will forward the message to the
Biller’s Repository Provider.
Payer’s Repository Provider
5.3.3.3 E2E process for response option – Request extension
Figure 3 E2E process - Request extension
# Process Name Description
6 Request extension The process of requesting an extension of the due date for payment
by the Payer.
- 54 -
-
5.3.3.3.1 Process Overview – Request extension
As a prerequisite, the Payer must have received and successfully retrieved a Request to Pay.
Step Description Initiator
Send extension request Payer prepares a request extension message using Request to Pay option.
Payer
Validate message Business Process is same Validate
message.
Biller’s Repository
Provider
Forward extension
request message
If all validations and verifications are
successful, the Payer’s Repository
Provider forwards the message to the
recipient.
Payer’s Repository
Provider
Store extension request message
Payer’s Repository Provider saves a copy of the extension request in the
Payer’s message box.
Payer’s Repository Provider
Receive extension request
message
Biller’s Repository Provider receives
Payer’s extension request. Business Process is same than Receive Request to
Pay message.
Biller’s Repository
Provider
Retrieve extension request Biller retrieves the extension request from its Biller’s Repository Provider.
Business Process is same than Retrieve
message.
Biller
Apply business rules Biller may validate Payer’s previous payments behaviour and apply business logics for extension.
Biller
Approve extension Biller may approve Payer’s extension request depending on business logic.
Biller
Decline extension Biller may decline Payer’s extension
request depending on business logic.
Biller
Send response message Biller notifies Payer of the outcome. Biller
Update request status Biller updates request status (same
business process than Update request
status.
Biller
- 55 -
-
5.3.3.4 E2E processes for response option – Make payment (PayAll and PayPartial)
Figure 4 E2E process for Make Payment
# Process Name Description
7 Make payment The process of initiating payment through a PSP by the Payer.
5.3.3.4.1 Process Overview – Make payment through PSP
As a prerequisite, the Payer must have received and successfully retrieved a Request to Pay.
Step Description Initiator
Prepare payment message Payer prepares a payment message to biller using Request to Pay options: PayAll or PayPartial.
Payer
Initiate payment Payer initiates payments3. Payer’s Application
Provider
Send payment message Payer’s Repository Provider forwards Payer’s payment message to Biller.
Payer’s Repository Provider
Receive payment message Biller’s Repository Provider receives
Payer’s payment message. Business Process is same than Receive Request to
Pay message.
Biller’s Repository
Provider
Retrieve payment message
Biller retrieves payment message from its Biller’s Repository Provider. Business
Process is same than Retrieve message.
Biller
Apply computation Biller calculates total payments made by the Payer towards the Request to
Pay.
Biller
3 The process of making and settling payment takes place outside of the boundaries of the Request to Pay communication
mechanism and is therefore not elaborated here.
- 56 -
-
Step Description Initiator
Update request status Biller updates request status (business
process same as Update request status.
Biller
5.3.3.5 E2E processes for response option – Decline Request to Pay and
block Biller (Decline and DeclineBlock)
Figure 5 E2E process - Decline a request and block a Biller
# Process Name Description
8 Decline Request to Pay The process of declining a Request to Pay by the Payer.
9 Block Biller The process of declining a Request to Pay, as well as blocking all future incoming Request to Pay from this Biller, by the Payer.
5.3.3.5.1 Process Overview – Decline Request to Pay
As a prerequisite, the Payer must have received and successfully retrieved a Request to Pay.
Step Description Initiator
Decline request Payer prepares a Decline message. Payer
Validate decline message Business Process is same than Validate message.
Payer’s Repository Provider
Forward message If all validations and verifications are
successful, the Payer’s Repository Provider forwards the message to the
Biller’s Repository Provider.
Payer’s Repository
Provider
Store message Payer’s Repository Provider saves a copy of the decline message in the
Payer’s message box.
Payer’s Repository Provider
5.3.3.5.2 Process Overview – Block Biller
As a prerequisite, the Payer must have received and successfully retrieved a Request to Pay.
Step Description Initiator
Decline request Payer prepares a DeclineBlock message. Payer
Validate decline message Business Process is same than Validate message.
Payer’s Repository Provider
- 57 -
-
Step Description Initiator
Perform blocking checks Payer’s Repository Provider performs
business validations for blocking Biller.
Payer’s Repository
Provider
Block biller If Payer requests a block4 on Biller,
Payer’s Repository Provider will update accordingly.
Payer’s Repository
Provider
Forward message If all validations and verifications are
successful, the Payer’s Repository Provider forwards the message to the Biller’s Repository Provider.
Payer’s Repository
Provider
Store message Payer’s Repository Provider saves a copy of the decline message in the
Payer’s message box.
Payer’s Repository Provider
5.3.3.6 E2E process for updating request status
Figure 6 E2E process for update request status
# Process Name Description
10 Update request status The process of updating or closing a request by the Biller, depending on responses received from the Payer.
5.3.3.6.1 Process Overview – Update request status
Step Description Initiator
Retrieve message Business Process is same than Retrieve message.
Biller
Apply computation Biller calculates total payments made
by the Payer towards Request to Pay.
Biller
Close request If all outstanding payments are settled, Biller
4 Future messages sent by the Biller to the Payer will be rejected with an error delivery message sent to the Biller with
error 003 “SenderIsBlocked” (refer to section 2.1.4.5 Errors description). Note that Payer can unblock the Biller with the
Block/Unblock option via its Payer’s Application Provider.
- 58 -
-
Step Description Initiator
Biller closes the Request to Pay.
Send acknowledgement If a Request to Pay is successfully closed, Biller sends an
acknowledgement message to Payer. Business Process is same Create and
send Request to Pay message.
Biller
Compute outstanding amount
In case Payer makes partial payment, Biller will compute new outstanding amount to internally update the
request.
Biller
Provide information Biller can prepare information if
requested by Payer.
Biller
Apply business rules Biller applies business rules to deal with declined or un-responded requests.
Biller
Update request Biller updates Request to Pay status
depending on the outcome of the
business validation.
Biller
Send response Biller submits outgoing response message to its Biller’s Repository
Provider. Business Process is same than Create and send Request to Pay
message.
Biller
5.4 Business Transactions
5.4.1 Business Transactions definitions
The main objective of this section is to document the Business Transactions and their Participants (sequence diagrams).
Description Definition
Business Transaction Particular solution that meets the communication
requirements and the interaction requirements of a
particular Business Process and Business Area.
Message Definition Formal description of the structure of a Message Instance.
The following Request to Pay Business Transactions show how Biller and Payer interact using Request to Pay communication channel. These Business Transactions scenarios illustrate some
typical responses without being an exhaustive list. They are supported by exchanges of Request to Pay messages as described in this document.
- 59 -
-
5.4.2 Payer makes full payment to a Request to Pay
Messages exchanged:
Message Name Message Identifier
RequestToPay rqtp.001
PayAll rqtp.002
AcknowledgeInFull rqtp.007
Figure 7 Payer makes full payment towards Request to Pay
5.4.3 Payer makes partial payments to a Request to Pay
Messages exchanged:
Message Name Message Identifier
RequestToPay rqtp.001
PayPartial rqtp.002
Figure 8 Payer makes partial payments towards Request to Pay
5.4.4 Payer asks for extension Messages exchanged:
Message Name Message Identifier
RequestToPay rqtp.001
ReqPayExtension rqtp.003
- 60 -
-
Message Name Message Identifier
ExtensionGranted rqtp.004
ExtensionDeclined rqtp.004
Figure 9 Biller approves Payer's request for extension
Figure 10 Biller declines Payer's request for extension
5.4.5 Payer declines Messages exchanged:
Message Name Message Identifier
RequestToPay rqtp.001
Decline rqtp.005
DeclineBlock rqtp.005
- 61 -
-
Figure 11 Payer declines a Request to Pay
Figure 12 Payer blocks a Biller
5.4.6 Payer & Biller exchange information on a Request to Pay Messages exchanged:
Message Name Message Identifier
RequestToPay rqtp.001
NoteToBiller rqtp.006
NoteToPayer rqtp.006
- 63 -
-
6. Pre-Authorisation Messages
In addition to the RtP messages outlined earlier in this document, the Request to Pay solution
requires a mechanism by which the Payer can agree in advance to accept RtP requests from a specific Biller before a RtP message can be sent from that Biller to the Payer. This Pre-Authorisation process will rely on a standard definition for Pre-Authorisation Messages that will need to be exchanged between the Biller and Payer to ensure consistency. The flow of messages also requires
definition between the biller’s application and repository, biller and payer repositories and between the payer’s repository and application in both directions of message flow. This section covers those definitions.
6.1 Pre-Authorisation Message (PAM) definition
This section contains the definitions of the Pre-Authorisation Message (PAM) API’s. PAM messages
are required to be passed from application to repository on both the biller and payer side and also between the repositories themselves. The point at which each of these API’s will be invoked will depend upon the context of the PAM message exchange.
There are 11 API’s defined, 6 covering application to repository data exchange, and 5 covering
repository to repository data exchange. The API’s for these are as follows:
Application to Repository API’s:
Ref Name Initiator
AR1 Request for Authorisation (POST) Billers App Operator
AR2 Retrieve Authorisations Requests (GET) Biller and Payer App Operator
AR3 Retrieve Single Authorisation Request (GET) Biller and Payer App Operator
AR4 Update Authorisation (PATCH) Payer App Operator
AR5 Request for More Info (POST) Payer App Operator
AR6 Update with More Info (PATCH) Biller App Operator
Repository to Repository API’s:
Ref Name Initiator
RR1 Request for Authorisation (POST) Biller Repository Provider
RR2 Update Authorisation (PUT) Payer Repository Provider
RR3 Request for More Info (POST) Payer Repository Provider
RR4 Update with More Info (PATCH) Biller Repository Provider
RR5 Sync Authorisations (POST) Biller and Payer Repository Provider
- 64 -
-
6.1.1 Application to Repository API’s These API’s will be called by the Application that interacts with the Repository.
6.1.1.1 AR1 - Request for Authorisation POST /user/authorisation-requests/
This ‘POST’ API will be called by the Billers Application Provider to the Billers Repository Provider. It represents the initiation of the process to establish the Pre-Authorisation agreement between biller and payer.
6.1.1.1.1 Authorization
Definition: The field Authorization must contain the token of the authorized user that initiated this PAM message.
Usage: The format of Authorization is bearer <token> where:
bearer – prefix the token type,
<token> is the generated authorisation token,
Data type: String
Presence: Mandatory field.
5 M/O stands for Mandatory or Optional fields.
Header/Body Field Name Field Description
M/
O5
Data
Type
Header Authorization The token of the authorised user M String
Body
pamId This is the unique id of the PAM request
originating from the biller application
M Max 1024
chars
Body requestMessage This contains an optional message to
accompany the authorisation request
O Max 300
chars
Body billerName This contains the name of the biller initiating the request
M Max 70 chars
Body billerId This contains the Pid of the biller from which
the PAM request is being sent
M Max 300
chars
Body payerId This contains the Pid of the payer to which
the PAM request is being sent with whom they are wishing to authorise with
M Max 300
chars
Body status This contains the status, which in all cases
when the initial message is sent will have ‘requested’ as the initial setting
M Max 15
chars
- 65 -
-
6.1.1.1.2 pamId
Definition: The field pamId is the unique id of the PAM request. This must be generated by the biller’s application and appears for the first time in this API call from the application to the biller
repository.
Usage: The format of pamId is PAM-timestamp_nano-64_bitsrandom, where:
PAM – prefix for PAM messaging, timestamp_nano is the epoch time in nanoseconds, 64_bitsrandom is a BASE64-encoded value.
Data type: String of maximum 1024 chars
Presence: Mandatory field.
6.1.1.1.3 requestMessage
Definition: The field requestMessage can contain an optional message to accompany the authorisation request.
Usage: N/A
Data type: String of maximum 300 characters.
Presence: Optional field.
6.1.1.1.4 billerName Definition: The field billerName must contain the name of the biller initiating the request.
Usage: N/A
Data type: String of maximum 70 characters.
Presence: Mandatory field.
6.1.1.1.5 billerId
Definition: The field billerId must contain the pid of the biller from where the PAM request
originated.
Usage: This field must be lowercase.
Data type: String of maximum 300 characters.
Presence: Mandatory field.
6.1.1.1.6 payerId
- 66 -
-
Definition: The field payerId must contain the pid of the payer to which the PAM request is being sent, i.e. with whom they are wishing to create an agreement to bill with.
Usage: This field must be in lowercase.
Data type: String of maximum 300 characters.
Presence: Mandatory field.
6.1.1.1.7 status Definition: The field status must contain the status of the PAM request, which in the initial case will
be populated with the value of ‘requested’
Usage: requested
Data type: String of maximum 15 chars.
Presence: Mandatory field.
6.1.1.2 AR2 – Retrieve Authorisation Requests
GET /user/authorisation-requests/
This ‘GET’ API can be called by both the billers Application Provider to the billers Repository Provider and by the payers Application Provider to the payers Repository Provider. The context of use will be where the app on either side of the relationship wishes to retrieve the current status of
PAM entries in the associated repository data store.
Note: This will only return records relevant to the user.
- 67 -
-
6.1.1.2.1 Authorization
Definition: The field Authorization must contain the token of the authorised user that initiated this API call.
Usage: The format of Authorization is bearer <token> where:
bearer – prefix the token type, <token> is the generated authorisation token,
Data type: String
Presence: Mandatory field.
6.1.1.2.2 role
Definition: The field role can be used to filter the PAM records based on biller or sender. For
example, a user may have records in the PAM data store where they are both either biller or payer, but may only wish to retrieve the records where their role is biller only.
Usage: Three options can be used for role field:
Field role populated with ‘biller’. Response will only include PAM records where the user is the biller.
Field role populated with ‘payer’. Response will only include PAM records where the user is the payer.
Field is left blank. Response will not be filtered by any specific role.
Data type: String of maximum 6 chars
Presence: Optional field.
6.1.1.2.3 status
Definition: The field status can be used to filter the PAM records in the response that only have
entries with that status. For example, a user may have records in the PAM data store that are either
1 M/O stands for Mandatory or Optional fields.
Header/Body Field Name Field Description
M/O6
Data Type
Header Authorization The token of the authorized user M String
Header
role This is for specifying the role/s of the app
provider user that is submitting the request
O Max 6
chars
Header status This is for specifying the specific status of PAM records required in the response
O Max 15 chars
Header pid
This is for specifying a specific pid to filter the records returned in the response
O Max 300 Chars
- 68 -
-
Requested, Accepted or Denied and may wish to filter down the response to just those that are requested only.
Usage:
Field status is populated with ‘requested’. Response will only include PAM records where
the status is ‘requested’. Field status is populated with ‘accepted’. Response will only include PAM records where the
status is ‘accepted’. Field status is populated with ‘denied’. Response will only include PAM records where the
status is ‘denied’. Field status is left blank. Response will not be filtered by any specific status.
Data type: String of max 15 chars
Presence: Mandatory field.
6.1.1.2.4 pid Definition: The field pid can be used to filter the PAM records returned that contain the pid of the
opposing party.
Usage:
Field pid is populated with the user pid with whom the relationship is established. Response
will only include PAM records where the pid is populated in the PAM data store as either
Biller, Payer or both but in separate records. In this latter case, 2 records should be
returned.
Field pid is left blank. Response will not be filtered by any specific pid.
Data type: String of maximum 300 chars
Presence: Optional field.
6.1.1.3 AR3 – Retrieve Single Authorisation Request GET /user/authorisation-requests/{pamId}
This ‘GET’ API will be called by the app on the biller or payer side to its associated repository, to
respond with the current status of a single PAM entry. This will include the associated more
information messages.
1 M/O stands for Mandatory or Optional fields.
Header/Body Field Name Field Description
M/O7
Data Type
Header Authorization The token of the authorized user M String
Header
pamId This is the unique id of the original PAM request
M Max 1024 chars
- 69 -
-
6.1.1.3.1 Authorization
Definition: The field Authorization must contain the token of the authorised user that initiated this API call .
Usage: The format of Authorization is bearer <token> where:
bearer – prefix the token type, <token> is the generated authorisation token,
Data type: String
Presence: Mandatory field.
6.1.1.3.2 pamId
Definition: The field pamId is the unique id of the original PAM request to which the single request relates.
Usage: The format of pamId is PAM-timestamp_nano-64_bitsrandom, where:
PAM – prefix for PAM messaging, timestamp_nano is the epoch time in nanoseconds,
64_bitsrandom is a BASE64-encoded value.
Data type: String of maximum 1024 chars
Presence: Mandatory field.
6.1.1.4 AR4 – Update Authorisation PATCH /user/authorisation-requests/{pamId}
This ‘PATCH’ API will be called by the app on the payer side of the relationship to its associated repository, to update the status with either accepted or denied.
1 M/O stands for Mandatory or Optional fields.
Header/Body Field Name Field Description
M/O8
Data Type
Header Authorization The token of the authorized user M String
Header status The new status for which the status of the
PAM record will be updated.
M Max 15
chars
Header
pamId This is the unique id of the original PAM request
M Max 1024 chars
- 70 -
-
6.1.1.4.1 Authorization
Definition: The field Authorization must contain the token of the authorised user that initiated this API call.
Usage: The format of Authorization is bearer <token> where:
bearer – prefix the token type,
<token> is the generated authorisation token, Data type: String
Presence: Mandatory field.
6.1.1.4.2 status
Definition: The field status must contain the new status to be applied to the PAM record.
Usage:
Field status is populated with ‘accepted’. Used by the payer application to update the payer repository PAM entry with an accepted status.
Field status is populated with ‘denied’. Used by the payer application to update the payer repository PAM entry with a denied status.
Data type: Max 15 chars.
Presence: Mandatory field.
6.1.1.4.3 pamId
Definition: The field pamId is the unique id of the original PAM request to which the request for authorisation relates.
Usage: The format of pamId is PAM-timestamp_nano-64_bitsrandom, where:
PAM – prefix for PAM messaging,
timestamp_nano is the epoch time in nanoseconds, 64_bitsrandom is a BASE64-encoded value.
Data type: String of maximum 1024 chars
Presence: Mandatory field.
6.1.1.5 AR5 – Request for More Info
POST /user/authorisation-requests/{pamId}/moreInformation
- 71 -
-
This ‘POST’ API will be called by the app on the payer side of the relationship to its associated payer repository, to add a request for more information as to why the biller is seeking to establish Pre-Authorisation with the payer.
6.1.1.5.1 Authorization
Definition: The field Authorization must contain the token of the authorised user that initiated this API call.
Usage: The format of Authorization is bearer <token> where:
bearer – prefix the token type,
<token> is the generated authorisation token,
Data type: String
Presence: Mandatory field.
6.1.1.5.2 pamId
Definition: The field pamId is the unique id of the original PAM request to which the request relates.
Usage: The format of pamId is PAM-timestamp_nano-64_bitsrandom, where:
PAM – prefix for PAM messaging, timestamp_nano is the epoch time in nanoseconds,
64_bitsrandom is a BASE64-encoded value.
Data type: String of maximum 1024 chars
Presence: Mandatory field.
6.1.1.5.3 mimId
1 M/O stands for Mandatory or Optional fields.
Header/Body Field Name Field Description
M/
O9
Data
Type
Header Authorization The token of the authorized user M String
Header
pamId This is the unique id of the original PAM
request
M Max 1024
chars
Header mimId This is the unique id allocated to the request for more information message
M Max 1024 chars
Body moreInfoMessa
ge
This is the for the content of the message the
payer wishes to send when requesting more information from the biller
M Max 300
chars
- 72 -
-
Definition: The field mimId is the unique id of the request for more information message. This must be generated by the payer’s application and appears for the first time in this API call from the application to the payer repository.
Usage: The format of mimId is MSG-timestamp_nano-64_bitsrandom, where:
MSG – prefix for More information messages, timestamp_nano is the epoch time in nanoseconds, 64_bitsrandom is a BASE64-encoded value.
Data type: String of maximum 1024 chars
Presence: Mandatory field.
6.1.1.5.4 moreInfoMessage
Definition: The field moreInfoMessage must be used to contain the message the payer wishes to send when requesting more information from the biller.
Usage: N/A
Data type: String of maximum 300 chars
Presence: Mandatory field.
6.1.1.6 AR6 – Update with More Info (PATCH)
PATCH /user/authorisation-requests/{pamId}/moreInformation/{mimId}
This ‘PATCH’ API will be called by the app on the biller side of the relationship to its associated biller repository, to reply to a request for more information (AR5).
6.1.1.6.1 Authorization
Definition: The field Authorization must contain the token of the authorized user that initiated this API call.
1 M/O stands for Mandatory or Optional fields.
Header/Body Field Name Field Description
M/
O10
Data
Type
Header Authorization The token of the authorized user M String
Header
pamId This is the unique id of the original PAM
request
M Max 1024
chars
Header mimId This is the unique id allocated to the request for more information message
M Max 1024 chars
Body moreInfoReply This is the for the content of the message the biller wishes to send when replying to the request for more information from the biller
M Max 300 chars
- 73 -
-
Usage: The format of Authorization is bearer <token> where:
bearer – prefix the token type, <token> is the generated authorisation token,
Data type: String
Presence: Mandatory field.
6.1.1.6.2 pamId
Definition: The field pamId is the unique id of the original PAM request to which the single request
relates.
Usage: The format of pamId is PAM-timestamp_nano-64_bitsrandom, where:
PAM – prefix for PAM messaging, timestamp_nano is the epoch time in nanoseconds, 64_bitsrandom is a BASE64-encoded value.
Data type: String of maximum 1024 chars
Presence: Mandatory field.
6.1.1.6.3 mimId
Definition: The field mimId is the unique id of the original request for more information message.
Usage: The format of mimId is MSG-timestamp_nano-64_bitsrandom, where:
MSG – prefix for More information messages,
timestamp_nano is the epoch time in nanoseconds, 64_bitsrandom is a BASE64-encoded value.
Data type: String of maximum 1024 chars
Presence: Mandatory field.
6.1.1.6.4 moreInfoReply
Definition: The field moreInfoReply must be used to contain the billers response for a payers request
for more information.
Usage: N/A
Data type: String of maximum 300 chars
Presence: Mandatory field.
- 74 -
-
6.1.2 Repository to Repository API’s
These API’s will be called for repository to repository messaging. The interaction between repositories through the use of these API’s is intrinsic to the delivery of PAM requests/updates, and will ensure that the relevant PAM data store records are kept in sync.
6.1.2.1 RR1 - Request for Authorisation
POST /repo/authorisation-requests This ‘POST’ API will be called by the biller repository to the payer repository, to pass on the original
Request for Authorisation detail provided in ‘AR1 – Request for Authorisation message’.
6.1.2.1.1 pamId
Definition: The field pamId is the unique id of the PAM request. This will have been originally
generated by the biller’s application.
Usage: The format of pamId is PAM-timestamp_nano-64_bitsrandom, where:
PAM – prefix for PAM messaging, timestamp_nano is the epoch time in nanoseconds,
64_bitsrandom is a BASE64-encoded value.
Data type: String of maximum 1024 chars
Presence: Mandatory field.
1 M/O stands for Mandatory or Optional fields.
Header/Body Field Name Field Description
M/O11
Data Type
Body pamId
This is the unique id of the PAM request originating from the biller application
M Max 1024 chars
Body requestMessage This contains an optional message to
accompany the authorisation request
O Max 300
chars
Body
billerName This contains the name of the biller initiating
the request
M Max 70
chars
Body
billerId This contains the Pid of the biller from which the PAM request is being sent
M Max 300 chars
Body payerId This contains the Pid of the payer to which
the PAM request is being sent with whom they are wishing to authorise with
M Max 300
chars
Body status This contains the status, which in all cases
when the initial message is sent will have
‘requested’ as the initial setting
M Max 15
chars
- 75 -
-
6.1.2.1.2 requestMessage
Definition: The field requestMessage can contain an optional message to accompany the authorisation request.
Usage: N/A
Data type: String of maximum 300 chars.
Presence: Optional field.
6.1.2.1.3 billerName
Definition: The field billerName must contain the name of the biller initiating the request.
Usage: N/A
Data type: String of maximum 70 chars.
Presence: Mandatory field.
6.1.2.1.4 billerId Definition: The field billerId must contain the pid of the biller from where the PAM request
originated.
Usage: This field must be in lowercase.
Data type: String of maximum 300 chars.
Presence: Mandatory field.
6.1.2.1.5 payerId
Definition: The field payerId must contain the pid of the payer to which the PAM request is being sent, i.e. with whom they are wishing to create an agreement to bill with.
Usage: This field must be in lowercase.
Data type: String of maximum 300 chars.
Presence: Mandatory field.
6.1.2.1.6 status
Definition: The field status will contain the status of the PAM request. Given that the only time this API will be invoked will be to pass on an initial request for authorisation, the status should always be ‘requested’, having been generated originally by the biller app to the biller repository.
Usage: requested
Data type: String of maximum 15 chars.
- 76 -
-
Presence: Mandatory field.
6.1.2.2 RR2 - Update Authorisation PATCH /repo/authorisation-requests/{pamId}
This ‘PUT’ API will be called by the payer repository to the biller repository, to pass on the original Request for Authorisation detail provided in the original AR4 – Request for Authorisation message.
6.1.2.2.1 status Definition: The field status must contain the new status to be applied to the PAM record.
Usage:
Field status is populated with ‘accepted’. Used by the payer repository to update the biller
repository PAM entry with an accepted status.
Field status is populated with ‘denied’. Used by the payer repository to update the biller
repository PAM entry with a denied status.
Data type: String of maximum 15 chars
Presence: Mandatory field.
6.1.2.2.2 pamId
Definition: The field pamId is the unique id of the original PAM request to which the request for
authorisation relates.
Usage: The format of pamId is PAM-timestamp_nano-64_bitsrandom, where:
PAM – prefix for PAM messaging, timestamp_nano is the epoch time in nanoseconds,
64_bitsrandom is a BASE64-encoded value. Data type: String of maximum 1024 chars
Presence: Mandatory field.
1 M/O stands for Mandatory or Optional fields.
Header/Body Field Name Field Description
M/O12
Data Type
Header status The new status for which the status of the PAM record will be updated.
M Max 15 chars
Header
pamId This is the unique id of the original PAM request
M Max 1024 chars
- 77 -
-
6.1.2.3 RR3 - Request for More Info POST /repo/authorisation-requests/{pamId}/moreInformation
This ‘POST’ API will be called by the payer repository to the biller repository to pass on the original Request more info detail provided in the original AR5 – Request more info message.
6.1.2.3.1 pamId
Definition: The field pamId is the unique id of the original PAM request to which the request relates.
Usage: The format of pamId is PAM-timestamp_nano-64_bitsrandom, where:
PAM – prefix for PAM messaging,
timestamp_nano is the epoch time in nanoseconds,
64_bitsrandom is a BASE64-encoded value.
Data type: String of maximum 1024 chars
Presence: Mandatory field.
6.1.2.3.2 mimId
Definition: The field mimId is the unique id of the request for more information message. This must have been originally generated by the payer’s application and passed on for the first time in this API
call from the payer repository to the biller repository.
Usage: The format of mimId is MSG-timestamp_nano-64_bitsrandom, where:
MSG – prefix for More information messages,
timestamp_nano is the epoch time in nanoseconds, 64_bitsrandom is a BASE64-encoded value.
Data type: String of maximum 1024 chars
1 M/O stands for Mandatory or Optional fields.
Header/Body Field Name Field Description
M/O13
Data Type
Header
pamId This is the unique id of the original PAM
request
M Max 1024
chars
Header mimId This is the unique id allocated to the request for more information message
M Max 1024 chars
Body moreInfoMessa
ge
This is the for the content of the message the
payer wishes to send when requesting more
information from the biller
M Max 300
chars
- 78 -
-
Presence: Mandatory field.
6.1.2.3.3 moreInfoMessage
Definition: The field moreInfoMessage must be used to pass on the message the payer wishes to send when requesting more information from the biller.
Usage: N/A
Data type: String of maximum 300 chars
Presence: Mandatory field.
6.1.2.4 RR4 – Update with More Info PATCH /repo/authorisation-requests/{pamId}/moreInformation/{mimId}
This ‘PATCH’ API will be called by the biller repository to the payer repository to pass on the original reply to more information detail in the original AR6 – Reply to more info message.
6.1.2.4.1 pamId
Definition: The field pamId is the unique id of the original PAM request to which the request relates.
Usage: The format of pamId is PAM-timestamp_nano-64_bitsrandom, where:
PAM – prefix for PAM messaging, timestamp_nano is the epoch time in nanoseconds,
64_bitsrandom is a BASE64-encoded value.
Data type: String of maximum 1024 chars
Presence: Mandatory field.
1 M/O stands for Mandatory or Optional fields.
Header/Body Field Name Field Description
M/
O14
Data
Type
Header
pamId This is the unique id of the original PAM request
M Max 1024 chars
Header mimId This is the unique id allocated to the request for more information message
M Max 1024 chars
Body moreInfoReply This is the for the content of the message the
biller wishes to send when replying to the
request for more information from the biller
M Max 300
chars
- 79 -
-
6.1.2.4.2 mimId
Definition: The field mimId is the unique id of the request for more information message.
Usage: The format of mimId is MSG-timestamp_nano-64_bitsrandom, where:
MSG – prefix for More information messages, timestamp_nano is the epoch time in nanoseconds,
64_bitsrandom is a BASE64-encoded value. Data type: String of maximum 1024 chars
Presence: Mandatory field.
6.1.2.4.3 moreInfoReply
Definition: The field moreInfoReply must be used to pass on the message the biller wishes to send when replying to the request for more information from the payer.
Usage: N/A
Data type: String of maximum 300 chars
Presence: Mandatory field.
6.1.2.5 RR5 - Sync Authorisations (POST) POST /repo/sync/authorisation-requests
This ‘POST’ API will be called by either the Biller or Payer Repository Provider where there is a need to synchronise with another repository. This may either be as a routine maintenance type of
request, or may be invoked in a reactionary manner if there is cause to suspect the repository is out of sync with the contents of another repository, for example if an RtP message arrives at the Payer repository where there is no PAM record in the data store to support it.
The body contains an array of authorisation ids:
6.1.2.5.1 pamId
1 M/O stands for Mandatory or Optional fields.
Header/Body Field Name Field Description
M/
O15
Data
Type
Body
pamId This is the unique id of the original PAM request
M Max 1024 chars
- 80 -
-
Definition: The field pamId is the unique id of the PAM request. This must be generated by the biller’s application and appears for the first time in this API call from the application to the biller repository.
Usage: The format of pamId is PAM-timestamp_nano-64_bitsrandom, where:
PAM – prefix for PAM messaging, timestamp_nano is the epoch time in nanoseconds, 64_bitsrandom is a BASE64-encoded value.
Data type: String of maximum 1024 chars
Presence: Mandatory field.
- 81 -
-
7. Glossary
7.1 Terms and definitions
Term Definition
Originator Sender of the initial message of the thread. This can be either the Payer or the Biller.
Respondent Receiver of the initial message of the thread. This can be either the Payer or the Biller.
Sender Sender of messages in a thread. This can be either the Payer or the Biller.
Recipient Receiver of messages in a thread. This can be either the Payer or the Biller.
End user A biller or payer using the Request to Pay framework.
Biller The person to whom money is to be paid. The biller sends a Request to Pay message.
Payee Same as biller.
Payer The person by whom a bill or note should be paid. A payer responds to a
Request to Pay message.
Payment A transfer of funds from an end user to another (i.e. payer to the biller).
7.2 Acronyms
Acronym Definition
BACS Bankers' Automated Clearing Services.
BIC Identifier of an institution or corporate branch in a Business Identifier Code
format.
FPS Faster Payment Service.
IBAN Account number provided in an International Bank Account Number format.
JSON Javascript Object Notation.
Pay.UK The managing body of the Request to Pay framework.
PID Payment address identifier.
PISP Payment Initiation Service Provider.
PSF Payments Strategy Forum.
PSP Payment Service Provider.
PSR Payment Systems Regulator.
RtP Request to Pay service.
TPP Third-Party Provider, either an Application Provider or a Repository
Provider.
TPSP Third-Party Service Provider. Note that PSPs, PISPs, AISPs and Fin Techs can perform the role of the
TPSP.
URL Website address in a Uniform Resource Locator format.
7.3 References
- 82 -
-
Reference Website
Request to Pay www.requesttopay.co.uk
Faster Payments Standards Library Specifications
https://www.standardslibrary.org/ValidationPortal/FASTERPAYMENTSSTANDARDSLIB
RARY/TreeTable.aspx?id=2&new=1&Proj=1&Lang=EN
ISO 20022 Standards www.iso20022.org
- 83 -
-
8. Change log
Changes between version DRAFT v0.7.0 and version v0.8.
Paragraph Description
2.0 Clarified camelCase requirements. Clarified Field Descriptions for envelope & attachments in table
2.1 Requirement for envelope object to be digitally signed is now optional
2.1.1.3 64_bitrandom part of threadId reworded to value rather than number
2.1.2.1 64_bitrandom part of messageId reworded to value rather than number
2.1.4.5.1 Enriched description for Delivery Errors. Clarified failureReason for
TemporarydeliveryError
2.2 Clarified description of messageMeta. Clarified field description of
numMessages and made it mandatory
2.2.1 Removed the following fields fromIP & toIP. Enriched field descriptions for fromId & toId and made them mandatory. Updated data type for
timestamp and clarified field description in table
NA Removed fromIP section
2.2.1.1 Modified definition and presence of fromID and defined usage
2.2.1.3 Modified definition, data type and presence of timestamp and defined usage
NA Removed toIP section
2.2.1.4 Modified definition and presence of toID and defined usage
2.2.2 Modified definition and presence of numMessages
2.3 Signing of attachments no longer mandatory. Added content field to table.
2.3.2 Added URID to usage of contentType
2.3.4 Defined usage for path and modified presence
2.3.5 Added section for content
3.2.2 Modified usage for endToEndIdentification
3.2.4.2.1.1 Modified usage for BICFI
3.2.4.2.1.2.1 Modified description for clearingSystemID
3.2.4.2.1.2.1.1 Modified usage for code
3.2.4.2.1.2.2 Modified usage and data type character limit for memberId
3.2.4.3 Defined data types for currency and name in table
3.2.4.3.1 Enriched description for identification
3.2.4.3.1.1 Enriched definition for IBAN
3.2.4.3.1.2.1 Enriched usage for id
3.2.4.3.3 Modified data type max char length for name
3.2.7.2 Modified data type max char length for billName in table
3.3.7 Modified data type max char length for transactionStatus
3.6.1 Enriched usage for messageType