Skip to main content
A collection is money that arrived on one of your balances. A USD 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 USD: virtual accounts

GET /v2/virtual-accounts?asset=USD gives your USD bank details. Give them to the person who pays you. There is one account for each rail. Jenzy must enable USD collections for your org. If Jenzy did not, the request gets 403 with the code corridor_not_enabled, or 404 with the code not_found.
A USD virtual account has these fields: account_name is the legal name of your org. Jenzy operations makes the virtual account for you. You cannot make one from the API. The list shows only active accounts. An account that is not ready yet does not show. If no account is active yet, the request gets 403 with the code corridor_not_enabled. USD that a payer sends to this account arrives as USDC. Your USDC balance increases. You have no USD balance. See USD collections. 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": "ethereum" } gives you your address on that network. Each call for the same network returns the same address. There is no Idempotency-Key. The response is one address:
GET /v2/deposit-addresses lists all your addresses:
An address is per network, not per asset. One address can take more than one asset. assets lists each stablecoin that the address takes. To show where to send each asset, make one row for each asset in assets:
  • Use the networks that the list shows for your organization. Not each organization has the same networks or the same assets on a network.
  • A request for a network that your organization cannot use gets a 422 with the code unsupported_network.
Send only an asset in the assets list of the address, on the network of the address. The network accepts each token, but Jenzy credits only the listed assets. A different token does not become a collection. To get it back, speak to Jenzy operations. The recovery can take some time.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.

When a deposit credits

Hermes credits a deposit after the network confirms it: These times are usual times, not a guarantee.

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.
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.

USD collections

USD that a payer sends to your USD virtual account arrives as USDC. The collection has asset: "USDC", and amount is the USDC that landed. source.amount and source.asset give the USD that your virtual account received.
The difference between the two amounts is the fees. GET /v2/collections?asset=USD gets 404 with the code not_found. Use asset=USDC.

The source object

source tells you where the money came from. Its type mirrors the destination.type of a payout. 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 USD payment to your invoice, use its USD amount, source.amount, and the time. 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. For a stablecoin transfer, see When a deposit credits.

When the source changes

Sometimes Hermes credits a USD collection or a payout_refund before it knows the origin of the USDC. Then the collection starts with source.type: "wallet". When Hermes knows the origin, the source changes one time, to bank or payout_refund. Hermes then sends collection.updated, with the full collection in data. Hermes sends collection.updated only for this change. The amount, the status, and your balance do not change. Replace the source that you keep.

Give money back to a payer

There is no refund request for a collection. To give money back, register the payer as a USD beneficiary, and pay it with a USD payout. The payout fees apply again. A person can also be a USD beneficiary. See The holder for the fields to send.

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.
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.