Simulator

Simulate Transfer

Simulate an inbound transfer into one of your external-customer virtual accounts.

POST /v1/sandbox/simulate-transfer

This runs the exact same credit + webhook flow a real inflow would — crediting the business wallet (less the collection fee), updating the account's running total, and dispatching the virtual_account.credit webhook.

Works for NGN and for foreign-currency accounts. The deposit currency is taken from the account itself, so a USD account credits your USD wallet.

Use this endpoint to

Verify your webhook handling and reconciliation logic before going live
Generate test collections against a real virtual account you've already created, in any currency
Confirm your integration credits the right amount after fees

Note: For USD/EUR accounts, activate the account first — see Activate Account.

Request

Body parameters

Field	Type	Required	Description
`account_number`	string	Yes	An external-customer account you generated — must be `active`
`amount`	number	Yes	In major units of the account's currency (naira, dollars, euros). Must be greater than 0
`currency`	string	No	Optional assertion. If given, it must match the account's currency, otherwise `CURRENCY_MISMATCH`. Omit it and the account's own currency is used
`sender_name`	string	No	Defaults to a sandbox value
`sender_bank`	string	No	Defaults to a sandbox value for the account's currency
`reference`	string	No	Your idempotency key — reusing it returns the existing transaction without double-crediting

Code Samples

const response = await fetch(
  "https://sandbox.hitchpay.ng/v1/sandbox/simulate-transfer",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      account_number: "9912345678",
      amount: 250,
      currency: "USD",
      sender_name: "John Sender",
      sender_bank: "Chase",
      reference: "test-inflow-001"
    })
  }
);

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

<?php

$ch = curl_init();

curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/sandbox/simulate-transfer",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    "account_number" => "9912345678",
    "amount" => 250,
    "currency" => "USD",
    "sender_name" => "John Sender",
    "sender_bank" => "Chase",
    "reference" => "test-inflow-001"
  ]),
  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/sandbox/simulate-transfer"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "account_number": "9912345678",
    "amount": 250,
    "currency": "USD",
    "sender_name": "John Sender",
    "sender_bank": "Chase",
    "reference": "test-inflow-001"
}

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

Response

{
  "status": "success",
  "message": "Transfer simulated successfully",
  "data": {
    "account_number": "9912345678",
    "currency": "USD",
    "amount": 250,
    "fee": 0,
    "amount_credited": 250,
    "wallet_balance": 1250.00,
    "reference": "SIM_test-inflow-001",
    "note": "Simulated USD inflow processed. Check the business USD wallet balance and your virtual_account.credit webhook."
  }
}

Fields

Field	Type	Description
`account_number`	string	Echoes the account you simulated a transfer into
`currency`	string	The account's currency, `NGN`, `USD`, or `EUR`
`amount`	number	Gross amount simulated
`fee`	number	Collection fee deducted - see fee model below
`amount_credited`	number	Net amount credited to your wallet (`amount` − `fee`)
`wallet_balance`	number	Your wallet balance in this currency after the credit
`reference`	string	Effective transaction id, always `SIM_` + your `reference`
`note`	string	Reminder of what to check next

Errors

Code	HTTP	Meaning
`NOT_ALLOWED`	403	Called on the production environment -simulation is sandbox-only
`INVALID_REQUEST`	400	Missing `account_number`/`amount`, or non-positive amount
`NOT_FOUND`	404	Account doesn't exist or doesn't belong to your business
`ACCOUNT_INACTIVE`	400	Account not active yet - for USD/EUR, call Activate Account first
`CURRENCY_MISMATCH`	400	The `currency` you sent doesn't match the account's currency
`SIMULATION_FAILED`	400	Could not process the simulated credit

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