Deposits and withdrawals API Workflow

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

Status	Description
submitted	Request received and validated
pending_trade	Trade associated with the trade id is not terminated
pending	Balance and authorization confirmed with Plaid and transaction initialized
posted	Withdrawn from end customer account
settled	Hold period is over and funds have moved to the bank
cancelled	Transaction was proactively cancelled
failed	Transaction failed during the process
returned	Transaction was returned prior to settlement (reason listed in the reason_code and reason_description of the webhook - most often “insufficient funds”)
returned_settled	Transaction was returned after settlement (reason listed in the reason_code and reason_description of the webhook)
rejected	Transaction 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:

Parameter	Description	Type
participant_code	The Zero Hash identifier for the customer requesting an Fiat transaction.	string
type	Indicates if the payment is a credit or a debit for the end customer	string
transaction_id	The unique identifier generated by Zero Hash for the transaction.	string
payment_status	The current status of the payment. See payment statuses for more.	string
reason_code	The NACHA failure reason code (for ACH), if the payment_status is returned.	string
reason_description	The description matching the reason_code, if the payment_status is returned.	string
expected_settlement_date	For 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.