USD Account

This section describes the requirements for creating a virtual account in USD. In this section, the payloads have been separated into the requirements for individual and corporate accounts. Please take time to go through each request properly.

With a USD Virtual Account, merchants can receive payments in USD.

📘
Hey 👋 , we recommend reading the sections below because they are critical to understanding each virtual account request.
How to create a virtual account
Currencies we support for virtual account creations
Virtual Account Webhook Structure

USD Account Settlement Time

The settlement time is the amount of time it takes for funds to be deposited into your Fincra account/IBAN, which is determined by the payment scheme the sender uses.

Payment Scheme	Time
CHAPS	Within 24 hours
FPS	10 seconds to one day
SWIFT	1-5 days
Wire	Less than 10 hours

Endpoint Parameters

These parameters can be tested on an API explorer by calling the various endpoints supported for our virtual account requests :

Create a virtual account: This endpoint can be used to request a Virtual Account in any currency

{{host}}/profile/virtual-accounts/requests

Create a virtual account for a sub-account : This endpoint can be used to request a Virtual Account for a sub account in any currency

{{host}}/profile/virtual-accounts/business/{businessId}/sub-accounts/{subAccountId}/requests

Note

After a Virtual Account creation request is made, a response with a data object containing a unique identifier _id of the virtual account will be returned, which would also be included in the webhook sent as id if the virtual account is declined or approved.
The meansOfId can be sent as a string, file, or array of URLs when making use of the create virtual account endpoint

Individual Request

These are the fields required to process an individual Virtual Account request in USD

Field	Mandatory	type	Description
currency	Yes	String	The virtual account currency.e.g USD
accountType	Yes	String	The virtual account type. Please see the API documentation for more details
meansOfId	Yes	String/Array	The customer's means of identification which should be a valid government ID e.g voters card, driving license. Please see the API documentation
utilityBill	No	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.
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.phone	Yes	String	The customer's phone number.
KYCInformation.birthDate	Yes	String	The birthdate of the customer(YYYY-MM-DD ).
KYCInformation.nationality	Yes	String	The customer's place of birth
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
KYCInformation.address.street	yes	String	The street name
KYCInformation.address.number	yes	string	The house number
KYCInformation.address.city	yes	String	The city name
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.employmentStatus	yes	String	Customer's employment status
KYCInformation.incomeBand	yes	String	Customer's income band. IncomeBand can be described as earning range or salary range of the customer.
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("YYYY-mm-dd")
KYCInformation. document.occupation	Yes	String	The occupation of the customer.

The payload should look like this :

{"currency":"USD",
  "meansOfId":["https://reviewtestbucket.s3.amazonaws.com/va_documents/passport-min-compressed_f5f30001-34cc-466b-a49f-4931b6531117.jpg"],
            "utilityBill":"https://reviewtestbucket.s3.amazonaws.com/va_documents/image%20%2816%29_04a5a024-14de-491e-9ecf-2861dd111cb7.png",
            "bankStatement": "https://reviewtestbucket.s3.amazonaws.com/va_documents/ZEN_20220801_20221031_191_AAAAA_152_-387091521_1668626227521_feeaa8e5-28b9-487a-1172-f1b5ecc96158.pdf",
            "accountType":"individual",
 "KYCInformation": {
            "firstName": "John",
            "lastName": "Doe",
            "email": "[email protected]",
            "birthDate": "1984-07-24",
            "nationality": "NG",
            "incomeBand": "0-100000",
            "phone": "09031234321",
            "address": {
                "countryOfResidence": "NG",
                "zip": "23401",
                "street": "Obada",
                "number":"10",
                "state": "Lagos",
                "city": "Alimosho"
            },
            "document": {
                "type": "passport",
                "number": "B00530002",
                "issuedCountryCode": "NG",
                "issuedBy": "government",
                "issuedDate": "2000-09-14",
                "expirationDate": "2000-09-13"
            },
            "occupation": "Software-Developer",
            "sourceOfIncome": "Software-Development",
            "accountDesignation": "personal",
            "employmentStatus": "Employed"
        }

Corporate Request

These are the fields required to process a corporate Virtual Account request in EUR/GBP.

Field	Mandatory	type	Description
currency	Yes	String	The virtual account currency.e.g USD
accountType	Yes	String	The virtual account type e.h corporate
reason	Yes	String	The reason for requesting a virtual account.
paymentFlowDescription	Yes	String	The countries payments are coming from and going to, The general purpose of these payments, Customer categories of the business etc.
monthlyVolume	Yes	String	This is the committed transaction volume multiplied by the number of days in the relevant month.
entityName	Yes	String	This is the legal name of the business or company.
KYCInformation.address.state	Yes	String	The address of the state
KYCInformation.address.zip	Yes	String	The zip code
KYCInformation.address.city	Yes	String	The business City
KYCInformation.address.houseId	Yes	String	The house number (This is only required for UK residents)

The payload should look like this :

{
  "currency": "USD",
  "accountType": "corporate",
  "KYCInformation": {
        "city": "Lekki",
      	"state": "lagos",
        "zip": "234",
    "houseId": "12345" //for UK residents
      },
   "reason": "The reason for requesting a corporate account",
  "monthlyVolume": 10000,
  "entityName": "john doe legal enterprise",
  "paymentFlowDescription": "we pay in pounds every month",
}

Please Note That we will get the other information from the KYC that was submitted during onboarding

📘Hey 👋 , we recommend reading the sections below because they are critical to understanding each virtual account request.

USD Account Settlement Time

Endpoint Parameters

Individual Request

Corporate Request

📘
Hey 👋 , we recommend reading the sections below because they are critical to understanding each virtual account request.