EUR Virtual Account

Fincra Multicurrency (MCY) Virtual Account product allows merchants to offer their individual users the ability to create a virtual EUR account in their own names. With Fincra MCY Account, users can receive funds in foreign currencies, providing a seamless and efficient way to manage international transactions.

This account is designed for personal use and supports SEPA and SEPA Instant transactions, with a monthly limit of 10,000 EUR. The Fincra MCY account is accessible exclusively via API integration.

The section below, 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.

Monthly limit per virtual account is 10,000 EUR

The generated accounts are personal accounts, EUR virtual account is issued in the individual’s name, and not suitable for business use.

The account supports SEPA, ensuring swift and efficient payments across Europe.

To ensure compliance, it's important to note the prohibited activities and countries restricted from having access to this product.

Check possible verification errors that may occur during account request here.

Consult the guide here, for more information on how to treat requests for information on an expected deposit/inflow.

You can check out our FAQ section for more information.

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. Bank Statement is also accepted. This can be a File Upload or a URL link to the document. Note, utility bill must be a valid document within the last 3 months. Name and address on utility has to match details sent in payload.
bankStatement	Yes	string	Account statement from the user's bank. This can be a File Upload or URL link to the document. Note, bankStatement must be a valid document within the last 3 months. Name and address on statement has to match details sent in payload.
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. Refer to the ZIP Code Format Guide .
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`, `nationalId`.
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 ("YYYY-mm-dd"). Optional only when document type is `nationalId`.
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 (Not NIN or v-NIN).
Identity Card	idCard	This would accept an identity card, including Resident Permit.

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"
  }
}

{
  "event": "virtualaccount.declined",
  "data": {
    "id": "6655eecd8f61b674ad119828",
    "business": "64f1c9edf3c8f2940df4a710",
    "isSubAccount": false,
    "currency": "EUR",
    "currencyType": "fiat",
    "status": "declined",
    "accountType": "individual",
    "reason": "Address proof and document proof are of different persons",
    "accountOpeningFee": 0,
    "virtualAccountType": "additional",
    "createdAt": "2024-05-28T14:48:45.857Z",
    "updatedAt": "2024-05-28T14:51:26.445Z"
  }
}

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.
For detailed information on verification errors that might be encountered here, please refer to our Multicurrency Account Verification Errors Documentation.

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
    }
}

📘Important