Deposits and withdrawals API Workflow

End customers can deposit fiat to a USD wallet for later use in funding crypto buys. End customers can withdraw USD balance directly to their connected bank account.

After you Link a bank account, you can request fiat deposits and withdrawals. Fiat deposits debit the end customer bank account and credit their Zero Hash USD account. Fiat withdrawals debit the end customer Zero Hash USD account and credit their bank account.

Platforms must be on the Direct or Default liquidity model to use fiat deposits and withdrawals.

Request a fiat deposit

POST /payments

Sample request

	'message': {
        'participant_code': 'ABC123',
        'external_account_id': '0f68333e-2114-469d-b505-c850d776e063',
        'currency': 'USD',
        'amount': '150.00',
        'description': 'COMPANY0',
        'transfer_type': 'debit'

Sample response

  'message': {
    'request_id': '0f65678e-2114-469d-b505-c850d776e078',	
    'participant_code': 'ABC123',
    'external_account_id': '0f68333e-2114-469d-b505-c850d776e063',
    'currency': 'USD',
    'amount': '150.00',
    'description': 'COMPANY0',
    'transfer_type': 'debit',
    'transaction_id': '0f34533e-2114-469d-b505-c850d776e061',
    'status': 'submitted',
    'created_at': 1561996924964

Buy crypto with a funded USD account

Prefunded accounts leverage Zero Hash’s liquidity endpoints ( GET /liquidity/rfq and POST /liquidity/execute). You may ignore sending an account_label as Zero Hash knows to default to the general account, as assigned when you reached POST /payments.

Sell crypto for USD

Selling acquired assets for USD follows the GET /liquidity/rfq and POST /liquidity/execute) flows. Please ignore the funding_details and ach_details mentions. These are only applicable for a deprecated Zero Hash product.

Withdraw USD to bank account

Withdrawing USD to a customer bank account follows the POST /payments flow, where transfer_type = credit.

Check payment status

GET /payments/status

Shares the current status of a debit or credit payment. Platforms should use this endpoint to understand funds availability and make their own decisions on how/when to make funds available to end customers.

Understanding payment statuses follows the existing GET /payments/status flow.

Request parameters

submittedRequest received and validated
pending_tradeTrade associated with the trade id is not terminated
pendingBalance and authorization confirmed with Plaid and transaction initialized
postedWithdrawn from end customer account
settledHold period is over and funds have moved to the bank
cancelledTransaction was proactively cancelled
failedTransaction failed during the process
returnedTransaction was returned prior to settlement (reason listed in the reason_code and reason_description of the webhook - most often “insufficient funds”)
returned_settledTransaction was returned after settlement (reason listed in the reason_code and reason_description of the webhook)
rejectedTransaction request blocked for risk mitigation or contractual reasons

Sample response

  "message": [
      "transaction_id": "0f68333e-2114-469d-b505-c850d776e061",
      "participant_code": "ALI123",
      "amount": "12.01",
      "status": "posted",
      "transfer_type": "credit",
      "bank_transfer_id": "0f68333e-2114-469d-b505-c850d776e061",
      "trade_id": "0f68333e-2114-469d-b505-c850d776e061",
      "trade_status": "terminated",
      "velocity_status": "pending",
      "velocity_failed_rule": "participant_transactions(in_flight_transfers_by_participant)",
      "created_at": "1975-08-19T23:15:30.000Z",
      "updated_at": "1975-08-19T23:15:30.000Z"
  "page": 1,
  "total_pages": 1,
  "page_size": 200,
  "count": 10

Webhook notifications

Webhooks let you know the status of a payment and if funds are available to the end customer or platform. The payload is a JSON object containing the following fields:

participant_codeThe Zero Hash identifier for the customer requesting an ACH transaction.string
typeIndicates if the payment is a credit or a debit for the end customerstring
transaction_idThe unique identifier generated by Zero Hash for the transaction.string
payment_statusThe current status of the payment. See payment statuses for more.string
reason_codeThe NACHA failure reason code, if the payment_status is returned.string
reason_descriptionThe description matching the reason_code, if the payment_status is returned.string
expected_settlement_dateFor payment type of credit, when the funds are expected to settle to the end customer bank account. This is an approximation as receiving banks are ultimately responsible for posting the update.string; YYYY-MM-DD format

For more information on the payments webhooks, check out our documentation here.

ACH returns

ACH returns are available in GET /payments/status under the status returned. While webhooks share the reason for returns, currently the GET call does not include this information.

Return funding

When a return comes in, Zero Hash will first check the end customer account to attempt to recover funds:

  • Full funds available in end customer account: Zero Hash funds the return with end customer balance.
  • Partial funds available in end customer account: Zero Hash funds as much of the return as possible with end customer balance, and pulls the remaining balance from platform loss reserves.
  • No funds available in end customer account: Zero Hash funds the return with platform loss reserves.

Unauthorized returns

An unauthorized return means that the bank account owner has flagged an issue with the transaction. When these returns are received, Zero Hash immediately locks the end customer account in an effort to mitigate further risk. The Zero Hash compliance team must evaluate risk before moving the participant back to approved, or along to disabled (more on participant statuses).

Participant status webhooks alert platforms to movements from approved to locked. In the case of unauthorized returns, those results share a reason of ach.