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.
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 anIdempotency-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
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 arejected beneficiary again. A
second request gets the rejected beneficiary. Speak to Jenzy.
Webhooks
Hermes sends one event when thestatus 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.