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
| Term | Definition |
|---|---|
| Platform | The company that is under contract with zerohash and integrates directly with zerohash's APIs or SDKs. |
| Merchant | A 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. |
| Shopper | The 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.
| Step | API or SDK? | Notes |
|---|---|---|
| Merchant onboarding | API | |
| Shopper onboarding | API | |
| Shopper accepts zerohash t's and c's | SDK | This is the first page on the SDK a first-time Shopper will see |
| Shopper makes payment | SDK | The 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 refund | API | |
| Initiate return | API |
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").
| Setting | Options |
|---|---|
| Fee type | Flat: 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 floor | The minimum fee charged per transaction, in USD. |
| Fee payor | Shopper or Merchant |
| Scope | A Platform-wide default, or a per-Merchant configuration. A Merchant configuration overrides the Platform default for that Merchant. |
| Scenario | Shopper sends | Settlement |
|---|---|---|
| Platform is the Merchant, Shopper pays fee | Purchase amount + fee | Fee → Platform pay_transaction_feesRemainder → Platform pay |
| Platform has many Merchants, Shopper pays fee | Purchase amount + fee | Fee → Platform pay_transaction_feesPurchase amount → Merchant pay |
| Platform has many Merchants, Merchant pays fee | Purchase amount | Fee → Platform pay_transaction_feesPurchase amount less fee → Merchant pay |
What the Shopper seesShopper 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 toThis 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:
| Account | Description | Technical Details |
|---|---|---|
| Settlement Account | The fiat account that contains the balance of successful payments |
|
| Refund Float Account | The 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 |
|
| Error Account | The fiat account that accumulates due to error scenarios (over payment, under payment, incorrect asset or network, late payment |
|
| Transaction Fees Account | The fiat account that collects Payins transaction fees charged by the Platform. Only used when fees are enabled. See "Transaction Fees" above |
|
7. Initiate Payment
Now, let's move onto money movement. Begin by requesting an access token specifying:
| Field | Description | Example Value | Required? |
|---|---|---|---|
participant_code | The 6-digit alpha numeric code associated with the Shopper that is looking to pay (the response of the original POST /participants/customers/new call) | SHOPP1 | Y |
permissions | The 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_currency | 100 | Y |
denominated_currency(part of the payment_details object) | The fiat or crypto currency in which the purchase amount is priced | USD | Y |
reference_id | Platform-dictated reference id that is tied to any successful payment | 0bd7f7f0-cf26-495f-b2df-e8afe8481ba3 | N |
merchant_participant_code | The 6-digit alpha numeric code associated with the Merchant or Platform that is receiving payment | MERCH1 | N |
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 feesAlways 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
- Copies address
- Navigates to their preferred exchange or wallet (ie, Coinbase Exchange or Metamask wallet)
- Selects the same Asset they chose on the zerohash SDK
- Selects the same Network they chose on the zerohash SDK
- Enters the exact amount that was displayed on the Payment Pending screen, including any applicable fees
- Initiate the transaction
If the Shopper is paying from their computer (web)
- Navigates to their preferred exchange or wallet (ie, Coinbase Exchange or Metamask wallet)
- Selects the same Asset they chose on the zerohash SDK
- When asked to enter the address, selects the "scan QR code" option
- Point your device’s camera at the QR code displayed on your computer screen, ensuring it’s centered and clearly visible
- Selects the same Network they chose on the zerohash SDK
- Enters the exact amount that was displayed on the Payment Pending screen, including any applicable fees
- 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 scenario | Expected remediation steps |
|---|---|
| Under payment | Shopper to contact Platform → Platform to facilitate a withdraw via POST /payments to Shopper's wallet |
| Depeg | Shopper to contact Platform → Platform to contact zerohash via Slack or Email to facilitate withdrawals back to the Shopper manually |
| Above max threshold | Shopper to contact Platform → Platform to contact zerohash via Slack or Email to facilitate withdrawals back to the Shopper manually |
| Quarantine | Shopper 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 payment | Shopper to contact Platform → Platform to facilitate a withdraw via POST /payments to Shopper's wallet |
| Wrong asset or network | Shopper 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.
Updated 3 days ago