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 request, e.g.

{ 
"name":"Test Customer",
"email":"tetst@customer.com",
"state":"IL",
"signed_timestamp":"1569014063570",
"country":"United States",
"ssn":"123456789",
"metadata":{}
}

As a response, we will return:

{
"message": {
"name":"Test Customer",
"registration_code":"ABCDEF", <-- this is a key field
"email":"tetst@customer.com",
"ssn":"123456789"
}
}

The registration_code is very important as it uniquely identifies the customer. This is also known as the participant_code for the customer you just submitted to us.

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"
},
{
"participant_code":"PLAT01", <-- platform's participant_code
"asset":"USD",
"amount":"3500.0000",
"side":"sell"
}
]
}

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

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.

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