POST /v2/payouts. Hermes holds the money at once.
Hermes then tracks the transfer to a terminal state.
For money that comes into your balance, see Collections.
One endpoint, two destination types
There is no rail in the path. Thetype field of the destination object
selects the rail.
The asset selects the type. A USD payout takes only
beneficiary. USD
beneficiaries are for USD payouts only. Each other asset takes only
wallet. A USD payout with a different type gets
beneficiary_required (422). A different asset with beneficiary gets
beneficiary_not_allowed (422).
Rules for each type:
networkisethereumorsolana. Hermes must support the asset on that network. USDT is onethereum. USDC is onethereumandsolana. A different pair getsinvalid_wallet_address.addressmust have the correct shape for the network. Onethereum, an address in mixed case must pass the EIP-55 checksum. An address in lower case only needs the correct shape.beneficiary_typeisindividualorbusiness. The default isindividual.beneficiary_date_of_birthis necessary for eachindividual, inYYYY-MM-DDform.beneficiary_countryis an ISO-2 code.- Hermes does not support a wallet destination that needs a memo or a tag.
400 or 422, and Hermes makes no payout.
USD payouts
A USD payout pays a USD beneficiary from your USDC balance. Register the beneficiary first, and wait until itsstatus is
active. USD beneficiaries are for USD payouts only.
source_assetis alwaysUSDC. A differentsource_assetgetsunsupported_pair(422).amountis the USD that the beneficiary receives.feeis the all-in fee. It is all the fees of the payout, in one figure.source_amountis equal toamount, andrateis1.00000000.- Hermes debits
source_amountplusfeefrom your USDC balance.
fee of 37.05 debits
10,037.05 USDC. There is no quote step. To know the fee first, use the price list that you agreed with
Jenzy.
The minimum is USD 100. A smaller amount gets amount_below_minimum
(422).
A beneficiary that is not active gets beneficiary_not_active (422).
Hermes holds no money.
The invoice
A USD payout to athird_party beneficiary needs an invoice. Upload the
invoice first with POST /v2/documents. Then put its id in
invoice_document_id.
- Send the file as
multipart/form-data, in the fieldfile. - The file is a PDF, a JPEG, or a PNG, of 5 MB or less. A larger file gets
payload_too_large(413). A different type getsunsupported_media_type(415). - The request needs an
Idempotency-Key. - One invoice is for one payout. You cannot use an invoice again.
third_party beneficiary with no invoice gets
invoice_required (422). Hermes holds no money. A payout to a first_party
beneficiary does not need an invoice, but it can have one.
When the beneficiary gets the money
- Fedwire: the cutoff is 4:45 PM Eastern Time. A payout that Hermes accepts after the cutoff completes on the next business day. A payout on a US bank holiday also completes on the next business day.
- SWIFT: intermediary banks can take fees. So the beneficiary can get
less than
amount.
When a USD payout fails
Afailed USD payout is final. Its failure.code is always declined. Ask
Jenzy for the reason.
If the USDC did not leave your balance, Hermes releases the full hold. If
the USDC left your balance, the USDC comes back as a
collection. Its source.type is payout_refund, and
source.payout_id is the id of the payout. The refund is the USDC that
Hermes sent, less the fees that the bank network keeps. The fee of a failed
USD payout does not change to 0.
When the bank of the beneficiary returns the money after a succeeded
payout, the payout becomes reversed. The USDC comes back as a
payout_refund collection.
The money fields
amount and asset are always what the beneficiary receives. Hermes
never changes them.
source_asset is the asset that you pay from. The default is asset. For
each payout except a USD payout, source_asset must be the same as asset.
A different source_asset gets unsupported_pair (422). The response shows
source_amount equal to amount, and rate is null.
When Hermes accepts a payout, it holds
source_amount, the fee, and a
reserve for the provider fee, all in source_asset. Your available in
that asset must cover the three together. If it does not, you get
insufficient_funds (402), and Hermes makes no payout.Idempotency
Each create request needs anIdempotency-Key header. A request with no
key gets 400 validation_error. Make one key for each payout that you intend
to send. You can use a UUID.
Send the same key with the same body again, and Hermes returns the first
response again, with the same bytes. Because of this, a network timeout or a
second request cannot cause two payments.
The same key with a different body gets 409 conflict. One key group
covers /v1 and /v2. Do not use one key on both APIs.
A payout can be failed in its creation response
Hermes sends the payout to the provider inside the create call. Most refusals
happen before Hermes holds money, and those are a 4xx with no payout. In
rare cases the provider refuses the payout at once. Then the 201 response
carries the payout with status: "failed", and failure set.
Hermes already released the hold. Hermes also sends payout.failed. Read the
status of each 201 response. Do not assume that a 201 is a payout in
progress.
The payout resource
Read payouts withGET /v2/payouts and GET /v2/payouts/{id}.
GET /v2/payouts puts the newest payout first and uses keyset pagination.
Filter with asset and status. The create response and the data field of
each payout webhook use the same shape.
The receipt link
A USD payout to a saved beneficiary has areceipt_url. Send receipt_url
to your beneficiary. The page shows the status of the payment. It does not
show your fee or rate. The link is in the create response and in each payout
webhook. It does not expire.
receipt_url is null for all other payouts. In the sandbox, the link is on
track.sandbox.jenzy.com, and the page shows that it is a sandbox receipt.
The transaction hash
Awallet payout has a tx_hash. This is the hash of the transfer on the
network: an Ethereum transaction hash, or a Solana signature. Use it to
find the transfer on a block explorer, for example Etherscan or Solscan.
- Hermes sets
tx_hashwhen the payout ispending, as soon as Hermes knows the hash. Apendingpayout can shownullfor a short time. - The
datafield of each payout webhook also hastx_hash. tx_hashisnullfor all other payouts.
When a wallet payout is succeeded
- Ethereum: when the transfer is 13 blocks deep. This is about 3 minutes after the network includes the transfer.
- Solana: when the network finalizes the transfer. This takes about 15 seconds.
failed, and
Hermes releases the full hold.
Status lifecycle
held— the money is on hold. The provider did not confirm the payout yet. A payout stays here for a short time, or when the provider is not available. Hermes continues from here by itself.pending— the provider has the payout and works on it. This is the only status where a payout waits. Hermes reads the status again. Hermes does not send the payout a second time.succeeded/failed— terminal. No other status is final.reversed— the payout succeeded, and then the provider took the money back. This is not a failure. Thefailurefield staysnull. Theterminal_atfield keeps the time of the first success.
/v1. The failure.code words are the
same too. The reference also lists received, validated, and submitted.
A /v2 payout passes through them inside the create call. You do not see
them in a response or in an event.
How to learn the result
Webhooks (recommended) — Hermes sendspayout.succeeded, payout.failed,
or (not often) payout.reversed. A /v2 delivery carries
api_version: "v2", and data is the payout in the shape above. See
Webhooks.
A poll — read GET /v2/payouts/{id} again until the status is terminal.
A poll and a webhook give the same data. So you can always use
GET /v2/payouts to catch up after an outage.
When a payout fails, Hermes releases the full hold back to available in
source_asset. A failed payout shows fee: "0". A USD payout is different.
See When a USD payout fails. The failure.code field
tells you if a second payout can succeed:
Hermes never sends a failed payout again. To try again, always create a
new payout with a new
Idempotency-Key.
Limits
Each asset and each destination type has a minimum and a maximum for one payout. Hermes measures the limits onamount, the figure that the
beneficiary receives.
- Below the minimum gets
amount_below_minimum(422). - Above the maximum gets
limit_exceeded(422).
/v2. Your available in source_asset is the
ceiling. The request rate limit of your org still applies. See
Authentication.
Common rejections
Hermes refuses the request and holds nothing. See Errors for the complete list.insufficient_funds(402) —source_amountplus the fee is more than youravailableinsource_asset.corridor_not_enabled(403) — Jenzy did not enable this asset, or this operation in this asset, for your org.unsupported_pair(422) —source_assetis not the same asasset, or notUSDCon a USD payout.invalid_wallet_address(422) — the address has the wrong shape for the network, or the asset does not exist on the network.amount_below_minimum/limit_exceeded(422) — see Limits above.