Crypto buy/sell via Fiat API Workflow

After you Link a bank account, you can request crypto buys and sells. Crypto buys debit the end customer bank account, while crypto sells credit the end customer bank account. The platform float is leveraged to exchange crypto while the fiat leg of the transaction settles.

Platforms must be on the Novated liquidity model to use crypto buys and sells via ACH.

Request an on-demand payment

POST /payments/rfq

Follow the same requirements as GET /liquidity/rfq. Sells are ACH or RTP credits and Buys are ACH debits.

The quote duration will default to your platform setting, as configured with Client Services. We recommend a one minute quote with this endpoint to accommodate required balance and authorization checks for the ACH payment. However, you may pass in the optional field quote_expiry with RFQ to override your default.

Request parameters

Response parameters

Execute quote

POST /payments/execute

Prerequisite

• An external account must already be created via POST /payments/external_accounts.
• A quote must be retained from POST /payments/rfq.

Sample response

{
  "message": {
    "request_id": "14f8ebb8-7530-4aa4-bef9-9d73d56313f3",
    "quote": {
      "request_id": "ce819fe8-b1d7-43bb-961c-e09ede0988d3",
      "participant_code": "CUST01",
      "quoted_currency": "USD",
      "side": "BUY",
      "quantity": "1",
      "price": "11430.90",
      "quote_id": "5cd07738b861c31e3bd61467BTC1Buy1568311644602",
      "expire_ts": 1568311649602,
      "account_group": "GRP001",
      "account_label": "sub_account_test",
      "obo_participant": {
        "participant_code": "20XRLH",
        "account_group": "WRD1K0",
        "account_label": "general"
      },
      "network_fee_notional": "1",
      "network_fee_quantity": "1",
      "total_notional": "2.00",
      "underlying": "BTC",
      "asset_cost_notional": "2.00"
    },
    "trade_id": "ba97133e-ab15-4c86-86c1-86671b8420bc",
    "status": "Completed",
    "ach_details": {
      "inbound_reference_id": "string"
    },
    "payment_amount": "string",
    "external_account_id": "0f68333e-2114-469d-b505-c850d776e063",
		"quote_id": "ba97133e-ab15-4c86-86c1-86671b8420bc",
		"description": "PLATFORM",
    "ach_signed_timestamp": 1561996924964
  }
}

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 crypto available to end customers.

Understanding payment statuses follows the existing GET /payments/status flow. 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
}

ACH On-Demand

ACH Pre-funded

📘

Final states

States marked are all possible end-states for a transaction, though a transaction can move from settled → returned

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:

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.

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.