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 asid
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
Updated 9 months ago