> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Collections

> Money that arrives on one of your balances is a collection. Where to send it, and what you see.

A **collection** is money that arrived on one of your balances. A bank
transfer to your virtual account is a collection. A stablecoin transfer to
your deposit address is a collection. Both use the same resource.

Hermes credits your balance, sends `collection.settled` to your webhook
endpoint, and adds the collection to `GET /v2/collections`. There is no work
for you on the side of the payer.

## Where to send fiat: virtual accounts

Your org has one virtual account for each fiat asset that Jenzy enabled for
collections. `GET /v2/virtual-accounts?asset=KES` gives the coordinates. Give
them to the person who pays you.

```json theme={null}
{
  "virtual_accounts": [
    {
      "id": "b7c9d1e2-3f4a-4b5c-8d6e-7f8a9b0c1d2e",
      "asset": "KES",
      "type": "bank",
      "institution": "Partner Bank",
      "account_number": "0123456789",
      "account_name": "Acme Remittances Ltd",
      "status": "active",
      "paybill_number": "444174"
    }
  ]
}
```

Jenzy operations makes the virtual account for you. You cannot make one from
the API. A row with `status: "pending"` is not ready yet. Wait for
`status: "active"` before you give the details to a payer.

**KES has two ways to pay.** A payer at a bank sends a transfer to the
`account_number` at the `institution`, over PesaLink, RTGS, or SWIFT. A payer
on M-Pesa uses the paybill.
The payer enters `paybill_number` as the business number, and your
`account_number` as the account number. Both ways credit the same balance.

`asset=USDT` on this endpoint gets `422`. A stablecoin has no virtual
account. It has a deposit address.

## Where to send stablecoins: deposit addresses

`POST /v2/deposit-addresses { "network": "tron" }` gives you an address on
that network. The first call makes the address. Each later call for the same
network returns the same address. There is no `Idempotency-Key`.

```json theme={null}
{ "network": "tron", "address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9", "assets": ["USDT"] }
```

* An address is per **network**, not per asset. `assets` lists each
  stablecoin that the address takes. One `ethereum` address takes both USDT
  and USDC.
* The networks are `ethereum`, `solana`, and `tron`. Hermes does not support
  another network, not even one that uses the same address form.
* `GET /v2/deposit-addresses` lists your addresses.

<Warning>
  **A transfer below 1 USDT or 1 USDC does not arrive.** Hermes never sees
  it, and it never becomes a collection. The money does not come back. Send
  1 or more.

  Send only an asset in the `assets` list, on the network of the address. A
  different token on the same address does not become a collection.
</Warning>

## The collection resource

Read collections with `GET /v2/collections` and `GET /v2/collections/{id}`.
`GET /v2/collections` puts the newest collection first and uses keyset
pagination. Filter with `asset`. The `data` field of the `collection.settled`
event uses the same shape.

```json theme={null}
{
  "id": "7a4be2a4-90f4-4a5e-b7c9-1d2f5f6f8a31",
  "asset": "KES",
  "amount": "99300.00",
  "status": "settled",
  "source": { "type": "bank", "virtual_account_id": "b7c9d1e2-3f4a-4b5c-8d6e-7f8a9b0c1d2e" },
  "created_at": "2026-09-09T09:40:53.000Z"
}
```

**`amount` is what landed on your balance.** It is one figure. There is no
`fee` field and no gross figure. The collection fee that you agreed with
Jenzy is already out of it. Your balance increases by exactly `amount`.

## The `source` object

`source` tells you where the money came from. Its `type` mirrors the
`destination.type` of a payout.

| `source.type` | Fields               | When                                                          |
| ------------- | -------------------- | ------------------------------------------------------------- |
| `bank`        | `virtual_account_id` | A bank transfer or a paybill payment to your virtual account. |
| `wallet`      | `network`, `address` | A stablecoin transfer to your deposit address.                |

**A bank pay-in carries no payer identity.** Hermes does not get the name or
the account of the payer, so `source` has none. To match a pay-in to your own
customer, use the amount and the time. Or give each customer a separate
instruction. A paybill payment also shows as `type: "bank"`.

A wallet `source` names your own deposit address and its network. It does not
name the address of the sender. `network` can be `null` for a short time
while Hermes resolves it.

## How to learn about a collection

Hermes sends exactly one `collection.settled` event for each movement of your
balance. The delivery carries `api_version: "v2"`. Process each event `id`
one time only. After an outage, use `GET /v2/collections` to catch up. A
poll and a webhook give the same data.

A collection can take some minutes to appear after the payer sends the
money. A stablecoin transfer appears after the network confirms it.

## Reversals

Sometimes a provider takes a pay-in back after it settles. Hermes then sends
you a `collection.reversed` event. The `status` of the collection changes to
`reversed` on the read endpoints.

<Warning>
  **Use the event as the correct signal, and let your balance catch up.**

  For a short time after a `collection.reversed` event, `GET /v2/balances`
  can read **high**. The provider already took the money back. A person in
  Jenzy operations posts the correction. Your `available` in that asset can
  go below zero, and then `shortfall` shows the gap.

  Do not give goods or services against a balance that includes a reversed
  collection. A reversal is not usual, and Jenzy always examines one.
</Warning>