Create VIrtual Accounts

Create virtual account

POST {{baseUrl}}/business/virtual-account/create

This endpoint allows you to create a virtual account that can be used to receive funds.

KYC must have been completed by the customer before this can be enabled.

Each customer can have only 1 Virtual account per currency

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Create virtual account

post

StartFragment

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.

Field	Mandatory	type	Description
currency	Yes	string	The virtual account currency.e.g USD
accountType	Yes	string	The virtual account type. For USD, we currently only offer individual accounts.
meansOfId	Yes	string/array	The customer's means of identification which should be a valid government ID e.g passport, driver license. Please see the Accepted Documents
utilityBill	Yes	string	Electricity 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.
bankStatement	Yes	string	Account statement from the user's bank. This can be a File Upload or URL link to the document. Note, bankStatement must be a valid document within the last 3 months. Name and address on statement has to match details sent in payload.
KYCInformation	Yes	Object	KYC Information object
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.birthDate	Yes	string	The 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.birthPlace	No	string	The place of birth
KYCInformation.birthCountry	No	string	Please 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.taxCountry	Yes	string	Please 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.taxNumber	No	string	Only required when tax country is US
KYCInformation.nationality	Yes	string	The birthplace of the customer
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 must be valid. Refer to the ZIP Code Format Guide .
KYCInformation.address.street	Yes	string	The street name
KYCInformation.address.city	Yes	string	The city name
KYCInformation.address.number	Yes	string	The house number
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.incomeBand	Yes	string	Customer's income band. IncomeBand can be described as earning range or salary range of the customer.
KYCInformation.phone	Yes	string	The customer's phone number
KYCInformation.employmentStatus	Yes	string	Customer's employment status
KYCInformation.document	Yes	object	The document
KYCInformation.document.type	Yes	string	The type of ID document e.g passport, driverLicense, nationalId.
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"). Optional only when document type is nationalId.
KYCInformation.occupation	Yes	string	The occupation of the customer.
merchantReference	No	string	A unique ID/reference of the virtual account on your system.

Accepted identity documents for USD virtual account.

Document	API Value	Description
International Passport	passport	The 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 License	driverLicense	The 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 only	nationalId	National ID Card (Not NIN or v-NIN).
Identity Card	idCard	This 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.

StartFragment

Accepted identity documents for EUR virtual account.

Document	API Value	Description
International Passport	passport	The 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 License	driverLicense	The 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 only	nationalId	National ID Card (Not NIN or v-NIN).
Identity Card	idCard	This 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.

Authorizations

Body

all ofOptional

and

anyOptionalExample: {"currency":"USD","customer_id":"ae68f0ef-0e59-4a23-b8da-9e07bf2af361"}

Responses

200Success

post

HTTPcURLJavaScriptPython

POST /api/v1/business/virtual-account/create HTTP/1.1
Host: smtp.yativo.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "currency": "USD",
  "customer_id": "ae68f0ef-0e59-4a23-b8da-9e07bf2af361"
}

200Success

No content

Body

Name	Type	Description
customer_id	number	Customer ID
currency	string	USD, MXN, BRL

Response

200

{
    "status": "success",
    "status_code": 201,
    "message": "Virtual account creation in progress",
    "data": {
        "account_id": "va_67890",
        "account_number": "9876543210",
        "account_type": "savings",
        "currency": "USD",
        "created_at": "2023-05-27T14:45:00Z"
    }
}

400

{
  "error": "Invalid request"
}

Request Example

PHP

<?php
$baseUrl = 'https://sandbox.yativo.com'; // Replace with the actual base URL
$accessToken = 'YOUR_ACCESS_TOKEN';
$customerId = 'YOUR_CUSTOMER_ID';

$url = $baseUrl . '/example-endpoint';

$data = [
    "currency": "USD", // supported are BRL, MXN,
    "customer_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxx"
    ];

$options = [
    'http' => [
        'header'  => "Authorization: Bearer $accessToken\r\n" .
                     "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($data)
    ]
];

$context  = stream_context_create($options);
$response = file_get_contents($url, false, $context);

if ($response === FALSE) {
    die('Error occurred');
}

$responseData = json_decode($response, true);
print_r($responseData);
?>

Python

import requests

baseUrl = 'https://sandbox.yativo.com'  # Replace with the actual base URL
accessToken = 'YOUR_ACCESS_TOKEN'
customerId = 'YOUR_CUSTOMER_ID'
url = f'{baseUrl}/example-endpoint'

data = {
    "currency": "USD", // supported are BRL, MXN,
    "customer_id": "ae68f0ef-0e59-4a23-b8da-9e07bf2af361"
}

headers = {
    'Authorization': f'Bearer {accessToken}',
    'Content-Type': 'application/json'
}

response = requests.post(url, json=data, headers=headers)

if response.status_code != 200:
    print(f'Error: {response.status_code} - {response.text}')
else:
    responseData = response.json()
    print('Response:', responseData)

JavaScript

const baseUrl = 'https://sandbox.yativo.com'; // Replace with the actual base URL
const accessToken = 'YOUR_ACCESS_TOKEN';
const customerId = 'YOUR_CUSTOMER_ID';
const url = `${baseUrl}/example-endpoint`;

const data = {
    "currency": "USD", // supported are BRL, MXN,
    "customer_id": "ae68f0ef-0e59-4a23-b8da-9e07bf2af361"
};

const options = {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
};

fetch(url, options)
  .then(response => {
    if (!response.ok) {
      throw new Error(`Network response was not ok ${response.statusText}`);
    }
    return response.json();
  })
  .then(data => console.log('Response:', data))
  .catch(error => console.error('Error:', error));