Payins API Integration Guide

Power your checkout with crypto and stablecoins - end to end integration guide

See core product page here.

Definitions

TermDefinition
PlatformThe company that is under contract with zerohash and integrates directly with the zerohash's API
MerchantA business entity (non-natural person) that serves as the customer-facing front-end in the transaction flow. Typically, the Merchant is a customer of the Platform and is where the Shopper initiates their interaction. In some cases, the Merchant and Platform may be the same entity.
ShopperThe natural person that pays for the good or service

How the Integration Works

A high-level summary of each step of the Payins API integration

StepNotes
Merchant onboardingOnboard the merchants that sell goods and services through your platform. Only applicable when Platform is not acting as the Merchant (ex. PSPs that acquire merchants)
Shopper onboardingOnboard Shoppers making their first crypto or stablecoin purchases
Initiate Shopper's paymentGenerate deposit instructions for Shoppers
Initiate refundLink external account where Shopper will receive funds and facilitate repayment

Payins prerequisites

Pre-conditionIf missing:
Ask zerohash to enable this product for youPOST /pay/rfq returns: 401 — "Your Platform is not configured to use the Pay product"
Transacting participant has signed the ACCOUNT_FUNDING_PAY agreementPOST /pay/rfq returns: 401 — "Participant has not signed the required agreement for Pay"
API key has Pay READ_AND_WRITE permissionPOST /pay/rfq returns: 403 — "This api key does not have write permission to this endpoint" (GET endpoints return the read-permission variant)
Pre-fund Refund Float AccountYou wont be able to initiate refunds to shoppers

Transaction Fees (optional)

Platforms can charge a transaction fee on Payins, paid by either the Shopper or the Merchant. zerohash configures fees for your Platform. Contact your zerohash Relationship Manager to enable or change them. All collected fees settle to the Platform's pay_transaction_fees account (see "7. Accounts").

Configuration options

SettingOptions
Fee typeFlat: a single bps rate applied to the payment amount.
Tiered: bps rates that vary by amount. Each portion of the payment is charged at the rate for its tier.
Minimum fee floorThe minimum fee charged per transaction, in USD.
Fee payorShopper or Merchant
ScopeA Platform-wide default, or a per-Merchant configuration. A Merchant configuration overrides the Platform default for that Merchant.

How fees flow

ScenarioShopper sendsSettlement
Platform is the Merchant, Shopper pays feeQuoted amount + feeFee → Platform pay_transaction_fees
Remainder → Platform pay
Platform has many Merchants, Shopper pays feeQuoted amount + feeFee → Platform pay_transaction_fees
Quoted amount → Merchant pay
Platform has many Merchants, Merchant pays feeQuoted amountFee → Platform pay_transaction_fees
Quoted amount less fee → Merchant pay
📘

Shopper as Fee Payor

When the Shopper pays the fee, the quoted_total and underlying_quantity returned by POST /pay/rfq already include the fee. Present these values to the Shopper as the amount due. Over and under payments are evaluated against this fee-inclusive amount.

When the Merchant pays the fee, the RFQ amounts are not affected. The fee is deducted from the amount settled to the Merchant.

1. Submit Merchant

ℹ️

Who this applies to

This guide is relevant when the Platform has many merchants. If the Platform is itself the merchant, this step is not required.

Begin by submitting the Merchant via POST /participants/entity/new. See more information here.


2. Query Merchant

You can query already-submitted Merchants via the GET /participants endpoint. If you'd like to query a specific Merchant, use theparticipant_code parameter.


3. Fund Refund Account

To enable future refunds, you must pre-fund your Refund account by sending a wire transfer to the designated bank account provided by our settlement team. Ensure the wire memo is tagged with your Platform code + "_refund" (ie, PLAT01_refund):

Here are the account details:

  • Participant_code: PLAT01 (replace with your participant_code)
  • Account_group: PLAT01 (replace with your participant_code)
  • Account_label: pay_refund
  • Account_type: available
  • Asset: USD

4. Submit Shopper

Next, you'll need to onboard the end users (ie, "Shoppers"). Depending on transaction type and the Shopper's transaction volume and residence, we have differing level of diligence requirements. See more information on Shopper Onboarding here.

Use POST /participants/customers/new to create a new shopper. Set onboarding_profile = "shopper" and partial = true to distinguish this participant from a standard participant.

Sample Request

{
  "onboarding_profile": "shopper",
  "email": "[email protected]",
  "partial": true
}

Shoppers with onboarding_profile = "shopper" and partial = true are auto-approved upon creation as long as the minimum required data is present: a phone_number or email. No additional fields are required at creation time — further data can be added later via PATCH as the shopper's transaction tier requires it.

📘

Signature Collection

For the Payins API Solution, it is critical that you collect consent from the Shopper to zerohash's user agreements and share confirmation that consent was collected through the POST /participants/customers/new endpoint.


5. Query Shopper

To retrieve general information about the Shopper, query the GET /participants endpoint. You can use the participant_code filter to retrieve an individual Shopper.


6. Query Shopper Limits

To retrieve transaction limits for a Shopper's tier, query the GET /pay/limits endpoint. You can use the participant_code attribute to retrieve an individual Shopper. Use the merchant_participant_code attribute to query total volume aggregated for a particular merchant.

Example Response:

{
  "message": {
    "request_id": "test-request-id",
    "participant_code": "SHOPP1",
    "merchant_participant_code": "MERCH1",
    "merchant_classification": "NON-TRANSFERABLE-3",
    "current_level": 2,
    "current_limits": [
      {
        "limit": "1000.00",
        "spent": "250.00",
        "remaining": "750.00",
        "window": "daily"
      }
    ],
    "platform_totals": [
      {
        "window": "daily",
        "currency": "USD",
        "total_amount": "5000.00",
        "transaction_count": 12
      }
    ],
    "merchant_totals": [
      {
        "window": "daily",
        "currency": "USD",
        "total_amount": "250.00",
        "transaction_count": 3
      }
    ]
  }
}

7. Accounts

The Platform will have the following accounts at zerohash:

AccountDescriptionTechnical Details
Settlement AccountThe fiat account that contains the balance of successful payments
  • participant_code = [your platform code or merchant's participant code]
  • account_group = [your platform code] - account_label = pay
  • account_type = available
  • asset = USD (or other fiat currency being used)
Refund Float AccountThe fiat account, funded by the Platform, that is used to refund Shoppers. The balances here will be converted to a crypto or stablecoin asset and sent on-chain to the Shopper. See section, "11. Refund a Payment" below for details
  • participant_code = [your platform code]
  • account_group = [your platform code]
  • - account_label = pay_refund
  • account_type = available
  • asset = USD (or other fiat currency being used)
Error AccountThe fiat account that accumulates due to error scenarios (over payment, under payment, incorrect asset or network, late payment
  • participant_code = [your platform code or merchant's participant code]
  • account_group = [your platform code]
  • account_label = pay_error
  • account_type = available
  • asset = USD (or other fiat currency being used)
Transaction Fees AccountThe fiat account that collects Payins transaction fees charged by the Platform. Only used when fees are enabled. See "Transaction Fees" above
  • participant_code = 00SCXM
  • account_group = [your platform code]
  • account_label = pay_transaction_fees
  • account_type = available
  • asset = USD (or other fiat currency being used)

8. Initiate Payment

Request a quote - POST /pay/rfq

Generate quote for the payment amount.

Example Request:

{
  "participant_code": "SHOPP1",
  "pay_asset": "USDC",
  "quoted_total": "100.00",
  "quoted_currency": "USD",
  "account_label": "pay",
  "client_reference_id": "order-12345",
  "merchant_participant_code": "MERCH01" //optional, only use when Platform!= Merchant
}

Interpretation of this request - the Shopper (SHOPP1) is making a $100 payment to the Merchant (MERCH01)using USDC as the payment asset. quoted_currency is an enum with one supported value: USD.

If the Shopper (SHOPP1) has sufficient PII data for the diligence Tier required for the transaction, POST /pay/rfq will return the quote with a deposit_address.

Example Response:

{
  "request_id": "14f8ebb8-7530-4aa4-bef9-9d73d56313f3",
  "participant_code": "SHOPP1",
  "pay_asset": "USDC",
  "rate": "1",
  "quoted_currency": "USD",
  "quoted_total": "100",
  "underlying_quantity": "100",
  "price_expire_ts": null,
  "deposit_address": "0x5f59B625036ccB4f7aD27Ca4Cb896e4452AfFDAF",
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_reference_id": "order-1001",
  "is_static": true
}
FieldTypeNotes
request_idUUID stringEchoed back from Zero Hash for request correlation.
participant_codestringShopper participant code.
pay_assetstringNetwork-qualified asset, such as USDC.SOL, USDC.BASE, or BTC.
ratedecimal stringQuoted rate at the moment of RFQ.
quoted_currencystringEnum: USD.
quoted_totaldecimal stringAmount in quoted_currency.
underlying_quantitydecimal stringAmount in pay_asset.
price_expire_tsISO 8601 UTC string or nullMay be null for stablecoins.
deposit_addressstringBlockchain address on the pay_asset network.
transaction_idUUID stringUse this as the path parameter for POST /pay/{id}/rfq. This is distinct from the settled transaction_id in webhook payloads and GET /pay/transactions rows.
client_reference_idstring, optionalWhatever you sent on the request, echoed back. This is a free-form string.
is_staticbooleanIndicates whether the deposit address is reused or generated per RFQ

Quotes with fees enabled

If fees are configured for the Platform or Merchant, the RFQ response includes the fee configuration. In this example, the Shopper is the Fee Payor with a 100 bps flat fee, so the $100 request returns a fee-inclusive total of $101.

Example Response (flat fee, Shopper pays):

{
  "request_id": "14f8ebb8-7530-4aa4-bef9-9d73d56313f3",
  "participant_code": "SHOPP1",
  "pay_asset": "USDC",
  "rate": "1",
  "quoted_currency": "USD",
  "quoted_total": "101",
  "underlying_quantity": "101",
  "price_expire_ts": null,
  "deposit_address": "0x5f59B625036ccB4f7aD27Ca4Cb896e4452AfFDAF",
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_reference_id": "order-1001",
  "is_static": true,
  "deposit_fee_type": "flat",
  "fee_bps": 100,
  "minimum_fee_floor": "0.50",
  "fee_payor": "SHOPP1"
}

Example Response (tiered fee, Shopper pays):

{
  "request_id": "14f8ebb8-7530-4aa4-bef9-9d73d56313f3",
  "participant_code": "SHOPP1",
  "pay_asset": "USDC",
  "rate": "1",
  "quoted_currency": "USD",
  "quoted_total": "101",
  "underlying_quantity": "101",
  "price_expire_ts": null,
  "deposit_address": "0x5f59B625036ccB4f7aD27Ca4Cb896e4452AfFDAF",
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_reference_id": "order-1001",
  "is_static": true,
  "deposit_fee_type": "tiered",
  "fee_bps": 20,
  "minimum_fee_floor": "1.00",
  "fee_tiers": [
    { "tier": 1, "min_amount": 0, "max_amount": 1000, "fee_bps": 40 },
    { "tier": 2, "min_amount": 1000, "max_amount": null, "fee_bps": 20 }
  ],
  "fee_payor": "SHOPP1"
}
FieldTypeNotes
deposit_fee_typestringflat or tiered. Returned only when fees are enabled.
fee_bpsintegerThe flat fee rate. For tiered fees, this is the lowest tier's rate, kept for backward compatibility. Use fee_tiers for the full schedule.
minimum_fee_floordecimal stringThe minimum fee charged per transaction, in USD.
fee_tiersarrayTiered fees only. Each object contains tier (integer), min_amount (USD), max_amount (USD, null for the final tier), and fee_bps (integer).
fee_payorstringThe participant code of the party paying the fee: the Shopper's or the Merchant's.

When the Shopper is the Fee Payor, quoted_total and underlying_quantity include the fee on top.

Error Responses

KYC Requirements Not Met

If the Shopper (SHOPP1) has insufficient PII data for the Shopper Tier required for the transaction, POST /pay/rfq will return an error message identifying missing requirements:

{
  "error": "Shopper KYC requirements for this transaction are not met",
  "missing_requirements": [
    "first_name",
    "last_name",
    "date_of_birth"
  ]
}

You can use these guidelines to update the Shopper accordingly via PATCH /participants/customers, and then call POST /pay/rfq again.

Manual Approval Required

Manual approval by zerohash is required for transactions at or above $500,000, or when a Shopper's lifetime spend reaches $500,000 or more. When a Platform calls POST /pay/rfq to generate a quote and deposit_address for a transaction that breaches $500,000, the response will look like this:

{
   "error": "Manual approval required for this transaction",
  "transaction_id": "txn_01HZF7QWXJ8XK3VYNS6TKDM4G2"
}

This response means that the transaction has been submitted for zerohash approval. You will receive a webhook once the status of the transaction has been updated, and can then use the transaction_id returned in the response as the path parameter when calling POST /pay/{id}/rfq to refresh the quote.


End customer initiates on-chain payment

On the Platform's user interface, the Shopper is presented with the deposit_address returned by POST /pay/rfq, and the amount to deposit. They use their Metamask wallet, for example, to trigger a withdrawal into the deposit_address for the amount of the payment.


Payment Successful

Successful Payment (exact amount)

Once a successful payment is received for the exact amount, we'll send a webhook to you. The webhook payload includes all fields returned by GET /pay/transactions (see "9. Query payments"), including fee fields when fees are enabled. This example shows a 100 bps flat fee paid by the Shopper:

{
  "participant_code": "SHOPP1",
  "fund_asset": "USDC.BASE",
  "rate": "1",
  "quoted_currency": "USD",
  "source_address": "external",
  "deposit_address": "0xb07C48f0BF25A97034c818Dc643A98e42703D20c",
  "quantity": "101",
  "notional": "101",
  "fund_id": "6767a149-4771-4166-ba07-a2542e361318",
  "fund_timestamp": 1756376889792000000,
  "deposit_timestamp": 1756376889499000000,
  "transaction_id": "d1d731ed-952c-410e-b62b-eb00e3d096fc",
  "account_label": "general",
  "success": true,
  "status_reason_code": "DEPOSIT_PROCESSED",
  "reference_id": "04918aef-41d1-4dfb-82b8-2fdc232a8d88",
  "deposit_fee_type": "flat", //only returned if fees are enabled
  "deposit_fee_bps": 100,  //only returned if fees are enabled
  "deposit_fee_notional": "1.00",  //only returned if fees are enabled
  "fee_payor": "SHOPP1" //only returned if fees are enabled 
}

Successful Payment (over payment)

Once a successful payment is received where the Shopper sent too much, we'll send a webhook to you that looks like this:

{
  "participant_code": "SHOPP1",
  "fund_asset": "USDC.BASE",
  "rate": "1",
  "quoted_currency": "USD",
  "source_address": "external",
  "deposit_address": "0xb07C48f0BF25A97034c818Dc643A98e42703D20c",
  "quantity": "100",
  "notional": "100",
  "fund_id": "6767a149-4771-4166-ba07-a2542e361318",
  "fund_timestamp": 1756376889792000000,
  "deposit_timestamp": 1756376889499000000,
  "transaction_id": "d1d731ed-952c-410e-b62b-eb00e3d096fc",
  "account_label": "general",
  "success": true,
  "status_reason_code": "DEPOSIT_PROCESSED",
  "status_reason": "over payment",
  "reference_id": "04918aef-41d1-4dfb-82b8-2fdc232a8d88"
}

Payment Unsuccessful

Failure scenarioExpected remediation steps
Under paymentShopper to contact Platform → Platform to facilitate a withdraw via POST /payments to Shopper's wallet
DepegShopper to contact Platform → Platform to contact zerohash via Slack or Email to facilitate withdrawals back to the Shopper manually
Above max thresholdShopper to contact Platform → Platform to contact zerohash via Slack or Email to facilitate withdrawals back to the Shopper manually
QuarantineShopper to contact Platform → Platform to contact zerohash via Slack or Email. Note: zerohash will likely disable this Shopper, as this scenario is typically triggered due receiving a deposit from a high-risk source address
Late paymentShopper to contact Platform → Platform to facilitate a withdraw via POST /payments to Shopper's wallet
Wrong asset or networkShopper to contact Platform → Platform to facilitate a withdraw via POST /payments to Shopper's wallet

Payment Unsuccessful (under payment)

Upon a payment for an insufficient amount, a webhook notification will be triggered as follows

{
  "participant_code": "SHOPP1",
  "fund_asset": "USDC.BASE",
  "rate": "1",
  "quoted_currency": "USD",
  "source_address": "external",
  "deposit_address": "0xb07C48f0BF25A97034c818Dc643A98e42703D20c",
  "quantity": "90",
  "notional": "",
  "fund_id": "6767a149-4771-4166-ba07-a2542e361318",
  "fund_timestamp": 1756376889792000000,
  "deposit_timestamp": 1756376889499000000,
  "transaction_id": "d1d731ed-952c-410e-b62b-eb00e3d096fc",
  "account_label": "general",
  "success": false,
  "status_reason_code": "PROCESSING_FAILED",
  "status_reason": "under payment",
  "reference_id": "04918aef-41d1-4dfb-82b8-2fdc232a8d88"
}

Successful Payment (depeg)

If a stablecoin becomes depegged, to mitigate zerohash's risk, we will manually mark the asset as depegged on our side. This will block all “sell” transactions converting that stablecoin to USD. Should we receive a payment deposit during this period, we will not convert the deposit to fiat. Instead, the funds will be moved to a dedicated depeg account, and a webhook notification will be triggered as follows:

{
  "participant_code": "SHOPP1",
  "fund_asset": "USDC.BASE",
  "rate": "1",
  "quoted_currency": "USD",
  "source_address": "external",
  "deposit_address": "0xb07C48f0BF25A97034c818Dc643A98e42703D20c",
  "quantity": "100",
  "notional": "",
  "fund_id": "6767a149-4771-4166-ba07-a2542e361318",
  "fund_timestamp": 1756376889792000000,
  "deposit_timestamp": 1756376889499000000,
  "transaction_id": "d1d731ed-952c-410e-b62b-eb00e3d096fc",
  "account_label": "general",
  "success": false,
  "status_reason_code": "PROCESSING_FAILED",
  "status_reason": "depeg",
  "reference_id": "04918aef-41d1-4dfb-82b8-2fdc232a8d88"
}

Above max threshold

zerohash has certain liquidation maximums on our end. If a large deposit is received above this threshold, a webhook notification will be triggered as follows:

{
  "participant_code": "SHOPP1",
  "fund_asset": "USDC.BASE",
  "rate": "1",
  "quoted_currency": "USD",
  "source_address": "external",
  "deposit_address": "0xb07C48f0BF25A97034c818Dc643A98e42703D20c",
  "quantity": "10000000",
  "notional": "",
  "fund_id": "6767a149-4771-4166-ba07-a2542e361318",
  "fund_timestamp": 1756376889792000000,
  "deposit_timestamp": 1756376889499000000,
  "transaction_id": "d1d731ed-952c-410e-b62b-eb00e3d096fc",
  "account_label": "general",
  "success": false,
  "status_reason_code": "PROCESSING_FAILED",
  "status_reason": "above max threshold",
  "reference_id": "04918aef-41d1-4dfb-82b8-2fdc232a8d88"
}

Quarantine

If zerohash detects that the source address of the payment deposit is high-risk, a webhook notification will be triggered as follows:

{
  "participant_code": "SHOPP1",
  "fund_asset": "USDC.BASE",
  "rate": "1",
  "quoted_currency": "USD",
  "source_address": "external",
  "deposit_address": "0xb07C48f0BF25A97034c818Dc643A98e42703D20c",
  "quantity": "10000000",
  "notional": "",
  "fund_id": "6767a149-4771-4166-ba07-a2542e361318",
  "fund_timestamp": 1756376889792000000,
  "deposit_timestamp": 1756376889499000000,
  "transaction_id": "d1d731ed-952c-410e-b62b-eb00e3d096fc",
  "account_label": "general",
  "success": false,
  "status_reason_code": "PROCESSING_FAILED",
  "status_reason": "For Zero Hash Compliance reasons, the deposit has not been converted to fiat and the crypto has been credited to a Zero Hash holding account",
  "reference_id": "04918aef-41d1-4dfb-82b8-2fdc232a8d88"
}

Late payment

If zerohash receives a payment deposit past the Payment Window, a webhook notification will be triggered as follows:

{
  "participant_code": "SHOPP1",
  "fund_asset": "USDC.BASE",
  "rate": "1",
  "quoted_currency": "USD",
  "source_address": "external",
  "deposit_address": "0xb07C48f0BF25A97034c818Dc643A98e42703D20c",
  "quantity": "10000000",
  "notional": "",
  "fund_id": "6767a149-4771-4166-ba07-a2542e361318",
  "fund_timestamp": 1756376889792000000,
  "deposit_timestamp": 1756376889499000000,
  "transaction_id": "d1d731ed-952c-410e-b62b-eb00e3d096fc",
  "account_label": "general",
  "success": false,
  "status_reason_code": "DEPOSIT_WINDOW_EXPIRED",
  "status_reason": "payment session has expired",
  "reference_id": "04918aef-41d1-4dfb-82b8-2fdc232a8d88"
}

Wrong asset or network

If zerohash receives a payment deposit for an asset that was not selected by the Shopper on the Select Asset page, a webhook notification will be triggered as follows:

{
  "participant_code": "SHOPP1",
  "fund_asset": "ETH",
  "rate": "1",
  "quoted_currency": "USD",
  "source_address": "external",
  "deposit_address": "0xb07C48f0BF25A97034c818Dc643A98e42703D20c",
  "quantity": ".15",
  "notional": "",
  "fund_id": "6767a149-4771-4166-ba07-a2542e361318",
  "fund_timestamp": 1756376889792000000,
  "deposit_timestamp": 1756376889499000000,
  "transaction_id": "d1d731ed-952c-410e-b62b-eb00e3d096fc",
  "account_label": "general",
  "success": false,
  "status_reason_code": "PROCESSING_FAILED",
  "status_reason": "deposit currency does not match the expected currency",
  "reference_id": "04918aef-41d1-4dfb-82b8-2fdc232a8d88"
}

9. Query payments

You can query our REST endpoint GET /pay/transactions to retroactively view payment details.

Query parameters

All filters combine with AND. The response shape matches the List payin transactions reference page.

Query paramTypeNotes
participant_codestringRequired for default listing.
pageintegerDefault 1.
page_sizeintegerDefault 50, capped at 50. Passing 100 is silently clamped.
transaction_idstringExact match on the settled transaction ID.
pay_assetstringAsset filter, such as USDC.SOL. Response rows return this value as fund_asset.
successbooleantrue returns only settled-with-success transactions.
client_reference_idstringExact match on the value you sent in the RFQ.
deposit_timestamp_gteinteger, Unix secondsLower-bound inclusive.
deposit_timestamp_gtinteger, Unix secondsLower-bound exclusive.
deposit_timestamp_lteinteger, Unix secondsUpper-bound inclusive.
deposit_timestamp_ltinteger, Unix secondsUpper-bound exclusive.

Sample Response:

    {
      "participant_code": "SHOPP1",
      "fund_asset": "USDC",
      "quoted_currency": "USD",
      "deposit_address": "0xabc123usdcwalletaddress",
      "rate": "1.00",
      "quantity": "100.00",
      "notional": "100.00",
      "fund_timestamp": 1712756400,
      "transaction_id": "111e8400-e29b-41d4-a716-446655440000",
      "account_label": "pay",
      "fund_id": "fund-usdc-1001",
      "success": true,
      "status_reason": "",
      "status_reason_code": "",
      "is_first_deposit": true,
      "fee_payor": "MERCH01",
      "deposit_fee_bps": "25",
      "deposit_fee_notional": "0.25",
      "deposit_timestamp": 1712756700,
      "source_address": "0xsenderwallet123",
      "deposited_asset": "USDC",
      "client_reference_id": "order-1001",
      "source": {
        "source_type": "on_chain",
        "integration": "ethereum"
      },
      "deposit_fee_type": "flat"

    }

Fee fields

When fees are enabled, each transaction includes the following fields. The same fields are included in webhook payloads.

FieldTypeNotes
deposit_fee_typestringflat or tiered
deposit_fee_bpsintegerEffective fee rate charged
deposit_fee_notionaldecimal stringFee amount charged
fee_payorstringParticipant code of the Shopper or Merchant that paid the fee
fee_tier_breakdownarrayTiered fees only. Each object contains tier (integer), amount_in_tier (USD amount falling in that tier), fee_bps (rate applied), and fee_amount (fee for that tier). Empty for flat fees.

How to read the amounts

  • quantity / notional always reflect what the Shopper actually sent (gross). When the Shopper is the Fee Payor, these match the fee-inclusive underlying_quantity / quoted_total from the RFQ.
  • Fee fields always report the fee on its own.
  • The net amount settled to the Merchant or Platform is always notional − deposit_fee_notional.

Example fee_tier_breakdown for a $1,500 payment:

"fee_tier_breakdown": [
  { "tier": 1, "amount_in_tier": 1000, "fee_bps": 40, "fee_amount": 4.00 },
  { "tier": 2, "amount_in_tier": 500, "fee_bps": 20, "fee_amount": 1.00 }
]

10. Settlement

Withdrawals from Merchant or Platform participant accounts to external bank accounts can be initiated through POST /withdrawals/requests.


11. Refund a Payment

In order to initiate a refund, you should use the following endpoints:

  • POST /payments/external_accounts - links a crypto account where the Shopper will receive their refund
  • POST /payments - initiates a conversion from USD (using Refund account) to the crypto asset. This API call will also automatically and immediately send the funds on-chain.
🚧

IMPORTANT: You cannot rely on the deposit’s source address as the refund destination. Blockchain transactions are not inherently bidirectional, and returning funds to the sender address may result in loss of funds or failed deliveries.

Some Platforms may choose to pair their zerohash integration with their own transaction monitoring tools. In situations where zerohash accepts a deposit, but the Platform’s monitoring logic flags and rejects it, the Platform may opt to return the deposit by using the POST /convert_withdraw/rfq and POST /convert_withdraw/execute endpoint.

The required flow is to always request and confirm a return address directly from the Shopper before initiating the return.

Please speak to a zerohash solutions engineer for guidance if interested in this flow.


Did this page help you?