Multicurrency Virtual Account
This section describes the requirements for creating a multicurrency virtual account. 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 Multicurrency Virtual Account, merchants can receive payments in Multiple currencies.
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
List of Available Currencies on Multicurrency Endpoint
Currency | Currency Name |
---|---|
USD | United States Dollar |
GBP | British Pounds |
EUR | Euro |
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 multiple currencies
{{host}}/profile/virtual-accounts/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 Multiple Currencies
Field | Mandatory | type | Description |
---|---|---|---|
currency | Yes | String | The virtual account currency.e.g MCY |
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 | Yes | File | Electricity bills, water bills or any detailed invoice showing the usage of a service. This can be a File Upload or URL link to the document. |
bankStatement | Yes | File | Recent customer's bank statement that contains the bank name, customerβs name, address, and transaction record. |
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 nationality e.g NG |
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 (This field is compulsory for UK residents). |
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":"MCY",
"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 Multiple Currencies.
Field | Mandatory | type | Description |
---|---|---|---|
currency | Yes | String | The virtual account currency.e.g MCY |
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": "MCY",
"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 documents from the information provided during onboarding
Corporate account to A Third Party(Another corporate entity)
These fields are required to process a corporate Virtual Account request by a corporate account merchant for another corporate organisation/firm/merchant in Multiple Currencies.
Please note that our supporting documents for accepting third-party payments are: Invoices of the transaction, Purchase orders, and Agreements between both parties.
Field | Mandatory | type | Description |
---|---|---|---|
currency | Yes | String | The virtual account currency.e.g MCY |
accountType | Yes | String | The virtual account type e.g 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. |
purpose | Yes | String | The purpose. For a third-party account, third_party is the compulsory value to be passed here |
meansOfId | Yes | String/Array | The customer's means of identification should be a valid government ID e.g voters card, driving license. Please see the API documentation |
attachments | Yes | array | These fields require passing in documents which are business_registration_certificate,holding_structure_certificate, operating_business_utility_bill and regulatory_licenses. |
monthlyVolume | Yes | String | This is the committed transaction volume multiplied by the number of days in the relevant month. |
KYCInformation.state | Yes | String | The address of the state |
KYCInformation.zip | Yes | String | The zip code |
KYCInformation.city | Yes | String | The business City |
KYCInformation.houseId | Yes | String | The house number (This is only required for UK residents) |
KYCInformation.businessDetails | Yes | Array | The array contains details about the business |
KYCInformation.businessDetails.email | Yes | String | The business email |
KYCInformation.businessDetails.riskRating | Yes | String | For the risk rating of the business, kindly check here for business risk ratings |
KYCInformation.businessDetails.companyType | Yes | String | The company type e.g public, private, ngo etc |
KYCInformation.businessDetails.tradingName | Yes | String | The company name used in trading(this is to capture the correct data for cases where the trading name is different from the business name). |
KYCInformation.businessDetails.businessRegistrationNumber | Yes | String | The business RC number |
KYCInformation.businessDetails.businessRegistrationCountry | Yes | String | The business registration Country e.g NG for businesses registered in Nigeria |
KYCInformation.businessDetails.residentialAddress | Yes | String | The business building address |
KYCInformation.businessDetails.directorsName | Yes | String | The business director's name |
KYCInformation.businessDetails.shareHoldersName | Yes | String | The business shareHolder's name |
KYCInformation.businessDetails.percentageShareHolding | Yes | String | The percentage share held by the shareholder |
{"currency":"MCY",
"accountType":"corporate",
"entityName": "aaa",
"reason": "aasfsdf",
"paymentFlowDescription": "afsdf",
"purpose": "third_party",
"meansOfId": ["https://reviewtestbucket.s3.amazonaws.com/va_documents/favourPassport_ms8zme_da09ecd5-62c0-49e8-935e-8f63cd72b81a.png"],
"attachments": ["https://reviewtestbucket.s3.amazonaws.com/va_documents/favourPassport_ms8zme_da09ecd5-62c0-49e8-935e-8f63cd72b81a.png"],
"monthlyVolume": "1000",
"KYCInformation": {
"zip": "2039021",
"state": "afsdfd",
"city": "Lagos",
"houseId" : "20", // required for UK residents only
"businessDetails": {
"email": "[email protected]",
"riskRating": "low",
"companyType": "pub",
"tradingName": "name",
"businessRegistrationNumber": "090193",
"businessRegistrationCountry": "NG",
"residentialAddress": "tawa street",
"directorsName": "asiwaju",
"shareHoldersName": "abiola",
"percentageShareHolding": "1%"
}
}
}
Updated 12 days ago