• Send a Payment
  • Send a Payment

    This guide covers how to use the Form3 API to make a payment. The API is designed to be as scheme-agnostic as possible, so almost all information in this guide apply independent of which scheme you use to make the payment. Wherever scheme-specific information is required, the text will note solutions for each supported scheme.

    The guide covers the following topics:


    Before diving into the implementation, let's have a look at what it means to send a payment from one bank account to another. Naturally, the specific process varies from scheme to scheme, so here we'll stick to a very high level overview.

    A transfer of funds usually requires a bank and an account with that bank on the sender side, as well as the receiving side.

    The sending bank and the receiving bank are identified using the bank ID. The format of this ID depends on the country the bank is registered in. In the UK it is a 6-digit number that denotes the bank and the branch of the bank. The account is identified by the account number.

    To make a payment, the sending party creates a payment resource that specifies all important information about the payment: who sends it, who receives it, the amount, the currency, and so forth.

    The sending party then submits the payment. The banking scheme performs several steps of validation and routes the payment to the receiving party. On its way through the system, the status of the payment submission changes until its delivery is either acknowledged or declined by the receiving bank.



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

    Create the Payment

    To make a payment, you need to complete two steps. First, create a payment resource to define the payment parameters, then send it by creating a payment submission resource. This payment submission is also used later to track the status of your payment.

    Create the Payment Resource

    Create a payment resource for the payment you are going to send. It contains all information required to process the payment.

    The key parameters that you need to provide are:

    Depending on the payment scheme, the following parameters are either required or recommended:

    Debtor and Beneficiary Data

    To identify the sending and receiving parties of the payment, you need to provide an account_name, the account_number, the account_number_code, as well as the bank_id and bank_id_code for the bank the account is registered with.

    In this example, use your UK sortcode for the sending party's bank_id.

    The bank_id_code attribute denotes the type of the bank_id. Since only domestic UK accounts are used in this example, the bank_id_code is preset as GBDSC.

    A detailed description of each field of the payment resource is available in the API documentation.

    Scheme-Specific Information

    The scheme used for sending the payment is identified in the payment_scheme attribute. The following values are currently supported:

    A scheme can offer different payment services. The specific type of payment is identified in the scheme_payment_type. See this list for all supported payment types.

    Faster Payments further supports the scheme_payment_sub_type attribute. See here for a list of possible values.

    Test Your Application using the Transaction Simulator

    You can use the scheme simulator to test how your application handles both successful and failed payments:

    See the API documentation for a complete list of trigger amounts and the connected events.

    Submit the Payment

    The next step is to send the payment by creating a Payment Submission resource. In the call URL to create the Payment Submission, you have to provide the ID of the Payment resource you created above .

    In the message body, only the id, type and organisation_id fields need to be provided, but not resource-specific fields.

    Track the Payment

    Payment status

    The status attribute of the Payment Submission resource tracks the status of the payment through the Form3 system and to the scheme. If the scheme provides it, information about successful or unsuccessful receipt at the beneficiary side is also reported via the status attribute.

    When a payment is submitted, the initial status is accepted. If the payment succeeds, its final resting state in delivery_confirmed. If the payment fails, the final resting state is delivery_failed.

    See this list for all possible values of the attribute. Not all values may be supported by all schemes and products, check your user guide or contact your implementation manager for details.

    Failure analysis

    In case of an error, the status_reason attribute of the Payment Submission resource contains an error message that can help you determine what went wrong.

    If available from the scheme, the scheme_status_code attribute contains the status values from the scheme once the payment has been submitted. Not all schemes provide such a code. See the API documentation for code listings for FPS and SEPA.

    Event Notifications

    You can use Form3's Notification API to be notified through a webhook or SQS queue when the status of a submitted payment changes. This is the recommended method to track payments in the Form3 system.

    In order to be notified when this happens, create a Subscription resource and choose the following parameters to subscribe to changes of Payment Submission resources:

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

    Other ways to track

    Other ways to track a payment includes fetching the Payment Submission resource and using the Audit API.

    Further reading

    Congratulations, you've completed the first tutorial and now know how to send a payment with the Form3 Payments API.

    Continue with the next tutorial and learn how to receive payments.