Create Virtual Account

Create a dedicated virtual bank account for receiving fiat deposits.

Creates a permanent virtual bank account that can receive fiat deposits. Deposits are automatically settled into crypto.

Endpoint

POST /v1/virtual-accounts

Authentication

API key only (JWT not accepted). This route uses the API-key guard exclusively.

Header	Value
Authorization	<api_key>

Request body

Field	Type	Required	Description
email	string	Yes	Customer's email address
identityType	string	Yes	Identity verification type: bvn, nin, or cac
identityNumber	string	Yes	Identity number corresponding to the identity type
currency	string	Yes	Fiat currency for the account. See Supported Currencies

Example request

cURL

curl -X POST https://ramp-api.ivorypay.io/api/v1/virtual-accounts \
  -H "Authorization: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "identityType": "bvn",
    "identityNumber": "22222222222",
    "currency": "NGN"
  }'

Node.js

const response = await fetch("https://ramp-api.ivorypay.io/api/v1/virtual-accounts", {
  method: "POST",
  headers: {
    "Authorization": "your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "[e-mail]",
    identityType: "bvn",
    identityNumber: "22222222222",
    currency: "NGN",
  }),
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    "https://ramp-api.ivorypay.io/api/v1/virtual-accounts",
    headers={
        "Authorization": "your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "email": "[e-mail]",
        "identityType": "bvn",
        "identityNumber": "22222222222",
        "currency": "NGN",
    },
)

print(response.json())

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]string{
		"email":          "[e-mail]",
		"identityType":   "bvn",
		"identityNumber": "22222222222",
		"currency":       "NGN",
	})

	req, _ := http.NewRequest("POST", "https://ramp-api.ivorypay.io/api/v1/virtual-accounts", bytes.NewBuffer(body))
	req.Header.Set("Authorization", "your_api_key")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}

Example response

{
  "success": true,
  "message": "Virtual account created",
  "data": {
    "id": "9b1a3e6f-7c2d-4e5a-8f12-1234567890ab",
    "businessId": "1c2b3a4d-5e6f-7081-9203-abcdef012345",
    "customerIdentifier": "8e8b6f5a-1234-4abc-9def-0fedcba98765",
    "email": "[e-mail]",
    "customerName": "Amina Okafor",
    "identityType": "bvn",
    "identityNumber": "22222222222",
    "accountNumber": "9900123456",
    "accountName": "IvoryPay - Merchant User",
    "bankCode": "101",
    "bankName": "Providus Bank",
    "currency": "NGN",
    "processor": "providus",
    "status": "ACTIVE",
    "context": "LIVE",
    "createdAt": "2026-03-26T12:00:00.000Z",
    "updatedAt": "2026-03-26T12:00:00.000Z"
  }
}

Response fields

Field	Type	Description
id	string	Virtual account UUID (local record)
businessId	string	Owning business UUID
customerIdentifier	string	Customer UUID linked to the VA
email	string	Customer email supplied at creation
customerName	string	Customer's full name (derived from firstName + lastName)
identityType	string	bvn, nin, or cac
identityNumber	string	Identity number supplied at creation
accountNumber	string	The virtual account number — share this with your user
accountName	string	Account name displayed to senders
bankCode	string	Bank code of the virtual account provider
bankName	string	Bank name
currency	string	Fiat currency
processor	string	Underlying payment processor identifier
status	string	BasicStatus enum — ACTIVE or INACTIVE
context	string	Environment (TEST or LIVE)
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last-update timestamp

Identity types

Type	Description	Example
bvn	Bank Verification Number (Nigeria)	11-digit number
nin	National Identification Number (Nigeria)	11-digit number
cac	Corporate Affairs Commission (Nigeria, businesses)	Registration number