Modular Payouts API Integration Guide
Always-on global payouts at internet speed - end to end technical integration guide
zerohash LLC (US entity)The following steps should be followed if you're onboarding a Customer to zerohash LLC (the US entity)
Introduction
Our API-powered Payouts product allows marketplaces, payment service providers, employer of record platforms, and more to offer stablecoins as a payout option. The benefits include:
- Stablecoins are used as a store of value in countries with volatile currencies and high inflation
- Platforms using this product can reach their customers globally, without the hassle of integrating new or updating existing local fiat payment methods
- Stablecoins act as an alternative payment rail to send payments across borders near instantly with reduced fees
Definitions
| Term | Definition |
|---|---|
| Payout | The conversion of fiat to stablecoin and an automatic on-chain transfer to a destination address. |
| Platform | The company that's in contract with zerohash and directly interacts with zerohash's API's or SDK's. |
| Payor | A non-natural person (typically a business) that is a customer of the Platform. This is the core front-end that the Beneficiary interacts with. |
| Beneficiary | The natural person that receives the stablecoin payout. |
High Level Flow
- Submit Payor
- Query Payor
- Fund Float Account
- Submit Beneficiary
- Query Beneficiary
- Connect External Account
- Query External Accounts
- Initiate Payout
- Query Payouts
- Network Fee Procedures
- Email Receipt Requirements
Initial Setup
The Platform will need to onboard its business to the zerohash platform. They then need to add additional users, create API keys, and whitelist IP addresses. See instructions here.
Platforms should be listening to the following webhooks for Modular Payouts:
1. Submit Payor
Once API keys are created and approved, the Platform can begin to integrate to the API. For the following examples, we’ll assume the Platform's platform code is PLAT01.
US Payor Information
The Platform submits the Payor via POST /participants/entity/new
{
"platform_code": "PLAT01",
"entity_name": "Freelancer Platform XYZ",
"legal_name": "Freelancer Platform XYZ Inc.",
"contact_number": "15553765432",
"website": "www.freelancerplatform.com",
"date_established": "2018-01-15",
"entity_type": "llc",
"address_one": "1 Main St.",
"address_two": "Suite 1000",
"city": "Chicago",
"postal_code": "12345",
"jurisdiction_code": "US-IL",
"tax_id": "883987654",
"id_issuing_authority": "United States",
"risk_rating": "low",
"risk_vendor": "passbase",
"sanction_screening": "pass",
"sanction_screening_timestamp":1677252628000,
"metadata":{},
"signed_timestamp":1677252629000,
"submitter_email": "[email protected]",
"submitter_first_name": "Josh", // new addition to these specs 11.6.24 (to be a required field in the future)
"submitter_last_name": "Doe", // new addition to these specs 11.6.24 (to be a required field in the future)
"submitter_title": "Senior Legal Council", // new addition to these specs 11.6.24 (to be a required field in the future)
"control_persons":[
{
"name": "Joe Doe",
"email": "[email protected]",
"address_one": "1 South St.",
"address_two": "Suite 2000",
"city": "Chicago",
"postal_code": "12345",
"jurisdiction_code": "US-IL",
"date_of_birth": "1980-01-30",
"citizenship_code": "US",
"tax_id": "123456789",
"id_number_type": "us_passport",
"id_number": "332211200",
"kyc": "pass",
"kyc_timestamp": 1630623005000,
"sanction_screening":"pass",
"sanction_screening_timestamp":1677252628000,
"control_person": 1
}
],
"beneficial_owners":[
{
"name": "Jane Doe Jr",
"beneficial_owner":1,
"email": "[email protected]",
"address_one": "1 North St.",
"address_two": "Suite 3000",
"city": "Chicago",
"postal_code": "12345",
"jurisdiction_code": "US-IL",
"date_of_birth": "1980-01-30",
"citizenship_code": "US",
"tax_id": "012345578",
"id_number_type": "us_drivers_license",
"id_number": "P11122243333",
"kyc": "pass",
"kyc_timestamp": 1630623005000,
"sanction_screening": "pass",
"sanction_screening_timestamp":1677252628000
}
]
}The Platform must submit at least 1 beneficial_owners and 1 control_persons. If these persons do not have an SSN, the Platform must submit a document via POST /participants/entity/documents.
You’ll receive a participant_code in the response - this is the Payor participant code that uniquely identifies the entity indefinitely. We’ll use PAYOR1 as the participant_code throughout the examples.
See response for expected shape.
Payor Documents
Your Payor will not become approved unless you also supply the proper documents via POST /participants/entity/documents endpoint. Depending on the entity_type that was used in the original POST /participants/entity/new call, the document requirements vary. See details here.
The Platform submits the Payor documents via POST /participants/entity/documents:
{
"document": "...", // base 64 encoded file that you wish to upload (10mb limit)
"mime": "image/png",
"document_type": "articles_of_incorporation",
"file_name": "test.png",
"participant_code": "PAYOR1"
}State Logic
After a successful POST /participants/entity/new submission, the initial status of the entity will be submitted. In order to transition this to approved, the Platform must then submit all required documents, via POST /participants/entity/documents.
2. Query Payor
Platforms can query already-submitted Payors via the GET /participants endpoint. If you'd like to query a specific Payor use the participant_code parameter.
3. Fund Float Account
The Platform will fund their float account by sending fiat to the proper bank account. Here are the account details:
participant_code: 00SCXMaccount_group:PLAT01 (replace with your Platform's code)account_label: generalaccount_type: availableasset: USD
In Cert, your platform will be pre-funded with Float account funds.
4. Submit Beneficiary
US Natural Person - Beneficiary
The Platform submits a Natural Person Beneficiary via POST /participants/beneficiaries/new
Available to select Platforms only: you can conditionally submit either a phone_number or an email- you must submit at least one, otherwise the request will fail.
{
"first_name": "Lucas",
"last_name": "Martinez",
"email": "[email protected]",
"address_one": "Calle San Martín 305",
"address_two": "305",
"city": "Buenos Aires",
"zip": "C1000",
"jurisdiction_code": "AR-X",
"citizenship_code": "AR",
"date_of_birth": "1985-09-02",
"id_number_type": "non_us_passport",
"id_number": "A12345678",
"employment_status": "part_time", // optional
"industry": "consulting", // optional
"source_of_funds": "salary", // optional
"signed_agreements": [
{
"type": "payment_services_terms",
"region": "us",
"signed_timestamp": 1726005278070
}
]
}US Non-Natural Person - Beneficiary
The Platform submits a Non-Natural Person Beneficiary via POST /participants/entity-beneficiaries/new
{
"legal_name": "Legal Name",
"contact_number": "+1234567890",
"address_one": "123 Main St.",
"city": "Chicago",
"postal_code": "12345",
"jurisdiction_code": "US-IL",
"tax_id": "000-00-0000",
"id_issuing_authority": "US",
"address_two": "Suite 1000",
"email": "[email protected]",
"id_number": "549300TRWGQX5XMHYZ82"
}See response for expected shape.
You’ll receive a participant_code in the response - this is the Beneficiary participant code that uniquely identifies the payout recipient indefinitely. We’ll use BENEF1 as the participant_code throughout the examples.
NOTE:
- Even in Cert, zerohash will run each submitted Beneficiary through our Sanction Checks, subjecting the Beneficiaries to real validations. This means that if your entry is an actual sanctioned individual, the Beneficiary will be sent to a
rejectedstatus.- In Cert, if the Platform would like to test a rejection scenario, please submit a Beneficiary like the following, passing an
id_numberequal to111111111 - In Cert, if the Platform would like to test a rejection scenario, please submit a Beneficiary like the following, passing an
first_nameequal toJosephandlast_nameequal toKony
- In Cert, if the Platform would like to test a rejection scenario, please submit a Beneficiary like the following, passing an
- zerohash requires that the
jurisdiction_codeis not null and contains both a Country (ie, Brazil "BR") and a Subdivision (ie, Sao Palo "SP") to form BR-SP, for example. If your systems don't contain the subdivision and you only collect Country and Postal Code, we recommend performing a mapping on your side to derive the correct Subdivision, using the Country and Postal code as inputs. See this step-by-step guide on how to use an external API (ie, Google Geocoding API) to make a conversion between your data structure, to ours. - The API will allow for either a
tax_idor (id_numberandid_number_type). So, US persons with an SSN for example, can submit their SSN without additionally needing to undergo ID verification. - Platforms can query already-submitted Beneficiaries via the GET /participants endpoint.
- You should expect that Beneficiaries transition from
submittedtoapproved,rejected,pending_approval.
Beneficiary State Logic
After a successful POST /participants/beneficiaries/new submission, the initial status of the Beneficiary will be submitted. At this point, zerohash is running an automated compliance screening. If the person passes this check, the status will transition to an approved state. If the compliance screening results in a hit, the status will transition to a pending_approval status. Note: there is also a scenario where the Beneficiary transitions directly into a rejected state, depending on the compliance score. If the determination after a zerohash review is that the Beneficiary should not have been flagged, the status will transition to approved. Otherwise, the status will transition to rejected.
5. Query Beneficiary
Platforms can query already-submitted Beneficiaries via the GET /participants endpoint. A common query parameter is the participant_code, however the full list can be found on the API reference.
See response for expected shape.
6. Connect External Account
The Platform will connect the Beneficiary to an external account via POST /payments/external_accounts:
{
"participant_code": "BENEF1",
"type": "crypto", // enum: crypto, fiat
"details": {
"network": "SOL",
"supported_assets": ["USDC"],
"address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
}
}POST /payments/external_accounts responses:
| Scenario | Return code | status | Error Response |
|---|---|---|---|
| Valid request, approval required | 201 Created | pending | none |
| Valid request, no approval required | 201 Created | approved | none |
Missing or invalid participant_code | 400 Bad RequestOR 404 Client Error | n/a | should have required property 'participant_code'OR participant CUST01 not found OR failed to validate participant CUST01OR participant_code participant_code must be at least 6 characters long. |
Missing type; expecting type = "crypto" | 400 Bad Request | n/a | "For crypto accounts, "type" is required.","For fiat accounts, plaid_processor_token is required.","You should provide either valid details for crypto accounts or a plaid_processor_token for a fiat account." |
Missing or invalid details- this is where you provide external account information required for type = "crypto" | 400 Bad Request | n/a | For crypto accounts, "details" are required. |
Within details object, missing or containing invalid address | 400 Bad Request | n/a | details should have required property 'address'OR address should NOT be shorter than 5 charactersOR address should NOT be longer than 128 characters |
Within details object, Missing or unsupported network | 400 Bad Request | n/a | details should have required property 'network' |
Within details object, Neither supported_assets nor supported_symbols submitted | 400 Bad Request | n/a | details should have required property 'supported_assets' THEN details should have required property 'supported_symbols' THEN details should match exactly one schema in oneOf |
Within details object, supported_assets or supported_symbolsobject have missing or invalid content | 400 Bad Request | n/a | supported_assets (or supported_symbols) should be arrayOR 0 should NOT be shorter than # charactersOR no_destination_tag should be boolean |
| Crypto accounts not enabled for the platform Reach out to your zerohash Relationship Manager to fix your configuration. | 400 Bad Request | n/a | plaid_processor_token is required. |
External Account Webhooks
Listen to External Account Webhooks for notifications on crypto accounts created through POST /payments/external_accounts.
Webhook type: x-zh-hook-payload-type: external_account_status_changed
Payload fields:
- Always: participant_code, account_nickname, external_account_id, external_account_status, timestamp.
- Sometimes: account_type, status_reason, reference_id. The pending payload omits account_type.
| Scenario | Webhook |
|---|---|
| Account created. Every account passes through this. | External Account Webhook with external_account_status = pending |
| Crypto account passes address screening | External Account Webhook with external_account_status = approved |
| Crypto address is malformed, on the deny list, or fails validation definitively | External Account Webhook with external_account_status = rejected and status_reason = invalid or denied destination address |
| Crypto address is sanctioned | External Account Webhook with external_account_status = rejected and status_reason = sanctioned address |
| Address screening still unavailable after the final retry attempt | External Account Webhook with external_account_status = rejected and status_reason = unable to validate external account |
| Account isn’t a crypto account | External Account Webhook with external_account_status = rejected and status_reason = account not crypto |
| Asset or network isn’t supported | External Account Webhook with external_account_status = rejected and status_reason = <value> is not supported |
| Account closed by the platform or the end customer | External Account Webhook with external_account_status = closed |
| Account locked, zerohash risk and compliance team was alerted to suspicious activity and locked the account for further investigation. | External Account Webhook with external_account_status = locked |
| Account disabled, zerohash risk and compliance team investigations resulted in a positive hit of suspicious activity and the team determined that the account can no longer be used. | External Account Webhook with external_account_status = disabled |
7. Query External Accounts
Platforms can view all previously-connected external accounts via GET /payments/external_accounts (shown initially in a pending status below):
{
"external_account_id": "2cc93b20-ee43-4877-8cdc-863e61829015",
"account_nickname": "",
"participant_code": "BENEF1",
"platform_code": "PLAT01",
"type": "crypto",
"details": {
"network": "SOL",
"supported_assets": ["USDC"],
"address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
},
"created_at": "2024-08-15T22:39:24.171Z",
"updated_at": "2024-08-15T22:39:24.171Z",
"status_reason": "",
"external_account_status": "pending"
}
8. Initiate Payout
8. Initiate Payout
The Platform will initiate a Payout transaction via the POST /payments endpoint:
{
"participant_code": "BENEF1", //beneficiary
"obo_participant": {
"participant_code": "PAYOR1",
"account_group": "PLAT01",
"account_label": "general"
},
"external_account_id": "2cc93b20-ee43-4877-8cdc-863e61829015",
"asset":"USDC", // note: do not specify the network (ie USDC.BASE). the network is implied by the external account
"quoted_asset": "USD",
"total": "125.50",
"payment_type": "payout",
"description": ""
}Response example:
{
"request_id": "0f68333e-2114-469d-b505-c850d776e063",
"participant_code": "BENEF1",
"obo_participant": {
"participant_code": "PAYOR1",
"account_group": "PLAT01",
"account_label": "general
},
"payment_id": "0f68333e-2114-469d-b505-c850d776e061", //zerohash payment UUID
"asset": "USDC",
"network": "SOL",
"total": "125.50",
"quoted_asset": "USD",
"status": "submitted",
"external_account_id": "2cc93b20-ee43-4877-8cdc-863e61829015",
"created_at": "2024-08-19T23:15:05.000Z"
}POST /payments possible responses:
| Scenario | Return code | Status | Error response |
|---|---|---|---|
| Payout created | 201 Created | submitted | none |
| Payout request failed; float account balance is insufficient compared to the Payout amount | 400 Bad Request | — | insufficient balance |
Payout request failed; quoted_asset not supported (Allowed values: USD, EUR) | 400 Bad Request | — | quoted currency code: XYZ is not a supported asset |
Payout request failed; payment_type not identified | 400 Bad Request | — | payment_type should be equal to one of the allowed values |
| Payout request failed; missing required field | 400 Bad Request | — | should have required property '...' |
Payout request failed; valid Payor not identified: OR | 400 Bad Request | — | participant is not approvedOR participant <participant_code> not found |
Payout request failed; valid Beneficiary not identified:participant_code (Beneficiary) is not in an approved statusOR participant_code (Beneficiary) does not exist | 400 Bad Request | — | participant is not approved OR participant <participant_code> not found |
Payout request failed; valid receiving wallet not identified:external_account_id is not in an approved statusOR external_account_id doesn’t existOR asset or symbol not in the external_account_idsupported assets or symbols | 400 Bad Request | — | account is not approvedOR account not foundOR asset is not supported |
Payout request failed; receiving wallet identified does not link to Beneficiary:participant_code (Beneficiary) doesn’t match the owner of external_account_id | 404 Not Found | — | account not found |
Payouts Webhooks
Webhook type:x-zh-hook-payload-type: payment_status_changed
The Payout will initially enter a status of submitted. From here, it's possible (yet rare) that zerohash has issues internally processing the transaction. If this happens, it will enter a terminal status of failed. When the transaction has been successfully broadcasted on-chain, it will enter a status of posted. A terminal status of settled is reached when the Payout has been confirmed on-chain and received by the Beneficiary.
| Condition | Outcome | Webhook |
|---|---|---|
| Payout request accepted | Payment is created and queued for processing. | Payments Status Update webhook with status = submitted |
| Processing starts | Payment moves to pending while destination screening, the asset check and the quote run. | Payments Status Update webhook with status = pending |
| Full processing succeeds | The payment is created and sent to the network. | Payments Status Update webhook with status = posted |
| Initial processing succeeds and payout is high value ($1M+) | The payment is accepted waits for the first on-chain event. | Payments Status Update webhook with status = processing. Then status = posted on the first on-chain event |
| Withdrawal confirmed on-chain | Payment is complete. | Payments Status Update webhook with status = settled |
| Destination address is rejected by pre-trade screening | The payment fails and nothing is sent. | Payments Status Update webhook with status = failed, failure_reason = destination address failed compliance screening |
| Asset is depegged | The payment fails and nothing is sent. | Payments Status Update webhook with status = failed, failure_reason = asset is currently depegged and conversions are halted |
| The vault rejects the withdrawal after submission | The payment fails. A payment already settled ignores the rejection. | Payments Status Update webhook with status = failed, failure_reason = withdrawal rejected |
9. Query Payouts
The Platform can view all Payouts via GET /payments (shown initially in a submitted status below):
{
"message": [
{
"payment_id": "0f68333e-2114-469d-b505-c850d776e061",
"obo_participant": {
"participant_code": "PAYOR1",
"account_group": "PLAT01",
"account_label": "general"
},
"payment_details": {
"withdrawal_id": "",
"trade_id": "",
"on_chain_transaction_id": "",
"network_fee_notional": "",
"network_fee_quantity": ""
},
"asset": "USDC",
"network": "SOL",
"payment_type": "payout",
"external_account_id": "2cc93b20-ee43-4877-8cdc-863e61829015",
"participant_code": "BENEF1",
"amount": "125.50",
"status": "submitted",
"failure_reason": "",
"created_at": "2024-08-19T23:15:30.000Z",
"updated_at": "2024-08-19T23:15:35.000Z"
}
]
}Platforms can also query an individual Payout with GET /payments/id.
10. Network Fee Procedure
The Platform will be paying for the network fee associated with any Payouts. There are 2 options:
- Fund the network fee account. Account details:
- Participant_code: PLAT01 (the Platform's participant_code)
- Account_group: PLAT01
- Account_label: network_fee
- Asset: USD
All network fees will paid out of this account in real-time
- Don’t fund the network fee account. This account will build up a payable balance
zerohash will add the amount of the receivable balance on this account to the end of month invoice, coupling it with the Payout usage activity amount due.
11. Email Receipt Requirements
zerohash requires that the Payor receives an email receipt for each Payout. We also insist that the email contain
- Certain fields and values, which can be obtained using our API
- Adequate support contact information
Fields
Here are the required field names and their associated API fields:
| Email Receipt Field Name | Description | Example | API Location |
|---|---|---|---|
| Order Number | Unique order identifier | 9a738372-0855-4b25-8c65-5de0aa858b8b | payment_id from GET /payments or POST /payments response |
| Order Type | The type of order | Payout Transmission (must present this value verbatim) | N/a, can hard-code to "Payout Transmission" |
| Transmission Amount | The transmission amount for the Payout, in quoted currency terms | $10 | total GET /payments or POST /payments response |
| Amount Received by Beneficiary | The amount of the underlying Payout received by the Beneficiary | 10 USDC | total GET /payments or POST /payments response |
| Fees | Any added fee values included in the Payout. If there are no fees, then this needs to be expressly stated. This includes processing fees (ie, a fee assessed by the Platform to the Payor) or blockchain network fees. | "$0", "1.99", "$0 Fees", or "No Fees" |
|
| Date/Time | Date and timestamp of the Payout's transmission (meaning the time that the fiat was converted and settled into USDC within the zerohash system) | 2024-10-11 18:38:00 | created_at from GET /payments or POST /payments response |
| Account ID | zerohash’s unique account identifier for the Payor ( the “participant code” within zerohash). | BENEF1 | participant_code from GET /payments or POST /payments response |
Support Information
| Field | Value (examples) |
|---|---|
| Platform Contact Email | [email protected] |
| Platform Phone | (123) 123-1234 |
| Platform Address | 123 Main Street New York, NY 10014 |
| Platform Support Contact Email (if different from above) | [email protected] - this is an email that is used to contact zerohash directly |
| zerohash Contact Information | Zero Hash LLC (NMLS ID 1699379) This value should be included in the email verbatim |
zerohash B.V. (EU entity)The following steps should be followed if you're onboarding a Customer to zerohash B.V. (the EU entity)
Base URL changeFor EU API calls, use the following base URL: https://api.zerohash.eu
Introduction
Our API-powered Payouts product allows marketplaces, payment service providers, employer of record platforms, and more to offer stablecoins as a payout option. The benefits include:
- Stablecoins are used as a store of value in countries with volatile currencies and high inflation
- Platforms using this product can reach their customers globally, without the hassle of integrating new or updating existing local fiat payment methods
- Stablecoins act as an alternative payment rail to send payments across borders near instantly with reduced fees
Definitions
| Term | Definition |
|---|---|
| Payout | The conversion of fiat to stablecoin and an automatic on-chain transfer to a destination address. |
| Platform | The company that's in contract with zerohash and directly interacts with zerohash's API's or SDK's. |
| Payor | A non-natural person (typically a business) that is a customer of the Platform. This is the core front-end that the Beneficiary interacts with. |
| Beneficiary | The natural person that receives the stablecoin payout. |
High Level Flow
- Submit Payor
- Query Payor
- Fund Float Account
- Submit Beneficiary
- Query Beneficiary
- Connect External Account
- Query External Accounts
- Initiate Payout
- Query Payouts
- Network Fee Procedures
- Email Receipt Requirements
Initial Setup
The Platform will need to onboard its business to the zerohash platform. They then need to add additional users, create API keys, and whitelist IP addresses. See instructions here.
Platforms should be listening to the following webhooks for Modular Payouts:
1. Submit Payor
Once API keys are created and approved, the Platform can begin to integrate to the API. For the following examples, we’ll assume the Platform's platform code is PLAT01.
EU Payor Information
The Platform submits the Payor via POST /participants/entity/new
{
"request_id": "b2c3d4e5-6789-01bc-defg-234567890bcd",
"platform_code": "PLAT01",
"entity_name": "Entity B",
"legal_name": "Entity B B.V.",
"contact_number": "31201234567",
"website": "https://entityb.eu",
"date_established": "2018-03-10",
"entity_type": "llc",
"address_one": "Herengracht 100",
"address_two": "",
"city": "Amsterdam",
"postal_code": "1015 BS",
"jurisdiction_code": "NL",
"tax_id": "NL861821195B01",
"id_issuing_authority": "Netherlands",
"risk_rating": "low",
"sanction_screening": "pass",
"sanction_screening_timestamp": 1603378501286,
"signed_timestamp": 1603378501286,
"submitter_email": "[email protected]",
"submitter_first_name": "Anna",
"submitter_last_name": "de Vries",
"submitter_title": "Compliance Officer",
"id_number_type": "legal_entity_identifier",
"id_number": "724500XVX2LKTAJ2ML85",
"chamber_of_commerce_number": "34123456",
"reason_for_business_relationship": "Provision of digital asset custody and settlement services to entity clients",
"expected_annual_volume": "over_500k",
"activity_locations": ["NL", "DE", "FR"],
"entity_source_of_funds": "operating_revenues",
"entity_source_of_funds_description": "Revenue from proprietary trading algorithms",
"no_persons_with_effective_control_declaration": false,
"declaration_no_foreseeable_ownership_changes": true,
"board_members": [
{
"first_name": "Johan",
"last_name": "Bakker",
"email": "[email protected]",
"address_one": "Herengracht 100",
"city": "Amsterdam",
"postal_code": "1015 BS",
"jurisdiction_code": "NL",
"citizenship_code": "NL",
"date_of_birth": "1975-04-22",
"place_of_birth": "Rotterdam, Netherlands",
"place_of_birth_country_code": "NL",
"id_number_type": "passport",
"id_number": "NL1234567",
"id_issuing_authority": "Netherlands",
"sanction_screening": "pass",
"sanction_screening_timestamp": 1603378501286
}
],
"control_persons": [
{
"name": "Johan Bakker",
"first_name": "Johan",
"last_name": "Bakker",
"email": "[email protected]",
"address_one": "Herengracht 100",
"city": "Amsterdam",
"postal_code": "1015 BS",
"jurisdiction_code": "NL",
"citizenship_code": "NL",
"country_of_birth": "NL",
"place_of_birth_country_code": "NL",
"date_of_birth": "1975-04-22",
"id_number_type": "passport",
"id_number": "NL1234567",
"id_issuing_authority": "Netherlands",
"role": "Managing Director",
"ownership_percentage": 0,
"sanction_screening": "pass",
"sanction_screening_timestamp": 1603378501286,
"control_person": 1,
"kyc": "pass",
"kyc_timestamp": 1603378501286
}
],
"beneficial_owners": [
{
"name": "Maria Jansen",
"first_name": "Maria",
"middle_name": "Elisabeth",
"last_name": "Jansen",
"email": "[email protected]",
"phone_number": "31612345678",
"address_one": "Keizersgracht 200",
"city": "Amsterdam",
"postal_code": "1016 DW",
"jurisdiction_code": "NL",
"country_of_birth": "NL",
"place_of_birth_country_code": "NL",
"citizenship_code": "NL",
"date_of_birth": "1980-11-02",
"tax_id": "123456789",
"id_number_type": "legal_entity_identifier",
"id_number": "123456789",
"id_issuing_authority": "Netherlands",
"ownership_percentage": 30,
"beneficial_owner": 1,
"sanction_screening": "pass",
"sanction_screening_timestamp": 1603378501286,
"kyc": "pass",
"kyc_timestamp": 1603378501286
}
],
"signed_agreements": [
{
"type": "zheu_user_agreement_rfq",
"region": "eu",
"signed_timestamp": 1603378501286
}
]
}You’ll receive a participant_code in the response - this is the Payor participant code that uniquely identifies the entity indefinitely. We’ll use PAYOR1 as the participant_code throughout the examples.
See response for expected shape.
Payor Documents
Your Payor will not become approved unless you also supply the proper documents via POST /participants/entity/documents endpoint. Depending on the entity_type that was used in the original POST /participants/entity/new call, the document requirements vary. See details here.
The Platform submits the Payor documents via POST /participants/entity/documents:
{
"document": "...", // base 64 encoded file that you wish to upload (10mb limit)
"mime": "image/png",
"document_type": "articles_of_incorporation",
"file_name": "test.png",
"participant_code": "PAYOR1"
}State Logic
After a successful POST /participants/entity/new submission, the initial status of the entity will be submitted. In order to transition this to approved, the Platform must then submit all required documents via POST /participants/entity/documentsand the zerohash team must approve them.
2. Query Payor
Platforms can query already-submitted Payors via the GET /participants endpoint. If you'd like to query a specific Payor use the participant_code parameter.
3. Fund Float Account
The Platform will fund their float account by sending fiat to the proper bank account. Here are the account details:
participant_code: ZHDSEUaccount_group:PLAT01 (replace with your Platform's code)account_label: generalaccount_type: availableasset: USD
In Cert, your platform will be pre-funded with Float account funds.
4. Submit Beneficiary
EU Natural Person - Beneficiary
The Platform submits a Natural Person Beneficiary via POST /participants/beneficiaries/new
{
"onboarding_profile": "payouts_beneficiary",
"first_name": "Lucas",
"last_name": "Martinez",
"email": "[email protected]", //optional, email or phone number
"phone_number": "31612345678", //optional, email or phone number
"address_one": "Herengracht 100",
"address_two": "2",
"city": "Amsterdam",
"postal_code": "1015 BS",
"jurisdiction_code": "NL-NH",
"citizenship_code": "NL",
"date_of_birth": "1985-09-02",
"id_number_type": "non_us_passport",
"id_number": "NL1234567",
"id_issuing_authority": "Netherlands",
"employment_status": "part_time", // optional
"industry": "consulting", // optional
"source_of_funds": "salary" // optional
}EU Non-Natural Person - Beneficiary
The Platform submits a Non-Natural Person Beneficiary via POST /participants/entity-beneficiaries/new
{
"legal_name": "Acme Supplies B.V.",
"dba_name": "Acme Supplies",
"address_one": "1 Example Street",
"city": "Amsterdam",
"postal_code": "1011AB",
"jurisdiction_code": "NL-NH",
"id_issuing_authority": "Netherlands",
"email": "[email protected]", //optional, email or phone number
"contact_number": "+31201234567", //optional, email or phone number
"legal_entity_identifier": "5493001KJTIIGC8Y1R12", //optional, LEI or CRN or TIN
"company_registration_number": "12345678", //optional, LEI or CRN or TIN
"tax_id": "12345678", //optional, LEI or CRN or TIN
"incorporation_address": { "jurisdiction_code": "NL-NH" },
"date_established": "2015-04-01"
}See response for expected shape.
You’ll receive a participant_code in the response - this is the Beneficiary participant code that uniquely identifies the non-natural person indefinitely. We’ll use BENEF1 as the participant_code throughout the examples.
NOTE:
- Even in Cert, zerohash will run each submitted Beneficiary through our Sanction Checks, subjecting the Beneficiaries to real validations. This means that if your entry is an actual sanctioned individual, the Beneficiary will be sent to a
rejectedstatus. - zerohash requires that the
jurisdiction_codeis not null and contains both a Country (ie, Brazil "BR") and a Subdivision (ie, Sao Palo "SP") to form BR-SP, for example. If your systems don't contain the subdivision and you only collect Country and Postal Code, we recommend performing a mapping on your side to derive the correct Subdivision, using the Country and Postal code as inputs. See this step-by-step guide on how to use an external API (ie, Google Geocoding API) to make a conversion between your data structure, to ours. - Platforms can query already-submitted Beneficiaries via the GET /participants endpoint.
You should expect that Beneficiaries transition from submitted to approved, rejected, pending_approval .
Beneficiary State Logic
After a successful POST /participants/beneficiaries/new submission, the initial status of the Beneficiary will be submitted. At this point, zerohash is running an automated compliance screening.
- If a Natural Person Beneficiary passes this check, their status will automatically transition to an
approvedstate. - Non-Natural Person Beneficiaries require manual review and approval by zerohash before they can transition to an
approvedstate.
If the compliance screening results in a hit, the status will transition to a pending_approval status. Note: there is also a scenario where the Beneficiary transitions directly into a rejected state, depending on the compliance score. If the determination after a zerohash review is that the Beneficiary should not have been flagged, the status will transition to approved. Otherwise, the status will transition to rejected.
5. Query Beneficiary
Platforms can query already-submitted Beneficiaries via the GET /participants endpoint. A common query parameter is the participant_code, however the full list can be found on the API reference.
See response for expected shape.
6. Connect External Account
The Platform will connect the Beneficiary to an external account via POST /payments/external_accounts:
{
"participant_code": "BENEF1",
"type": "crypto", // enum: crypto, fiat
"details": {
"network": "SOL",
"supported_assets": ["USDC"],
"address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
}
}POST /payments/external_accounts responses:
| Scenario | Return code | status | Error Response |
|---|---|---|---|
| Valid request, approval required | 201 Created | pending | none |
| Valid request, no approval required | 201 Created | approved | none |
Missing or invalid participant_code | 400 Bad RequestOR 404 Client Error | n/a | should have required property 'participant_code'OR participant CUST01 not found OR failed to validate participant CUST01OR participant_code participant_code must be at least 6 characters long. |
Missing type; expecting type = "crypto" | 400 Bad Request | n/a | "For crypto accounts, "type" is required.","For fiat accounts, plaid_processor_token is required.","You should provide either valid details for crypto accounts or a plaid_processor_token for a fiat account." |
Missing or invalid details- this is where you provide external account information required for type = "crypto" | 400 Bad Request | n/a | For crypto accounts, "details" are required. |
Within details object, missing or containing invalid address | 400 Bad Request | n/a | details should have required property 'address'OR address should NOT be shorter than 5 charactersOR address should NOT be longer than 128 characters |
Within details object, Missing or unsupported network | 400 Bad Request | n/a | details should have required property 'network' |
Within details object, Neither supported_assets nor supported_symbols submitted | 400 Bad Request | n/a | details should have required property 'supported_assets' THEN details should have required property 'supported_symbols' THEN details should match exactly one schema in oneOf |
Within details object, supported_assets or supported_symbolsobject have missing or invalid content | 400 Bad Request | n/a | supported_assets (or supported_symbols) should be arrayOR 0 should NOT be shorter than # charactersOR no_destination_tag should be boolean |
| Crypto accounts not enabled for the platform Reach out to your zerohash Relationship Manager to fix your configuration. | 400 Bad Request | n/a | plaid_processor_token is required. |
External Account Webhooks
Listen to External Account Webhooks for notifications on crypto accounts created through POST /payments/external_accounts.
Webhook type: x-zh-hook-payload-type: external_account_status_changed
Payload fields:
- Always: participant_code, account_nickname, external_account_id, external_account_status, timestamp.
- Sometimes: account_type, status_reason, reference_id. The pending payload omits account_type.
| Scenario | Webhook |
|---|---|
| Account created. Every account passes through this. | External Account Webhook with external_account_status = pending |
| Crypto account passes address screening | External Account Webhook with external_account_status = approved |
| Crypto address is malformed, on the deny list, or fails validation definitively | External Account Webhook with external_account_status = rejected and status_reason = invalid or denied destination address |
| Crypto address is sanctioned | External Account Webhook with external_account_status = rejected and status_reason = sanctioned address |
| Address screening still unavailable after the final retry attempt | External Account Webhook with external_account_status = rejected and status_reason = unable to validate external account |
| Account isn’t a crypto account | External Account Webhook with external_account_status = rejected and status_reason = account not crypto |
| Asset or network isn’t supported | External Account Webhook with external_account_status = rejected and status_reason = <value> is not supported |
| Account closed by the platform or the end customer | External Account Webhook with external_account_status = closed |
| Account locked, zerohash risk and compliance team was alerted to suspicious activity and locked the account for further investigation. | External Account Webhook with external_account_status = locked |
| Account disabled, zerohash risk and compliance team investigations resulted in a positive hit of suspicious activity and the team determined that the account can no longer be used. | External Account Webhook with external_account_status = disabled |
[Recommended] Whitelist a self-custody receiving wallet's Travel Rule information
Proof of ownership is required for self-custody wallets above the Travel Rule threshold. zerohash manually reviews each submission, which can take up to 2 days, so it is recommended that you submit it well before you plan to initiate the payout. Until the review is approved, payouts to that wallet are limited to €1,000 every 12 hours.
Request - POST /travel-rule/submit
{
"participant_code": "BENEF1",
"address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"address_belongs_to": "zh_participant",
"address_owner_type": "individual",
"wallet_type": "self_custody",
"wallet_proof_of_ownership": {
"document": "<base64-encoded document>",
"mime": "application/pdf"
}
}Warning: Skip this step for Exchange wallets. Their Travel Rule information is retained only briefly, so submission immediately before POST /payments is recommended. Find more information on Travel Rule here.
At any time, you can confirm a wallet's Travel Rule information availability through GET /travel-rule/state-approval
Request - GET /travel-rule/state-approval
{
"intention_action": "withdrawal",
"participant_code": "BENEF1",
"wallet_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"asset": "USDC.SOL",
"crypto_amount": "100"
}-
intention_action(required):depositorwithdrawal. For a payout, set towithdrawal -
participant_code(withdrawal only): 6 uppercase alphanumeric characters. For a payout, use the beneficiary’s code. -
wallet_address(withdrawal only): non-empty string. Should match External Account'sdetails.address
Response - GET /travel-rule/state-approval
{
"message": {
"status": "action_required",
"status_reasons": ["proof_of_ownership"]
}
}Other GET /travel-rule/state-approval responses:
status | status_reasons | Meaning |
|---|---|---|
allowed | not returned | Travel Rule checks have passed |
action_required | ["info_required"] | Owner identity information, or the hosting VASP, is needed. Send it with POST /travel-rule/submit. |
action_required | ["proof_of_ownership"] | A self-custody wallet needs proof of ownership |
processing | not returned | Information has been received and is under review |
blocked | not returned | The transfer was rejected and can’t go ahead |
unknown | not returned | The status couldn’t be determined |
7. Query External Accounts
Platforms can view all previously-connected external accounts via GET /payments/external_accounts (shown initially in a pending status below):
{
"external_account_id": "2cc93b20-ee43-4877-8cdc-863e61829015",
"account_nickname": "",
"participant_code": "BENEF1",
"platform_code": "PLAT01",
"type": "crypto",
"details": {
"network": "SOL",
"supported_assets": ["USDC"],
"address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
},
"created_at": "2024-08-15T22:39:24.171Z",
"updated_at": "2024-08-15T22:39:24.171Z",
"status_reason": "",
"external_account_status": "pending"
}8. Initiate Payout
Submit Travel Rule Information for Receiving Wallet
A payout can’t be initiated until Travel Rule information for the receiving wallet has been submitted via POST /travel-rule/submit. This applies to both Exchange wallets and self-custody wallets. Because Travel Rule data for Exchange wallets is stored only briefly, be sure to always submit it immediately before initiating the payout.
ReminderIf you already whitelisted a self-custody wallet's Travel Rule information, confirm its status with GET /travel-rule/state-approval before initiating the payout.
Initiate Payout to Receiving Wallet
EUR quoted currencyFor zerohash B.V. (EU), you can quote in USD or EUR. The examples on this page use USD. To quote in EUR, set the quoted currency to EUR in your request. EUR pairs are available for a growing set of assets. Visit Supported Instruments (RFQ) to see which assets can be quoted in EUR.
The Platform will initiate a Payout transaction via the POST /payments endpoint:
{
"participant_code": "BENEF1", //beneficiary of payment
"obo_participant": {
"participant_code": "PAYOR1",
"account_group": "PLAT01",
"account_label": "general"
},
"external_account_id": "2cc93b20-ee43-4877-8cdc-863e61829015",
"asset":"USDC", // note: do not specify the network (ie USDC.BASE). the network is implied by the external account
"quoted_asset": "USD", //defaults to USD
"total": "125.50",
"payment_type": "payout",
"description": "" //optional
}Note:
- The
external_account_idmust have sufficient Travel Rule information recorded for the wallet address - Use
quoted_assetto specify quoted currency (EUR vs USD)
Response example:
{
"request_id": "0f68333e-2114-469d-b505-c850d776e063",
"participant_code": "BENEF1",
"obo_participant": {
"participant_code": "PAYOR1",
"account_group": "PLAT01",
"account_label": "general"
},
"payment_id": "0f68333e-2114-469d-b505-c850d776e061", //zerohash payment UUID
"asset": "USDC",
"network": "SOL",
"total": "125.50",
"quoted_asset": "USD",
"status": "submitted",
"external_account_id": "2cc93b20-ee43-4877-8cdc-863e61829015",
"created_at": "2024-08-19T23:15:05.000Z"
}POST /payments possible responses:
| Scenario | Return code | Status | Error response |
|---|---|---|---|
| Payout created | 201 Created | submitted | none |
| Payout request failed; float account balance is insufficient compared to the Payout amount | 400 Bad Request | — | insufficient balance |
Payout request failed; quoted_asset not supported (Allowed values: USD, EUR) | 400 Bad Request | — | quoted currency code: XYZ is not a supported asset |
Payout request failed; payment_type not identified | 400 Bad Request | — | payment_type should be equal to one of the allowed values |
| Payout request failed; missing required field | 400 Bad Request | — | should have required property '...' |
Payout request failed; valid Payor not identified:obo_participant.participant_code (Payor) is not in an approved statusOR obo_participant.participant_code (Payor) does not exist | 400 Bad Request | — | participant is not approvedOR participant <participant_code> not found |
Payout request failed; valid Beneficiary not identified:participant_code (Beneficiary) is not in an approved statusOR participant_code (Beneficiary) does not exist | 400 Bad Request | — | participant is not approvedOR participant <participant_code> not found |
Payout request failed; valid receiving wallet not identified:external_account_id is not in an approved statusOR external_account_id doesn’t existOR asset or symbol not in the external_account_id supported assets or symbols | 400 Bad Request | — | account is not approvedOR account not foundOR asset is not supported |
Payout request failed; receiving wallet identified does not link to Beneficiary:participant_code (Beneficiary) doesn’t match the owner of external_account_id | 404 Not Found | — | account not found |
Payout request failed; Travel Rule information not available for receiving walletexternal_account_id has no wallet address on file for participant_code (Beneficiary)OR Travel Rule information has not been submitted for the receiving wallet associated with external_account_id | 400 Bad Request | — | Insufficient Travel Rule information available: unable to resolve destination wallet for external_account_id. OR Insufficient Travel Rule information available for receiving wallet. |
| Payout request failed; Travel Rule information has been submitted for receiving wallet, manual review is required and in progress. Once you receive a status update on this wallet, you can confirm it with GET /travel-rule/state-approval, then try to initiate the payout again. | 400 Bad Request | — | This withdrawal is pending Travel Rule review. Please try again later. |
| Payout request failed; proof of ownership required for receiving wallet: Receiving wallet is self-custody and the payout exceeds €1,000 in the last 12 hours to this address, which requires proof of ownership submission via POST /travel-rule/submit and manual review by zerohash before a this payout can be initiated. | 400 Bad Request | — | Insufficient Travel Rule information available for unhosted receiving wallet: Proof of ownership required for withdrawals to unhosted wallets that exceed the maximum of €1,000 allowed every 12 hours. Please reach out to zerohash customer support to provide proof of ownership for verification. |
Payouts Webhooks
Webhook type:x-zh-hook-payload-type: payment_status_changed
The Payout will initially enter a status of submitted. From here, it's possible (yet rare) that zerohash has issues internally processing the transaction. If this happens, it will enter a terminal status of failed. When the transaction has been successfully broadcasted on-chain, it will enter a status of posted. A terminal status of settled is reached when the Payout has been confirmed on-chain and received by the Beneficiary.
| Condition | Outcome | Webhook |
|---|---|---|
| Payout request accepted | Payment is created and queued for processing. | Payments Status Update webhook with status = submitted |
| Processing starts | Payment moves to pending while destination screening, the asset check and the quote run. | Payments Status Update webhook with status = pending |
| Full processing succeeds | The payment is created and sent to the network. | Payments Status Update webhook with status = posted |
| Initial processing succeeds and payout is high value ($1M+) | The payment is accepted waits for the first on-chain event. | Payments Status Update webhook with status = processing. Then status = posted on the first on-chain event |
| Withdrawal confirmed on-chain | Payment is complete. | Payments Status Update webhook with status = settled |
| Destination address is rejected by pre-trade screening | The payment fails and nothing is sent. | Payments Status Update webhook with status = failed, failure_reason = destination address failed compliance screening |
| Asset is depegged | The payment fails and nothing is sent. | Payments Status Update webhook with status = failed, failure_reason = asset is currently depegged and conversions are halted |
| The vault rejects the withdrawal after submission | The payment fails. A payment already settled ignores the rejection. | Payments Status Update webhook with status = failed, failure_reason = withdrawal rejected |
9. Query Payouts
The Platform can view all Payouts via GET /payments (shown initially in a submitted status below):
{
"message": [
{
"payment_id": "0f68333e-2114-469d-b505-c850d776e061",
"obo_participant": {
"participant_code": "PAYOR1",
"account_group": "PLAT01",
"account_label": "general"
},
"payment_details": {
"withdrawal_id": "",
"trade_id": "",
"on_chain_transaction_id": "",
"network_fee_notional": "",
"network_fee_quantity": ""
},
"asset": "USDC",
"network": "SOL",
"payment_type": "payout",
"external_account_id": "2cc93b20-ee43-4877-8cdc-863e61829015",
"participant_code": "BENEF1",
"amount": "125.50",
"status": "submitted",
"failure_reason": "",
"created_at": "2024-08-19T23:15:30.000Z",
"updated_at": "2024-08-19T23:15:35.000Z"
}
]
}Platforms can also query an individual Payout with GET /payments/id.
10. Network Fee Procedure
The Platform will be paying for the network fee associated with any Payouts. There are 2 options:
- Fund the network fee account. Account details:
- Participant_code: PLAT01 (the Platform's participant_code)
- Account_group: PLAT01
- Account_label: network_fee
- Asset: USD
All network fees will paid out of this account in real-time
- Don’t fund the network fee account. This account will build up a payable balance
zerohash will add the amount of the receivable balance on this account to the end of month invoice, coupling it with the Payout usage activity amount due.
11. Email Receipt Requirements
zerohash requires that the Payor receives an email receipt for each Payout. We also insist that the email contain
- Certain fields and values, which can be obtained using our API
- Adequate support contact information
Fields
Here are the required field names and their associated API fields:
| Email Receipt Field Name | Description | Example | API Location |
|---|---|---|---|
| Order Number | Unique order identifier | 9a738372-0855-4b25-8c65-5de0aa858b8b | payment_id from GET /payments or POST /payments response |
| Order Type | The type of order | Payout Transmission (must present this value verbatim) | N/a, can hard-code to "Payout Transmission" |
| Transmission Amount | The transmission amount for the Payout, in quoted currency terms | $10 | total GET /payments or POST /payments response |
| Amount Received by Beneficiary | The amount of the underlying Payout received by the Beneficiary | 10 USDC | total GET /payments or POST /payments response |
| Fees | Any added fee values included in the Payout. If there are no fees, then this needs to be expressly stated. This includes processing fees (ie, a fee assessed by the Platform to the Payor) or blockchain network fees. | "$0", "1.99", "$0 Fees", or "No Fees" |
|
| Date/Time | Date and timestamp of the Payout's transmission (meaning the time that the fiat was converted and settled into USDC within the zerohash system) | 2024-10-11 18:38:00 | created_at from GET /payments or POST /payments response |
| Account ID | zerohash’s unique account identifier for the Payor ( the “participant code” within zerohash). | BENEF1 | participant_code from GET /payments or POST /payments response |
Support Information
| Field | Value (examples) |
|---|---|
| Platform Contact Email | [email protected] |
| Platform Phone | (123) 123-1234 |
| Platform Address | 123 Main Street New York, NY 10014 |
| Platform Support Contact Email (if different from above) | [email protected] - this is an email that is used to contact zerohash europe directly |
| zerohash europe Contact Information | zerohash europe B.V. This value should be included in the email verbatim |
Updated 11 days ago