NAV Navbar
  • 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:

    Each topic is illustrated with a ready-to-run example in Python.

    Introduction

    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.

    Sending_Payment_Diagram

    Prerequisites

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

    The code example is written in Python using the requests package to access the Form3 API. Each code snippet is a standalone Python program, but make sure to paste the required data for each program at the top. The snippets are tested with Python 3.5, but most likely will also work with other Python versions.

    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.

    Example FPS Payment

    The code example below creates an FPS payment. Note that amount is set to 200, triggering the payment to be accepted when sent to the transaction simulator.

    Create an FPS payment

    import math, requests, time, uuid
    
    ### Replace these variables with your own data! ###
    client_id = 'YOUR CLIENT ID HERE'
    client_secret = 'YOUR CLIENT SECRET HERE'
    organisation_id = 'YOUR ORGANISATION ID HERE'
    bank_id = 'YOUR UK SORTCODE HERE'
    
    base_url = 'https://api.staging-form3.tech/v1'
    
    # Generate IDs
    payment_id = uuid.uuid4()
    print("Payment ID: %s" % payment_id)
    
    # Obtain authentication token
    print("Obtaining bearer token...")
    auth_payload = "grant_type=client_credentials"
    auth_url = '%s/oauth2/token' % base_url
    auth_headers = {'Content-Type': 'application/x-www-form-urlencoded'}
    auth_request = requests.auth.HTTPBasicAuth(client_id, client_secret)
    
    auth = requests.request('post', auth_url, data=auth_payload, auth=auth_request, headers=auth_headers)
    auth_token = auth.json().get('access_token')
    
    # Create payment resource
    payment_url = "%s/transaction/payments" % base_url
    payment_payload = """
    {
        "data": {
            "type": "payments",
            "id": "%s",
            "version": 0,
            "organisation_id": "%s",
            "attributes": {
                "amount": "200.00",
                "beneficiary_party": {
                    "account_name": "Mrs Receiving Test",
                    "account_number": "71268996",
                    "account_number_code": "BBAN",
                    "account_with": {
                        "bank_id": "400302",
                        "bank_id_code": "GBDSC"
                    }
                },
                "currency": "GBP",
                "debtor_party": {
                    "account_name": "Mr Sending Test",
                    "account_number": "87654321",
                    "account_number_code": "BBAN",
                    "account_with": {
                        "bank_id": "%s",
                        "bank_id_code": "GBDSC"
                    }
                },
                "processing_date": "%s",
                "reference": "Something",
                "payment_scheme": "FPS",
                "scheme_payment_sub_type": "TelephoneBanking",
                "scheme_payment_type": "ImmediatePayment"
            }
        }
    }
    """ % (payment_id, organisation_id, bank_id, time.strftime("%Y-%m-%d"))
    
    payment_headers = {
        'authorization': "bearer " + auth_token,
        'accept': "application/json",
        'content-type': "application/json",
        'cache-control': "no-cache"
        }
    
    payment = requests.request("POST", payment_url, data=payment_payload, headers=payment_headers)
    print(payment.text)
    

    Submit the Payment

    The next step is to send the payment by creating a payment submission resource. Note that you have to provide the payment ID in the call.

    Submit the payment

    import requests, uuid
    
    ### Replace these variables with your own data! ###
    client_id = 'YOUR CLIENT ID HERE'
    client_secret = 'YOUR CLIENT SECRET HERE'
    organisation_id = 'YOUR ORGANISATION ID HERE'
    payment_id = 'A VALID PAYMENT ID HERE'
    
    base_url = 'https://api.staging-form3.tech/v1'
    
    # Generate IDs
    submission_id = uuid.uuid4()
    print("Submission ID: %s" % submission_id)
    
    # Obtain authentication token
    print("Obtaining bearer token...")
    auth_payload = "grant_type=client_credentials"
    auth_url = '%s/oauth2/token' % base_url
    auth_headers = {'Content-Type': 'application/x-www-form-urlencoded'}
    auth_request = requests.auth.HTTPBasicAuth(client_id, client_secret)
    
    auth = requests.request('post', auth_url, data=auth_payload, auth=auth_request, headers=auth_headers)
    auth_token = auth.json().get('access_token')
    
    submission_url = "%s/transaction/payments/%s/submissions" % (base_url, payment_id)
    submission_payload = """
    {
        "data": {
            "id": "%s",
            "type": "paymentsubmissions",
            "organisation_id": "%s"
        }
    }
    """ % (submission_id, organisation_id)
    
    submission_headers = {
        'authorization': "bearer %s" % auth_token,
        'accept': "application/json",
        'content-type': "application/json",
        'cache-control': "no-cache",
        'postman-token': "f09ad285-4223-ef05-0d4c-bc1048546a82"
        }
    
    submission = requests.request("POST", submission_url, data=submission_payload, headers=submission_headers)
    
    print(submission.text)
    

    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 Notications

    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. See this tutorial to learn more.

    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.