Guides & Recipes

Generate & Use a Static Account

This guide walks you through creating a permanent virtual bank account for a customer that can receive multiple payments over time.

Overview

1. Enroll Customer        POST /v1/customer/enroll
2. Generate Static Account POST /v1/customer/generate-account
3. Share Account Details   → give account number to payer
4. Retrieve Accounts       GET  /v1/customer/{uuid}/accounts
5. Receive Payment         Webhook: wallet.funded

Step 1 — Enroll the Customer

const axios = require("axios");

const { data: enrollment } = await axios.post(
  "https://sandbox.hitchpay.ng/v1/customer/enroll",
  {
    customerid: "CUST_STATIC_001",
    email: "[email protected]",
    phone: "07068363556",
    firstname: "Olajide",
    lastname: "Olamide",
    dob: "12-04-1990",
    nationality: "NG",
    image: "https://storage.yourapp.com/profile.jpg",
    address: {
      house_no: 2, street: "12 Victoria Island Road",
      city: "Lagos", state: "Lagos",
      postal_code: "100001", country: "NG"
    }
  },
  { headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" } }
);

const customerUuid = enrollment.data.uuid;
console.log("Customer UUID:", customerUuid);

<?php

$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/customer/enroll",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    "customerid" => "CUST_STATIC_001", "email" => "[email protected]",
    "phone" => "07068363556", "firstname" => "Olajide", "lastname" => "Olamide",
    "dob" => "12-04-1990", "nationality" => "NG",
    "image" => "https://storage.yourapp.com/profile.jpg",
    "address" => [
      "house_no" => 2, "street" => "12 Victoria Island Road",
      "city" => "Lagos", "state" => "Lagos",
      "postal_code" => "100001", "country" => "NG"
    ]
  ]),
  CURLOPT_HTTPHEADER => ["Authorization: Bearer {$accessToken}", "Content-Type: application/json"]
]);
$enrollment   = json_decode(curl_exec($ch), true);
curl_close($ch);
$customerUuid = $enrollment["data"]["uuid"];

import requests

enrollment = requests.post(
    "https://sandbox.hitchpay.ng/v1/customer/enroll",
    json={
        "customerid": "CUST_STATIC_001", "email": "[email protected]",
        "phone": "07068363556", "firstname": "Olajide", "lastname": "Olamide",
        "dob": "12-04-1990", "nationality": "NG",
        "image": "https://storage.yourapp.com/profile.jpg",
        "address": {
            "house_no": 2, "street": "12 Victoria Island Road",
            "city": "Lagos", "state": "Lagos",
            "postal_code": "100001", "country": "NG"
        }
    },
    headers={"Authorization": f"Bearer {access_token}"}
).json()

customer_uuid = enrollment["data"]["uuid"]

Step 2 — Generate a Static Account

const { data: account } = await axios.post(
  "https://sandbox.hitchpay.ng/v1/customer/generate-account",
  {
    customer_id: customerUuid,
    bank_type: "dotbank"
  },
  { headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" } }
);

const { account_number, account_name, bank_name } = account.data;
console.log(`Account: ${account_number} — ${account_name} @ ${bank_name}`);

<?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" => $customerUuid,
    "bank_type"   => "dotbank"
  ]),
  CURLOPT_HTTPHEADER => ["Authorization: Bearer {$accessToken}", "Content-Type: application/json"]
]);
$account = json_decode(curl_exec($ch), true)["data"];
curl_close($ch);

echo "Account: {$account['account_number']} — {$account['account_name']} @ {$account['bank_name']}";

account = requests.post(
    "https://sandbox.hitchpay.ng/v1/customer/generate-account",
    json={"customer_id": customer_uuid, "bank_type": "dotbank"},
    headers={"Authorization": f"Bearer {access_token}"}
).json()["data"]

print(f"Account: {account['account_number']} — {account['account_name']} @ {account['bank_name']}")

Display the account details to your customer so payers can transfer funds directly to it:

Account Number : 1000164160
Account Name   : Olajide Olamide
Bank           : Dot MFB

This account is permanent — it can receive unlimited payments without regenerating.

Step 4 — Retrieve All Accounts for a Customer

At any time, you can fetch all static accounts linked to a customer.

const { data: accounts } = await axios.get(
  `https://sandbox.hitchpay.ng/v1/customer/${customerUuid}/accounts`,
  { headers: { Authorization: `Bearer ${accessToken}` } }
);

accounts.data.forEach(acct => {
  console.log(`${acct.bank_name} — ${acct.account_number} (${acct.status})`);
});

<?php

$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/customer/{$customerUuid}/accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer {$accessToken}"]
]);
$accounts = json_decode(curl_exec($ch), true)["data"];
curl_close($ch);

foreach ($accounts as $acct) {
  echo "{$acct['bank_name']} — {$acct['account_number']} ({$acct['status']})\n";
}

accounts = requests.get(
    f"https://sandbox.hitchpay.ng/v1/customer/{customer_uuid}/accounts",
    headers={"Authorization": f"Bearer {access_token}"}
).json()["data"]

for acct in accounts:
    print(f"{acct['bank_name']} — {acct['account_number']} ({acct['status']})")

Step 5 — Receive Payment Notifications

When a payment is made to the static account, HitchPay fires a wallet.funded or payment.success webhook to your configured endpoint.

{
  "event": "wallet.funded",
  "data": {
    "account_number": "1000164160",
    "amount": 5000,
    "currency": "NGN",
    "customer_uuid": "01113ca3-d86e-4812-ace7-69fe7d72fb4f"
  },
  "sent_at": "2026-04-20T10:00:00.000Z"
}

Summary

Step	Action	Endpoint
1	Enroll customer	`POST /v1/customer/enroll`
2	Generate static account	`POST /v1/customer/generate-account`
3	Share account details	—
4	List customer accounts	`GET /v1/customer/{uuid}/accounts`
5	Receive payment event	`wallet.funded` webhook

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