> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# USD beneficiaries

> Register a USD bank account one time. Then pay it with a USD payout.

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.

> [!NOTE]
>
> USD beneficiaries are for USD payouts only. A payout in a different asset
> carries its destination in the request. See [Payouts](https://docs.jenzy.com/v2/payouts.md).

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

```bash theme={null}
curl -X POST https://api.jenzy.com/v2/beneficiaries \
  -H "Authorization: Bearer jz_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "holder": {
      "type": "business",
      "name": "Meridian Cargo Solutions LLC",
      "email": "accounts@meridiancargo.com",
      "phone": "+17189042371"
    },
    "holder_address": {
      "street_line_1": "200 Liberty Street",
      "city": "New York",
      "state": "US-NY",
      "postcode": "10281",
      "country": "US"
    },
    "bank": {
      "name": "Column NA",
      "account_number": "787212236285345",
      "account_type": "checking",
      "address": {
        "street_line_1": "1 Letterman Drive",
        "city": "San Francisco",
        "state": "US-CA",
        "postcode": "94129",
        "country": "US"
      }
    },
    "rail": "fedwire",
    "routing_number": "121145349",
    "counter_party": "third_party",
    "relationship": "supplier",
    "purpose": "freight"
  }'
```

| Field | What to send |
| - | - |
| `holder` | The holder of the account. See [The holder](#the-holder). |
| `holder_address` | The address of the holder. |
| `bank` | `name`, `account_number`, `account_type`, and the `address` of the bank. The `account_number` has 4 to 17 digits. The `account_type` is `checking` or `savings`. |
| `rail` | How the USD goes to the bank: `fedwire` or `swift`. |
| `routing_number` | For `fedwire`, the 9-digit ABA number of the bank. For `swift`, the BIC of the bank. |
| `intermediary_routing_number` | For `swift` only, and necessary there. The ABA number or the BIC of the intermediary bank. |
| `counter_party` | `first_party` for an account of your own org. `third_party` for an account of a different business or a person. |
| `relationship` | What the holder is to your org. |
| `purpose` | Why your org pays the holder. |

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:

| Holder `type` | `purpose` |
| - | - |
| `business` | `goods`, `services`, `freight`, or `intercompany`. |
| `individual` | `family_support`, `goods`, `services`, `income`, `education`, `donation`, `investment`, or `own_account`. |

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](https://docs.jenzy.com/v2/payouts.md#usd-payouts).

## The holder

`holder.type` is `business` or `individual`.

| `type` | Fields |
| - | - |
| `business` | `name`, `email`, and `phone`. |
| `individual` | `first_name`, `last_name`, `email`, `phone`, and `occupation_id`. |

The `phone` is in E.164 form, with the `+`. `occupation_id` is an `id`
from `occupations` in [`GET /v2/lists`](https://docs.jenzy.com/v2/child-orgs#the-lists).

```json theme={null}
"holder": {
  "type": "individual",
  "first_name": "Ana",
  "last_name": "Lopez",
  "email": "ana.lopez@example.com",
  "phone": "+17189042371",
  "occupation_id": 504
}
```

## 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`.

| You send | You get |
| - | - |
| New bank details | `201` and a new beneficiary. |
| The same bank details and the same body again | `200` and the first beneficiary, with its current `status`. |
| The same bank details and a different body | `409` with the code `beneficiary_exists`. The message gives the `id` of the first beneficiary. |

So, after a timeout, send the same request again. You cannot get two
beneficiaries for one bank account.

## The beneficiary resource

```json theme={null}
{
  "id": "3f6c2a9e-8b1d-4c7e-9a2f-5d4e6b7c8a90",
  "asset": "USD",
  "status": "pending",
  "holder": {
    "type": "business",
    "name": "Meridian Cargo Solutions LLC",
    "email": "accounts@meridiancargo.com",
    "phone": "+17189042371"
  },
  "holder_address": { "street_line_1": "200 Liberty Street", "city": "New York", "state": "US-NY", "postcode": "10281", "country": "US" },
  "bank": {
    "name": "Column NA",
    "account_number": "787212236285345",
    "account_type": "checking",
    "address": { "street_line_1": "1 Letterman Drive", "city": "San Francisco", "state": "US-CA", "postcode": "94129", "country": "US" }
  },
  "rail": "fedwire",
  "routing_number": "121145349",
  "intermediary_routing_number": null,
  "counter_party": "third_party",
  "relationship": "supplier",
  "purpose": "freight",
  "failure": null,
  "created_at": "2026-10-15T09:14:02.000Z",
  "updated_at": "2026-10-15T09:14:02.000Z"
}
```

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](https://docs.jenzy.com/v2/child-orgs.md) 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.

| `status` | Meaning | Can you pay it? |
| - | - | - |
| `pending` | The check continues. | No. |
| `active` | The beneficiary passed the check. | Yes. Only an `active` beneficiary can get a payout. |
| `rejected` | The beneficiary did not pass. This status is final. | No. |
| `inactive` | The beneficiary cannot get a payout now. It can become `active` again. | No. |

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.

| Event | When |
| - | - |
| `beneficiary.active` | The beneficiary passed the check, or became `active` again. You can pay it now. |
| `beneficiary.rejected` | The beneficiary did not pass. `failure` gives the code. |
| `beneficiary.inactive` | The beneficiary cannot get a payout now. |

The delivery carries `api_version: "v2"`. Its `data` is the beneficiary, as
`GET /v2/beneficiaries/{id}` shows it. See [Webhooks](https://docs.jenzy.com/webhooks.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.