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:
- Sending the payment
- Tracking the payment progress automatically using subscriptions
- Tracking the payment progress manually
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:
- An organisation ID. Contact Form3 to obtain it.
- A private-public key pair to authenticate with the Form3 API via HTTP Request Signing. Alternatively, you can use the deprecated OAuth method (not recommended).
- At least one UK sortcode and BIC registered with Form3
- Access to the transaction simulator. This is a sandbox environment that you can use to simulate transactions in order to test your application.
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:
amount: The amount to be paid
currency: The currency code of the currency for the amount
beneficiary_party: Data structures containing the account information of the sending and the receiving party (see below)
Depending on the payment scheme, the following parameters are either required or recommended:
reference: A reference number or short text to identify the payment. FPS and Bacs require this.
clearing_id: Bacs requires this field to contain the Service User Number, other schemes don't use it.
processing_date: The date when the payment is being processed. This has to be within -/+ 1 day of the current day. Note that you cannot use this field to delay the processing until the following day.
scheme_payment_type: The type of the payment, has to be a valid type for the scheme used for sending the payment. This field is not used for SEPA Credit Transfer.
Debtor and Beneficiary Data
To identify the sending and receiving parties of the payment, you need to provide an
account_number_code, as well as the
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_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
A detailed description of each field of the payment resource is available in the API documentation.
The scheme used for sending the payment is identified in the
payment_scheme attribute. The following values are currently supported:
FPSfor Faster Payments
BACSfor Bacs Direct Credit
SEPAINSTANTfor SEPA Instant
SEPASCTfor SEPA Credit Transfer
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:
- Sending a payment with an amount of
13.00will be accepted (assuming that all other necessary configurations are correct) - supported by all schemes.
- A payment with an amount of
216.16will be rejected. - not supported by Bacs.
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
organisation_id fields need to be provided, but not resource-specific fields.
Track the Payment
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
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
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.
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.
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
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.