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
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
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 ACH 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, 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
.
Updated 4 months ago