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

TermDefinition
PayoutThe conversion of fiat to stablecoin and an automatic on-chain transfer to a destination address.
PlatformThe company that's in contract with zerohash and directly interacts with zerohash's API's or SDK's.
PayorA non-natural person (typically a business) that is a customer of the Platform. This is the core front-end that the Beneficiary interacts with.
BeneficiaryThe natural person that receives the stablecoin payout.

High Level Flow

  1. Submit Payor
  2. Query Payor
  3. Fund Float Account
  4. Submit Beneficiary
  5. Query Beneficiary
  6. Connect External Account
  7. Query External Accounts
  8. Initiate Payout
  9. Query Payouts
  10. Network Fee Procedures
  11. 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: 00SCXM
  • account_group: PLAT01 (replace with your Platform's code)
  • account_label: general
  • account_type: available
  • asset: 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 rejected status.
    • In Cert, if the Platform would like to test a rejection scenario, please submit a Beneficiary like the following, passing an id_number equal to 111111111
    • In Cert, if the Platform would like to test a rejection scenario, please submit a Beneficiary like the following, passing an first_name equal to Joseph and last_name equal to Kony
  • zerohash requires that the jurisdiction_code is 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_id or (id_number and id_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 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 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:

ScenarioReturn codestatusError Response
Valid request, approval required201 Createdpendingnone
Valid request, no approval required 201 Createdapprovednone
Missing or invalid participant_code400 Bad Request
OR
404 Client Error
n/ashould have required property 'participant_code'
OR
participant CUST01 not found
OR
failed to validate participant CUST01
OR
participant_code participant_code must be at least 6 characters long.
Missing type; expecting type = "crypto" 400 Bad Requestn/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 Requestn/aFor crypto accounts, "details" are required.
Within details object, missing or containing invalid address400 Bad Requestn/adetails should have required property 'address'
OR
address should NOT be shorter than 5 characters
OR
address should NOT be longer than 128 characters
Within details object, Missing or unsupported network400 Bad Requestn/adetails should have required property 'network'
Within details object, Neither supported_assets nor supported_symbols submitted400 Bad Requestn/adetails 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 content400 Bad Requestn/asupported_assets (or supported_symbols) should be array
OR
0 should NOT be shorter than # characters
OR
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 Requestn/aplaid_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.
ScenarioWebhook
Account created. Every account passes through this.External Account Webhook with external_account_status = pending
Crypto account passes address screeningExternal Account Webhook with external_account_status = approved
Crypto address is malformed, on the deny list, or fails validation definitivelyExternal Account Webhook with external_account_status = rejected and status_reason = invalid or denied destination address
Crypto address is sanctionedExternal Account Webhook with external_account_status = rejected and status_reason = sanctioned address
Address screening still unavailable after the final retry attemptExternal Account Webhook with external_account_status = rejected and status_reason = unable to validate external account
Account isn’t a crypto accountExternal Account Webhook with external_account_status = rejected and status_reason = account not crypto
Asset or network isn’t supportedExternal Account Webhook with external_account_status = rejected and status_reason = <value> is not supported
Account closed by the platform or the end customerExternal 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

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:

ScenarioReturn codeStatusError response
Payout created201 Createdsubmittednone
Payout request failed; float account balance is insufficient compared to the Payout amount400 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 identified400 Bad Request—payment_type should be equal to one of the allowed values
Payout request failed; missing required field400 Bad Request—should have required property '...'

Payout request failed; valid Payor not identified:

obo_participant.participant_code (Payor) is not in an approved status

OR
obo_participant.participant_code (Payor) does not exist

400 Bad Request—participant is not approved
OR
participant <participant_code> not found
Payout request failed; valid Beneficiary not identified:

participant_code (Beneficiary) is not in an approved status
OR
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 status
OR
external_account_id doesn’t exist
OR
asset or symbol not in the external_account_idsupported assets or symbols
400 Bad Request—account is not approved
OR
account not found
OR
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.

ConditionOutcomeWebhook
Payout request acceptedPayment is created and queued for processing.Payments Status Update webhook with status = submitted
Processing startsPayment moves to pending while destination screening, the asset check and the quote run.Payments Status Update webhook with status = pending
Full processing succeedsThe 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-chainPayment is complete.Payments Status Update webhook with status = settled
Destination address is rejected by pre-trade screeningThe payment fails and nothing is sent.Payments Status Update webhook with status = failed, failure_reason = destination address failed compliance screening
Asset is depeggedThe 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 submissionThe 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:

  1. 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

  1. 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

  1. Certain fields and values, which can be obtained using our API
  2. Adequate support contact information

Fields

Here are the required field names and their associated API fields:

Email Receipt Field NameDescriptionExampleAPI Location
Order NumberUnique order identifier9a738372-0855-4b25-8c65-5de0aa858b8bpayment_id from GET /payments or POST /payments response
Order TypeThe type of order

Payout Transmission

(must present this value verbatim)

N/a, can hard-code to "Payout Transmission"
Transmission AmountThe transmission amount for the Payout, in quoted currency terms$10total GET /payments or POST /payments response
Amount Received by BeneficiaryThe amount of the underlying Payout received by the Beneficiary10 USDCtotal 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"
  • Payouts does not currently support processing fees

  • If the Payor is incurring the network fee, take network_fee_notional from GET /payments. If not, no need to include it in the receipt

Date/TimeDate 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:00created_at from GET /payments or POST /payments response
Account IDzerohash’s unique account identifier for the Payor ( the “participant code” within zerohash).BENEF1participant_code from GET /payments or POST /payments response

Support Information

FieldValue (examples)
Platform Contact Email[email protected]
Platform Phone(123) 123-1234
Platform Address123 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)
327 N Aberdeen St
Chicago, IL 60607
855-744-7333
[email protected]
www.zerohash.com

This value should be included in the email verbatim






Did this page help you?