Payins SDK Integration Guide

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

Introduction

The Payins product allows payment service providers or merchants to offer stablecoins or crypto as a payment option at checkout.


Definitions

TermDefinition
PlatformThe company that is under contract with zerohash and integrates directly with zerohash's APIs or SDKs.
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 integration step, showing whether it uses the API or SDK.

StepAPI or SDK?Notes
Merchant onboardingAPI
Shopper onboardingAPI
Shopper accepts zerohash t's and c'sSDKThis is the first page on the SDK a first-time Shopper will see
Shopper makes paymentSDKThe SDK will facilitate the asset and network selection and will present the expected crypto/stablecoin quantity, address, and quote timing information. If the Shopper pays a transaction fee, the SDK also discloses the fee and includes it in the amount due
Initiate refundAPI
Initiate returnAPI

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 "6. Accounts").

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.
ScenarioShopper sendsSettlement
Platform is the Merchant, Shopper pays feePurchase amount + feeFee → Platform pay_transaction_fees
Remainder → Platform pay
Platform has many Merchants, Shopper pays feePurchase amount + feeFee → Platform pay_transaction_fees
Purchase amount → Merchant pay
Platform has many Merchants, Merchant pays feePurchase amountFee → Platform pay_transaction_fees
Purchase amount less fee → Merchant pay
📘

What the Shopper sees

Shopper pays the fee: the SDK shows the fee during network selection, asks the Shopper to acknowledge it when they select an asset, and displays a fee-inclusive amount due on the payment screen. See "7. Initiate Payment" below.

Merchant pays the fee: the SDK experience is unchanged. The Shopper pays the purchase amount, and the fee is deducted from the amount settled to the Merchant.

For the fee fields in webhooks and GET /pay/transactions, see the Payins API Integration Guide.

1. Submit Merchant

ℹ️

Who this applies to

This section 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. 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

3. 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.


4. Query Shopper

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


5. 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
      }
    ]
  }
}

6. 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)

7. Initiate Payment

Now, let's move onto money movement. Begin by requesting an access token specifying:

FieldDescriptionExample ValueRequired?
participant_codeThe 6-digit alpha numeric code associated with the Shopper that is looking to pay (the response of the original POST /participants/customers/new call)SHOPP1Y
permissionsThe array of permissions that will be granted to the returned JWT token["crypto-pay"]Y
purchase_amount
(part of the payment_details object)
The amount of the good or service being paid for, denominated in the denominated_currency100Y
denominated_currency
(part of the payment_details object)
The fiat or crypto currency in which the purchase amount is pricedUSDY
reference_idPlatform-dictated reference id that is tied to any successful payment0bd7f7f0-cf26-495f-b2df-e8afe8481ba3N
merchant_participant_codeThe 6-digit alpha numeric code associated with the Merchant or Platform that is receiving paymentMERCH1N

Example POST /client_auth_token request:

{
 "participant_code": "SHOPP1",
 "permissions": ["crypto-pay"],
 "payment_details" : {
      "purchase_amount": "100",
      "denominated_currency" : "USD"
   },
  "reference_id": "0bd7f7f0-cf26-495f-b2df-e8afe8481ba3"
  "merchant_participant_code": "MERCH01" //optional, only use when Platform!= Merchant
}
📘

Transaction fees

Always pass the price of the good or service as purchase_amount, without any fee. When the Shopper is the Fee Payor, the SDK adds the applicable fee to the amount the Shopper is asked to pay.

After successfully calling POST /client_auth_token, the next step is to initiate the Payins SDK flow. See the example below for how to implement this in a React application. Keep in mind that if you're using a Native Mobile App (Swift, Flutter, etc) instead of using zh-web-sdk you should follow the WebView approach, described here.

import React from 'react';
import ZeroHashSDK, { AppIdentifier } from 'zh-web-sdk';

const App = () => {
  const sdk = new ZeroHashSDK({
    zeroHashAppsURL: "https://web-sdk.cert.zerohash.com",
    payJWT: "<JWT_TOKEN_HERE>" 
  });

    sdk.openModal({
    appIdentifier: AppIdentifier.PAY, 
  })
  return <></>;
}

export default App;

Error Responses

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 /client_auth_token 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 to call POST /client_auth_token successfully.


KYC Requirements Not Met

If the Shopper (SHOPP1) has insufficient PII data for the Shopper Tier required for the transaction, POST /client_auth_token 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 /client_auth_token again.


7a. Accept T's and C's

First-time Shoppers will need to accept the zerohash terms and conditions:

7b. Select asset and network

The Shopper will now select the asset they want to pay with. Remember, the assets that are displayed on this screen are your choice - contact your zerohash contact to make the proper configurations:

Depending on the selected asset, the next screen may prompt the Shopper to choose a network. If the asset only supports a single network - for example, Bitcoin (BTC) only supports the Bitcoin network for this product currently - the Select Network screen is skipped.

In the example below, USDC was selected as the asset, which supports multiple networks. As a result, the next screen displays all available network options for the Shopper to choose from.

When the Shopper pays a transaction fee

  • Network selection: the fee rate is shown for each option, for example "Fee - 0.10%". For tiered fees, the SDK shows the range (for example "Fee - 0.20% - 0.40%") in a collapsed section the Shopper can expand to see the full tier breakdown.
  • Asset selection: a fee disclosure pop-up appears, and the Shopper must acknowledge it before continuing.

When the Merchant pays the fee, these screens are unchanged.

7c. Payment pending

The Shopper is now presented with the information to successfully make the payment:

  • Conversion rate
  • Payment amount
  • Payment expiration time
  • QR code and address

The expectation is that the Shopper, with relative urgency, takes the following steps:

If the Shopper is paying from their mobile phone

  1. Copies address
  2. Navigates to their preferred exchange or wallet (ie, Coinbase Exchange or Metamask wallet)
  3. Selects the same Asset they chose on the zerohash SDK
  4. Selects the same Network they chose on the zerohash SDK
  5. Enters the exact amount that was displayed on the Payment Pending screen, including any applicable fees
  6. Initiate the transaction

If the Shopper is paying from their computer (web)

  1. Navigates to their preferred exchange or wallet (ie, Coinbase Exchange or Metamask wallet)
  2. Selects the same Asset they chose on the zerohash SDK
  3. When asked to enter the address, selects the "scan QR code" option
  4. Point your device’s camera at the QR code displayed on your computer screen, ensuring it’s centered and clearly visible
  5. Selects the same Network they chose on the zerohash SDK
  6. Enters the exact amount that was displayed on the Payment Pending screen, including any applicable fees
  7. Initiate the transaction

7d. Payment Successful

If the Shopper sends at least the displayed amount of the correct crypto or stablecoin, using the specified asset and network, the SDK will automatically transition to the next screen:

When the Shopper pays a transaction fee, the success screen shows the total amount received (purchase amount + fee), followed by "You paid {amount} {asset}" and "Transaction fee ${fee}". The transaction fee is also broken out separately on this screen.

The failure screens are unchanged. They always reference the full amount the Shopper sent.

Successful Payment (exact amount)

Once a successful payment is received for the exact amount, we'll send a webhook to you. When fees are enabled, the payload includes fee fields. This example shows a 100 bps flat fee paid by the Shopper on a $100 purchase:

{
  "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",
  "deposit_fee_bps": 100,
  "deposit_fee_notional": "1.00",
  "fee_payor": "SHOPP1"
}

quantity and notional reflect what the Shopper sent. The net amount settled to the Merchant or Platform is notional − deposit_fee_notional. See the Payins API Integration Guide for the full list of fee fields, including fee_tier_breakdown for tiered fees.

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,
  "reason": "over payment",
  "reference_id": "04918aef-41d1-4dfb-82b8-2fdc232a8d88"
}

7d. Payment Unsuccessful

There are a few scenarios that will lead a failed payment which will be reflected on the SDK UI:


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,
  "reason": "under payment",
  "reference_id": "04918aef-41d1-4dfb-82b8-2fdc232a8d88"
}

Successful Payment (depeg)

If a stablecoin becomes depegged, to mitigate zerohahs'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,
  "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,
  "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,
  "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,
  "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,
  "reason": "deposit currency does not match the expected currency",
  "reference_id": "04918aef-41d1-4dfb-82b8-2fdc232a8d88"
}

8. Query payments

You can query our REST endpoint GET /pay/transactions to retroactively view payment details. When fees are enabled, each transaction includes the same fee fields as the webhook. See Query payments in the Payins API Integration Guide for query parameters and a sample response.


9. Settlement

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


10. 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?