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

CurrencyCurrency Name
USDUnited States Dollar
GBPBritish Pounds
EUREuro

Endpoint Parameters

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

{{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 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 Multiple Currencies

FieldMandatorytypeDescription
currencyYesStringThe virtual account currency.e.g MCY
accountTypeYesStringThe virtual account type. Please see the API documentation for more details
meansOfIdYesString/ArrayThe customer's means of identification which should be a valid government ID e.g voters card, driving license. Please see the API documentation
utilityBillYesFileElectricity 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.
bankStatementYesFileRecent customer's bank statement that contains the bank name, customer’s name, address, and transaction record.
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.phoneYesStringThe customer's phone number.
KYCInformation.birthDateYesStringThe birthdate of the customer(YYYY-MM-DD ).
KYCInformation.nationalityYesStringThe customer's nationality e.g NG
KYCInformation.emailYesStringThe customer's email.
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
KYCInformation.address.streetyesStringThe street name
KYCInformation.address.numberYesstringThe house number (This field is compulsory for UK residents).
KYCInformation.address.cityYesStringThe city name
KYCInformation.sourceOfIncomeYesStringCustomer's source of income
KYCInformation.accountDesignationYesStringSpecific use of the account e.g for personal use, corporate use, school fee payments etc
KYCInformation.employmentStatusYesStringCustomer's employment status
KYCInformation.incomeBandYesStringCustomer's income band. IncomeBand can be described as earning range or salary range of the customer.
KYCInformation.documentYesObjectThe document
KYCInformation.document.typeYesStringThe type of ID document e.g passport, driverLicense, idCard.

Please see the required values here
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")
KYCInformation.
document.occupation
YesStringThe 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.

FieldMandatorytypeDescription
currencyYesStringThe virtual account currency.e.g MCY
accountTypeYesStringThe virtual account type e.h corporate
reasonYesStringThe reason for requesting a virtual account.
paymentFlowDescriptionYesStringThe countries payments are coming from and going to, The general purpose of these payments, Customer categories of the business etc.
monthlyVolumeYesStringThis is the committed transaction volume multiplied by the number of days in the relevant month.
entityNameYesStringThis is the legal name of the business or company.
KYCInformation.address.stateYesStringThe address of the state
KYCInformation.address.zipYesStringThe zip code
KYCInformation.address.cityYesStringThe business City
KYCInformation.address.houseIdYesStringThe 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.

FieldMandatorytypeDescription
currencyYesStringThe virtual account currency.e.g MCY
accountTypeYesStringThe virtual account type e.g corporate
reasonYesStringThe reason for requesting a virtual account.
paymentFlowDescriptionYesStringThe countries payments are coming from and going to, The general purpose of these payments, Customer categories of the business etc.
purposeYesStringThe purpose. For a third-party account, third_party is the compulsory value to be passed here
meansOfIdYesString/ArrayThe customer's means of identification should be a valid government ID e.g voters card, driving license. Please see the API documentation
attachmentsYesarrayThese fields require passing in documents which are business_registration_certificate,holding_structure_certificate, operating_business_utility_bill and regulatory_licenses.
monthlyVolumeYesStringThis is the committed transaction volume multiplied by the number of days in the relevant month.
KYCInformation.stateYesStringThe address of the state
KYCInformation.zipYesStringThe zip code
KYCInformation.cityYesStringThe business City
KYCInformation.houseIdYesStringThe house number (This is only required for UK residents)
KYCInformation.businessDetailsYesArrayThe array contains details about the business
KYCInformation.businessDetails.emailYesStringThe business email
KYCInformation.businessDetails.riskRatingYesStringFor the risk rating of the business, kindly check here for business risk ratings
KYCInformation.businessDetails.companyTypeYesStringThe company type e.g public, private, ngo etc
KYCInformation.businessDetails.tradingNameYesStringThe 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.businessRegistrationNumberYesStringThe business RC number
KYCInformation.businessDetails.businessRegistrationCountryYesStringThe business registration Country e.g NG for businesses registered in Nigeria
KYCInformation.businessDetails.residentialAddressYesStringThe business building address
KYCInformation.businessDetails.directorsNameYesStringThe business director's name
KYCInformation.businessDetails.shareHoldersNameYesStringThe business shareHolder's name
KYCInformation.businessDetails.percentageShareHoldingYesStringThe 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%"
            }
        }
}