NAV Navbar
  • The Form3 Staging Environment
  • Transaction Simulator
  • Debug Endpoints
  • 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.test.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:

    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.

    SEPA Instant Simulator

    The SEPA Instant simulator uses Form3's own simulator of the SEPA Instant scheme 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.

    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, Bacs, SEPA Instant
    90.00 Outbound payment will be rejected FPS, Bacs, SEPA Instant
    204.00 Outbound payment will be accepted, but with redirection of funds FPS
    208.00 Outbound payment will be conditionally accepted FPS
    216.16 Outbound payment will be rejected - unknown sortcode or account FPS
    300.00 Outbound payment will be accepted, sending an outbound recall for the payment will generate a positive inbound recall decision SEPA Instant
    310.00 Outbound payment will be accepted, a following outbound recall for the payment will be accepted, no recall decision is generated SEPA Instant
    391.00 Outbound payment will be accepted, a following outbound recall for the payment will generate a negative recall decision SEPA Instant
    400.00 Generates an inbound payment and recall for the payment, any decision can then be made against the recall SEPA Instant
    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
    600.00 Outbound payment will be accepted and a separate inbound payment will be generated FPS, Bacs, SEPA Instant
    615.00 Outbound payment will be accepted and a separate inbound standing order payment will be generated FPS
    640.00 Outbound payment will be accepted and a return will be generated for the outbound payment Bacs
    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 Generates an inbound payment reversal FPS
    1009.71 Generates an Unsolicited Message of type Service status change (USM-971) FPS
    1009.72 Generates an Unsolicited Message of type FPS Institution and Third Party Beneficiary status change (USM-972) FPS
    1009.73 Generates an Unsolicited Message of type Settlement Risk - Net Sender Threshold Status Change (USM-973) FPS
    1009.74 Generates an Unsolicited Message of type Net Sender Cap Status (USM-974) FPS
    1009.75 Generates an Unsolicited Message of type Settlement Individual Transaction Limit Change (USM-975) FPS
    1009.76 Generates an Unsolicited Message of type Security Transaction Limit Change (USM-976) FPS
    1009.77 Generates an Unsolicited Message of type Net Sender Threshold Change (USM-977) FPS
    1009.78 Generates an Unsolicited Message of type Net Sender Cap Change (USM-978) FPS
    1009.79 Generates an Unsolicited Message of type Settlement Status (USM-979) FPS
    1009.80 Generates an Unsolicited Message of type Free Format (USM-980) FPS
    1009.81 Generates an Unsolicited Message of type Net Sender Threshold Change (USM-981) FPS
    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
    5000.19 Generates a reversal of a Direct Debit return 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.