Skip to main content
A USD beneficiary is the bank account of a business or a person that gets USD. You register it one time with POST /v2/beneficiaries. Then each USD payout to that account names the beneficiary.
USD beneficiaries are for USD payouts only. A payout in a different asset carries its destination in the request. See Payouts.
Jenzy must enable USD payouts for your org. If Jenzy did not, the request gets 403 with the code corridor_not_enabled.

Register a USD beneficiary

An address has street_line_1, city, state, postcode, and country. country is an ISO 3166-1 alpha-2 code, for example US. state is an ISO 3166-2 code that starts with the country, for example US-NY. relationship is one of these values: supplier, vendor, service_provider, merchant, contractor, customer, subsidiary, parent_company, affiliate_business, bank_account, employee, freelancer, gig_worker, affiliate, family_member, friend, or self. Each value is correct for the two types of holder. purpose has one list for each type of holder: A purpose from the list of the other type gets 422 with the code invalid_beneficiary. There is no “other” value in these lists. If no value is correct for your beneficiary, speak to Jenzy. Hermes checks each field before it keeps the beneficiary. A bad field gets 422 with the code invalid_beneficiary. The message names the field. A payout to a third_party beneficiary needs an invoice. See Payouts.

The holder

holder.type is business or individual. The phone is in E.164 form, with the +. occupation_id is an id from occupations in GET /v2/lists.

The bank details are the key

This request does not use an Idempotency-Key. The bank details are the key: rail, routing_number, and bank.account_number. So, after a timeout, send the same request again. You cannot get two beneficiaries for one bank account.

The beneficiary resource

Read your beneficiaries with GET /v2/beneficiaries, newest first, and one beneficiary with GET /v2/beneficiaries/{id}. Put the id in the destination.beneficiary_id of a USD payout. A Child org registers its own beneficiaries. Send the Hermes-Org header. A beneficiary of one org cannot get a payout from a different org.

Statuses

Each new beneficiary gets a check before you can pay it. Jenzy does not promise a time for the check. A USD payout to a beneficiary that is not active gets 422 with the code beneficiary_not_active. Hermes holds no money. A rejected beneficiary has a failure. Its code is recipient_account_invalid when the bank details are not correct, or declined. The 201 answer can already show rejected. Ask Jenzy for the reason.

After you register a beneficiary

You cannot edit or delete a beneficiary. To pay new bank details, register a new beneficiary. You cannot register the bank details of a rejected beneficiary again. A second request gets the rejected beneficiary. Speak to Jenzy.

Webhooks

Hermes sends one event when the status of a beneficiary changes. There is no event for pending. The answer to your POST gives that status. The delivery carries api_version: "v2". Its data is the beneficiary, as GET /v2/beneficiaries/{id} shows it. See Webhooks.