VIRTUAL ACCOUNTS

Generate Bank Account

Create a virtual account for a customer in the given currency. NGN accounts are issued instantly; USD/EUR/GBP accounts are provisioned asynchronously by our partner bank.

POST /v1/customer/generate-account

Use this endpoint to

Issue a customer a dedicated NGN virtual account for collections
Request a USD, EUR, or GBP virtual account after KYC approval
Hold multiple currency accounts side by side for the same customer

Request

Body parameters

Field	Type	Required	Description
`customer_id`	string	Yes	Customer `uuid` from Enroll Customer
`currency`	string	No	`NGN` (default), `USD`, `EUR`, or `GBP`
`bank_type`	string	Conditional	Required only for `NGN` e.g `safehaven`, `dotbank`, `9psb`. Ignored for USD/EUR/GBP

Note: One account is allowed per (customer, provider, currency) combination — a customer can hold NGN + USD + EUR accounts side by side.

Code Samples

const response = await fetch(
  "https://sandbox.hitchpay.ng/v1/customer/generate-account",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      customer_id: "CUSTOMER_UUID",
      currency: "NGN",
      bank_type: "9psb"
    })
  }
);

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

<?php

$ch = curl_init();

curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/customer/generate-account",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    "customer_id" => "CUSTOMER_UUID",
    "currency" => "NGN",
    "bank_type" => "9psb"
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Content-Type: application/json"
  ]
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

import requests

url = "https://sandbox.hitchpay.ng/v1/customer/generate-account"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "customer_id": "CUSTOMER_UUID",
    "currency": "NGN",
    "bank_type": "9psb"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

NGN — instant

{
  "status": "success",
  "message": "Account generated successfully.",
  "data": {
    "tracking_id": "EXTACCT…",
    "account_number": "1234567890",
    "account_name": "John Doe",
    "bank_name": "Safe Haven MFB",
    "bank_code": "090286",
    "currency": "NGN",
    "status": "active",
    "date_created": "1782947655"
  }
}

USD / EUR / GBP — asynchronous

{
  "status": "success",
  "message": "Account is being provisioned and will be available shortly.",
  "data": {
    "tracking_id": "EXTACCT…",
    "account_number": null,
    "account_name": "John Doe",
    "bank_name": "",
    "bank_code": "",
    "currency": "USD",
    "status": "pending",
    "date_created": "1782947655"
  }
}

When the partner bank finishes, account_number / bank_name arrive via the virtual_account.created webhook and status becomes active. If declined, you get virtual_account.failed instead.

Fields

Field	Type	Description
`tracking_id`	string	Our identifier for this account request
`account_number`	string \| null	Account number — `null` while a foreign-currency account is still provisioning
`account_name`	string	Name on the account
`bank_name`	string	Issuing bank — empty while provisioning
`bank_code`	string	Bank code — empty while provisioning
`currency`	string	Account currency
`status`	string	`active` or `pending`
`date_created`	string	Unix timestamp

Errors

Code	Meaning
`INVALID_REQUEST`	Unsupported `currency` or `bank_type`
`UNAUTHORIZED`	Business not found or inactive
`NOT_FOUND`	Customer not found
`KYC_REQUIRED`	A required verification is not yet approved for the requested currency
`KYC_INCOMPLETE`	The approved government ID is missing its document number
`DUPLICATE_REQUEST`	An active/pending account in that currency already exists for the customer
`DUPLICATE_ACCOUNT` / `DUPLICATE_IDENTITY`	The same identity (BVN) is already registered under another customer profile
`REQUEST_FAILED`	The partner bank rejected the account creation

Questions? Email [email protected]. Also on GitBook.