Onboarding - account opening API Service

Definitions

Entity Defintion
KYC Definition
Account Definition

Define an Entity

An Entity can be both a Corporate (moral person) and an Individual (physical person) listed in the following couterparties:

Lead: Basic form of an Entity.
Customer: When coupled with a KYC (and validated by IbanFirst).
Customer's Client: When coupled with a KYCC (and validated by IbanFirst)
Shareholder: When coupled with a KYCS (and validated by IbanFirst).
Users: When coupled with a KYCU (and validated by IbanFirst).
Supplier: When coupled with an Account.
Beneficiary: When coupled with an Account.

Define the KYC(s)

Know Your Customer (KYC) is the process identifying and verifying the identity of an Entity. Several level of KYC may be required depending on the type of relationship between IbanFirst and the Entity:

Know Your Customer (KYC): Standard Entity Identification Procedure for direct clients.
Know your Customers' Shareholder (KYCS): Specific Entity Identification Procedure for shareholders of IbanFirst's direct clients.
Know your Customers' Users (KYCU): Specific Entity Identification Procedure for users of IbanFirst's direct clients.
Know Your Customers' Counterparty (KYCC) : Third-party Customer Identification Procedure for indirect clients of licensed IbanFirst's direct clients.

Define an Account

An Account is identifying the bank details of an Entity thats can be an IbanFirst's Client or not.

IBAN account (IBAN): Standard Payment Account provided by IbanFirst for direct registered Customers or Customers' Clients.
Escrow IBAN account (EIBAN): Specific Escrow Account provided by IbanFirst for capital deposit purpose.
Liquidity account: TBD.
Counterparty account: external bank account referenced with IbanFirst (typically a Beneficiary of a payment).

Define the KYT

Know Your transaction (KYT) is the process permitting to spot potential risky transactions and unusual behaviour on an account.

Routes

Route	Description
`POST /entity/`	Post a new entity
`POST /entity/-{id}/kyc`	Add a KYC to an entity
`POST /entity/-{id}/kyc/documentation/`	Post a Documentation related to an entity
`POST /entity/-{id}/kyc/organizationStructure/`	Post an Organisation Structure related to an entity
`POST /contact/`	Post a new contact

Details

Create an Entity

Method: POST 
URL: /entity/

Create a new entity.

Parameters:

Field	Type	Required	Description
registeredParentNumber	String(100)	Optional	The unique legal identifier of the entity's parent registered company.
registeredNumber	String(100)	Required	The unique legal identifier of the entity opening the account.
registeredName	String(100)	Required	The legal name of the entity.
commercialName	String(100)	Optional	The commercial name of the entity.
tag	String(100)	Optional	The customized name of the entity.
address	Address Object	Required	The entity address.
phoneNumber	phone Object	Optional	The phone number of the entity.
email	email Object	Optional	The email address of the entity.
primaryUrl	email Object	Optional	The email address of the entity.

Add KYC informations to an Entity

Method: POST 
URL: /entity/-{id}/kyc/details

Add KYC informations to an Entity.

Parameters:

Field	Type	Required	Description
activityCode	NAF	Required	The code identifying the type of business.
registrationDate	Date	Required	The legal date of creation of the entity.
legalForm	legalForm	Required	The legal form of the entity.
authorizedCapital	amount Object	Required	The amount in shareholding capital.

Add KYC documentation to an Entity

Method: POST 
URL: /entity/-{id}/kyc/documentation

Add KYC documentation to an Entity.

Parameters:

Field	Type	Required	Description
proofOfIncorporation	page	Required	The code identifying the type of business.
registrationDate	Date	Required	The legal date of creation of the entity.
legalForm	legalForm	Required	The legal form of the entity.
authorizedCapital	amount Object	Required	The amount in shareholding capital.

Add KYC Organization Structure to an Entity

Method: POST 
URL: /entity/-{id}/kyc/organisationStructure

This structure describes an organisation structure.

Parameters:

Field	Type	Required	Description
entities	Array[entities]	Optional	List of the entities that own more than 10% of the entity we want to create.
contacts	Array[contacts]	Optional	List of the contacts that own more than 10% of the entity we want to create.

API Objects

Address Object
Entity Object
entities
Contact Object
contacts
Account Object
Phone Object
Individual Name Object
Amount Object

Details

Entity Object

What we call an Entity can be only an company incorporated in France or Belgium. When an entity is specified as part of a JSON body, it is encoded as an object with the following fields:

Object resources:

Field	Type	Description
id	ID	The IF code identifying the entity.
registeredParentNumber	String(100)	The unique legal identifier of the entity mother house.
registeredNumber	String(100)	The unique legal identifier of the entity opening the account.
registeredName	String(100)	The legal name of the entity.
commercialName	String(100)	The commercial name of the entity.
tag	String(100)	The customized name of the entity.
address	Address Object	The entity address.
activityCode	NAFID	The code identifying the type of business.
registrationDate	Date	The legal date of creation of the entity.
legalForm	legalForm	The legal form of the entity.
authorizedCapital	amount Object	The amount in shareholding capital.
phoneNumber	phone Object	The phone number of the entity.

Example:

"entity": {
    "id": "ND4ue2",
    "registeredParentNumber": "	814455614",
    "registeredNumber": "81445561400010",
    "registeredName": "DJPAD",
    "commercialName": "null",
    "tag":"null",
    "address": {address},
    "activityCode":"6201Z",
    "registrationDate":"2015-11-04",
    "legalForm":"SARL unipersonnelle",
    "authorizedCapital":{amount},
    "phoneNumber":{phone},
}

Contact Object

What we call a contact can be only an individual registered in France or Belgium. When an entity is specified as part of a JSON body, it is encoded as an object with the following fields:

Object resources:

Field	Type	Description
id	ID	The IF code identifying the contact.
registeredNumber	String(100)	The unique legal identifier of the contact.
registeredNCountry	String(100)	The registering country of the contact.
registeredName	Individual_Name Object	The individual name of the contact.
tag	String(100)	The customized name of the contact.
address	Address Object	The contact address.
birthDate	Date	The birthdate of the contact.
phoneNumber	phone Object	The phone number of the entity.
position	position Object	The position of the entity.
idProof	idProof Object	The url where the file is stored.
addressProof	addressProof Object	The url where the file is stored.

Example:

"contact": {
    "id": "ND4ue2",
    "registeredNumber": "81445561400010",
    "registeredName": {individual_name},
    "tag":"null",
    "address": {address},
    "birthDate":"1980-11-04",
    "phoneNumber":{phone},
    "position":{position},
}

Account Object

When an Account is specified as part of a JSON body, it is encoded as an object with the following fields:

Object resources:

Field	Type	Description
id	ID	The code identifying the account.
currency	Currency	The three-digit code specifying the currency of the account.
tag	String(50)	Custom reference of the account.
accountNumber	String(40)	The code specifying the account (can be either an Iban or an account number).
correspondentBank	ID	The intermediary bank details, used to reach the beneficiary bank.
holderBank	ID	The recipient bank details, holding the account.
holder	Entity Object	The recipient details, owner of the account.

Example:

"account": {
    "id": "NT4edA",
    "currency": "EUR",
    "tag": "My wallet account EUR",
    "accountNumber": "516981638516313513",
    "correspondantBank":{correspondentBank}
    "holderBank":{beneficiaryBank}
    "holder":{beneficiary}
}

Address Object

When an address is specified as part of a JSON body, it is encoded as an object with the following fields:

Object resources:

Field	Type	Description
street1	String(255)	The street for the address described.
street2	String(255)	The continuation street for the address described.
postCode	String(15)	The ZIP/Post code for the address described.
city	String(35)	The city for the address described.
state	String(2)	The state code for the address described. This field could be required if the country use a state system, like United States or Canada. To see a full list of state code, please refer to this site.
country	String(2)	The two-letters abbreviation for the country, following the ISO-3166 for the address described.

Example:

"address": {
	"street": "4 NEW YORK PLAZA, FLOOR 15",
	"postCode": "10004",
	"city": "NEW YORK",
	"state": "NY",
	"country": "US"
}

Phone Object

When a phone number is specified as part of a JSON body, it is encoded as an object with the following fields:

Object resources:

Field	Type	Description
countryCode	String(4)	Numeric country code. Optional +, followed by 1-3 digits.
phoneNumber	String(15)	Country code and phone number.

Example:

"phone": {
    "countryCode": "+33",
    "phoneNumber": "81445561400010",
}

Individual Name Object

When a phone number is specified as part of a JSON body, it is encoded as an object with the following fields:

Object resources:

Field	Type	Description
first	String(35)	The individual's first name. Truncated after the first 35 characters.
first	String(35)	The individual's middle name. Truncated after the first 35 characters.
last	String(35)	The individual's last name. Truncated after the first 35 characters.

Example:

"phone": {
    "first": "John",
    "last": "Doe",
}

Amount Object

When an amount of currency is specified as part of a JSON body, it is encoded as an object with the following fields:

Object resources:

Field	Type	Description
value	QuotedDecimal	The quantity of the currency.
currency	Currency	The three-digit code specifying the currency related to the amount.

Example:

"amount": {
	"value": "10000.00",
	"currency": "GBP"
}

Formatting Conventions

Date Type

The Date type represents a date with its year, month and day.

Type	Real type	format	description	example
Date	String	`^[0-9]{4}\-[0-9]{2}\-[0-9]{2}$` - `YYYY-MM-DD`	A String representing a date by its year, month and day in month.	`2015-07-14`

maxchampoux/iBanFirst-Repository

Onboarding - account opening API Service

Definitions

Define an Entity

Define the KYC(s)

Define an Account

Define the KYT

Routes

Details

Create an Entity

Add KYC informations to an Entity

Add KYC documentation to an Entity

Add KYC Organization Structure to an Entity

API Objects

Details

Entity Object

Contact Object

Account Object

Address Object

Phone Object

Individual Name Object

Amount Object

Formatting Conventions

Date Type