---
updatedAt: 2026-09-07T20:21:28.000Z
agentTools:
projectIndex: https://docs.zerohash.com/llms.txt
---
# Fund Withdrawals SDK with AUTH Guide
Simplify withdrawals from your platform with AUTH connectivity to popular exchanges & wallets
## Setup
### Please note that for AUTH usage you must install zh-web-sdk v3.5.0 or higher
Platforms can instantiate the Fund Withdrawals SDK offering with [AUTH](https://docs.zerohash.com/zerohash/docs/auth) included that eliminates the need to use the Account Link SDK flow.
Fund Withdrawals differs from the Crypto Withdrawals SDK in that it requires fiat to convert into outgoing withdrawals from the platform's float account. Crypto Withdrawals SDK is a non-converted withdrawal of crypto on the zerohash ledger to the customer's exchange account or wallet. Both SDKs utilize the same permission `crypto-withdrawals` and the difference is in the parameters provided in the access token `quoted_asset = USD` triggers the Fund Withdrawals flow).
The key difference between this integration and the [Account Link SDK + Withdraw SDK](https://docs.zerohash.com/zerohash/docs/wallet-link-sdk-integration-guide) integration is the absence of the external account reference. Otherwise, the SDK flow is similar.
## Flow
### Fund Withdrawls SDK - Request Access Token
Platform [generates a client access token](https://docs.zerohash.com/zerohash/reference/post_client-auth-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](https://docs.zerohash.com/reference/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:
```c JSON
{
"participant_code": "CUST01",
"permissions": ["crypto-withdrawals"],
"withdrawal_details": {
"quoted_asset": "USD",
"withdrawal_request_amount": "200"
},
"reference_id": "0bd7f7f0-cf26-495f-b2df-e8afe8481ba3"
}
```
#### Starting the Fund 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](https://docs.zerohash.com/zerohash/docs/mobile-sdks) to access full AUTH functionality.
```swift Swift
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 |
### Fund Withdrawals SDK - Initiate Withdrawal
At this point, the End Customer is interacting with the front end SDK. The Customer will ultimately initiate the withdrawal.
### Fund Withdrawls 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](https://docs.zerohash.com/reference/payments-status-changes).
**Note:** the `x-zh-hook-payload-type` is `payment_status_changed` (more details on webhooks [here](https://docs.zerohash.com/reference/webhook-security))
#### 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:
```c JSON
{
"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:
```c JSON
{
"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:
```c JSON
{
"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:
```c JSON
{
"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:
```c JSON
{
"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](https://docs.zerohash.com/v1.0/docs/withdrawals-releasing-funds). Example payload:
```c JSON
{
"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"
}
```
### Fund Withdrawals SDK - Query Payments
The Platform can also query the [GET /payments](https://docs.zerohash.com/reference/get_payments) to view information about the Withdrawal. Example response:
```c JSON
{
"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.