Withdraw SDK with Auth

Setup

📘
Please note that for Auth usage you must install zh-web-sdk v3.5.0 or higher

Platforms can instantiate the Withdraw SDK offering with Auth included that eliminates the need to use the Account Link SDK flow.

The key difference between this integration and the Account Link SDK + Withdraw SDK integration is the absence of the external account reference. Otherwise, the SDK flow is similar.

Flow

Crypto Withdraw SDK - Request Access Token

Platform generates a client access token with the standard set of parameters with the exception of an external_account_id

Field	Description	Example Value	Required?
`participant_code`	The 6-digit alpha numeric code associated with the Customer that is looking to withdraw (the response of the original POST /participants/customers/new call)	CUST01	Y
`permissions`	The array of permissions that will be granted to the returned JWT token	`["crypto-withdrawals"]`	Y
`quoted_asset`	The fiat currency being used to fund the trade	USD	Y
`withdrawal_request_amount`	The amount, in `quoted_asset` terms, to be withdrawn	200	Y
`reference_id`	Platform reference id for a specific transaction	0bd7f7f0-cf26-495f-b2df-e8afe8481ba3	N

Example POST /client_auth_token request:

 {
    "participant_code": "CUST01",
    "permissions": ["crypto-withdrawals"],
    "withdrawal_details": {
        "quoted_asset": "USD",   
        "withdrawal_request_amount": "200"
    },
   "reference_id": "0bd7f7f0-cf26-495f-b2df-e8afe8481ba3"
}

Starting the Withdrawal flow

After a successful POST /client_auth_token call, the next step is to start the Withdrawal SDK flow, see the example below for doing it in a React application. Keep in mind that Auth requires making usage of our native mobile SDKs to access full Auth functionality.

import UIKit
import ZerohashSDK

class WithdrawalsViewController: UIViewController {

    private var withdrawalsSession: ZerohashCryptoWithdrawalsSession?

    @IBAction func startWithdrawalTapped(_ sender: UIButton) {
        let callbacks = CryptoWithdrawalsCallbacks(
            onClose: { print("Crypto Withdrawals closed") },
            onWithdrawal: { withdrawal in
                print("Withdrawal submitted: \(withdrawal.withdrawalRequestId ?? "unknown")")
            },
            onError: { error in
                print("Crypto Withdrawals error \(error.code): \(error.message)")
            },
            onEvent: { event in
                print("Crypto Withdrawals event: \(event.type)")
            }
        )

        withdrawalsSession = ZerohashSDK.configureCryptoWithdrawals(
            jwt: "your-jwt-token",
            environment: .production,
            theme: .system,
            callbacks: callbacks
        )

        withdrawalsSession?.present(from: self)
    }
}

The End Customer will be shown the Withdrawal screen with a pre-populated withdrawal request, outlining the following data points:

Data Point	Description	Example
Withdrawal Request Amount	The amount of `quoted_asset` they want to withdraw (USD or EUR)	200
Rate	The rate at which the conversion from Fiat to Crypto will be made	1 USDC = $1.01
Asset	The asset which the user will be receiving its funds converted to	USDC
Network	The network used to send the transaction	Ethereum
Network Fee	The blockchain-assessed network fee on the withdrawal, in `quoted_asset` terms	1.25
Withdrawal Fee	The transaction fee being assessed on the withdrawal	1.50
Withdrawal Receive Amount	The amount of the stablecoin or crypto asset that the user will be receiving	197.25

Crypto Withdraw SDK - Initiate Withdrawal

At this point, the End Customer is interacting with the front end SDK. The Customer will ultimately initiate the withdrawal.

Crypto Withdraw SDK - Consume Payments Webhook

📘
Platform must be configured with a valid webhook URL in order to receive these webhooks. Please get in touch with a zerohash representative so that they can set this up for you. Your Platform will need to be specifically configured to receive these webhooks.

After the End Customer successfully initiates the Withdrawal via the SDK, the Platform can consume webhooks related to that payment.

Note: the x-zh-hook-payload-type is payment_status_changed (more details on webhooks here)

Status Summary

The Withdrawal will initially enter a status of submitted. If zerohash is unable to process the transaction, the Withdrawal 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 Withdrawal has been confirmed on-chain and received by the End Customer.

Initialized Status

After you successfully generate a JWT token via the POST /client_auth_token endpoint, zerohash will send an initialized webhook. Example payload:

{
   "payment_id":"0f68333e-2114-469d-b505-c850d776e061",
   "obo_participant":{
      "participant_code":"CUST01",
      "account_group":"PLAT01",
      "account_label":"general"
   },
   "payment_details":{
      "withdrawal_request_id":"",
      "trade_id":"",
      "on_chain_transaction_id":"",
      "network_fee_notional":"",
      "network_fee_quantity":"",
      "withdrawal_fee_notional": "",
      "destination_address":"0xa6b0Cd1baaa15AE97D8135f0E87F61af27c6cB89"
   },
   "asset":"",
   "network":"ETH",
   "payment_type":"payout",
   "participant_code":"CUST01",
   "quantity":"",
   "status":"initialized",
   "created_at":"2024-09-26T13:05:22.657Z",
   "updated_at":"2024-09-26T13:05:22.657Z",
   "total":"200",
   "reference_id": "0bd7f7f0-cf26-495f-b2df-e8afe8481ba3"
}

Submitted Status

The Withdrawal will initially and briefly enter a status of submitted. Example payload:

{
   "payment_id":"0f68333e-2114-469d-b505-c850d776e061",
   "obo_participant":{
      "participant_code":"CUST01",
      "account_group":"PLAT01",
      "account_label":"general"
   },
   "payment_details":{
      "withdrawal_request_id":"",
      "trade_id":"b752503c-1c42-4dfe-ad1d-7b39da5db59c",
      "on_chain_transaction_id":"",
      "network_fee_notional":"",
      "network_fee_quantity":"",
      "withdrawal_fee_notional": "",
      "destination_address":"0xa6b0Cd1baaa15AE97D8135f0E87F61af27c6cB89"
   },
   "asset":"USDC",
   "network":"ETH",
   "payment_type":"payout",
   "participant_code":"CUST01",
   "quantity":"",
   "status":"submitted",
   "created_at":"2024-09-26T13:05:22.657Z",
   "updated_at":"2024-09-26T13:05:22.657Z",
   "total":"200",
   "reference_id": "0bd7f7f0-cf26-495f-b2df-e8afe8481ba3"
}

Posted Status

The Withdrawal will transition into a status of posted, which means that the asset has been broadcasted on-chain. Note the presence of the on_chain_transaction_id field, which represents the on-chain hash. Typically, this is displayed to the End Customer on the Platform's "Transaction History" or equivalent page in order to allow the Customer to trace the transaction. Example payload:

{
   "payment_id":"0f68333e-2114-469d-b505-c850d776e061",
   "obo_participant":{
      "participant_code":"CUST01",
      "account_group":"PLAT01",
      "account_label":"general"
   },
   "payment_details":{
      "withdrawal_request_id":"14f8ebb8-7530-4aa4-bef9-9d73d56313f3",
      "trade_id":"b752503c-1c42-4dfe-ad1d-7b39da5db59c",
   "on_chain_transaction_id":"0x55dfac6137387a81e32fc353fca45eea3124cd42564a4112192323add8dee1da",
      "network_fee_notional":"1.25",
      "network_fee_quantity":".00032",
      "withdrawal_fee_notional": "1.50",
      "destination_address":"0xa6b0Cd1baaa15AE97D8135f0E87F61af27c6cB89",
   "asset":"USDC",
   "network":"ETH",
   "payment_type":"payout",
   "participant_code":"CUST01",
   "quantity":"197.25",
   "status":"posted",
   "created_at":"2024-09-26T13:05:22.657Z",
   "updated_at":"2024-09-26T13:05:22.657Z",
   "total":"200",
   "reference_id": "0bd7f7f0-cf26-495f-b2df-e8afe8481ba3"
}

Settled Status

When the withdrawal transitions to a settled status, the transaction has been fully settled on-chain and the balance should be reflected on the End Customer's destination exchange or wallet account. Example payload:

{
   "payment_id":"0f68333e-2114-469d-b505-c850d776e061",
   "obo_participant":{
      "participant_code":"CUST01",
      "account_group":"PLAT01",
      "account_label":"general"
   },
   "payment_details":{
      "withdrawal_request_id":"14f8ebb8-7530-4aa4-bef9-9d73d56313f3",
      "trade_id":"b752503c-1c42-4dfe-ad1d-7b39da5db59c",
      "on_chain_transaction_id":"0x55dfac6137387a81e32fc353fca45eea3124cd42564a4112192323add8dee1da",
      "network_fee_notional":"1.25",
      "network_fee_quantity":".00032",
      "withdrawal_fee_notional": "1.50",
      "destination_address":"0xa6b0Cd1baaa15AE97D8135f0E87F61af27c6cB89"
   },
   "asset":"USDC",
   "network":"ETH",
   "payment_type":"payout",
   "participant_code":"CUST01",
   "quantity":"197.25",
   "status":"settled",
   "created_at":"2024-09-26T13:05:22.657Z",
   "updated_at":"2024-09-26T13:05:22.657Z",
   "total":"200",
   "reference_id": "0bd7f7f0-cf26-495f-b2df-e8afe8481ba3"
}

Failed Status

Due to either zerohash processing issues or issues with the blockchain itself, a Withdrawal can transition to a failed status. Example payload:

{
   "payment_id":"0f68333e-2114-469d-b505-c850d776e061",
   "obo_participant":{
      "participant_code":"CUST01",
      "account_group":"PLAT01",
      "account_label":"general"
   },
   "payment_details":{
      "withdrawal_request_id":"14f8ebb8-7530-4aa4-bef9-9d73d56313f3",
      "trade_id":"b752503c-1c42-4dfe-ad1d-7b39da5db59c",
      "on_chain_transaction_id":"0x55dfac6137387a81e32fc353fca45eea3124cd42564a4112192323add8dee1da",
      "network_fee_notional":"1.25",
      "network_fee_quantity":".00032",
      "withdrawal_fee_notional": "1.50",
      "destination_address":"0xa6b0Cd1baaa15AE97D8135f0E87F61af27c6cB89"
   },
   "asset":"USDC",
   "network":"ETH",
   "payment_type":"payout",
   "participant_code":"CUST01",
   "quantity":"197.25",
   "status":"failed",
   "created_at":"2024-09-26T13:05:22.657Z",
   "updated_at":"2024-09-26T13:05:22.657Z",
   "total":"200",
   "reference_id": "0bd7f7f0-cf26-495f-b2df-e8afe8481ba3"
}

Abandoned Status

When the End Customer leaves the SDK UI without having initiated a Withdrawal, zerohash will send an abandoned webhook message. This is helpful when accounting for balance ledgering and reconciliation, learn more here. Example payload:

{
   "payment_id":"0f68333e-2114-469d-b505-c850d776e061",
   "obo_participant":{
      "participant_code":"CUST01",
      "account_group":"PLAT01",
      "account_label":"general"
   },
   "payment_details":{
      "withdrawal_request_id":"",
      "trade_id":"",
      "on_chain_transaction_id":"",
      "network_fee_notional":"",
      "network_fee_quantity":"",
      "withdrawal_fee_notional": "",
      "destination_address":"0xa6b0Cd1baaa15AE97D8135f0E87F61af27c6cB89"
   },
   "asset":"USDC",
   "network":"ETH",
   "payment_type":"payout",
   "participant_code":"CUST01",
   "quantity":"",
   "status":"abandoned",
   "created_at":"2024-09-26T13:05:22.657Z",
   "updated_at":"2024-09-26T13:05:22.657Z",
   "total":"200",
   "reference_id": "0bd7f7f0-cf26-495f-b2df-e8afe8481ba3"
}

Crypto Withdraw SDK - Query Payments

The Platform can also query the GET /payments to view information about the Withdrawal. Example response:

{
    "request_id": "a502a26d-3734-497e-826b-d8d5734221e7",
    "participant_code": "CUST01",
    "platform_code": "PLAT01",
    "obo_participant": {
        "participant_code": "CUST01",
        "account_group": "PLAT01",
        "account_label": "general"
    },
    "payment_id": "0f68333e-2114-469d-b505-c850d776e061",
    "asset": "USDC",
    "network": "ETH",
    "quoted_asset": "USD",
    "status": "submitted",
    "created_at": "2024-11-15T23:02:06.836Z",
    "total": "200",
    "reference_id": "0bd7f7f0-cf26-495f-b2df-e8afe8481ba3"
}

Complete End of Day (EOD) Settlement

After each session, the Platform will be required to top up their float account to its original level. This is referred to as a Net Delivery Obligation (NDO). First, here are the standard settlement session and its schedules:

Session	NDO Wire Due
Monday	By Tuesday EOD
Tuesday	By Wednesday EOD
Wednesday	By Thursday EOD
Thursday	By Friday EOD
Friday	By Monday EOD

For Bank Holidays in the US, the NDO will be due during the next valid business day.