EUR Virtual Account
This section describes the requirements for creating a virtual account in EURO (EUR). We would like to start by explaining how permanent EUR virtual accounts can be created on Fincra. For EUR, we currently only offer individual
accounts.
API Reference: create virtual account endpoint
Important
- Funds received by a virtual account created, settles in the respective currency balance of the merchant.
API Guide
1 - Collect Customer Details
To create a virtual account, you'll need to pass information such as currency, accountType, meansOfID KYCInformation, etc.
Please find below the request parameters for the endpoint.
Field | Mandatory | type | Description |
---|---|---|---|
currency | Yes | string | The virtual account currency.e.g EUR |
accountType | Yes | string | The virtual account type. For EUR, we currently only offer individual accounts. |
meansOfId | Yes | string/array | The customer's means of identification which should be a valid government ID e.g passport, driver license. Please see the Accepted Documents |
utilityBill | Yes | string | Electricity bills, water bills or any detailed invoice showing the usage of a service. This can be a File Upload or a URL link to the document. |
bankStatement | Yes | string | Account statement from the user's bank. This can be a File Upload or URL link to the document. |
KYCInformation | Yes | Object | KYC Information object |
KYCInformation.firstName | Yes | string | The customer's first name. This is required to create an individual account |
KYCInformation.lastName | Yes | string | The customer's last name. This is required to create an individual account |
KYCInformation.birthDate | Yes | string | The birthdate of the customer(YYYY-MM-DD). Please ensure that the DOB presented here matches with the date of birth visible on the means of ID. |
KYCInformation.nationality | Yes | string | The birthplace of the customer |
KYCInformation.email | Yes | string | The customer's email. |
KYCInformation.address | Yes | Object | The address of the customer |
KYCInformation.address.countryOfResidence | Yes | string | The address of the country |
KYCInformation.address.state | Yes | string | The address of the state |
KYCInformation.address.zip | Yes | string | The zip code must be valid. |
KYCInformation.address.street | Yes | string | The street name |
KYCInformation.address.city | Yes | string | The city name |
KYCInformation.address.number | Yes | string | The house number |
KYCInformation.sourceOfIncome | Yes | string | Customer's source of income |
KYCInformation.accountDesignation | Yes | string | Specific use of the account e.g for personal use, corporate use, school fee payments etc. |
KYCInformation.incomeBand | Yes | string | Customer's income band. IncomeBand can be described as earning range or salary range of the customer. |
KYCInformation.phone | Yes | string | The customer's phone number |
KYCInformation.employmentStatus | Yes | string | Customer's employment status |
KYCInformation.document | Yes | object | The document |
KYCInformation.document.type | Yes | string | The type of ID document e.g passport , driverLicense , idCard .Please see the required values here |
KYCInformation. document.number | Yes | string | The number on the document |
KYCInformation. document.issuedCountryCode | Yes | string | The country that issued the document.Should be in ISO 3166-1 alpha-2 β two-letter country codes format(NG) |
KYCInformation. document.issuedBy | Yes | string | The government agency in charge of issuing the document. |
KYCInformation. document.issuedDate | Yes | string | The date the document was issued("YYYY-mm-dd") |
KYCInformation. document.expirationDate | Yes | string | The expiration date on the document ("mm-dd-YYYY"). |
KYCInformation.occupation | Yes | string | The occupation of the customer. |
merchantReference | No | string | A unique ID/reference of the virtual account on your system. |
Accepted identity documents for EUR virtual account.
Document | API Value | Description |
---|---|---|
International Passport | passport | The International passport of the customer (This is the only ID type where a string url is accepted as the "meansOfId ", payload. For the rest, an array is expected.) |
Driver License | driverLicense | The driver's license of the customer. (When uploading this in the meansOfId field, ensure to send two string urls in an array, one for front and one for back). |
National ID card only | nationalId | National ID card only, (Not NIN or v-NIN) |
2 - Request a virtual account
Make an API request to the create virtual account endpoint
Endpoint:
{{base_url}}/profile/virtual-accounts/requests
curl --location 'https://api.fincra.com/profile/virtual-accounts/requests' \
--header 'api-key: <Your API secret key>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
Payload:
{
"currency": "EUR",
"accountType": "individual",
"utilityBill": "https://yourtestbucket.s3.amazonaws.com/va_documents/utility-bill.pdf",
"bankStatement": "https://yourtestbucket.s3.amazonaws.com/va_documents/account-statement.pdf",
"meansOfId": [
"https://yourtestbucket.s3.amazonaws.com/va_documents/passport.pdf"
],
"KYCInformation": {
"address": {
"state": "State",
"city": "City",
"street": "Full Street Address",
"zip": "100020",
"countryOfResidence": "NG",
"number": "25"
},
"email": "[email protected]",
"incomeBand": "$0 - $2,000",
"sourceOfIncome": "Salary",
"accountDesignation": "Personal use",
"phone": "08012345678",
"occupation": "Business",
"nationality": "NG",
"birthDate": "1998-03-29",
"firstName": "John",
"lastName": "Doe",
"document": {
"type": "passport",
"number": "A89238923",
"issuedCountryCode": "NG",
"issuedBy": "government",
"issuedDate": "2017-09-07",
"expirationDate": "2027-07-23"
},
"employmentStatus": "Business",
}
}
You would receive a JSON snippet with the details of the virtual account, along with the id
and status
:
{
"success": true,
"message": "Thank you, John Doe. We are now processing your EUR account request",
"data": {
"status": "pending",
"isActive": false,
"accountNumber": null,
"merchantReference": null,
"virtualAccountType": "additional",
"riskRating": "high",
"channelKycUpdateStatus": null,
"channelKycUpdateResponse": null,
"metadata": null,
"_id": "661e83489349bwe342c6a70",
"business": "62787427843dfn3848ws",
"currency": "EUR",
"accountType": "individual",
"entityType": "main_account",
"currencyType": "fiat",
"createdAt": "2024-04-16T14:03:50.757Z",
"updatedAt": "2024-04-16T14:03:50.757Z"
}
}
Important Notes:
\_id
: This is the unique Identifier for the virtual account that was just created. Ensure to save this ID, as it would be needed when trying to retrieve the details of the created bank account or when retrieving transaction records.- It is also good to note that other fields would be included in the response. The ones shared are the ones that are necessary to note. The full payload sent in the request would also be returned in this response.
3 - Receive and validate webhook notification
Listen for webhook events. We will send a notification to your webhook URL that indicates the status of the virtual account creation. Read our guide on securing and validating the webhook notification on your end.
Webhook Response:
{
"event": "virtualaccount.approved",
"data": {
"id": "661e83489349bwe342c6a70",
"business": "62787427843dfn3848ws",
"isSubAccount": false,
"currency": "EUR",
"currencyType": "fiat",
"status": "approved",
"email": "[email protected]",
"accountType": "individual",
"accountInformation": {},
"accountOpeningFee": 0,
"isPermanent": true,
"virtualAccountType": "additional",
"createdAt": "2024-04-17T13:41:38.658Z",
"updatedAt": "2024-04-17T13:46:01.528Z"
}
}
{
"event": "virtualaccount.declined",
"data": {
"id": "661e83489349bwe342c6a70",
"business": "62787427843dfn3848ws",
"isSubAccount": false,
"currency": "EUR",
"currencyType": "fiat",
"status": "declined",
"accountType": "individual",
"reason": "Document type is different from the provided options",
"accountOpeningFee": 0,
"virtualAccountType": "additional",
"createdAt": "2024-04-16T14:07:12.781Z",
"updatedAt": "2024-04-16T14:08:32.442Z"
}
}
{
"event": "virtualaccount.declined",
"data": {
"id": "661e83489349bwe342c6a70",
"business": "62787427843dfn3848ws",
"isSubAccount": false,
"currency": "EUR",
"currencyType": "fiat",
"status": "declined",
"accountType": "individual",
"reason": "Address on the document does not match with the provided one",
"accountOpeningFee": 0,
"virtualAccountType": "additional",
"createdAt": "2024-04-17T08:34:44.138Z",
"updatedAt": "2024-04-17T08:36:47.462Z"
}
}
{
"event": "virtualaccount.declined",
"data": {
"id": "661e83489349bwe342c6a70",
"business": "62787427843dfn3848ws",
"isSubAccount": false,
"currency": "EUR",
"currencyType": "fiat",
"status": "declined",
"accountType": "individual",
"reason": "Document number is not clearly visible",
"accountOpeningFee": 0,
"virtualAccountType": "additional",
"createdAt": "2024-04-17T08:39:22.670Z",
"updatedAt": "2024-04-17T08:41:05.941Z"
}
}
{
"event": "virtualaccount.declined",
"data": {
"id": "661e83489349bwe342c6a70",
"business": "62787427843dfn3848ws",
"isSubAccount": false,
"currency": "EUR",
"currencyType": "fiat",
"status": "declined",
"accountType": "Error occured while approving virtual account, Missing or invalid parameter: registrant.individual.address.zip - Invalid zip.",
"accountOpeningFee": 0,
"virtualAccountType": "additional",
"createdAt": "2024-04-17T17:11:27.858+00:00",
"updatedAt": "2024-04-17T17:13:27.858+00:00"
}
}
Important Notes:
id
: This is the unique Identifier for the virtual account that was just created. Ensure to save this ID, as it would be needed when trying to retrieve the details of the created bank account or when retrieving transaction records.
4 - Retrieving the details of a virtual bank account
The details of a Virtual Bank Account can be retrieved at any time after creating the account. To do this, you will need to make an API request to the Virtual Bank Account Query API.
Endpoint:
{{base_url}}/profile/virtual-accounts/<virtual account id>
curl --location 'https://api.fincra.com/profile/virtual-accounts/{{virtual_account_id}}' \
--header 'accept: application/json' \
--header 'api-key: <Your API secret key>'
If successful, you will receive a JSON snippet with the details of the virtual account.
{
"success": true,
"message": "[Notice: Virtual Account endpoint changing soon. Date to be communicated soon] Virtual account fetched successfully",
"data": {
"status": "approved",
"isActive": true,
"accountNumber": "GB77CLJU28398298924722",
"merchantReference": null,
"KYCInformation": {...},
"accountInformation": {
"accountNumber": "GB77CLJU28398298924722",
"bankName": "Clear Junction Limited",
"bankCode": "CLJU",
"countryCode": "GB",
"reference": "9b24f8b-6242a-4c77-b1t73-117e343103a",
"otherInfo": {
"iban": "GB77CLJU28398298924722",
"accountNumber": "92898942",
"checkNumber": "19",
"sortCode": "0089829",
"bankSwiftCode": "CLJUGB21XXX"
}
},
"verifiedKYCData": null,
"note": null,
"accountOpeningFee": 0,
"pendingAdditionalInfoCount": 0,
"isPermanent": true,
"expiresAt": null,
"isCheckoutVa": false,
"isBankTransferVa": false,
"isSuspended": false,
"reason": null,
"monthlyVolume": null,
"entityName": null,
"paymentFlowDescription": null,
"attachments": [],
"meansOfId": [
{
"name": "Passport",
"url": "https://yourtestbucket.s3.amazonaws.com/va_documents/International%2BPassport.pdf"
}
],
"bankStatement": [
{
"name": "Statement.pdf",
"url": "https://yourtestbucket.s3.amazonaws.com/va_documents/Statement.pdf"
}
],
"utilityBill": [
{
"name": "Statement.pdf",
"url": "https://yourtestbucket.s3.amazonaws.com/va_documents/Statement.pdf"
}
],
"virtualAccountType": "additional",
"riskRating": "high",
"checklist": {...},
"riskScreening": "no negative check",
"channelKycUpdateStatus": null,
"channelKycUpdateResponse": null,
"metadata": null,
"_id": "6620061298389es2279c4",
"business": {
"name": "Merchant Name",
"email": "[email protected]"
},
"currency": "EUR",
"accountType": "individual",
"entityType": "main_account",
"currencyType": "fiat",
"createdAt": "2024-04-17T17:25:46.508Z",
"updatedAt": "2024-04-17T17:32:00.980Z"
}
}
5 - Retrieving list of virtual accounts created
A list of all virtual accounts created can be returned via an API call to the list virtual accounts endpoint.
{{base_url}}/profile/virtual-accounts/?currency=eur
curl --location 'https://api.fincra.com/profile/virtual-accounts/?currency=eur' \
--header 'accept: application/json' \
--header 'api-key: <Your API secret key>'
If successful, you will receive a JSON snippet with the details of all virtual account requests made.
{
"success": true,
"message": "Merchant virtual accounts fetched successfully",
"data": {
"results": [
{...},
{...},
{...}
],
"total": 3
}
}
Updated 15 days ago