Skip to content
HitchPay API Docs

VIRTUAL ACCOUNTS

Get Account Collections

List money received into your customers' virtual accounts across all currencies. Use this to reconcile inflows independently of webhooks.

GET /v1/customer/collections

Use this endpoint to

  • Pull a paginated list of all collections, optionally filtered by customer, currency, or date range
  • Reconcile inflows against your own records
  • Confirm the net amount credited to your wallet after fees

Request

Query parameters

Parameter Type Required Description
customer_id string No Filter to a single customer
currency string No Filter to NGN, USD, EUR, or GBP
from string No ISO date — start of range
to string No ISO date — end of range
page number No Page number
limit number No Results per page, max 100

Code Samples

const params = new URLSearchParams({
  currency: "USD",
  from: "2026-07-01",
  to: "2026-07-10",
  page: "1",
  limit: "20"
});

const response = await fetch(
  `https://sandbox.hitchpay.ng/v1/customer/collections?${params}`,
  { headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN" } }
);

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

$query = http_build_query([
  "currency" => "USD",
  "from" => "2026-07-01",
  "to" => "2026-07-10",
  "page" => 1,
  "limit" => 20
]);

$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/customer/collections?" . $query,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ]
]);

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

echo $response;
import requests

url = "https://sandbox.hitchpay.ng/v1/customer/collections"
headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
params = {
    "currency": "USD",
    "from": "2026-07-01",
    "to": "2026-07-10",
    "page": 1,
    "limit": 20
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

Response

{
  "status": "success",
  "message": "Collections retrieved successfully.",
  "data": {
    "total_count": 42,
    "page": 1,
    "limit": 20,
    "collections": [
      {
        "reference": "<provider transaction id>",
        "customer_uuid": "…",
        "tracking_id": "EXTACCT…",
        "account_number": "…",
        "account_name": "John Doe",
        "provider": "",
        "currency": "USD",
        "amount": 500.00,
        "fee": 0,
        "amount_credited": 500.00,
        "status": "successful",
        "sender_name": "ACME LTD",
        "sender_bank": "…",
        "created_at": "2026-07-10T10:15:00.000Z"
      }
    ]
  }
}

Fields

Field Type Description
total_count number Total collections matching the filter
page / limit number Pagination echoed back
reference string Provider transaction id — use with Get Collection by Reference
customer_uuid string Customer this collection belongs to
tracking_id string Account this collection landed in
account_number / account_name string Receiving account details
provider string safehaven, dotbank, 9psb
currency string Collection currency
amount number Gross amount received
fee number Fee deducted
amount_credited number Net amount credited to your wallet (amount − fee)
status string Collection status
sender_name / sender_bank string Payer details, when available
created_at string ISO 8601 timestamp

Errors

Code Meaning
UNAUTHORIZED Business not found or inactive
INVALID_REQUEST Invalid filter values (e.g. malformed date or unsupported currency)

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