Ask us anything. We're here to help.

Payments Integration Flow

The following is a specific integration flow for platforms using Zero Hash for payments settlement. Note: there are specific configurations that must be enabled to enable this flow:

  • The ability to submit customers to us must be turned ON after an agreed-upon KYC process.
  • The ability to submit trades where we settle just one leg, i.e. the crypto leg, must be turned ON - the standard is for Zero Hash to settle both legs.
  • The ability to submit a withdrawal directly to an address must be turned ON - the standard is to submit a withdrawal to a previously whitelisted address.

Once properly configured, the payments flow is very straightforward:

1. Participant Onboarding

This is where you submit a POST /participants/customers/new request, e.g.

{
"first_name": "Test",
"last_name": "Customer",
"email": "test.customer@example.com",
"address_one": "1 main street",
"address_two": "Suite 1000",
"city": "Chicago",
"state": "IL",
"zip": "12345",
"country": "United States",
"date_of_birth": "1980-09-02",
"id_number_type": "ssn",
"id_number": "123456789",
"signed_timestamp": 1630623005000,
"metadata": {
}
}

As a response, we will return:

{

"message": {
"first_name": "Test",
"last_name": "Customer",
"email": "test.customer@example.com",
"address_one": "1 main street",
"address_two": "Suite 1000",
"country": "United States",
"state": "IL",
"city": "Chicago",
"zip": "12345",
"date_of_birth": "1980-09-02",
"id_number_type": "ssn",
"id_number": "123456789",
"non_us_other_type": "",
"id_issuing_authority": "",
"signed_timestamp": 1630623005000,
"risk_rating": "",
"metadata": {},
"platform_code": "PLAT01",
"participant_code": "ABCDEF"
}
}

There is a validation on the signed_timestamp field to ensure an authentic timestamp. This refers to the time in milliseconds when the platform's customer accepted Zero Hash's T&Cs. Validation logic is to check if the signed_timestamp field is greater than 1-1-2020 and less than the current date/ This date format is in DD-MM-YYYY.

You can read more here: https://zerohash.com/api/web/#participants

2. Trade Submission

This is where you submit the actual payment terms as a trade. The trade submitted must include the relevant customer's participant_code from step 1. In most cases, you want to include the customer on the buy side as the customer is buying crypto.

{ 
"symbol":"BTC/USD",
"trade_price":"7000.00000",
"product_type":"spot",
"trade_type":"regular",
"trade_reporter":"reporter@platform.com",
"platform_code":"PLAT01",
"client_trade_id":"test1",
"physical_delivery":true,
"parties_anonymous":false,
"transaction_timestamp":1569014063570,
"parties":[
{
"participant_code":"ABCDEF", <-- customer's participant_code
"asset":"BTC",
"amount":"0.5",
"side":"buy",
"settling": true
},
{
"participant_code":"PLAT01", <-- platform's participant_code
"asset":"USD",
"amount":"3500.0000",
"side":"sell"
"settling": false
}
]
}

As a response you will receive a trade_id. This is the unique ID for the trade, useful in step 3.

You can read more here: https://zerohash.com/api/web/#trades

Key Field Explanations

  • trade_reporter_code: your participant code, zero hash adds
  • trade_reporter: an identifiable string, the platform submits
  • platform_code: your participant code, the platform submits

3. Trade Settlement

We can process a trade as soon as we receive it. You will want to wait for the trade to settle before processing the withdrawal. So you can submit a GET /trades/:trade_id request using the trade_id from step 2. You will want to see that the trade_state is terminated and the settlement_state is settled. This means that we have legally transferred the ownership of the crypto to the buyer / customer. This is money transmission.

Optional validation: you can perform a GET /accounts request and filter on account_owner = your customer’s participant_code and you can see that they now have crypto in their account. But this can be safely assumed if the settlement_state is settled.

You can read more here: https://zerohash.com/api/web/#accounts

4. Withdraw

Once settled, you can send out a POST /withdrawals/requests request to withdraw the assets and have them sent to the customer. The request body looks like:

{ 
"address":"customer's address",
"participant_code":"ABCDEF", <-- customer's participant_code
"amount":"0.5",
"asset":"BTC",
"account_group":"PLAT01" <-- platform's participant_code
}

You will then be able to query the GET /withdrawals/requests endpoint, and filter on the customer’s participant_code to identify the status of the withdrawal, as well as the on-chain transaction ID.

Important note about withdrawals: Zero Hash will settle what it can. If your customer has .05 BTC in their account for example, and you submit a withdrawal request for .07 BTC, we will settle the .05 and process the withdrawal.

 

You can read more here: https://zerohash.com/api/web/#withdrawals