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

    Introduction

    In order to 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.

    Receiving_Payment_Diagram

    Prerequisites

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

    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"
                }
              ]
            }
          }
        }
      }
    }
    

    Further Reading

    That's it, you have successfully received a payment and tracked it using the Form3 Payments API. To learn more about using the Form3 API, see our other tutorials: