Bank transfers

Bank transfers are transactions that represent client funds entering the system. They fulfill multiple roles:

  • An expectation from Freemarket that a bank transfer will be made by a customer, using a specific reference, amount & currency, e. g. when a bank transfer is expected towards an exchange that has already been booked but not yet funded. This bank transfer will have a status code of "E", status of "Enabled", and Deposited equal to 0.

  • Funds being held on behalf of the customer while additional transferor information is being provided by the customer for KYC purposes. This bank transfer will have a status code of "E", status of "Enabled", and Deposited equal to 0.

  • A record of a bank transfer made into the customer account. The bank transfer will have a status code of "T", status of "Completed" and Deposited equal to Amount.

  • Note that where this guide refers to deposits (depositors, deposited, etc.) this does not indicate or imply that Freemarket offers regulated deposits. In line with enhanced Terms and Conditions June 21, deposit refers to a Bank Transfer.

Root OData endpoint

The root endpoint for OData queries for bank transfers is /api/v1/Accounts({AccountId})/Deposits.

Bank transfer structure

{
    "@odata.context": "https://portal.wearefreemarket.com/api/v1/$metadata#Deposits/$entity",
    "Depositor": {
        "VirtualAccount": {
            "Type": "BicIban",
            "Bic": "COBADEFFXXX",
            "Iban": "DE89370400440532013000",
            "CountryCode": "DE"
        },
        "Counterparty": {
            "Type": "Iban",
            "Iban": "GB29NWBK60161331926819",
            "CountryCode": "GB"
        },
        "Name": "remitter name"
    },
    "Id": 1234,
    "AccountId": 12345,
    "CurrencyCode": "EUR",
    "Amount": 10712.75,
    "Reference": "A123456-XYZ123",
    "Narrative": [
        "A123456-XYZ123",
        "another reference",
        "and yet another reference"
    ],
    "ValueDate": "2020-03-06T09:40:16.4566667Z",
    "Deposited": 10712.75,
    "StatusCode": "T",
    "Status": "Completed",
    "ClientDepositor": 1
}
property description
Depositor information about the transferor, when and as provided by the sending bank
Depositor.VirtualAccount the virtual account the bank transfer has been made into, if applicable
Depositor.Counterparty the routing information of the transferor
Depositor.Name the name of the transferor
Id the unique identifier of the bank transfer
AccountId the unique identifier of the Freemarket account that the bank transfer was made into
CurrencyCode currency of the bank transfer
Amount amount of the bank transfer
Reference the primary reference of the bank transfer, as picked by Freemarket from the narrative (typically a reference in an expected format)
Narrative the entire bank transfer narrative
ValueDate the date & time the bank transfer was recognized by Freemarket
Deposited the amount actually transferred (see bank transfer roles above)
StatusCode status code of the bank transfer, "E" for expected bank transfers, "T" for completed bank transfers (see bank transfer roles above)
Status status of the bank transfer, "Enabled" for expected bank transfers, "Completed" for completed bank transfers (see bank transfer roles above)
ClientDepositor the identifier of the tranferor, as recognized within Freemarket

Bank transfer life cycle

When Freemarket receives a bank transfer on behalf of a customer, a workflow is started to verify the bank transfer's origin. This workflow varies based on whether the bank transfer has been made by the owner of the customer account (a first party bank transfer) or not (a third party bank transfer) and whether Freemarket has already seen and verified this transferor or not (based on the routing information provided by the receiving bank). Bank transfers from both first and third party transferors that have been verified already are reconciled to the customer account balance automatically.

Deposit reconciliation

Webhook events

Bank transfer pending

This event is raised when a bank transfer has been identified as belonging to the customer account, however additional information is required for successful transferor verification and bank transfer workflow completion.

 [
    {
        "EntityType": "Deposit",
        "EntityId": 1234,
        "Reason": "DepositPending",
        "ApiUrl": "https://portal.wearefreemarket.com/api/v1/Deposits(1234)"
    }
]

Bank transfer completed

This event is raised when a bank transfer has been reconciled to the customer account balance and the funds are ready for use.

 [
    {
        "EntityType": "Deposit",
        "EntityId": 1234,
        "Reason": "DepositCompleted",
        "ApiUrl": "https://portal.wearefreemarket.com/api/v1/Deposits(1234)"
    }
]

Providing Transferor details

When a Bank transfer pending webhook event is received, additional information is required to reconcile the bank transfer to the customer account. It can be provided via the Deposits_AssignDepositor endpoint. A sample follows:

Individual Transferor

POST /api/v1/Deposits/{depositId}/AssignDepositor HTTP/1.1
Host: portal.wearefreemarket.com
Authorization: Bearer {authToken}
Content-Type: multipart/form-data; boundary=Boundary

--Boundary
Content-Disposition: form-data; name="Depositor"

{
    "IsThirdParty": true,
    "Individual": {
        "FirstName": "First",
        "MiddleName": "Middle",
        "LastName": "Last",
        "PhoneNumber": "+44123456",
        "Address": {
            "HouseNumber": "1",
            "Street": "foo street",
            "District": "",
            "Town": "london",
            "PostCode": "12345",
            "CountryCode": "GB"
        }
    }
}

--Boundary
Content-Disposition: form-data; name="SupportingDocuments"; filename="document.pdf"
Content-Type: text/plain

{file content}
--Boundary--

Company Transferor

The IndustryId is only mandatory for third-party company Transferors. List of Industries can be fetched from the /v1/Sectors endpoint:
The IndustryDetails is only mandatory for third-party company Transferors where the industry provided starts with Other

POST /api/v1/Deposits/{depositId}/AssignDepositor HTTP/1.1
Host: portal.wearefreemarket.com
Authorization: Bearer {authToken}
Content-Type: multipart/form-data; boundary=Boundary

--Boundary
Content-Disposition: form-data; name="Depositor"

{
    "IsThirdParty": true,
    "Company": {
        "Name": "CompanyName",
        "PhoneNumber": "+44123",
        "Website": "https://company.tld",
        "IndustryId": 1492,
        "IndustryDetails": "industry details",
        "Address": {
            "Street": "Union Street",
            "HouseNumber": "62",
            "Town": "London",
            "PostCode": "ABC123",
            "CountryCode": "GB"
        }
    }
}
--Boundary
Content-Disposition: form-data; name="SupportingDocuments"; filename="document.pdf"
Content-Type: text/plain

{file content}
--Boundary--