Skip to main content
A Child org is an account that you open for one of your customers. Your customer can be a person or a business. The money in a Child org belongs to your customer, not to you. Your customer does not use Hermes. Your customer uses your product, and you use the API for your customer. A Child org is a full org. It has its own balances, its own USD bank details, its own deposit addresses, and its own USD beneficiaries. It does not have API keys, users, or webhook endpoints. Only you, the parent, can use it.
Jenzy must let your org have Child orgs. If Jenzy did not, POST /v2/child-orgs gets 403 with the code forbidden. To get Child orgs, speak to Jenzy.

How a Child org opens

  1. Create the Child org with POST /v2/child-orgs. Send the details of your customer. The Child org starts incomplete.
  2. Upload the documents that requirements lists, with POST /v2/child-orgs/{id}/documents.
  3. Show the terms at terms_url to your customer. When your customer accepts them, send the value with POST /v2/child-orgs/{id}/terms.
  4. When you owe nothing, the review starts. The status becomes in_review.
  5. The review approves the Child org (active), asks for more (action_required), or refuses it (rejected).
Jenzy does not do the review and does not promise a time for it. You get a child_org.updated event each time the status, the requirements, or the capabilities change.

Create a Child org

Send type and one object for that type. You can also send reference. It is your own id for the customer. It must be unique among your Child orgs. This request does not use an Idempotency-Key. Send a reference to make a retry safe: a second request with the same reference gets 409 with the code conflict.
The answer is 201 and the Child org. Hermes checks each field first. A bad field gets 400 with the code validation_error. The message names the field. Some rules for the fields:
  • A country is an ISO 3166-1 alpha-2 code, for example DE. subdivision_code is an ISO 3166-2 code that starts with the country, for example DE-NW.
  • A date is YYYY-MM-DD. A phone number is in E.164 form, with the +.
  • identity_document.type is passport, national_id, drivers_license, or residence_permit. You upload the file later, with the same type.
  • A business has one or more associated_parties: its owners, directors, and signers. Each party has its own email.
  • industry_codes are 6-digit NAICS 2022 codes. See Industries that Jenzy does not serve.
  • tax_id is optional. It has country, type, and number.

The lists

Some fields take a value from a fixed list. Get the lists with GET /v2/lists:
A value that is not in its list gets 400 with the code validation_error. The lists do not change often. You can keep a copy.

Industries that Jenzy does not serve

Jenzy does not open a Child org for a business in these industries:
  • Bearer share corporations and shell companies
  • Pornography, escort services, and the sale or advertising of sexual services
  • Bonded warehouses
  • Cash intensive businesses, for example the import of used vehicles or vehicle parts, laundromats, and pawn shops
  • Charities without a registration, and crowdfunding
  • Convenience stores
  • Defence and weapons, and nuclear or military energy
  • Development aid and embassies
  • Gambling and gaming
  • Lobbying, pressure groups, and think tanks
  • Sanctioned businesses
  • Cannabis and cannabis products or services
industry_codes are 6-digit NAICS 2022 codes. A code in prohibited_industry_codes gets 422 with the code prohibited_industry. Hermes does not keep the Child org. Jenzy can also refuse or close a Child org in one of these industries after the review.

The Child org resource

Read your Child orgs with GET /v2/child-orgs, newest first, and one Child org with GET /v2/child-orgs/{id}.

Statuses

An incomplete Child org does not expire. A rejected Child org stays in your list.

Requirements

Each item in requirements is one thing that you owe. It is for the Child org, or for one associated party. For the Child org, party_id is null. For a party, party_id is the id of the party.
  • A document has a document_category and the document_types that are correct for it. One file of one of these types is enough. field is null.
  • A detail has a field, for example terms_value or identity_document.expiry_date. document_category is null.
reason is missing, expired, or invalid. An active Child org can also get a request after the approval. Then requirements lists it, and the status stays active.

Capabilities

capabilities tells you what the Child org can do in USD. Each value is pending, active, or unavailable. A check by the bank can continue after the approval. Until it ends, a capability stays pending. When the Child org is rejected, each capability is unavailable.

Upload documents

Send each document as multipart/form-data:
The answer is 201 and the document. A file that is too large gets 413 with the code payload_too_large. A file that is not a PDF, a JPEG, or a PNG gets 415 with the code unsupported_media_type.

Send the terms value

You must show the terms page at terms_url to your customer. Your customer must accept the terms. You cannot accept them for your customer. When your customer accepts, the page gives a tos_policies_value. Send it as terms_value:
The answer is the Child org. When you owe nothing more, its status is in_review. After you send the value, terms_url is null.

Answer a request for information

When the review needs more, the status is action_required, or requirements lists new items on an active Child org. Do these steps:
  1. Upload each document that requirements lists, with POST /v2/child-orgs/{id}/documents.
  2. Send POST /v2/child-orgs/{id}/information with the details that requirements lists:
    • identity_documents: a new identity document, when requirements lists an identity_document.* field. Each item has party_id, type, number, country, issue_date, and expiry_date. Upload the file with the same type first.
    • terms_value: when requirements lists terms_value.
The answer is the Child org, with its new status. If an item that requirements lists has no answer, the request gets 400 with the code validation_error. The message names the item. If the review asks for nothing, the request gets 409 with the code conflict. Only Jenzy can answer some requests. For these, the request gets 409 with the code conflict. Speak to Jenzy.

Use the API for a Child org

To make a /v2 request for a Child org, send its id in the Hermes-Org header. Use your own API key.
  • With the header, the request is for the Child org: its balances, its collections, its payouts, and its beneficiaries. Without the header, the request is for your org.
  • The header works only on /v2, and only when the Child org is active.
  • An id that is not one of your Child orgs gets 404 with the code not_found. A Child org that is not active yet also gets 404.
  • A suspended Child org gets 403 with the code forbidden.
  • Orders are not available for a Child org. An order request with the header gets 404.
  • An Idempotency-Key is unique for each org. The same key on your org and on a Child org makes two different requests.

What a Child org gets from you

  • Prices. A Child org pays your prices. When Jenzy changes your prices, the change applies to each Child org at once. Jenzy does not add a margin for you. You charge your customer outside Hermes.
  • Assets. A Child org can use the stablecoins and the USD that Jenzy enables for your org. capabilities also controls USD for the Child org.
  • Suspension. When Jenzy suspends your org, each Child org is also suspended. When Jenzy removes the suspension, the Child orgs continue.

No money moves between orgs

Hermes does not move money between your org and a Child org, or between two Child orgs. Each Child org owns its money. To move the stablecoins of a Child org, send a wallet payout from the Child org to an address. The address can be a deposit address of your org. See Payouts. Each Child org registers its own USD beneficiaries. A beneficiary of one org cannot get a payout from a different org.

Webhooks

The events of a Child org go to your webhook endpoint. Each event of a Child org has org_id. It is the id of the Child org, the same value as the Hermes-Org header. The events of your own org do not have org_id.
Hermes sends child_org.updated when the status, the requirements, or the capabilities of a Child org change. There is no event when you create a Child org. The answer to your POST gives the Child org.

Test in the sandbox

In the sandbox, you select the result of the review. Use the last name of a person, or the legal_name of a business. See Sandbox → Child orgs.