NAV Navbar
  • Account Creation
  • Account Creation

    This tutorial explains the role of bank accounts in the Form3 API. The first part of the tutorial provides an overview of how bank accounts are managed at Form3 and illustrates the differences between accounts in different countries. The second part provides a step by step guide on how to register, view, and remove accounts.

    Bank Accounts at Form3

    In order to receive an inbound payment through the Form3 API, you need to register the beneficiary bank account with Form3. This enables the API to verify the provided bank account details in the inbound payment.

    You can either register existing bank accounts at Form3 or create a new bank account and let Form3 generate a valid account number and IBAN (if applicable) for you. See below for more information on the Account Number Generation feature.

    Information required during setup

    A bank account has to be linked to a banking institution through a bank ID or a BIC (depending on the country). To be able to create bank accounts using a bank ID or BIC, you first need to make sure Form3 knows that this bank ID or BIC is associated with your organisation ID. Contact your implementation manager at Form3 or file a service request at our Customer Success Portal to do this.

    Some countries require that account numbers are generated in a specific range or are led by a partner code. If you want Form3 to create account numbers is countries where these rules apply, make sure to register your allocated account number range or partner code with Form3. See the table below for a list of countries that require ranges or partner codes.

    Country Bank ID BIC Partner Code / Account Range
    United Kingdom required, 6 characters, UK sort code required
    Australia optional, 6 characters, Australian Bank State Branch (BSB) code required
    Belgium required, 3 characters optional
    France required, 10 characters, national bank code + branch code (code guichet) optional
    Germany required, 8 characters, Bankleitzahl (BLZ) optional
    Greece required, 7 characters, HEBIC (Hellenic Bank Identification Code) optional
    Italy required, 10 characters, national bank code (ABI) + branch code (CAB) optional
    Luxembourg required, 3 characters, IBAN Bank Identifier optional range
    Netherlands not supported required range
    Poland required, 8 characters, national bank code + branch code + national check digit optional
    Portugal required, 8 characters, bank identifier + PSP reference number optional
    Spain required, 8 characters, Código de entidad + Código de oficina optional
    Switzerland required, 5 characters optional
    United States required, 9 characters, ABA routing number required partner code

    Information required by country

    Depending on the country, different data is required to register a bank account. All accounts require the country attribute to be filled with the ISO 3166-1 code for the country they are registered in. The bank_id_code field is also required for most countries (see table below).

    All countries further require either the bank_id field or the bic field to be filled with a bank ID or BIC you have previously associated with your organisation ID at Form3.

    See the table below for a list of required attributes by country.

    Country Attributes
    United Kingdom Country code: GB
    Bank ID: required, 6 characters, UK sort code
    BIC: required
    Bank ID Code: required, has to be GBDSC
    Account Number: optional, 8 characters, generated if not provided
    IBAN: Generated if not provided
    Australia Country code: AU
    Bank ID: optional, 6 characters, Australian Bank State Branch (BSB) code
    BIC: required
    Bank ID Code: required, has to be AUBSB
    Account Number: optional, 6-10 characters, first character cannot be 0, generated if not provided
    IBAN: has to be empty
    Belgium Country code: BE
    Bank ID: required, 3 characters
    BIC: optional
    Bank ID Code: required, has to be BE
    Account Number: optional, 7 characters, generated if not provided
    IBAN: generated if not provided
    France Country code: FR
    Bank ID: required, 10 characters, national bank code + branch code (code guichet)
    BIC: optional
    Bank ID Code: required, has to be FR
    Account Number: optional, 10 characters, generated if not provided
    IBAN: generated if not provided
    Germany Country code: DE
    Bank ID: required, 8 characters, Bankleitzahl (BLZ)
    BIC: optional
    Bank ID Code: required, has to be DEBLZ
    Account Number: optional, 7 characters, generated if not provided
    IBAN: generated if not provided
    Greece Country code: GR
    Bank ID: required, 7 characters, HEBIC (Hellenic Bank Identification Code)
    BIC: optional
    Bank ID Code: required, has to be GRBIC
    Account Number: optional, 16 characters, generated if not provided
    IBAN: generated if not provided
    Italy Country code: IT
    Bank ID: required, national bank code (ABI) + branch code (CAB), 10 characters if account number is not present, 11 characters with added check digit as first character if account number is present
    BIC: optional
    Bank ID Code: required, has to be ITNCC
    Account Number: optional, 12 characters, generated if not provided
    IBAN: generated if not provided
    Luxembourg Country code: LU
    Bank ID: required, 3 characters, IBAN Bank Identifier
    BIC: optional
    Bank ID Code: required, has to be LULUX
    Account Number: optional, 13 characters, generated if not provided
    IBAN: generated if not provided
    Netherlands Country code: NL
    Bank ID: not supported, has to be empty
    BIC: required
    Bank ID Code: not supported, has to be empty
    Account Number: optional, 10 characters, generated if not provided
    IBAN: generated if not provided
    Poland Country code: PL
    Bank ID: required, 8 characters, national bank code + branch code + national check digit
    BIC: optional
    Bank ID Code: required, has to be PLKNR
    Account Number: optional, 16 characters, generated if not provided
    IBAN: generated if not provided
    Portugal Country code: PT
    Bank ID: required, 8 characters, bank identifier + PSP reference number
    BIC: optional
    Bank ID Code: required, has to be PTNCC
    Account Number: optional, 11 characters, generated if not provided
    IBAN: generated if not provided
    Spain Country code: ES
    Bank ID: required, 8 characters, Código de entidad + Código de oficina
    BIC: optional
    Bank ID Code: required, has to be ESNCC
    Account Number: optional, 10 characters, generated if not provided
    IBAN: generated if not provided
    Switzerland Country code: CH
    Bank ID: required, 5 characters
    BIC: optional
    Bank ID Code: required, has to be CHBCC
    Account Number: optional, 12 characters, generated if not provided
    IBAN: generated if not provided
    United States Country code: US
    Bank ID: required, 9 characters, ABA routing number
    BIC: required
    Bank ID Code: required, has to be USABA
    Account Number: optional, 8 characters, generated if not provided
    IBAN: not supported, has to be empty

    Account Number Generator

    The Account Number Generation feature allows you to register an account without providing an account number or IBAN. In that case, Form3 will generate a valid account number and IBAN (if applicable).

    The generated account number will include check digits as required by the central banking authorities of the respective country. The table below provides more information on which check procedure is used to verify the account number for each country. Each account number is further checked for uniqueness, making sure it is not currently registered at Form3 by you or has been at any point in the past.

    For most countries, the generator will create a random account number. In countries where account number ranges or partner codes are allocated, the generator will create account numbers in the given range or with the leading partner code.

    This table provides an overview of account number generation methods and check procedures by country:

    Country (Country Code) What is generated Check Digit Rule Comment
    United Kingdom (UK) Account number, IBAN Combination of "Mod 11" and "Double Alternate" methods as described here
    Australia (AU) Account number 2 check digits based on "Mod 97"
    France (FR) Account number, IBAN Relevé d'identité bancaire
    Belgium (BE) Account number, IBAN 2 check digits as described here
    Germany (DE) Account number, IBAN Bundesbank Check Digit Method 28 Last 2 chars of account number are sub-account ID, always chosen as "01" by Form3
    Greece (GR) Account number, IBAN No check digits used
    Italy (IT) Account number, IBAN 1 Alpha (CIN) Check Character as described here
    Luxembourg (LU) Account number, IBAN No check digits used Account number generation is incremental
    Netherlands (NL) Account number, IBAN Integrated check as described here Account number generation is incremental
    Poland (PL) Account number, IBAN No check digits used
    Portugal (PT) Account number, IBAN 2 check digits as described here
    Spain (ES) Account number, IBAN 2 check digits as described here
    Switzerland (CH) Account number, IBAN No check digits used
    United States (US) Account number 2 check digits based on "Mod 97" Account number generation is incremental

    Step by step guide

    Now we'll walk you through each step of creating and managing bank account with Form3. A code example at the end provides a working implementation. You will learn how to:

    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.

    Register an existing account

    To register an existing bank account, create an Account resource using the POST /v1/organisation/accounts call.

    Assuming we are creating a UK account, the following parameters have to be provided (see here for which parameters you need to provide for other countries):

    Optionally, you can include a customer_id. This can be any identifier that you use internally for this account.

    The response to a successful account creation looks like this:

    Register an account with Form3

    {
        "data": {
            "id": "0d209d7f-d07a-4542-947f-5885fddddae2",
            "organisation_id": "ba61483c-d5c5-4f50-ae81-6b8c039bea43",
            "type": "accounts",
            "attributes": {
                "bank_id": "400300",
                "bank_id_code": "GBDSC",
                "bic": "NWBKGB22",
                "country": "GB",
                "base_currency": "GBP",
                "iban": "GB11NWBK40030041426819",
                "account_number": "41426819",
                "customer_id": "123"
            }
        }
    }
    


    Create a new account

    To let Form3 create an account number and IBAN (if applicable) for you, make sure the Account Number Generator feature is activated for you. Contact Form3 if you are unsure.

    The rest is as simple as creating an Account resource without providing the account_number or iban field. For a UK account, the call requires the following attributes:

    Upon creation of the resource, the API will respond with a new account number and a corresponding IBAN.

    Manage registered accounts

    The API offers several options to manage the accounts you have registered. It supports calls to list all accounts and filter them by a number of parameters. You can also delete an account.

    List Existing Accounts

    You can fetch existing accounts by using the GET /v1/accounts/{account.id} method. The account is specified by its ID.

    If you want to retrieve an account using a different identifier (e.g. the account number), you can use the GET /accounts call to list all available accounts.

    There are several filters you can use to narrow down the list of results, such as account_number and iban. If multiple filter parameters are provided, the call only returns accounts that satisfy all given filters.

    See the API documentation for a complete list of possible filter parameters.

    Delete Account

    You can delete an account with the DELETE /accounts/{account.id} call. Deleted account numbers will remain stored at Form3 to prevent the Account Number Generator from accidentally creating an account with the same number.

    Code Example

    The following example code first creates 2 accounts and then retrieves the account data. The first call fetches all accounts with the given Bank ID. The second call further filters by Customer ID and only fetches one of the newly registered accounts.

    Fetch accounts while applying different filters

    import json, uuid, requests
    
    ### 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'
    bic = 'YOUR BIC HERE'
    
    # Generate IDs
    acc1_id = uuid.uuid4()
    acc2_id = uuid.uuid4()
    print("Account 1 ID: %s" % acc1_id)
    print("Account 2 ID: %s" % acc2_id)
    
    base_url = 'https://api.test.form3.tech/v1'
    
    # 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')
    
    # Function to create an account resource
    def create_account(acc_id, customer_id):
        acc_url = "%s/organisation/accounts" % base_url
    
        acc_payload = """
        {
            "data": {
                "id": "%s",
                "organisation_id": "%s",
                "type": "accounts",
                "attributes": {
                    "bank_id": "%s",
                    "bank_id_code": "GBDSC",
                    "bic": "%s",
                    "country": "GB",
                    "base_currency": "GBP",
                    "customer_id": "%s"
                }
            }
        }
        """ % (acc_id, organisation_id, bank_id, bic, customer_id)
    
        acc_headers = {
            'authorization': "bearer %s" % auth_token,
            'content-type': "application/json",
            'cache-control': "no-cache",
            }
    
        return requests.request("POST", acc_url, data=acc_payload, headers=acc_headers)
    
    # Create 1st account resource
    print("Creating 1st account resource...")
    acc1 = create_account(acc1_id, '345')
    
    # Create 2nd account resource
    print("Creating 2nd account resource...")
    acc2 = create_account(acc2_id, '356')
    
    # Fetch all accounts with your Bank ID
    print("Fetching all your accounts...")
    all_acc_url = "%s/organisation/accounts" % base_url
    all_acc_querystring = {"filter[bank_id]":"%s" % bank_id}
    all_acc_headers = {
        'Authorization': "bearer %s" % auth_token,
        'Accept': "application/vnd.api+json",
        'Cache-Control': "no-cache"
        } 
    
    all_acc = requests.request("GET", all_acc_url, headers=all_acc_headers, params=all_acc_querystring)
    all_accounts = json.loads(all_acc.text)
    print(json.dumps(all_accounts, indent=4, sort_keys=True))
    
    # Fetch account and filter by Bank ID and Customer ID
    print("Fetching account with customer ID 345...")
    cust_acc_url = "%s/organisation/accounts" % base_url
    cust_acc_querystring = {"filter[bank_id]":"%s" % bank_id, "filter[customer_id]":"345"}
    cust_acc_headers = {
        'Authorization': "bearer %s" % auth_token,
        'Accept': "application/vnd.api+json",
        'Cache-Control': "no-cache"
        } 
    
    cust_acc = requests.request("GET", cust_acc_url, headers=cust_acc_headers, params=cust_acc_querystring)
    customer_id_account = json.loads(cust_acc.text)
    print(json.dumps(customer_id_account, indent=4, sort_keys=True))