NAV Navbar
  • Receive a Payment
  • Receive a Payment

    In this tutorial, you will learn how to receive a payment from a third party through the Faster Payments Service (FPS) using the Form3 Payments API. The following steps will be covered:

    Each step is illustrated with Python code snippets, so you can play around with the API as you read along. The snippets are ready-to-run programs and work in Python's interactive console.


    In order to better understand how to receive a payment, let's take a look at what happens when a third party sends a payment to an account that you manage.

    A transfer of funds 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 a 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.

    When a payment is sent, 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.

    A payment admission resource is created when the payment reaches the receiving side. This admission resource represents the transaction on the receiving side and contains the status of the admission, as well as a description of an error in case one occurred.

    If the payment admission was successful and the funds have been added to the beneficiary bank account, the receiving bank sends an acknowledge message to the sending bank and the transfer is complete.



    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 an Account

    To track incoming payments to a bank account, that account needs to be registered with Form3. The key attributes for an account that we'll use further below in this guide are account_number, bank_id and account_name.

    Take a look at this tutorial to learn how to create an account.

    Create a Subscription

    The easiest way to track inbound payments is to set up a subscription for the created event of the payment_admissions resource. That way, you are automatically notified when the event occurs.

    See this tutorial on how to create a subscription.

    Trigger an Inbound Payment

    The Form3 transaction simulator can be used to trigger an inbound payment. Sending an outbound payment with an amount of 600.00 through the simulator will trigger an immediate inbound payment with the same amount. This inbound payment will switch debtor and beneficiary from the trigger payment and thus get sent back to you.

    To create an outbound payment, first create a payment resource. Use the following key attributes:

    Once the payment resource is created, create a payment submission resource to send the payment.

    See our Send a Payment tutorial for a detailed description on how to create these resources.

    Receive the Inbound Payment

    The outbound payment has triggered an immediate inbound payment to the debtor account of the outgoing payment. This inbound payment consists of a Payment resource and a Payment Admission resource

    The Payment Admission

    Take a look at your webhook that you registered with the Notification API earlier. You should see a notification for a new Payment Admission resource.

    The status attribute of the admission should say confirmed, while the status_reason attribute should have the value accepted:

      "id": "f0e98413-ab3f-4ab7-8bd2-87da6b966821",
      "organisation_id": "ee1d1e0c-42e2-4dee-ae94-3dfed82ecae1",
      "event_type": "created",
      "record_type": "payment_admissions",
      "data": {
        "data": {
          "type": "payment_admissions",
          "id": "73bb2ad4-4668-4c5f-b9dc-d937a471c9aa",
          "version": 0,
          "organisation_id": "ee1d1e0c-42e2-4dee-ae94-3dfed82ecae1",
          "attributes": {
            "status": "confirmed",
            "status_reason": "accepted",
            "admission_datetime": "2018-11-02T19:38:12.256Z",
          "relationships": {
            "payment": {
              "data": [
                  "type": "payments",
                  "id": "aa6239b2-6d83-42d7-ab65-f2ac75f70f8b"

    The attribute in the relationship section of the admission contains the ID of the Payment resource. You can use it to retrieve the payment through the GET /transaction/payments/{payment_id} fetch call.

    import requests
    ### Replace these variables with your own data! ###
    client_id = 'YOUR CLIENT ID HERE'
    client_secret = 'YOUR CLIENT SECRET HERE'
    payment_id = 'A VALID PAYMENT ID HERE'
    base_url = ''
    # 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')
    # Retrieve the payment
    get_payment_url = "%s/transaction/payments/%s" % (base_url, payment_id)
    get_payment_headers = {
        'authorization': "bearer %s" % auth_token,
        'cache-control': "no-cache",
    get_payment = requests.request("GET", get_payment_url, headers=get_payment_headers)

    That's it, you have successfully received a payment and tracked it using the Form3 Payments API.