Guides
ChangelogAPI ReferenceAPI keysSupportBlog

Request FCY Account

Suggest Edits

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

The section below, describes the requirements for creating a virtual account for USD/EUR/GBP collections. We would like to start by explaining how permanent FCY virtual accounts can be created on Fincra. 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 USD/GBP
  • The generated accounts are personal accounts, FCY virtual account is issued in the individual’s name, and not suitable for business use.
  • The USD account supports ACH, SWIFT and Fedwire transactions, ensuring swift and efficient payments.
  • The EUR account supports SEPA and SEPA Instant ensuring swift and efficient payments across Europe.
  • The GBP account supports FPS and CHAPS ensuring swift and efficient payments.
  • 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.

Available Currencies

Virtual accounts are currently available in the following currencies :

Currency NameCurrency CodePayment SchemesAvailability
US DollarUSDACH, SWIFT and FedwireYes
EUROEURSEPA, SEPA InstantYes
British PoundsGBPFPS, CHAPSYes

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.

FieldMandatorytypeDescription
currencyYesstringThe virtual account currency.e.g USD
accountTypeYesstringThe virtual account type. For USD, we currently only offer individual accounts.
meansOfIdYesstring/arrayThe customer's means of identification which should be a valid government ID e.g passport, driver license. Please see the Accepted Documents
utilityBillYesstringElectricity 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.
bankStatementNostringAccount statement from the user's bank. This can be a File Upload or URL link to the document.

If you would be using bankStatement as the proof of address, you would need to pass the bank statement in both the utilityBill field and the bankStatement field.

Note, bankStatement must be a valid document within the last 3 months.
Name and address on statement has to match details sent in payload.
KYCInformationYesObjectKYC Information object
KYCInformation.firstNameYesstringThe customer's first name. This is required to create an individual account
KYCInformation.lastNameYesstringThe customer's last name. This is required to create an individual account
KYCInformation.birthDateYesstringThe 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.birthPlaceNostringThe place of birth
KYCInformation.birthCountryNostringPlease provide the country codes in the ISO 3166-1 alpha-2 format (e.g., US for the United States, EU for the European Union, NG for Nigeria)
KYCInformation.taxCountryYesstringPlease provide the country codes in the ISO 3166-1 alpha-2 format (e.g., US for the United States, EU for the European Union, NG for Nigeria)
KYCInformation.taxNumberNostringThis is required if taxCountry is US
KYCInformation.nationalityYesstringThe birthplace of the customer
KYCInformation.emailYesstringThe customer's email.
monthlyTransactionCountYesstringThe expected number of transactions.
monthlyTransactionVolumeYesstringThe expected volume account would be receiving monthly.
KYCInformation.addressYesObjectThe address of the customer
KYCInformation.address.countryOfResidenceYesstringThe address of the country
KYCInformation.address.stateYesstringThe address of the state
KYCInformation.address.zipYesstringThe zip code must be valid. Refer to the ZIP Code Format Guide .
KYCInformation.address.streetYesstringThe street name
KYCInformation.address.cityYesstringThe city name
KYCInformation.address.numberYesstringThe house number
KYCInformation.sourceOfIncomeYesstringCustomer's source of income.
Options:
salary, business_income, investment, gift, inheritance, real_estate, loan, pension, grant, trust, crypto, other.
KYCInformation.accountDesignationYesstringSpecific use of the account e.g for personal use, corporate use, school fee payments etc.
KYCInformation.incomeBandYesobjectCustomer's income band. IncomeBand can be described as earning range or salary range of the customer.
KYCInformation.incomeBand.lowerYesstringThe start of the income band
KYCInformation.incomeBand.upperYesstringThe end of the income band
KYCInformation.phoneYesstringThe customer's phone number
KYCInformation.employmentStatusYesstringCustomer's employment status.
Options:
employed, self_employed, unemployed, student, retired, homemaker, freelancer, other.
KYCInformation.documentYesobjectThe document
KYCInformation.document.typeYesstringThe type of ID document. Only passport is allowed for USD requests. Please see the Accepted Documents for other currencies.
KYCInformation.
document.number		YesstringThe number on the document
KYCInformation.
document.issuedCountryCode		YesstringThe country that issued the document.Should be in ISO 3166-1 alpha-2 – two-letter country codes format(NG)
KYCInformation.
document.issuedBy		YesstringThe government agency in charge of issuing the document.
KYCInformation.
document.issuedDate		YesstringThe date the document was issued("YYYY-mm-dd")
KYCInformation.
document.expirationDate		YesstringThe expiration date on the document ("YYYY-mm-dd"). Optional only when document type is nationalId.
KYCInformation.occupationYesstringThe occupation of the customer.
merchantReferenceNostringA unique ID/reference of the virtual account on your system.

Accepted identity documents for FCY virtual account

DocumentAPI ValueCurrencyDescription
International PassportpassportUSD, EUR, GBPThe 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 LicensedriverLicenseEURThe 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 onlynationalIdEURNational ID Card (Not NIN or v-NIN). (When uploading this in the meansOfId field, ensure to send two string urls in an array, one for front and one for back)
Identity CardidCardEURThis would accept an identity card, including Resident Permit. This identity card has to be a valid government issued ID, with the name, issue date and date of birth clearly visible. (When uploading this in the meansOfId field, ensure to send two string urls in an array, one for front and one for back)

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": "USD",
    "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": {
        "lower": "1000",
				"upper": "6460"
      },
      "sourceOfIncome": "Salary",
      "accountDesignation": "Personal use",
      "phone": "08012345678",
      "occupation": "Business",
      "nationality": "NG",
      "birthDate": "1998-03-29",
      "taxCountry": "US",
      "taxNumber": "199180037820", // only required if Tax Country is US
      "firstName": "John",
      "lastName": "Doe",
      "otherName": "Claude",
      "document": {
        "type": "passport",
        "number": "A89238923",
        "issuedCountryCode": "NG",
        "issuedBy": "government",
        "issuedDate": "2017-09-07",
        "expirationDate": "2027-07-23"
      },
      "employmentStatus": "Business",
      "monthlyTransactionCount": "5",
      "monthlyTransactionVolume": "10000"
    }
}

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": "USD",
        "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": "USD",
    "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": "USD",
    "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": "USD",
    "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": "USD",
    "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": "USD",
    "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": "USD",
    "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.
  • Expect to recieve a second webhook after the virtualaccount.approved event. The new webhook event "virtualaccount.issued", is dispatched once the bank account is ready. Contained within this new webhook, is the accountInformation field, which contains the details of the newly generated account.
{
   "event":"virtualaccount.issued",
   "data":{
      "id":"661e83489349bwe342c6a70",
      "business":"62787427843dfn3848ws",
      "isSubAccount":false,
      "currency":"USD",
      "currencyType":"fiat",
      "status":"approved",
      "email":"[email protected]",
      "accountType":"individual",
      "accountInformation":{
         "accountNumber":"8373878380",
         "bankName":"Community Federal Savings Bank",
         "bankCode":null,
         "countryCode":"",
         "reference":"n87z37-bd26-4b5b-a147-e6hd8j",
         "otherInfo":{
            "iban":"",
            "accountNumber":"8373878380",
            "checkNumber":"",
            "sortCode":"",
            "bankSwiftCode":"",
            "memo":"QP65B"
         }
      },
      "accountOpeningFee":0,
      "isPermanent":true,
      "virtualAccountType":"additional",
      "createdAt":"2024-04-17T13:41:38.658Z",
      "updatedAt":"2024-04-17T13:46:01.528Z"
   }
}

{
   "event":"virtualaccount.issued",
   "data":{
      "id":"661e83489349bwe342c6a70",
      "business":"62787427843dfn3848ws",
      "isSubAccount":false,
      "currency":"USD",
      "currencyType":"fiat",
      "status":"approved",
      "email":"[email protected]",
      "accountType":"individual",
      "accountInformation":{
         "accountNumber":"8373878380",
         "bankName":"Community Federal Savings Bank",
         "bankCode":null,
         "countryCode":"",
         "reference":"n87z37-bd26-4b5b-a147-e6hd8j",
         "otherInfo":{
            "iban":"",
            "accountNumber":"8373878380",
            "checkNumber":"",
            "sortCode":"",
            "bankSwiftCode":"",
            "memo":""
         }
      },
      "accountOpeningFee":0,
      "isPermanent":true,
      "virtualAccountType":"additional",
      "createdAt":"2024-04-17T13:41:38.658Z",
      "updatedAt":"2024-04-17T13:46:01.528Z"
   }
}

❗️

Changes to account details

In the event of any changes to the virtual account details, a virtualaccount.changed event will be triggered. Please use the _id field to uniquely identify and track virtual account records.

{
   "event":"virtualaccount.changed",
   "data":{
      "id":"661e83489349bwe342c6a70",
      "business":"62787427843dfn3848ws",
      "isSubAccount":false,
      "currency":"USD",
      "currencyType":"fiat",
      "status":"approved",
      "email":"[email protected]",
      "accountType":"individual",
      "accountInformation":{
         "accountNumber":"8373878380",
         "bankName":"Community Federal Savings Bank",
         "bankCode":null,
         "countryCode":"",
         "reference":"n87z37-bd26-4b5b-a147-e6hd8j",
         "otherInfo":{
            "iban":"",
            "accountNumber":"8373878380",
            "checkNumber":"",
            "sortCode":"",
            "bankSwiftCode":"",
            "memo":"QP65B"
         }
      },
      "accountOpeningFee":0,
      "isPermanent":true,
      "virtualAccountType":"additional",
      "createdAt":"2024-04-17T13:41:38.658Z",
      "updatedAt":"2024-04-17T13:46:01.528Z"
   }
}

{
   "event":"virtualaccount.changed",
   "data":{
      "id":"661e83489349bwe342c6a70",
      "business":"62787427843dfn3848ws",
      "isSubAccount":false,
      "currency":"USD",
      "currencyType":"fiat",
      "status":"approved",
      "email":"[email protected]",
      "accountType":"individual",
      "accountInformation":{
         "accountNumber":"8373878380",
         "bankName":"Community Federal Savings Bank",
         "bankCode":null,
         "countryCode":"",
         "reference":"n87z37-bd26-4b5b-a147-e6hd8j",
         "otherInfo":{
            "iban":"",
            "accountNumber":"8373878380",
            "checkNumber":"",
            "sortCode":"",
            "bankSwiftCode":"",
            "memo":""
         }
      },
      "accountOpeningFee":0,
      "isPermanent":true,
      "virtualAccountType":"additional",
      "createdAt":"2024-04-17T13:41:38.658Z",
      "updatedAt":"2024-04-17T13:46:01.528Z"
   }
}

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": "92898942",
            "bankName": "Community Federal Savings Bank",
            "bankCode": null,
            "countryCode": "",
            "reference": "9b24f8b-6242a-4c77-b1t73-117e343103a",
            "otherInfo": {
                "iban": "",
                "accountNumber": "92898942",
                "checkNumber": "",
                "sortCode": "",
                "bankSwiftCode": ""
            }
        },
        "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": "USD",
        "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
    }
}

6 - Virtual Account Closed

When a virtual account is closed; webhook notifications is sent.

🚧
  • Expect to recieve a webhook that states virtualaccount.closed event. Contained within this new webhook, is the accountInformation and reason field, which contains the details of the account closure.

{
  "event": "virtualaccount.closed",
  "data": {
    "id": "62135abbcb0e3e0535fdc2ac",
    "business": "61aa4e72cc67b6f04d97f874",
    "isSubAccount": false,
    "currency": "USD",
    "currencyType": "fiat",
    "status": "closed",
    "accountType": "corporate",
    "reason":"reason for account closure",
    "accountInformation": {
      "accountNumber": "GB88BLFN04270670217485",
      "email": "[email protected]", 
      "bankName": "Blacktorn Finance",
      "bankAddress": "The Business Complex, 100  Church Ln, London E1 1LX, UK",
      "accountName": " Ventures",
      "swiftCode": "BLFNGB21XXX"
    },
    "accountOpeningFee": 0,
    "virtualAccountType": "additional",
    "createdAt": "2022-02-21T09:26:19.167Z",
    "updatedAt": "2022-02-21T09:28:35.808Z"
  }
}

Updated 2 days ago