Documentation

Trade Settlement Integration Guide

Suggest Edits

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:

Participant Onboarding

  • This is where you submit a POST /participants/customers/new request, e.g.
{
   "first_name": "Test",
   "last_name": "Customer",
   "email": "[email protected]",
   "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": "[email protected]",
        "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 in out participants API documentation.

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":"[email protected]",  
   "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.

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.

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

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.

Updated 3 months ago