Using the Onboarding API

BETA

Intro

This document provides important information relevant to integrating with the Onboarding API in the Pilot phase.

Before the end of the Pilot, some of these rules will be further strengthened with additional validations on the Currencycloud side. We will always give you at least 10 days notice before we make any changes that may be breaking during the pilot period.

Accepted format

The format of strings should be provided as UTF-8 characters. Criteria such as Enums, Max Length or Min Length will be provided in the description.

All files uploaded must be JPG, PNG or PDF under 10MB, for further details please see Document Data Points Explained below.

Terms & conditions

It is really important that any applicant you seek to onboard through our Onboarding APIs:

• has had sight of, understands and accepts Currencycloud's terms and conditions; and
• understands that they are being provided with a regulated service by Currencycloud.

You must present the following wording to users signing up for Currencycloud's service:

Payment and foreign currency exchange service are provided by The Currency Cloud Ltd. The Currency Cloud Ltd is authorised by the Financial Conduct Authority for issuing of electronic money and the provision of payment services with FCA registration number 900199. If you are located in the European Economic Area, payment services are provided by Currencycloud B.V. Currencycloud B.V. is authorised by De Nederlandsche Bank N.V. for issuing of electronic money and the provision of payment services with DNB registration number R142701.

Your build must also present users with Currencycloud's terms & conditions and ensure that consent to these is obtained, and recorded on the application when it is sent to our API by setting the field agreed_to_terms_and_conditions to TRUE.

For corporate applications, you should also be sure that the person completing the application has a right to apply for this service on behalf of the company and record this on the application by setting the field agreed_to_corporate_authority to TRUE.

In both cases, the person agreeing to terms and conditions and corporate authority (i.e. the person filling the form) should be recorded on the application as the contact_name.

Authentication

To use the Onboarding API, you must first authenticate to Currencycloud. Rather than providing your username and API key with every request, you sign in once and receive a temporary authentication token. Please see our Authentication guide for step by step instructions for starting a new API session.

Onboarding

Onboarding applications can be submitted by either an individual or a corporate. This is the attribute called entity_type set on a Form.

Individual and corporate applications are assembled slightly differently. An overview of their respective structures is as follows:

Individual

{
  "data":{
     "agreed_to_marketing_emails":true,
     "agreed_to_terms_and_conditions":true,
     "country":"GB",
     "contact_name":"Jane Smith",
     "email":"[email protected]",
     "entity_type":"individual",
     "phone_number":"+4414898340839"
  },
  "account_usage":{
     "collections_account":true,
     "primary_purpose":"investment_activity",
     "source_of_funds":"property_sale"
  },
  "people":[
     {
        "roles":[
           "user"
         ],
         "first_name":"Jane",
         "last_name":"Smith",
         "dob":"1990-07-22",
         "phone_number":"+4414898340839",
         "email":"[email protected]",
         "home_country":"GB",
         "personal_address":{
            "city":"London",
            "street":"Steward Street",
            "country":"GB",
            "postal_code":"E1 6fQ",
            "building_number":"12"
          }
      }
  ]
}

Corporate

{
   "data":{
      "agreed_to_marketing_emails":true,
      "agreed_to_terms_and_conditions":true,
      "agreed_to_corporate_authority":true,
      "country":"GB",
      "contact_name":"Jane Smith",
      "email":"[email protected]",
      "entity_type":"corporate",
      "phone_number":"+4414898340839",
      "business_information":{
         "business_country":"GB",
         "company_name":"A Great Company",
         "trading_name":"Great Company",
         "legal_entity_type":"limited_liability_partnership",
         "sector":"advertising_or_public_relations_or_marketing",
         "company_registration_number":"12345",
         "vat_number":"12345",
         "incorporation_date":"1984-04-08",
         "business_website":"www.greatcompany.com",
         "registered_address":{
            "city":"London",
            "street":"Something Street",
            "country":"GB",
            "postal_code":"E1 6FQ",
            "building_number":"12"
         }
      },
      "account_usage":{
         "collections_account":true,
         "collection_currencies":[
            "GBP",
            "USD"
         ],
         "payment_currencies":[
            "GBP",
            "USD"
         ],
         "transaction_countries":[
            "GB",
            "US"
         ],
         "one_off_transaction":false,
         "estimated_monthly_transaction_currency":"GBP",
         "estimated_monthly_transaction_value":100000,
         "estimated_monthly_transaction_volume":100,
         "source_of_funds":"business_revenue",
         "primary_purpose":"investment_activity"
      },
      "people":[
         {
            "roles":[
               "director", "user", "ultimate_business_owner"
            ],
            "first_name":"Joe",
            "last_name":"Blogs",
            "dob":"1990-12-25",
            "phone_number":"+4414898340839",
            "email":"[email protected]",
            "ownership_percentage":74,
            "home_country":"GB",
            "personal_address":{
               "city":"London",
               "street":"Sesame Street",
               "country":"GB",
               "postal_code":"SM1 3ST",
               "building_name":"string",
               "building_number":"1"
            }
         }
      ]
   }
}

Base URLs

Endpoints

The following endpoints are provided by the Onboarding API:

GET /v1/countries
GET /v1/countries/{country_code}/document_types
GET /v1/currencies/supported
GET /v1/forms
GET /v1/forms/{form_id}
GET /v1/forms/{form_id}/people
GET /v1/forms/{form_id}/people/{person_id}
GET /v1/forms/{form_id}/account_usage
GET /v1/forms/{form_id}/business_information
GET /v1/forms/{form_id}/documents
GET /v1/forms/{form_id}/documents/{document_id}/document_images
POST /v1/forms
POST /v1/forms/{form_id}/submit
POST /v1/forms/{form_id}/people
POST /v1/forms/{form_id}/documents
POST /v1/forms/{form_id}/documents/{document.id}/document_images
PUT /v1/forms/{form_id}
PUT /v1/forms/{form_id}/people/{person_id}
PUT /v1/forms/{form_id}/account_usage
PUT /v1/forms/{form_id}/business_information
DELETE /v1/forms/{form_id}
DELETE /v1/forms/{form_id}/people/{person_id}
DELETE /v1/forms/{form_id}/account_usage
DELETE /v1/forms/{form_id}/business_information
DELETE /v1/forms/{form_id}/documents/{document_id}
DELETE /v1/forms/{form_id}/documents/{document_id}/document_images/{document_image_id}

Form data points

These data points record basic information about the application form itself (who's filling it in, where the application comes from, relevant permissions etc).

People - Identify vs. Verify

Throughout the Onboarding process, we collect information about various 'People'. For example, details of users who will be given access to the applicant's account (if approved), or details of directors or shareholders of corporate applicants.

Depending on the context, we will either need to identify or verify each person.

Identification

For People we need to identify, only limited information is required:

• first_name
• last_name
• roles
• home_country

Verification

For People we need to verify, we require more information (and this varies depending on the home_country of the individual).

• first_name
• Last_name
• roles
• home_country
• dob
• personal_address_attributes (must match home country)

IF home_country= US:

• id_number (this is their social security number)

IF home_country= any country other than UK or US:

• ID document (see Uploading Documents below)

People data points

Attributes shown in green are needed for persons we need to identify. In addition, for persons we need to verify we will also need to collect the attributes shown in blue. Items shown in red are only relevant for users with certain 'roles' (e.g. users, or ultimate beneficial owners).

Account Usage data points

These data points let Currencycloud know a bit more about how the applicant plans to use their account. All these data points apply for corporate applications, but only a small subset are needed for individual applications (shown in green).

Business Information data points

This is only relevant for corporate applications. These are data points relevant to collect about the business applying for an account (some are optional, others are mandatory).

Address data points

Structuring addresses accurately is very important as it improves the success rate of our automated checks. Currencycloud uses GBG Loqate to find and submit structured addresses.

Primary Purpose Enums

-- intercompany_transfers
-- liquidity_or_fx
-- liquidity_fx
-- paying_an_individual
-- payment_to_an_individual
-- paying_suppliers_or_bills
-- investment_activity
-- repatriating_overseas_earnings
-- collecting_funds_from_clients
-- property_purchase_or_sale
-- other

Error codes

How it all fits together

Individuals

Individual applications will only have one Person associated with them, who is both the person filling the form and the person applying for an account:

• We need to verify this Person: so you will need to provide full verification details for them.

• They must also be a User: they must have roles=["user"] so that they are given a user account.

Individual applications must also include basic Account Usage information, and Form attributes. In this case, the Form data points captured regarding who is filling the form and accepting our terms should also refer to the Person associated with the account.

Corporates

People

Corporate applications can have 3 kinds of Person associated with them: ultimate business owners, directors and users. The same person can be multiple.

Who are Ultimate Business Owners?

UBOs are natural persons (not corporates) who own some percentage of the business. They might hold their ownership directly, or they might hold it via some other entity or entities.

We only need to know about UBOs owning 10% or more of the corporate applicant. An explanation of how to determine this is set out below. In the example, we would need to know about Person A and Person C, since they both own more than 10% of Company A either directly or indirectly.

We would not need to know about:

• Companies B, C and D, since there are corporates rather than people.
• Person B, since they own less than 10% of Company A.
• Any person owning Company D, as even if Company D was wholly owned by one person, the maximum amount they could own of Company A would be 7.5% which is below 10%.

Who are Directors?

Directors are people who 'control' the company. Where a business doesn't have a board of directors, we need to be told about the equivalent. This might be, for example, managing partners, managing members, or trustees.

Who are Users?

Any person wanting to be a user on the corporate account (if the application is successful).

What information do we need to collect?

For corporate applications, we need to collect the following:

Directors:

• The application must have at least one director.
• Each director of the company must be added as a Person with roles: ["director"]
• For one director, we need verification details.
• For all the rest, we need identification details.

Ultimate business owners (UBOs):

• Each UBO owning 10% or more of the company, directly or indirectly, must be added as a Person with roles: ["ultimate_business_owner"]
• An application may not have any ultimate_business_owner, if no one person owns 10% or more.
• For one UBO, we need verification details.
• For all the rest, we need identification details.

Users:

• The application must have at least one user.
• Each Person wanting a user account should be added with roles=["user"]
• For all users, we need verification details.
• We also need an email, which will be used to login to their user account.

Note that a single Person may hold more than one role at the same time (e.g. roles=["user", "director"]). If you collect verification details for a single person who is both a UBO and a director, this will satisfy the verification requirement for both.

Business Information

When providing Business Information about a corporate, whether requiring "company_registration_number" and "vat_number" is appropriate will depend on the legal_entity type. Currencycloud currently uses the following grid to determine what is and isn't required for our various legal entity types:

Additional requirements if business has no online presence

Businesses with no online presence should provide us with:

• details of their business_activity description; and
• documentary proof of business activity (e.g. marketing materials, product list, contracts, sales invoices dated in the last 3 months).

Uploading documents

The following is an example workflow for attaching a document to a form.

Step 1

With a valid form_id create a document using the POST documents endpoint.

{
  "document_type": "passport",
  "category": "proof_of_identity"
}

Response

{
    "data": {
        "id": "11111111-2222-2222-2222-111111111111",
        "document_type": "passport",
        "category": "proof_of_identity",
        "created_at": "2022-11-30T12:00:00Z",
        "updated_at": "2022-11-30T12:00:00Z"
    }
}

Step 2

Using the document_id from step 1 Create a document image using the POST document images endpoint.

{
  "image": "base64",
  "side": "front"
}

Response

{
    "data": {
        "id": "11111111-2222-2222-2222-111111111111",
        "side": "front",
        "created_at": "2022-11-30T12:00:00Z",
        "updated_at": "2022-11-30T12:00:00Z"
    }
}

Step 3

Using the document_id from step 1 create an entity with documents attached.

Step 4 Optional

Should you wish to update an entity with additional documents then using the appropriate PUT endpoint is required.

Document data points explained

What to upload?

Other than ID Documents that may be required to verify individuals, our team may require additional documentation in relation to corporate applications. These documents can be uploaded ahead of time, referenced to the Form.

Proving that they're a real operating company

We need to prove that they're a real business operating as a going concern. If we're unable to do this through our own 3rd party providers, we'll need documentary evidence such as:

To prove they're a real company:

• Articles or certificate of incorporation/organisation/registration
• IRS tax exempt status s.501(c)(3), charities register extract, trust deed.
• To prove they're operating:
• Balance sheet / P&L
• Annual financial statement
• Bank statement
• Contracts -Recent invoices

Understanding source of funds

For young companies, or if we deem a company to be high risk, we need to understand a bit more about where their money comes from. In these cases, we may ask for documentary evidence of source of funds.

This can be provided by the end-user ahead of time. Applicable evidence would depend on the source_of_funds indicated by the user in Account Usage. For example, if source_of_funds is a loan, then loan documentation would be helpful evidence. For a property_sale, they might provide transaction documents from the sale etc.

Understanding company structure

We need to understand the ownership and control structure of the business applying for an account. This may be particularly hard if the business is part of a complex ownership structure, or in jurisdictions or for legal entity types where information about company ownership is hard to obtain.

The following documents can help us to understand who owns a corporate:

• Corporate structure chart
• Shareholder register
• Annual financial statement
• Partnership registration confirmation
• Partnership agreement or certificate
• Charities register extract, trust deed
• Trust deed
• Operating agreement
• Articles of incorporation
• Stock certificate
• Confirmation statement

And these documents can help us understand who controls a corporate (e.g. directors, partners, managing members etc):

• Register of directors
• Annual financial statement
• Partnership registration confirmation or agreement
• Charities register extract, trust deed\
• Operating agreement
• Corporate resolution
• Register of directors
• Account authorization form
• Copy of by-laws
• Confirmation statement