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
- Create the Child org with
POST /v2/child-orgs. Send the details of your customer. The Child org startsincomplete. - Upload the documents that
requirementslists, withPOST /v2/child-orgs/{id}/documents. - Show the terms at
terms_urlto your customer. When your customer accepts them, send the value withPOST /v2/child-orgs/{id}/terms. - When you owe nothing, the review starts. The status becomes
in_review. - The review approves the Child org (
active), asks for more (action_required), or refuses it (rejected).
child_org.updated event each time the status, the requirements, or the
capabilities change.
Create a Child org
Sendtype 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.
- Person
- Business
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_codeis an ISO 3166-2 code that starts with the country, for exampleDE-NW. - A date is
YYYY-MM-DD. A phone number is in E.164 form, with the+. identity_document.typeispassport,national_id,drivers_license, orresidence_permit. You upload the file later, with the sametype.- A business has one or more
associated_parties: its owners, directors, and signers. Each party has its own email. industry_codesare 6-digit NAICS 2022 codes. See Industries that Jenzy does not serve.tax_idis optional. It hascountry,type, andnumber.
The lists
Some fields take a value from a fixed list. Get the lists withGET /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
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 inrequirements 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_categoryand thedocument_typesthat are correct for it. One file of one of these types is enough.fieldisnull. - A detail has a
field, for exampleterms_valueoridentity_document.expiry_date.document_categoryisnull.
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 asmultipart/form-data:
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 atterms_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:
in_review. After you send the value, terms_url is null.
Answer a request for information
When the review needs more, the status isaction_required, or
requirements lists new items on an active Child org. Do these steps:
- Upload each document that
requirementslists, withPOST /v2/child-orgs/{id}/documents. - Send
POST /v2/child-orgs/{id}/informationwith the details thatrequirementslists:identity_documents: a new identity document, whenrequirementslists anidentity_document.*field. Each item hasparty_id,type,number,country,issue_date, andexpiry_date. Upload the file with the sametypefirst.terms_value: whenrequirementsliststerms_value.
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 isactive. - An
idthat is not one of your Child orgs gets404with the codenot_found. A Child org that is notactiveyet also gets404. - A
suspendedChild org gets403with the codeforbidden. - Orders are not available for a Child org. An order request with the
header gets
404. - An
Idempotency-Keyis 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.
capabilitiesalso 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 awallet 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 hasorg_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.
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 thelegal_name of a business. See
Sandbox → Child orgs.