NAV
  • Receive Reports
  • Receive Reports

    This tutorial shows you how to receive reports using the Form3 API. We provide an overview of how reports work in FPS, Bacs and SEPA, followed by a step by step guide on how to be notified when new reports are available and how to download them.

    Reports Overview

    FPS and Bacs offer a variety of reports on various topics for download. Depending on your status, different reports may be available to you. Depending on scheme rules, you may even be required to download some types of reports.

    Payment schemes regularly provide reports listing events that have occured between you and the scheme. Examples are failed and successful transactions, as well as returns or listings of issued indemnity claims. Reports are ususally distributed as a file and made available for download.

    Scheme Reports in FPS

    FPS issues the following reports for download:

    The Sponsored Participant Report will only be available to if you are sponsoring other FPS entities.

    For more information on reports, see the FPS scheme user guide "IPL00114 FPS Reference data maintenance Member, Agency and Scheme Guide" available from FPS. The document is also available for download from our customer portal.

    Scheme Reports in Bacs

    Bacs scheme reports provide information about files and transactions processed by Bacs and highlight any payment instructions that were amended, rejected or returned. There can be multiple formats for a report. You are required by scheme rules to download certain Bacs reports.

    For more information on reports in Bacs, take a look at the "Messaging Paying Banks Guide" and "Bacstel-IP Service User Guide" documents available for members at https://www.bacs.co.uk.

    Scheme Reports in SEPA Instant and Credit Transfer

    The following SEPA Instant reports are available for download through the Form3 API:

    Availability depends on time and your way of using SEPA Instant. Some reports are only generated if there are transactions that are relevant for this type of report. Additionally, some reports are issued once a month, while others are available daily.

    For SEPA Credit Transfer, the following reports can be downloaded via the Form3 API:

    For more information on reports in SEPA, see the API Documentation on the report types for SEPA Instant and SEPA Credit Transfer, as well as the user guides available on the Form3 Portal.

    Reports in the Form3 API

    Form3 downloads the reports from the scheme on your behalf and makes them available for download through the Reports API. Downloading report files is protected using the same access protection technology that controls access to all other parts of the API. A notification feature allows to be notified upon arrival of new reports.

    A report is represented in the Form3 API by the Report resource. The arrival of a new report is represented by the Report Admission resource. Subscribing to the creation of new Report Admission resources will enable you to receive notifications whenever a new report arrives.

    Example Report resource

    {
       "data": { 
          "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
          "type": "reports",
          "version": 1,    
          "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
          "created_on": "2019-01-16T16:04:31.486Z",
          "modified_on": "2019-01-16T16:05:45.984Z",    
          "attributes": {
              "report_type": "2013",
              "report_type_description": "Input",
              "generation_time": "2019-01-16T16:04:31.194Z",
              "processing_date": "2019-01-16",
              "report_source": "BACS",
              "formats": [
                  "pdf"
              ]
          },    
          "relationships": {
              "report_admission": {
                  "data": [
                      {
                          "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
                          "type": "report_admissions",
                          "version": 0,    
                          "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                          "modified_on": "2019-01-16T16:05:03.261Z",
                          "created_on": "2019-01-16T16:05:03.261Z",
                          "attributes": {
                              "admission_datetime": "2019-01-16T16:05:03.261Z",
                              "status": "delivery_confirmed"
                          }
                      }
                  ]
              }
          }    
       },
       "links": {
          "self": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a"
          },
          "pdf": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/pdf"
            }
          }
       }   
    }
    


    The Report resource contains information about the report it represents, the file types it is available in, as well as a download link to access the report file. The most important attributes in the Report resource are:

    Step by Step Guide

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

    Prerequisites

    Before getting started, make sure you have the following things ready to follow along:

    Before getting started, make sure you have the following things ready to follow along:

    Subscribe to Report Admissions

    You can use Form3's Notification service to be notified when a new report arrives. Create a subscription for the creation of Report 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.

    Receive a Report Notification

    With the subscription in place, a notification is sent to your callback URL when a new report arrives.

    The notification will look similar to this:

    Report notification

    {  
      "id": "9d7b6d0a-21cb-4de2-b8a4-f189635d6fc9",
      "organisation_id": "75198a6a-a4a5-430b-9098-b2d0678c6bf0",
      "event_type": "created",
      "record_type": "report_admissions",
      "data": {  
          "data": {  
            "id": "8850dfe8-9b51-4cc8-869c-cb97ec21e3df",
            "organisation_id": "75198a6a-a4a5-430b-9098-b2d0678c6bf0",
            "type": "report_admissions",
            "version": 0,
            "attributes": {  
              "admission_datetime": "2019-04-02T13:57:59.689Z",
              "status": "delivery_confirmed"
            },
            "relationships": {  
              "report": {  
                "data": [  
                  {
                    "id": "9bff8014-8a35-4244-92c2-f22362bec8df",
                    "organisation_id": "75198a6a-a4a5-430b-9098-b2d0678c6bf0",
                    "type": "reports",
                    "version": 1,  
                      "attributes": {
                        "formats": [
                        "xml",
                        "zipped_xhtml"
                        ],
                        "generation_time": "2019-04-02T13:57:58.000Z",
                        "report_source": "BACS_SERVICE_USER",
                        "report_type": "2013",
                        "report_type_description": "Input"
                    }
                  }
                ]
              }
            }
        }
      }
    }
    


    The notification contains the Reports Admission resource and, in its relationships section, the Report resource with the report details. To fetch the Report resource and get the download link, you will need the content of the id attribute of the Report resource, which is 9bff8014-8a35-4244-92c2-f22362bec8df in this example.

    Fetch the Report Resource

    To get the required information for downloading the report, fetch the Report resource:

    GET v1/notification/reports/{report_id}

    Note that report_id is the ID of the Reports resource from the notification in the previous section. The call will respond with the Report resource that will look similar to this:

    Report resource

    {
      "id": "9bff8014-8a35-4244-92c2-f22362bec8df",
      "organisation_id": "75198a6a-a4a5-430b-9098-b2d0678c6bf0",
      "type": "reports",
      "version": 1,
      "attributes": {
        "formats": [
          "xml",
          "zipped_xhtml"
        ],
        "generation_time": "2019-04-02T13:57:58.000Z",
        "report_source": "BACS_SERVICE_USER",
        "report_type": "2013",
        "report_type_description": "Input"
      },
      "relationships": {
        "report_admission": {
          "data": [
            {
              "id": "8850dfe8-9b51-4cc8-869c-cb97ec21e3df",
              "organisation_id": "75198a6a-a4a5-430b-9098-b2d0678c6bf0",
              "type": "report_admissions",
              "version": 0,
              "attributes": {
                "admission_datetime": "2019-04-02T13:57:59.689Z",
                      "status": "delivery_confirmed"
              },
            }
          ]
        }
      },
        "links": {
          "self": {
            "href": "/v1/notification/reports/9bff8014-8a35-4244-92c2-f22362bec8df"
          },
          "xml": {
            "href": "/v1/notification/reports/9bff8014-8a35-4244-92c2-f22362bec8df",
            "meta": {
              "content-type": "application/xml"
            }
          },
          "zipped_xhtml": {
            "href": "/v1/notification/reports/9bff8014-8a35-4244-92c2-f22362bec8df",
            "meta": {
              "content-type": "application/xhtml+zip"
            }
          }
        }
    }
    


    From the report_type and report_type_description attributes, you can see that the type of the report is "2013", which is an "Input" report.

    The formats attribute shows that the report is available as an XML file and a zipped XHTML file. The download links for the files are located in the links section in the href attribute. The meta.content-type attribute contains the content type for the download request.

    Download Report Files

    To download the reports file, you need the download link and the content type from the Reports resource. Perform a GET request on the download URL and add the content type to the Accept header of the request to get the desired format.

    Note that you also need to add the access token to the header like for any other API request:

    Report download request header

    GET /v1/notification/reports/9bff8014-8a35-4244-92c2-f22362bec8df HTTP/1.1
    Accept: application/xml
    Authorization: bearer eyJ0eXAiOiJKV1QiLCJ...
    Host: api.form3.tech
    


    The API will answer with a (200) OK status code and the download will start.

    Further Reading

    For more information on report files, see the following resources: