Skip to main content
A payout moves money out of one of your balances to a beneficiary. You create a payout with one call, 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. The type 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:
  • network is ethereum or solana. Hermes must support the asset on that network. USDT is on ethereum. USDC is on ethereum and solana. A different pair gets invalid_wallet_address.
  • address must have the correct shape for the network. On ethereum, an address in mixed case must pass the EIP-55 checksum. An address in lower case only needs the correct shape.
  • beneficiary_type is individual or business. The default is individual. beneficiary_date_of_birth is necessary for each individual, in YYYY-MM-DD form. beneficiary_country is an ISO-2 code.
  • Hermes does not support a wallet destination that needs a memo or a tag.
Hermes checks each destination field before it holds money. A bad field gets 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 its status is active. USD beneficiaries are for USD payouts only.
  • source_asset is always USDC. A different source_asset gets unsupported_pair (422).
  • amount is the USD that the beneficiary receives.
  • fee is the all-in fee. It is all the fees of the payout, in one figure.
  • source_amount is equal to amount, and rate is 1.00000000.
  • Hermes debits source_amount plus fee from your USDC balance.
For example, a payout of USD 10,000.00 with a 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 a third_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 field file.
  • 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 gets unsupported_media_type (415).
  • The request needs an Idempotency-Key.
  • One invoice is for one payout. You cannot use an invoice again.
A payout to a 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

A failed 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 an Idempotency-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 with GET /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.
A USD payout to a saved beneficiary has a receipt_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

A wallet 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_hash when the payout is pending, as soon as Hermes knows the hash. A pending payout can show null for a short time.
  • The data field of each payout webhook also has tx_hash.
  • tx_hash is null for 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.
If the network rejects the transfer, the payout becomes 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. The failure field stays null. The terminal_at field keeps the time of the first success.
The status words are the same as on /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 sends payout.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.
A reversal needs your attention, and your balance can be late.A payout.reversed event tells you that the provider took back a payout that succeeded before. The recipient no longer has the money. If you gave goods or services after payout.succeeded, this event tells you to act.For a short time after the event, GET /v2/balances can still show the payout as spent. A person in Jenzy operations posts the correction. Use the event as the correct signal, and let your balance catch up.A reversal is not usual, and Jenzy always examines one.

Limits

Each asset and each destination type has a minimum and a maximum for one payout. Hermes measures the limits on amount, the figure that the beneficiary receives.
  • Below the minimum gets amount_below_minimum (422).
  • Above the maximum gets limit_exceeded (422).
There is no daily cap on /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_amount plus the fee is more than your available in source_asset.
  • corridor_not_enabled (403) — Jenzy did not enable this asset, or this operation in this asset, for your org.
  • unsupported_pair (422) — source_asset is not the same as asset, or not USDC on 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.