Withdrawals

Withdrawals are transactions that request the move of funds out of the system into a bank account specified as the beneficiary of the transaction.

Root OData endpoint

The root endpoint for OData queries for withdrawals is /api/v1/Accounts({AccountId})/Withdrawals.

Withdrawal beneficiaries

Root OData endpoint

The root endpoint for OData queries for withdrawal beneficiaries is /api/v1/Accounts({AccountId})/Beneficiaries.

Creating a withdrawal beneficiary

The basic request to create a withdrawal beneficiary is in the form

POST /api/v1/Beneficiaries/CreateWithdrawalBeneficiary

{
    "AccountId": {AccountId},
    "Name": {BeneficiaryName},
    "CurrencyCode": {CurrencyCode},
    "PaymentRouting":
    {
        "Type": {BeneficiaryType},
        "CountryCode": {CountryCode},
        ...
    },
    "BeneficiaryType": {BeneficiaryType},
    "Address":
    {
        "Street": "street name",
        "HouseNumber": "123/a",
        "District": "district name",
        "Town": "town",
        "PostCode": "ABC123",
        "CountryCode": "GB"
    },
    "IndustryId": {IndustryId},
    "Website": {Website},
    "IndustryDetails": {IndustryDetails},
    "AdditionalInformation": {
        "key1": "value1",
        "key2": "value2"
    },
    "Reference": {Reference},
    "ReceiverLei": {ReceiverLei}
}

parameter	description	data type	validation rules
AccountId	The account id the beneficiary will be created under	int	required
Name	The friendly name of the beneficiary, used only on the platform	string	required
AccountHolderName	The official name of the bank account holder, sent to the bank with withdrawal details. If empty, is assumed to be the same as the Name	string
CurrencyCode	The currency of the bank account	string	required
PaymentRouting	The payment routing information	object	required
.Type	The type of the beneficiary	string	required
.CountryCode	The ISO Alpha-2 country code	string	required
...	Beneficiary type-specific properties	n/a	n/a
BeneficiaryType	The type of beneficiary, one of "Individual"or"Company"	string	required
Address	Address structure	object	required
.Street	The name of the street	string	required
.HouseNumber	The number of the house on the street, if applicable	string
.District	The name of the district, if applicable	string
.Town	The name of the town	string	required
.PostCode	The post code, if applicable	string
.CountryCode	a ISO 3166-1 alpha-2 two character country code	string	required
IndustryId	The ID of the Industry (obtained using the GET /v1/Sectors endpoint)	int	required *
Website	The website of the beneficiary	string
IndustryDetails	The details of the Industry	string	required **
AdditionalInformation	Additional information specific per beneficiary.	string	required ***
Reference	The withdrawal reference, up to 35 characters	string
ReceiverLei	A Legal Entity Identifier (LEI) is a 20-character alphanumeric code that uniquely identifies a legal entity engaged in financial transactions - Search for a LEI. For more information around LEIs, please click here.	string	conditional - only required when the CurrencyCode is GBP and the beneficiary is a company with a Vertical of FI and the Industry is Banks or Building Societies

*only required for corporate beneficiaries held by the customer account
**only required for when industry is provided which start with "Other"
***only required for certain countries of residence/payment routing country combinations. List of required additional information can be obtained from the Get Required Additional Information endpoint.

BIC & IBAN

• used in countries that have implemented the IBAN account numbering standard
• this beneficiary type has the following Payment routing properties
  • "Type": "BicIban"
  • "CountryCode": the country code of the destination country
  • "Bic": the BIC8 or BIC11 code of the institution holding the account, ^(?<InstitutionCode>[A-Z]{4,4})(?<CountryCode>[A-Z]{2,2})(?<LocationCode>[A-Z2-9][A-NP-Z0-9])(?<BranchCode>[A-Z0-9]{3,3}){0,1}?$
  • "Iban": the IBAN, in grouped format or not. IBAN structure and checksum is validated ^(?<CountryCode>[A-Z]{2})(?<CheckDigits>\d{2})(?<BankAccountNumber>[\w\s/-]+)$

sample:

{
  "AccountId": 12345,
  "Name": "Mr. Smith",
  "CurrencyCode": "GBP",
  "PaymentRouting":
  {
    "Type": "BicIban",
    "CountryCode": "GB",
    "Bic": "NWBKGB2L",
    "Iban": "GB29NWBK60161331926819"
  }
}

UK Sort code & account number

• used in the United Kingdom
• this beneficiary type has the following Payment routing properties
  • "Type": "SortCodeAccountNumber"
  • "CountryCode": "GB"
  • "SortCode": the 6 digit sort code of the institution holding the account
  • "AccountNumber": the 8 digit account number

sample:

{
  "AccountId": 12345,
  "Name": "Mr. Smith",
  "CurrencyCode": "GBP",
  "PaymentRouting":
  {
    "Type": "SortCodeAccountNumber",
    "CountryCode": "GB",
    "SortCode": "123456",
    "AccountNumber": "12345678"
  },
}

US Routing transit number & account number

• used in the United states of America
• this beneficiary type has the following Payment routing properties
  • "Type": "RoutingTransitNumberAccountNumber"
  • "CountryCode": "US",
  • "RoutingTransitNumber": the 9 digit Routing transit number of the institution holding the account. Checksum is validated
  • "Bic": the BIC8 or BIC11 code of the institution holding the account ^(?<InstitutionCode>[A-Z]{4,4})(?<CountryCode>[A-Z]{2,2})(?<LocationCode>[A-Z2-9][A-NP-Z0-9])(?<BranchCode>[A-Z0-9]{3,3}){0,1}?$
  • "AccountNumber": the 7 - 17 digit account number ^[0-9A-Z-]{7,17}$
• either one of BIC or Routing transit number is required

sample:

{
  "AccountId": 12345,
  "Name": "Mr. Smith",
  "CurrencyCode": "USD",
  "PaymentRouting":
  {
    "Type": "RoutingTransitNumberAccountNumber",
    "CountryCode": "US",
    "RoutingTransitNumber": "121000358",
    "AccountNumber": "12345678"
  }
}

Canadian transit number & account number

• used in Canada
• this beneficiary type has the following Payment routing properties
  • "Type": "TransitNumberAccountNumber"
  • "CountryCode": "CA",
  • "TransitNumber": the 9 digit Transit number (with a leading zero) of the institution holding the account.
  • "Bic": the BIC8 or BIC11 code of the institution holding the account ^(?<InstitutionCode>[A-Z]{4,4})(?<CountryCode>[A-Z]{2,2})(?<LocationCode>[A-Z2-9][A-NP-Z0-9])(?<BranchCode>[A-Z0-9]{3,3}){0,1}?$
  • "AccountNumber": the 7 digit account number ^[0-9A-Z-]{7}$

sample:

{
  "AccountId": 12345,
  "Name": "Mr. Smith",
  "CurrencyCode": "CAD",
  "PaymentRouting":
  {
    "Type": "TransitNumberAccountNumber",
    "CountryCode": "CA",
    "Bic": "ROYCCAT2",
    "TransitNumber": "012345678",
    "AccountNumber": "1234567"
  }
}

Australian Bank state branch & account number

• used in Australia
• this beneficiary type has the following Payment routing properties
  • "Type": "BankStateBranchAccountNumber"
  • "CountryCode": "AU"
  • "BankStateBranch": the 6 digit Bank state branch number of the institution holding the account
  • "Bic": the BIC8 or BIC11 code of the institution holding the account ^^(?<InstitutionCode>[A-Z]{4,4})(?<CountryCode>[A-Z]{2,2})(?<LocationCode>[A-Z2-9][A-NP-Z0-9])(?<BranchCode>[A-Z0-9]{3,3}){0,1}?$
  • "AccountNumber": the 6 - 10 digit account number ^[0-9A-Z-]{6,10}$

sample:

{
  "AccountId": 12345,
  "Name": "Mr. Smith",
  "CurrencyCode": "AUD",
  "PaymentRouting":
  {
    "Type": "BankStateBranchAccountNumber",
    "CountryCode": "AU",
    "Bic": "NATAAU33XXX",
    "BankStateBranch": "123456",
    "AccountNumber": "12345678"
  }
}

New Zealand account number

• used in New Zealand
• this beneficiary type has the following Payment routing properties
  • "Type": "NewZealandAccountNumber"
  • "CountryCode": "NZ"
  • "Bic": the BIC8 or BIC11 code of the institution holding the account ^(?<InstitutionCode>[A-Z]{4,4})(?<CountryCode>[A-Z]{2,2})(?<LocationCode>[A-Z2-9][A-NP-Z0-9])(?<BranchCode>[A-Z0-9]{3,3}){0,1}?$
  • "AccountNumber": the 15 - 16 digit account number ^[0-9A-Z-]{15,16}$

sample:

{
  "AccountId": 12345,
  "Name": "Mr. Smith",
  "CurrencyCode": "NZD",
  "PaymentRouting":
  {
    "Type": "NewZealandAccountNumber",
    "CountryCode": "NZ",
    "Bic": "ANZBNZ22102",
    "AccountNumber": "1234567890123456"
  }
}

Indian Financial system code & account number

• used in India
• this beneficiary type has the following Payment routing properties
  • "Type": "IndianFinancialSystemCodeAccountNumber"
  • "CountryCode": "IN"
  • "Bic": the BIC8 or BIC11 code of the institution holding the account ^(?<InstitutionCode>[A-Z]{4,4})(?<CountryCode>[A-Z]{2,2})(?<LocationCode>[A-Z2-9][A-NP-Z0-9])(?<BranchCode>[A-Z0-9]{3,3}){0,1}?$
  • "IndianFinancialSystemCode": the 11 character long IFSC code of the institution holding the account. ^\w{11}$
  • "AccountNumber": the 4 - 24 digit account number ^[0-9A-Z-]{4,24}$
• both the Indian Financial system code and BIC are required

sample:

{
  "AccountId": 12345,
  "Name": "Mr. Smith",
  "CurrencyCode": "INR",
  "PaymentRouting":
  {
    "Type": "IndianFinancialSystemCodeAccountNumber",
    "CountryCode": "IN",
    "Bic": "YESBINBBXXX",
    "IndianFinancialSystemCode": "YESB0000615",
    "AccountNumber": "12345678"
  }
}

BIC & NUBAN

• used in Nigeria
• this beneficiary type has the following Payment routing properties
  • "Type": "BicNuban"
  • "CountryCode": NG
  • "Bic": the BIC8 or BIC11 code of the institution holding the account ^(?<InstitutionCode>[A-Z]{4,4})(?<CountryCode>[A-Z]{2,2})(?<LocationCode>[A-Z2-9][A-NP-Z0-9])(?<BranchCode>[A-Z0-9]{3,3}){0,1}?$
  • "AccountNumber": the 10 digit NUBAN account number ^[0-9]{10}$

sample:

{
  "AccountId": 12345,
  "Name": "Mr. Smith",
  "CurrencyCode": "USD",
  "PaymentRouting":
  {
    "Type": "BicNuban",
    "CountryCode": "NG",
    "Bic": "ABNGNGLA",
    "AccountNumber": "1234567890"
  }
}

BIC & CLABE

• used in Mexico
• this beneficiary type has the following Payment routing properties
  • "Type": "BicClabe"
  • "CountryCode": MX
  • "Bic": the BIC8 or BIC11 code of the institution holding the account ^(?<InstitutionCode>[A-Z]{4,4})(?<CountryCode>[A-Z]{2,2})(?<LocationCode>[A-Z2-9][A-NP-Z0-9])(?<BranchCode>[A-Z0-9]{3,3}){0,1}?$
  • "AccountNumber": the 18 digit CLABE account number ^[0-9]{18}$

sample:

{
  "AccountId": 12345,
  "Name": "Mr. Smith",
  "CurrencyCode": "MXN",
  "PaymentRouting":
  {
    "Type": "BicClabe",
    "CountryCode": "MX",
    "Bic": "BNMXMXMM",
    "AccountNumber": "123456789012345678"
  }
}

BIC & account number

• used as a fallback for the rest of countries not covered above
• this beneficiary type has the following Payment routing properties
  • "Type": "BicAccountNumber"
  • "CountryCode": the country code of the destination country
  • "Bic": the BIC8 or BIC11 code of the institution holding the account ^(?<InstitutionCode>[A-Z]{4,4})(?<CountryCode>[A-Z]{2,2})(?<LocationCode>[A-Z2-9][A-NP-Z0-9])(?<BranchCode>[A-Z0-9]{3,3}){0,1}?$
  • "AccountNumber": the 4 - 24 digit account number ^[0-9A-Z-]{4,24}$

sample:

{
  "AccountId": 12345,
  "Name": "Mr. Smith",
  "CurrencyCode": "HKD",
  "PaymentRouting":
  {
    "Type": "BicAccountNumber",
    "CountryCode": "HK",
    "Bic": "HSBCHKHHHKH",
    "AccountNumber": "1234567890"
  }
}

Intermediaries

Some payments require the specification of an intermediary, or corresponding bank. This is specified by using the BIC of the intermediating bank.

sample:

{
 "AccountId": 12345,
 "Name": "Mr. Smith",
 "CurrencyCode": "HKD",
 "PaymentRouting":
 {
   "Type": "BicAccountNumber",
   "CountryCode": "HK",
   "Bic": "HSBCHKHHHKH",
   "AccountNumber": "1234567890"
 },
 "IntermediaryPaymentRouting":
 [
   {
       "Type": "Bic",
       "Bic": "NWBKGB2L"
   }
 ]
}

Withdrawal life cycle

Creating an account withdrawal

The basic request to create an ad-hoc withdrawal is in the form

POST /api/v1/Withdrawals/CreateAccountWithdrawal HTTP/1.1
Host: portal.wearefreemarket.com
Authorization: Bearer {authToken}
Content-Type: application/json

{
  "AccountId": {AccountId},
  "CurrencyCode": {CurrencyCode},
  "Amount": 1234.56,
  "BeneficiaryId": {BeneficiaryId},
  "Reference": "ref xyz",
  "Description": "xxx/yyy/123",
  "PaymentPurposeId": 1,
  "UltimateOriginator": {
    "Name": "Ultimate Originator Name",
    "Address": {
      "Street": "street name",
      "HouseNumber": "123/A",
      "HouseName": "house name",
      "FlatNumber": "7F",
      "District": "district name",
      "Town": "town",
      "County": "county",
      "PostCode": "ABC123",
      "CountryCode": "country code"
    },
    "SubaccountNumber": "A123456"
  },
  "PaymentChargesCode": "payment charges code",
  "ReceiverLei": "01234567890123456789",
  "BoEPurposeCodeId": 130
}

parameter	description	data type	validation rules
AccountId	The account id for which the withdrawal will be created	int	required
CurrencyCode	The currency to be withdrawn	string	required
Amount	The amount to be withdrawn. If left empty, the maximum withdrawable amount will be requested for withdrawal	decimal
BeneficiaryId	The beneficiary id who will receive the funds	int	required
Reference	The withdrawal reference, up to 35 characters	string
Description	The withdrawal description, up to 140 characters	string
PaymentPurposeId	The payment purpose id	int	Mandatory for beneficiaries with bank accounts in United Arab Emirates (all currencies) or China (CNH only).
UltimateOriginator	The ultimate originator. Use only if you are creating a withdrawal on behalf of another party or entity.	object	*
.Name	The ultimate originator name, up to 35 characters	string	required **
.Address	The ultimate originator address structure	object	required **
.Street	The name of the street	string	required
.HouseNumber	The number of the house on the street, if applicable	string
.HouseName	The name of the house on the street, if applicable	string
.FlatNumber	The number of the flat in the house, if applicable	string
.District	The name of the district, if applicable	string
.Town	The name of the town	string	required
.County	The name of the county, if applicable	string
.PostCode	The post code, if applicable	string	required where supported
.CountryCode	a ISO 3166-1 alpha-2 two character country code	string	required
.SubaccountNumber	Subaccount Number as obtained from the /v1/Accounts({accountId})/Subaccounts endpoint to be used as an Ultimate Originator	object	required **
PaymentChargesCode	The payment charges code, OUR or SHA. SHA: you will pay the FreemarketFX fee for the withdrawal, the beneficiary will incur charges raised by other banks handling the payment. OUR: you will pay the FreemarketFX fee for the withdrawal, plus a fee which covers charges raised by other banks handling the payment.	string	*
BoEPurposeCodeId	Id of a a new code required by Bank of England for GBP payments. To see all of our supported codes use the following endpoint /v1/Withdrawals/BoEPaymentPurposes	int	conditional - only required when the CurrencyCode is GBP
ReceiverLei	A Legal Entity Identifier (LEI) is a 20-character alphanumeric code that uniquely identifies a legal entity engaged in financial transactions - Search for a LEI. For more information around LEIs, please click here.	string	conditional - only required when the CurrencyCode is GBP and the beneficiary is a company with a Vertical of FI and the Industry is Banks or Building Societies

*accepting this parameter depends on the account setup
**Ultimate Originator Name and Address are required by default, for non-PSP accounts. For PSP accounts, only the SubaccountNumber property must be used, which can be obtained from the /v1/Accounts({accountId})/Subaccounts endpoint.\

Creating an instruction withdrawal

The basic request to create a withdrawal configured and triggered by completion of an instruction is in the form

POST /api/v1/Withdrawals/CreateInstructionWithdrawal HTTP/1.1
Host: portal.wearefreemarket.com
Authorization: Bearer {authToken}
Content-Type: application/json

{
  "InstructionId": {InstructionId},
  "BeneficiaryId": {BeneficiaryId},
  "PaymentPurposeId": 1,
  "UltimateOriginator": {
    "Name": "Ultimate Originator Name",
    "Address": {
      "Street": "street name",
      "HouseNumber": "123/A",
      "HouseName": "house name",
      "FlatNumber": "7F",
      "District": "district name",
      "Town": "town",
      "County": "county",
      "PostCode": "ABC123",
      "CountryCode": "country code"
    },
    "SubaccountNumber": "A123456"
  },
  "PaymentChargesCode": "payment charges code",
  "ReceiverLei": "01234567890123456789",
  "BoEPurposeCodeId": 130
}

parameter	description	data type	validation rules
InstructionId	The instruction id which will trigger this withdrawal	int	required
BeneficiaryId	The beneficiary id who will receive the funds	int	required
PaymentPurposeId	The payment purpose id	int	Mandatory for beneficiaries with bank accounts in United Arab Emirates (all currencies) or China (CNH only).
UltimateOriginator	The ultimate originator. Use only if you are creating a withdrawal on behalf of another party or entity.	object	*
.Name	The ultimate originator name, up to 35 characters	string	required **
.Address	The ultimate originator address structure	object	required **
.Street	The name of the street	string	required
.HouseNumber	The number of the house on the street, if applicable	string
.HouseName	The name of the house on the street, if applicable	string
.FlatNumber	The number of the flat in the house, if applicable	string
.District	The name of the district, if applicable	string
.Town	The name of the town	string	required
.County	The name of the county, if applicable	string
.PostCode	The post code, if applicable	string	required where supported
.CountryCode	a ISO 3166-1 alpha-2 two character country code	string	required
.SubaccountNumber	Subaccount Number as obtained from the /v1/Accounts({accountId})/Subaccounts endpoint to be used as an Ultimate Originator	object	required **
PaymentChargesCode	The payment charges code, OUR or SHA. SHA: you will pay the FreemarketFX fee for the withdrawal, the beneficiary will incur charges raised by other banks handling the payment. OUR: you will pay the FreemarketFX fee for the withdrawal, plus a fee which covers charges raised by other banks handling the payment.	string	*
BoEPurposeCodeId	Id of a a new code required by Bank of England for GBP payments. To see all of our supported codes use the following endpoint /v1/Withdrawals/BoEPaymentPurposes	int	conditional - only required when the CurrencyCode is GBP
ReceiverLei	A Legal Entity Identifier (LEI) is a 20-character alphanumeric code that uniquely identifies a legal entity engaged in financial transactions - Search for a LEI. For more information around LEIs, please click here.	string	conditional - only required when the CurrencyCode is GBP and the beneficiary is a company with a Vertical of FI and the Industry is Banks or Building Societies

*accepting this parameter depends on the account setup
**Ultimate Originator Name and Address are required by default, for non-PSP accounts. For PSP accounts, only the SubaccountNumber property must be used, which can be obtained from the /v1/Accounts({accountId})/Subaccounts endpoint.

Supporting Documents

in case you need to create a Withdrawal with supported documents, the request needs to be issued as multipart/form-data with documents added as separate parts, divided by the boundary.

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

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

{
  "AccountId": {AccountId},
  "CurrencyCode": {CurrencyCode},
  "Amount": 1234.56,
  "BeneficiaryId": {BeneficiaryId},
  "Reference": "ref xyz",
  "Description": "xxx/yyy/123",
  "PaymentPurposeId": 1,
  "UltimateOriginator": {
    "Name": "Ultimate Originator Name",
    "Address": {
      "Street": "street name",
      "HouseNumber": "123/A",
      "HouseName": "house name",
      "FlatNumber": "7F",
      "District": "district name",
      "Town": "town",
      "County": "county",
      "PostCode": "ABC123",
      "CountryCode": "country code"
    },
    "SubaccountNumber": "A123456"
  },
  "PaymentChargesCode": "payment charges code",
  "ReceiverLei": "01234567890123456789",
  "BoEPurposeCodeId": 130
}

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

< C:\Users\doc-location\document.pdf


--Boundary

Get Required Additional Information For Beneficiary

To get a list of required additional properties for beneficiary currency code/bank country code/address country code combination it is needed to hit specific GET endpoint.

GET /v1/Beneficiaries/{currencyCode}/RequiredAdditionalInformation?beneficiaryCountryCode={beneficiaryCountryCode}&beneficiaryBankCountry={beneficiaryBankCountry}&beneficiaryType={beneficiaryType} HTTP/1.1
Host: portal.wearefreemarket.com
Authorization: Bearer {authToken}
Content-Type: application/json

Get Information on Withdrawal Payment Purposes

To get a list of supported payment purposes required to create withdrawals.

### With a country code
GET /api/v1/Withdrawals/PaymentPurposes(CountryCode='{CountryCode}') HTTP/1.1
Host: portal.wearefreemarket.com
Authorization: Bearer {authToken}

### Without a country code, i.e. generic payment purposes
GET /api/v1/Withdrawals/PaymentPurposes(CountryCode=null) HTTP/1.1
Host: portal.wearefreemarket.com
Authorization: Bearer {authToken}

Get Information on Bank of England Payment Purposes

To get a list of supported Bank on England payment purposes for required for the creation of GBP withdrawals.

GET /api/v1/Withdrawals/BoEPaymentPurposes HTTP/1.1
Host: api.wearefreemarket.com
Authorization: Bearer {authToken}

Webhook events

Withdrawal created

This event is raised when a new withdrawal has been created.

 [
    {
        "EntityType": "Withdrawal",
        "EntityId": 1234,
        "Reason": "WithdrawalCreated",
        "ApiUrl": "https://portal.wearefreemarket.com/api/v1/Withdrawals(1234)"
    }
]

Withdrawal completed

This event is raised when a new withdrawal has been completed - when we have received a statement from a bank that confirms that the funds have left our bank account.

 [
    {
        "EntityType": "Withdrawal",
        "EntityId": 1234,
        "Reason": "WithdrawalCompleted",
        "ApiUrl": "https://portal.wearefreemarket.com/api/v1/Withdrawals(1234)"
    }
]

Withdrawal canceled

This event is raised when a withdrawal has been canceled and the allocated funds have been returned to your account.

 [
    {
        "EntityType": "Withdrawal",
        "EntityId": 1234,
        "Reason": "WithdrawalCanceled",
        "ApiUrl": "https://portal.wearefreemarket.com/api/v1/Withdrawals(1234)"
    }
]