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.
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:
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
422with the codeunsupported_network.
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 withGET /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 hasasset: "USDC", and amount is the USDC that landed.
source.amount and source.asset give the USD that your virtual account
received.
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 onecollection.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 apayout_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 acollection.reversed event. The status of the collection changes to
reversed on the read endpoints.