Articles in this section

Payments Integration Flow

  • Updated

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

Related articles