NAV Navbar
  • Receiving Unsolicited Messages (USMs) from FPS
  • Receiving Unsolicited Messages (USMs) from FPS

    This tutorial explains the basics of Unsolicited Messages (USMs) in Faster Payments and walks you through receiving USMs using the Form3 API.

    We'll provide a step-by-step guide how to automatically be notified when new USMs arrive and how to fetch them. At the end of this tutorial, you can find examples of common USMs and what they look like when fetching them via the Form3 API.

    Note that you only receive USMs if you are a Direct Settling Participant or Direct Non-Settling Participant, as an Indirect Participant, your sponsor will receive the USMs. Speak to your implementation manager if you're unsure if you should receive USMs.

    USM Basics

    Faster Payments uses Unsolicited Messages (USMs) to share information about both scheduled and unexpected events with their member institutions. As a settling or non-settling member (a Direct Settling Participant or Direct Non-Settling Participant at Form3), you are required to receive these messages. Form3 receives USMs on your behalf and acknowledges their receipt to FPS.

    USMs are sent to communicate a large variety of events, from updates on settlement status to net sender threshold changes and service status changes (see here for a list of USM types). USMs are designed as collections of fields with all USMs sharing certain fields such as a type, a unique ID, and the date and time when the USM was created. Each USM type also contains fields specific to the information it submits. See below for examples of different USMs.

    To learn more about USMs, take a look at Chapter 17 of the Faster Payments Service Functional Specification.

    Step by Step Guide

    In this section, we'll walk you through each step of receiving a USM. You will:

    USMs are available through the Form3 API via the Scheme Message service. When a new USM is received, a Scheme Message Admission resource is generated together with a Scheme Message resource.

    Subscribe to Scheme Message Admissions

    You can use Form3's Notification service to be notified when a new USM arrives. Create a subscription for the creation of Scheme Message Admission resources to be notified through a webhook or SQS queue when this happens. Create a Subscription resource with these parameters:

    See this tutorial to learn how to create a subscription and receive notifications.

    Send a Trigger Payment

    In this tutorial, we're using Form3's transaction simulator to trigger an inbound USM in a sandbox environment. You can do this by sending a payment with a specific trigger amount. A number of different trigger amounts are available for different types of USM, see here for a complete list of available trigger amounts.

    For this example, we'll use an amount of 1009.72. This triggers a USM-972 message which corresponds to the "FPS Institutions and Third Party Beneficiary Status Change" type.

    To send a trigger payment, first create a Payment resource. Note the following key attributes:

    Take a look at this tutorial and example to learn how to create a Payment resource.

    Finally, to send the trigger payment, create a Payment Submission resource. See here to learn how.

    Fetch the USM

    Upon successful delivery of the trigger payment, the transaction simulator will generate a Scheme Message resource and a Scheme Message Admission resource to indicate an inbound USM. Since you subscribed to the creation of Scheme Message Admissions above, check your webhook or SQS queue for a notification that an admission has been created.

    The notification contains the Scheme Message Admission resource and, in its relationships section, the Scheme Message resource with the USM. Alternatively, you can also perform a GET request using the ID of the Scheme Message resource to fetch the content: GET v1/notification/schememessages/{scheme_message_id}

    The notification will look similar to this:

    Scheme Message Admission notification

    {
      "id": "ad491e61-c7fa-4381-a84c-bceb65a3f3a3",
      "organisation_id": "79f29076-c708-4a9d-b077-ca037eb599e1",
      "event_type": "created",
      "record_type": "scheme_message_admissions",
      "data": {
        "data": {
          "type": "scheme_message_admissions",
          "version": 0,
          "id": "da84fe5d-5072-45a3-aad1-0c453989b478",
          "organisation_id": "79f29076-c708-4a9d-b077-ca037eb599e1",
          "attributes": {
            "admission_datetime": "2019-01-31T07:51:17.832Z",
            "status": "delivery_confirmed"
          },
          "relationships": {
            "scheme_message": {
              "data": [
                {
                  "id": "c36d4ffb-254a-452e-8c3f-56ba3078f331",
                  "organisation_id": "79f29076-c708-4a9d-b077-ca037eb599e1",
                  "type": "scheme_messages",
                  "version": 0,
                  "attributes": {
                    "date": "2019-01-31T07:51:16.863Z",
                    "payment_scheme": "FPS",
                    "scheme_message_type": "972",
                    "unique_scheme_id": "375983",
                    "entries": [
                      {
                        "key": "Settlement Method",
                        "value": "CLRG"
                      },
                      {
                        "key": "Settlement Date",
                        "value": "2019-01-09"
                      },
                      {
                        "key": "Function Code",
                        "value": "FPS Institution and Third Party Beneficiary status change"
                      },
                      {
                        "key": "Institutional Connection Status Priority",
                        "value": "2"
                      },
                      {
                        "key": "Institutional Connection Status Availability",
                        "value": "0"
                      },
                      {
                        "key": "Financial Institution Id",
                        "value": "000002"
                      },
                      {
                        "key": "Financial Institution Issuer",
                        "value": "01"
                      },
                      {
                        "key": "Financial Institution Name",
                        "value": "Test Bank 2"
                      }
                    ]
                  }
                }
              ]
            }
          }
        }
      }
    }
    

    Extract the USM from the Scheme Message

    The Scheme Message resource contains the USM data and some meta information. The scheme_message_type attribute contains the type of USM. In our example, it is 972. The unique_scheme_id attribute shows the ID that FPS has assigned to the USM.

    The USM itself is located in the entries attribute and is represented as list of key-value pairs. The key attribute contains the name of the USM field and the value attribute its value.

    Scheme message example

    "data": {
        "type": "scheme_messages",
        "id": "54f49e62-551d-4bb7-b2c9-da902d5a164b",
        "version": 0,
        "organisation_id": "79f29076-c708-4a9d-b077-ca037eb599e1",
        "attributes": {
            "unique_scheme_id":"000048",
            "scheme_message_type":"972",
            "date":"2019-01-09T16:58:45.000Z",
            "payment_scheme":"FPS",
            "entries":[
                {"key":"Settlement Method","value":"CLRG"},
                {"key": "Settlement Date","value": "2019-01-09"},
                {"key":"Function Code","value":"FPS Institution and Third Party Beneficiary status change"},
                {"key":"Institutional Connection Status Priority","value":"2"},
                {"key":"Institutional Connection Status Availability","value":"0"},
                {"key":"Financial Institution Id","value":"000002"},
                {"key":"Financial Institution Issuer","value":"01"},
                {"key":"Financial Institution Name","value":"Test Bank 2"}
            ]
        }
    }
    

    Examples of Common USMs

    Below is a list of examples of common USM types and their representation in the Scheme Message resource.

    Scheme message with USM-972

    "data": {
        "type": "scheme_messages",
        "id": "54f49e62-551d-4bb7-b2c9-da902d5a164b",
        "version": 0,
        "organisation_id": "79f29076-c708-4a9d-b077-ca037eb599e1",
        "attributes": {
            "unique_scheme_id":"000048",
            "scheme_message_type":"972",
            "date":"2019-01-09T16:58:45.000Z",
            "payment_scheme":"FPS",
            "entries":[
                {"key":"Settlement Method","value":"CLRG"},
                {"key": "Settlement Date","value": "2019-01-09"},
                {"key":"Function Code","value":"FPS Institution and Third Party Beneficiary status change"},
                {"key":"Institutional Connection Status Priority","value":"2"},
                {"key":"Institutional Connection Status Availability","value":"0"},
                {"key":"Financial Institution Id","value":"000002"},
                {"key":"Financial Institution Issuer","value":"01"},
                {"key":"Financial Institution Name","value":"Test Bank 2"}
            ]
        }
    }
    

    Scheme message with USM-981

    "data": {
        "type": "scheme_messages",
        "id": "54f49e62-551d-4bb7-b2c9-da902d5a164b",
        "version": 0,
        "organisation_id": "79f29076-c708-4a9d-b077-ca037eb599e1",
        "attributes": {
            "unique_scheme_id": "000058",
            "scheme_message_type":"981",
            "date":"2019-01-09T16:58:55.000Z",
            "payment_scheme":"FPS",
            "entries": [
                {"key" : "Settlement Method","value" : "CLRG"},
                {"key": "Settlement Date","value": "2019-01-09"},
                {"key" : "Function Code","value" : "Free Format"},
                {"key" : "Info Text","value" : "ABC"}
            ]
        }
    }
    

    Scheme message with USM-973

    "data": {
        "type": "scheme_messages",
        "id": "54f49e62-551d-4bb7-b2c9-da902d5a164b",
        "version": 0,
        "organisation_id": "79f29076-c708-4a9d-b077-ca037eb599e1",
        "attributes":{
            "unique_scheme_id":"000049",
            "scheme_message_type":"973",
            "date":"2019-01-09T16:58:46.000Z",
            "payment_scheme":"FPS",
            "entries":[
                {"key" : "Settlement Method","value" : "CLRG"},
                {"key": "Settlement Date","value": "2019-01-09"},
                {"key" : "Function Code","value" : "Settlement Risk - Net Sender Threshold Status Change"},
                {"key" : "Financial Institution Id","value" : "000002"},
                {"key" : "Financial Institution Issuer","value" : "01"},
                {"key" : "Financial Institution Name","value" : "Test Bank 2"},
                {"key" : "Net Sender Cap","value" : "9000.00"},
                {"key" : "Net Sender Threshold Status","value" : "00"},
                {"key" : "Net Sender Threshold Value","value" : "8000.01"},
                {"key" : "Net Sender Threshold Percent","value" : "88889"},
                {"key" : "Settlement Risk Position Value","value" : "8050.00"},
                {"key" : "Settlement Risk Position Percent","value" : "89444"}
            ]
        }
    }
    

    Scheme message with USM-974

     "data": {
        "type": "scheme_messages",
        "id": "54f49e62-551d-4bb7-b2c9-da902d5a164b",
        "version": 0,
        "organisation_id": "79f29076-c708-4a9d-b077-ca037eb599e1",
        "attributes":{
            "unique_scheme_id":"000050",
            "scheme_message_type":"974",
            "date":"2019-01-09T16:58:47.000Z",
            "payment_scheme":"FPS",
            "entries":[
                {"key":"Settlement Method","value":"CLRG"},
                {"key": "Settlement Date","value": "2019-01-09"},
                {"key":"Function Code","value":"Net Sender Cap Status"},
                {"key":"Settlement Amount","value":"5.04"},
                {"key":"Settlement Currency","value":"GBP"},
                {"key":"Financial Institution Id","value":"000002"},
                {"key":"Financial Institution Issuer","value":"01"},
                {"key":"Financial Institution Name","value":"Test Bank 2"},
                {"key":"Net Sender Cap","value":"1000000.00"},
                {"key":"Net Sender Cap Status","value":"01"},
                {"key":"Settlement Risk Position Value","value":"1000000.00"},
                {"key":"Residual Settlement Risk Position","value":"1000000.00"},
                {"key":"Payment Type Info","value":"10"},
                {"key":"Transaction Id","value" : "FTRT00000000000050"},
                {"key":"Clearing System Member Id","value" : "413567"}
            ]
        }
    }
    

    Scheme message with USM-975

    "data": {
        "type": "scheme_messages",
        "id": "54f49e62-551d-4bb7-b2c9-da902d5a164b",
        "version": 0,
        "organisation_id": "79f29076-c708-4a9d-b077-ca037eb599e1",
        "attributes": {
            "unique_scheme_id": "000051",
            "scheme_message_type":"975",
            "date":"2019-01-09T16:58:48.000Z",
            "payment_scheme":"FPS",
            "entries":[
                {"key" : "Settlement Method","value" : "CLRG"},
                {"key" : "Settlement Date","value": "2019-01-09"},
                {"key" : "Function Code","value" : "Settlement Individual Transaction Limit Change"},
                {"key" : "Settlement Amount","value" : "0.00"},
                {"key" : "Settlement Currency","value" : "GBP"},
                {"key" : "SITL Limit Status","value" : "01"},
                {"key" : "New SITL Limit","value" : "50.00"},
                {"key" : "Previous SITL Limit","value" : "42.00"}
            ]
        }
    }
    

    Scheme message with USM-976

    "data": {
        "type": "scheme_messages",
        "id": "54f49e62-551d-4bb7-b2c9-da902d5a164b",
        "version": 0,
        "organisation_id": "79f29076-c708-4a9d-b077-ca037eb599e1",
        "attributes": {
            "unique_scheme_id": "000052",
            "scheme_message_type":"976",
            "date":"2019-01-09T16:58:49.000Z",
            "payment_scheme":"FPS",
            "entries": [
                {"key" : "Settlement Method","value" : "CLRG"},
                {"key" : "Settlement Date","value": "2019-01-09"},
                {"key" : "Function Code","value" : "Security Transaction Limit Change"},
                {"key" : "New STL Limit","value" : "70.00"},
                {"key" : "Previous STL Limit","value" : "42.00"},
                {"key" : "Payment Type Info","value" : "10"}
            ]
        }
    }
    

    Scheme message with USM-977

    "data": {
        "type": "scheme_messages",
        "id": "54f49e62-551d-4bb7-b2c9-da902d5a164b",
        "version": 0,
        "organisation_id": "79f29076-c708-4a9d-b077-ca037eb599e1",
        "attributes":{
            "unique_scheme_id":"000053",
            "scheme_message_type":"977",
            "date":"2019-01-09T16:58:50.000Z",
            "payment_scheme":"FPS",
            "entries":[
                {"key" : "Settlement Method","value":"CLRG"},
                {"key" : "Settlement Date","value": "2019-01-09"},
                {"key" : "Function Code","value" : "Net Sender Threshold Change"},
                {"key" : "Financial Institution Id","value" : "000002"},
                {"key" : "Financial Institution Issuer","value" : "01"},
                {"key" : "Financial Institution Name","value" : "Test Bank 2"},
                {"key" : "Net Sender Threshold Status","value" : "01"},
                {"key" : "Net Sender Threshold Value","value" : "1000000.00"},
                {"key" : "Previous Net Sender Threshold Value","value" : "2000000.00"},
                {"key" : "Net Sender Threshold Percent","value" : "00100"},
                {"key" : "Previous Net Sender Threshold Percent","value" : "00200"}
            ]
        }
    }
    

    Scheme message with USM-978

    "data": {
        "type": "scheme_messages",
        "id": "54f49e62-551d-4bb7-b2c9-da902d5a164b",
        "version": 0,
        "organisation_id": "79f29076-c708-4a9d-b077-ca037eb599e1",
        "attributes":{
            "unique_scheme_id":"000054",
            "scheme_message_type":"978",
            "date":"2019-01-09T16:58:51.000Z",
            "payment_scheme":"FPS",
            "entries":[
                {"key" : "Settlement Method","value":"CLRG"},
                {"key" : "Settlement Date","value": "2019-01-09"},
                {"key" : "Function Code","value" : "Net Sender Cap Change"},
                {"key" : "Financial Institution Id","value" : "000002"},
                {"key" : "Financial Institution Issuer","value" : "01"},
                {"key" : "Financial Institution Name","value" : "Test Bank 2"},
                {"key" : "Net Sender Cap","value" : "256.00"},
                {"key" : "Previous Net Sender Cap","value" : "0.00"},
                {"key" : "Net Sender Cap Status","value" : "01"}
            ]
        }
    }
    

    Scheme message with USM-979

    "data": {
        "type": "scheme_messages",
        "id": "54f49e62-551d-4bb7-b2c9-da902d5a164b",
        "version": 0,
        "organisation_id": "79f29076-c708-4a9d-b077-ca037eb599e1",
        "attributes": {
            "unique_scheme_id": "000055",
            "scheme_message_type":"979",
            "date":"2019-01-09T16:58:52.000Z",
            "payment_scheme":"FPS",
            "entries": [
                {"key" : "Settlement Method","value" : "CLRG"},
                {"key" : "Settlement Date","value": "2019-01-09"},
                {"key" : "Function Code","value" : "Settlement Status"},
                {"key" : "Financial Institution Id","value" : "000002"},
                {"key" : "Financial Institution Issuer","value" : "01"},
                {"key" : "Financial Institution Name","value" : "TEST BANK 2"}
            ]
        }
    }
    

    Scheme message with USM-980

     "data": {
        "type": "scheme_messages",
        "id": "54f49e62-551d-4bb7-b2c9-da902d5a164b",
        "version": 0,
        "organisation_id": "79f29076-c708-4a9d-b077-ca037eb599e1",
        "attributes": {
            "unique_scheme_id": "000056",
            "scheme_message_type":"980",
            "date":"2019-01-09T16:58:53.000Z",
            "payment_scheme":"FPS",
            "entries":[
                {"key" :"Settlement Method","value":"CLRG"},
                {"key" : "Settlement Date","value": "2019-01-09"},
                {"key" : "Function Code","value" : "Scheme Return Payment Failure"},
                {"key" : "Settlement Amount","value" : "0.00"},
                {"key" : "Settlement Currency","value" : "GBP"},
                {"key" : "Financial Institution Id","value" : "000001"},
                {"key" : "Financial Institution Issuer","value" : "01"},
                {"key" : "Financial Institution Name","value" : "Test Bank 1"},
                {"key" : "Receiving Clearing System Member Id","value" : "000002"},
                {"key" : "Status Reason","value" : "9943"},
                {"key" : "Receiving Financial Institution Name","value" : "Test Bank 2"},
                {"key" : "Payment Type Info","value" : "30"},
                {"key" : "Transaction Id","value" : "FTRT00000000000056"},
                {"key" : "Clearing System Member Id","value" : "900009"}
            ]
        }
    }
    

    Scheme message with USM-971

    "data": {
        "type": "scheme_messages",
        "id": "54f49e62-551d-4bb7-b2c9-da902d5a164b",
        "version": 0,
        "organisation_id": "79f29076-c708-4a9d-b077-ca037eb599e1",
        "attributes": {
            "unique_scheme_id": "000047",
            "scheme_message_type":"971",
            "date":"2019-01-09T16:58:43.000Z",
            "payment_scheme":"FPS",
            "entries":[
                {"key":"Settlement Method","value":"CLRG"},
                {"key": "Settlement Date","value": "2019-01-09"},
                {"key":"Function Code","value":"Service status change"},
                {"key":"Service Status","value":"99"}
            ]
        }
    }