NAV Navbar
  • The Form3 Staging Environment
  • Transaction Simulator
  • Debug Endpoints
  • Upcoming Features
  • Staging Release Log
  • The Form3 Staging Environment

    Form3 Staging is a sandbox environment to try out the Form3 API, validate and debug your implementation.

    It closely resembles Form3's production environment, but isn't connected to any payment schemes. This means it doesn't support real-money transactions.

    Instead, the staging environment offers a transaction simulator that allows you to send and receive test transactions, as well as trigger a wide range of scenarios to make sure your client implementation handles them correctly.

    Addionally, the environment exposes debug endpoints to help you spot errors in your implementation.

    New features and changes to our services are deployed in the staging environment before being released into production. This gives you the chance to implement with new features and make sure your software is ready once an update reaches the production environment.

    Endpoint Connection

    The base URL for the staging environment is https://api.staging-form3.tech. Like with our production environment, you have to use TLS 1.2 or greater to connect to the API endpoints.

    Configuration

    Credentials

    Staging and production are two separate environments that require separate login information. This means that the login client ID and client secret that you use for the staging environment during implementation will not carry over to the production environment once you go live.

    Contact your Form3 implementation manager to acquire client credentials and set up your account on the staging environment.

    Organisation ID

    You will be issued an organisation ID when getting access to the staging environment. You can use the same organisation ID in staging and production, but different setups are also possible.

    User permissions

    When getting access to the staging environment, your organisation has one admin user with all possible permissions set up. You can create additional users with limited permissions if you prefer, see our tutorial on how to do that.

    Sort codes and BICs

    The staging environment performs sort code/BIC validation the same way the production environment does. This means that you will need a valid sort code or BIC to send payments in the staging environment.

    FPS Direct and Bacs

    Our sort code validation checks debtor and beneficiary sort codes on outbound payments against the Extended Industry Sorting Code Directory (EISCD). This mechanism ensures that you send payments to and from existing sort codes.

    For customers that already have one or several sort codes or BICs, we recommend you also use these in staging. Contact your implementation manager to have your codes configured in the staging environment.

    If you don't have a live sort code yet, your implementation manager can assign you a dummy sort code. Using that code, you can send payments to your own accounts that you have registered with our Account API, but not to accounts with other sort codes.

    FPS Indirect

    For new FPS Indirect customers, we will assign you a sort code to use with the FPS Indirect simulator. This codes may change in production as you go live.

    Validation API

    The Validation API allows you to check bank IDs and account number for validity. Currently only UK sort codes and account numbers are supported and checked against the EISCD.

    The EISCD file in the staging environment is frequently updated, however there can sometimes be a delay to propagate new sort codes to the staging environment.

    Transaction Simulator

    We provide simulators for all supported payment schemes. Talk to your Form3 contact about getting access to the scheme simulator for your intergration.

    Please note that we offer a specific solution for Faster Payments Indirect Participants. See here for more information.

    FPS Indirect Simulator

    FPS Indirect uses the Starling FPS simulator. It offers a number of test accounts that will accept or reject payments sent to them. See the tables below for a list of available test accounts.

    The simulator allows you to send transactions between two accounts to test both the sending and receiving logic of your integration. This approach also supports returns.

    Outbound payments

    Accounts that will accept valid transactions:

    Account Number Sort Code
    00004588 203002
    00027944 203002
    58110244 204514
    60282377 204514
    99993193 166051
    87889196 166051

    Account that will reject transactions:

    Account Number Sort Code
    00004900 203002
    00028000 203002
    58110250 204514
    60282380 204514
    99993200 166051
    87889200 166051

    Different error codes can be triggered for rejected payments. Use the syntax rejectCode:nnnn in the reference attribute of the Payment resource, where nnnn represents the 4-digit scheme error code you want to trigger.

    If no error code is specified, 1114 – "Beneficiary Sort Code/Account Number unknown" will be used. Below is a list of supported error codes. Note that some error codes will trigger a automatic retry of the payment as a Future Dated Payment (FDP):

    Code Description Retried as FDP
    1100 Other No
    1114 Beneficiary Sort Code/Account Number unknown No
    1160 Beneficiary Account closed No
    1161 Beneficiary Account stopped No
    1162 Beneficiary Account Name does not match Beneficiary Account Number No
    1163 Account cannot be identified without data in Reference Information field No
    1164 Reference Information is incorrect No
    1167 Beneficiary deceased No
    1168 Fraudulent payment suspected No
    9909 Central Infrastructure System Malfunction Yes
    9910 Direct Receiver’s system not logged on Yes
    9911 Direct Receiver’s system timed out Yes
    9912 Direct Receiver’s system not available Yes
    9913 Duplicate FPID Yes

    Inbound payments

    For triggering inbound payments from accounts other than your own as well as to create a reversal for an inbound payment, ask your Form3 implementation manager.

    FPS Direct Simulator

    The FPS Direct simulator uses Form3's own simulator of the FPS scheme. It supports a large number of simulator scenarios that can be triggered by sending outbound payments with a certain amount. See the table below for a list of supported simulator scenarios.

    The simulator does not route payments. This means it does not support sending payment from one of your accounts to another one.

    The simulator resembles the actual FPS scheme as closely as possible, however, there are a few small differences:

    Match Trigger Payments and Triggered Transactions

    To match trigger payments to triggered inbound transactions, use the reference field in the Payment resource of the trigger payment. Your reference will appear in the reference field of the inbound Payment resource that has been triggered as part of a scenario.

    Bacs Simulator

    The Bacs simulator uses Form3's own simulator of the Bacs scheme. It supports a large number of simulator scenarios that can be triggered by sending outbound payments with a certain amount. See the table below for a list of supported simulator scenarios.

    The simulator does not route payments. This means it does not support sending payment from one of your accounts to another one.

    Bacs Cycle Time

    In the real world, Bacs uses a 3-day cycle to complete transaction where the transaction information is entered to the system on day 1, the transaction is processed on day 2 and the funds applied on day 3. In the simulator, trigger payments are processed immediately and triggered transactions also arrive without delay.

    However, the date checking for Bacs transactions is still active. For example, a Bacs return can only be processed on Bacs day 3 of the original payment based on the processing_date attribute of the resource. Please take these delays into account when simulating Bacs transactions.

    Bacs is a batched service, meaning that all transactions are collected by Form3 and sent to Bacs on specific times on working days. In the simulator, this batching happens once every minute between 7am Monday and 7am Saturday UK time.

    Match Trigger Payments and Triggered Transactions

    To match trigger payments to triggered inbound transactions, use the reference field in the Payment resource of the trigger payment. Your reference will appear in the reference field of the inbound Payment, Direct Debit, Mandate, or Claim resource that has been triggered as part of a scenario.

    SEPA Direct Simulator

    The SEPA Direct simulator uses Form3's own simulator of the SEPA Instant and Credit Transfer schemes and gateway. It supports a large number of simulator scenarios that can be triggered by sending outbound payments with a certain amount. See the table below for a list of supported simulator scenarios.

    The simulator does not route payments. This means it does not support sending payment from one of your accounts to another one.

    Match Trigger Payments and Triggered Transactions

    To match trigger payments to triggered inbound transactions, use the end_to_end_reference field in the Payment resource of the trigger payment. Your reference will appear in the end_to_end_reference field of the inbound Payment resource that has been triggered as part of a scenario.

    SEPA Indirect Simulator

    The SEPA Indirect simulator emulates Form3's SEPA Indirect proposition via LHV in the Staging Environment. It supports several simulator scenarios that can be triggered by sending outbound payments with a certain amount. See the table below for a list of supported simulator scenarios.

    Account Management

    The SEPA Indirect simulator supports scenarios for creating and deleting bank account using Form3's Account API. These scenarios are triggered by providing a specific country code in the private_identification.country field of the Account resource. The following scenarios are supported:

    Scenario Country Code Description
    Create Account Success GB, FR Create an Account resource with trigger country code
    Account is created successfully
    Account Events resources generated for status changes
    Final status is confirmed, final routing_status is routable
    Create Account Failure Any code except GB, FR Create an Account resource with trigger country code
    Account creation fails
    Account Event resources generated for status changes
    Final status is failed, final routing_status is unroutable
    Delete Account Success All country codes Delete an existing account
    Account is deleted successfully
    Account Event resources generated for status changes
    Final status is confirmed, final routing_status is deleted

    Match Trigger Payments and Triggered Transactions

    To match trigger payments to triggered inbound transactions, use the end_to_end_reference field in the Payment resource of the trigger payment. Your reference will appear in the end_to_end_reference field of the inbound Payment resource that has been triggered as part of a scenario.

    Simulator Scenarios

    Payments with trigger amounts are used to generate a variety of scenarios. These include the acceptance or rejection of outbound transactions as well as the generation of several types of inbound transactions and messages.

    To trigger a scenario, create a Payment resource with the trigger amount in the amount parameter and send the payment by creating a Payment Submission resource. Here is a list of supported scenarios and trigger amounts:

    Trigger amount Scenario Supported Schemes
    13.00 Outbound payment will be accepted FPS Direct, Bacs, SEPA Instant & SCT (Direct and Indirect)
    30.00 Outbound payment will be accepted, payment scheme changed to SCT SEPA Instant (Indirect)
    90.00 Outbound payment will be rejected. SEPA Indirect: status reason receiving-agency-account-closed FPS Direct, SEPA Instant & SCT (Direct and Indirect)
    91.00 Outbound payment will be rejected. Status reason: faulty-sender-account SEPA Instant & SCT (Indirect)
    91.10, 91.11, 91.12 Outbound payment will be accepted after being soft-rejected and retried by Form3 as a ForwardDatedPayment FPS Direct
    204.00 Outbound payment will be accepted, but with redirection of funds FPS Direct
    208.00 Outbound payment will be conditionally accepted FPS Direct
    216.16 Outbound payment will be rejected - unknown sortcode or account FPS Direct
    300.00 Outbound payment will be accepted, sending an outbound recall for the payment will generate a positive inbound recall decision SEPA Instant & SCT (Direct)
    310.00 Outbound payment will be accepted, a following outbound recall for the payment will be accepted, no recall decision is generated SEPA Instant & SCT (Direct)
    391.00 Outbound payment will be accepted, a following outbound recall for the payment will generate a negative recall decision SEPA Instant & SCT (Direct)
    400.00 Generates an inbound payment and recall for the payment, any decision can then be made against the recall SEPA Instant & SCT (Direct)
    400.01 Generates an inbound payment and a recall for that payment, an outbound positive recall decision will be rejected and an inbound recall reversal is generated SEPA Instant & SCT (Direct)
    600.00 Outbound payment will be accepted and a separate inbound payment will be generated. Supports SIP, SOP, FDP payments for FPS Direct via the scheme_payment_type field of the Payment resource. FPS Direct, Bacs, SEPA Instant & SCT (Direct and Indirect)
    603.00 Outbound payment is accepted and a separate inbound POO payment is generated. There is a 50% chance an fx field is included in the Payment resource. FPS Direct
    609.00 Outbound payment will be accepted and a separate inbound payment with amount 709.00 will be generated. SEPA Instant (Direct)
    640.00 Outbound payment will be accepted and a return will be generated for the outbound payment FPS Direct, Bacs, SCT (Direct)
    700.00 Generates an inbound Direct Debit of type DirectDebitFirst Bacs
    700.01 Generates an inbound Direct Debit of type ClaimForUnpaidCheque Bacs
    750.00 Generates an inbound mandate of type DirectDebitInstructionNew Bacs
    751.00 Generates an inbound mandate of type DirectDebitInstructionCancel Bacs
    752.00 Generates an inbound mandate of type DirectDebitInstructionConvert Bacs
    854.03 Generates an inbound payment reversal Bacs
    854.05 Generates an outbound payment reversal Bacs
    855.00 Outbound payment is accepted and an inbound reversal is generated for that payment FPS Direct, SEPA Instant (Direct)
    1009.51 Generates a Scheme Message of type Scheme participant unavailable SEPA Instant (Direct)
    1009.71 Generates an Unsolicited Message of type Service status change (USM-971) FPS Direct
    1009.72 Generates an Unsolicited Message of type FPS Institution and Third Party Beneficiary status change (USM-972) FPS Direct
    1009.73 Generates an Unsolicited Message of type Settlement Risk - Net Sender Threshold Status Change (USM-973) FPS Direct
    1009.74 Generates an Unsolicited Message of type Net Sender Cap Status (USM-974) FPS Direct
    1009.75 Generates an Unsolicited Message of type Settlement Individual Transaction Limit Change (USM-975) FPS Direct
    1009.76 Generates an Unsolicited Message of type Security Transaction Limit Change (USM-976) FPS Direct
    1009.77 Generates an Unsolicited Message of type Net Sender Threshold Change (USM-977) FPS Direct
    1009.78 Generates an Unsolicited Message of type Net Sender Cap Change (USM-978) FPS Direct
    1009.79 Generates an Unsolicited Message of type Settlement Status (USM-979) FPS Direct
    1009.80 Generates an Unsolicited Message of type Scheme Return Payment Failure (USM-980) FPS Direct
    1009.81 Generates an Unsolicited Message of type ASPM Alert Message (USM-981) FPS Direct
    2000.17 Generates a reversal of an inbound Direct Debit Bacs
    2000.18 Generates a reversal of an inbound Direct Debit of type ClaimForUnpaidCheque Bacs
    3000.17 Generates a reversal of an outbound Direct Debit Bacs
    3000.18 Generates a reversal of an outbound Direct Debit of type ClaimForUnpaidCheque Bacs
    3000.19 Generates a reversal of an outbound Direct Debit of type AruddFirstCollection Bacs
    4000.19 Generates a return of an outbound Direct Debit of type AruddFirstCollection Bacs

    Debug Endpoints

    Request signing

    The HTTP signature debug endpoint can be used to verify if a client is correctly signing HTTP requests. It returns validation messages that are not available in the production environment for security reasons.

    See our tutorial for more information on how to use the request signing debug endpoint.

    Upcoming Features

    This section contains information about upcoming changes and features that are available in our test environment but not yet in the production environment.

    New Account Resource Fields

    Form3 adds several new fields to the Account resource. These fields will eventually replace a number of redundant other fields used by the Confirmation of Payee and SEPA Indirect via LHV services. The table below lists the new fields and describes their function.

    Field Description Replaces
    name array [4] of string [140] Name of the account holder, up to four lines possible.

    CoP: Primary account name. For concatenated personal names, joint account names and organisation names, use only the first array line.
    If first and last names of a personal name are separated, use the first array line for first names, the second array line for last names. Titles are ignored and should not be entered.
    required

    SEPA Indirect: Can be a person or organisation. Only the first array line is used.
    optional
    CoP: title, first_name, bank_account_names

    SEPA Indirect: private_identification.first_name, private_identification.last_name for private accounts, organisation_identification.name for organisation accounts.
    alternative_names array [3] of string [140] Alternative primary account names, only used for UK Confirmation of Payee

    CoP: Up to 3 alternative account names, one in each line of the array.
    optional
    CoP: alternative_bank_account_names

    SEPA Indirect: Not used.
    private_identification.identification string The number of the document used to identify the account holder

    SEPA Indirect: Must be between 5 and 20 characters long
    optional
    CoP: Not used.

    SEPA Indirect: private_identification.document_number
    organisation_identification.identification string The registration number used to identify the account holding organisation.

    SEPA Indirect: Must be between 5 and 20 characters long
    optional
    CoP: Not used.

    SEPA Indirect: organisation_identification.registration_number
    organisation_identification.actors.name array [4] of string [255] The name of a person representing the account holding organisation

    SEPA Indirect: Must be between 5 and 255 characters long. Only the first array line is used.
    optional
    CoP: Not used.

    SEPA Indirect: organisation_identification.representative.name
    organisation_identification.actors.birth_date string The birth date of the person named in organisation_identification.actors.name

    SEPA Indirect: Date must use the format YYYY-MM-DD
    optional
    CoP: Not used.

    SEPA Indirect: organisation_identification.representative.birth_date
    organisation_identification.actors.residency string The country of residency of the person named in organisation_identification.actors.name

    SEPA Indirect: Must be an ISO 3166-1 country code, e.g. 'GB', 'FR'
    optional
    CoP: Not used.

    SEPA Indirect: organisation_identification.representative.residency

    Below is an example Account resource containing the new fields:

    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 0,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "name": [
            "Samantha Holder"
          ],
          "alternative_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4",
          "switched": false,
          "private_identification": {
            "birth_date": "2017-07-23",
            "birth_country": "GB",
            "identification": "13YH458762",
            "address": "[10 Avenue des Champs]",
            "city": "London",
            "country": "GB"
          },
          "organisation_identification": {
            "tax_residency": "GB",
            "identification": "123654",
            "actors": [
              {
                "name": [
                  "Jeff Page"
                ],
                "birth_date": "1970-01-01",
                "residency": "GB"
              }
            ],
            "address": ["10 Avenue des Champs"],
            "city": "London",
            "country": "GB"
          }
        },
        "relationships": {
          "master_account": {
            "data": [{
              "type": "accounts",
              "id": "a52d13a4-f435-4c00-cfad-f5e7ac5972df"
            }]
          }
        }
      }
    }
    


    It is recommended to use the new fields from now on. However, the old fields will remain available. They will be removed in the future, but no firm date has been set to do that. Form3 will communicate the removal to customers in advance.

    While both old and new fields are available, the following logic is applied for UK Confirmation of Payee to avoid data conflicts:

    first_name bank_account_name name Action
    not present not present not present Error, name or bank_account_name are mandatory
    not present not present present name used as per documentation above
    not present present not present name filled with [bank_account_name]
    not present present present bank_account_name ignored, name takes precedent
    present not present not present Error, name or bank_account_name are mandatory
    present not present present first_name ignored, name takes precedent
    present present not present name filled with [first_name, bank_account_name]
    present present present first_name and bank_account_name ignored, name takes precedent

    SEPA Direct Debit

    We will soon add support for SEPA Direct Debit via the Form3 API. As part of this feature, we are releasing the Address Book API, which is currently available for testing and development in our Staging Environment. The API Documentation has been updated to include the Address Book API and SEPA Direct Debit-specific information for the Mandate and Direct Debit resources.

    For more information on SEPA Direct Debit, contact your implementation manager or get in touch via our website.

    New Standard Authentication Method: Message Signing

    Form3 is introducing HTTP Message Signing as the new standard authentication method for its API. New implementations will be required to implement message signing. Existing implementations can continue to use token-based OAuth authentication.

    To use request signing, a private and public key pair needs to be generated before accessing the API for the first time. The user then signs all messages sent to the API with the private key while Form3 uses the public key to verify the authenticity of the message.

    API Documentation: See the Authentication section for more information on message signing.

    Tutorial: Our message signing step-by-step guide describes how to create your keys and sign messages.

    SEPA Credit Transfer

    We will soon release support for SEPA Credit Transfer via the Form3 API. This feature is currently available in our Staging Environment. The API Documentation includes SEPA Credit Transfer in the relevant resources.

    For more information, contact your implementation manager or get in touch via our website.

    Staging Release Log

    This section contains a list of past updates to the staging environment. You can subscribe to updates on this release log using our Staging Releases RSS Feed.

    Note that the production environment has its own release log.

    Change types

    A change can be of the following types: breaking change, new feature, improvement and bug fix.

    See the table below for more information on the categories.

    Change Type Description
    Breaking Change A change in functionality that requires customers to update their implementation. These changes are very rare.
    New Feature A change that introduces a new feature or functionality
    Improvement A change that improves existing functionality that was working as expected before
    Bug Fix A change that fixes existing functionality that was not working as expected before

    April 1, 2020

    IMPROVEMENTS

    March 31, 2020

    NEW FEATURES

    March 30, 2020

    NEW FEATURES

    March 27, 2020

    IMPROVEMENTS

    March 23, 2020

    NEW FEATURES

    March 19, 2020

    IMPROVEMENTS

    March 12, 2020

    IMPROVEMENTS

    March 5, 2020

    IMPROVEMENTS

    BUG FIXES

    March 4, 2020

    IMPROVEMENTS

    March 2, 2020

    NEW FEATURES

    February 28, 2020

    BUG FIXES

    February 27, 2020

    NEW FEATURES

    February 24, 2020

    NEW FEATURES

    February 21, 2020

    NEW FEATURES

    February 20, 2020

    IMPROVEMENTS

    February 18, 2020

    IMPROVEMENTS

    February 14, 2020

    BUG FIXES

    February 10, 2020

    BUG FIXES

    February 6, 2020

    IMPROVEMENTS

    February 5, 2020

    IMPROVEMENTS

    February 4, 2020

    IMPROVEMENTS

    February 3, 2020

    NEW FEATURES

    January 31, 2020

    IMPROVEMENTS

    January 23, 2020

    BUG FIXES

    January 22, 2020

    NEW FEATURES

    IMPROVEMENTS

    January 17, 2020

    BUG FIXES

    January 13, 2020

    BUG FIXES

    January 07, 2020

    IMPROVEMENTS

    January 06, 2020

    BUG FIXES

    December 31, 2019

    BUG FIXES

    December 17, 2019

    BUG FIXES

    December 17, 2019

    BUG FIXES

    December 13, 2019

    IMPROVEMENTS

    December 12, 2019

    IMPROVEMENTS

    December 10, 2019

    IMPROVEMENTS

    December 4, 2019

    NEW FEATURES

    December 3, 2019

    BUG FIXES

    November 14, 2019

    IMPROVEMENTS

    November 13, 2019

    NEW FEATURES

    November 12, 2019

    NEW FEATURES

    November 07, 2019

    NEW FEATURES

    October 30, 2019

    NEW FEATURES

    BUG FIXES

    October 29, 2019

    IMPROVEMENTS

    October 28, 2019

    IMPROVEMENTS

    October 25, 2019

    IMPROVEMENTS

    October 24, 2019

    IMPROVEMENTS

    October 21, 2019

    IMPROVEMENTS

    October 18, 2019

    IMPROVEMENTS

    October 14, 2019

    IMPROVEMENTS

    October 11, 2019

    IMPROVEMENTS

    October 9, 2019

    IMPROVEMENTS

    October 2, 2019

    BUG FIXES

    October 1, 2019

    IMPROVEMENTS

    September 24, 2019

    BUG FIXES

    September 23, 2019

    BUG FIXES

    September 20, 2019

    BUG FIXES

    September 19, 2019

    IMPROVEMENTS

    September 16, 2019

    BUG FIXES

    September 13, 2019

    BUG FIXES

    September 12, 2019

    NEW FEATURES

    September 9, 2019

    BUG FIXES

    September 7, 2019

    BUG FIXES

    September 3, 2019

    BUG FIXES

    August 30, 2019

    BUG FIXES

    August 28, 2019

    NEW FEATURES

    IMPROVEMENTS

    August 27, 2019

    NEW FEATURES

    August 22, 2019

    BUG FIXES

    August 21, 2019

    BUG FIXES

    August 20, 2019

    NEW FEATURES

    August 19, 2019

    NEW FEATURES

    August 16, 2019

    NEW FEATURES

    August 15, 2019

    NEW FEATURES

    IMPROVEMENTS

    August 14, 2019

    IMPROVEMENTS

    August 13, 2019

    IMPROVEMENTS

    August 9, 2019

    IMPROVEMENTS

    August 8, 2019

    BUG FIXES