🇬🇧
Yativo Documentation
Spanish
English
English
  • Yativo
  • Introduction to Yativo
    • Financial Infrastructure
    • About Us
  • Dashboard
  • Business Plans
  • Getting Started with Yativo API
  • Yativo API Glossary
  • API reference
    • Misc.
      • Countries
      • States
      • City
  • Security and Authentication
    • Security
    • Authentication
    • Idempotency in API Requests
  • Environment
    • Environments
  • Notifications
    • Webhook
  • Compliance
    • Verification
      • KYC
      • KYB
      • KYC/KYB Update
      • KYC Status
      • Global Business Search
    • Supported Jurisdiction
    • Supported Countries, Currencies and Payment Method
  • User Management
    • Customer
      • Get Customers
      • Retrieve customer
      • Add Customer
  • Payments
    • Currencies
    • Crypto Wallets
      • Generate Wallet Address
      • Fetch Wallet Address
      • Crypto Deposit History
      • Single crypto deposit history
    • Payout
      • Payout
      • Get Payouts
      • Get Payout
      • Beneficiaries
        • Get Beneficiaries
        • Add Beneficiary Payment Details
        • Update Beneficiary
        • Archive Beneficiary
        • Add Beneficiary
    • Payin
    • Virtual Cards
      • Supported Currency, Country
      • Create card
      • Fetch card
      • Top up card
      • Get Transactions
      • Freeze and Unfreeze Card
    • Virtual Accounts
      • Create VIrtual Accounts
        • USD Virtual Account
        • Mexico Virtual Account
        • Brazil PIX QR
      • Virtual Account Management
      • Transaction History
  • Foreign Exchange
    • Exchange Rate
      • Request Quote
  • Transactions
    • Transaction Summary
    • Get Single Transaction
  • Crypto System
    • Yativo Crypto Platform API
Powered by GitBook
On this page
  1. Payments
  2. Virtual Accounts

Create VIrtual Accounts

PreviousVirtual AccountsNextUSD Virtual Account

Last updated 1 month ago

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>

Body

Name
Type
Description

customer_id

number

Customer ID

currency

string

USD, MXN, BRL

Response

{
    "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"
    }
}
{
  "error": "Invalid request"
}

Request Example

<?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);
?>
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)
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));
  • Create virtual account
  • POSTCreate virtual account

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
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