Overview

zerohash uses a tiered diligence model for shoppers. The data required to onboard a shopper scale with transaction size and type, as well as aggregate spend. Merchants are responsible for collecting and submitting shopper data via the API (Self Serve onboarding), or may use the zerohash SDK to collect it on their behalf (zerohash Managed onboarding).

Every shopper, regardless of tier or the transaction type, must agree to the zerohash Payment Sender Terms before transacting.

Creating a Shopper

Use POST /participants/customers/new to create a new shopper. Set the onboarding_profile attribute to shopper to distinguish this participant from a standard participant.

Sample Request

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

Shoppers with onboarding_profile = shopper 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.

Updating a Shopper

Use PATCH /participants/customers/{participant_code} to add or update fields on an existing shopper record. This is how merchants progressively collect data as a shopper's transaction activity moves them into higher tiers.

Shopper Statuses

Status	Description
`submitted`	The shopper has been submitted by the merchant.
`approved`	The shopper has been approved and may transact.
`pending_approval`	The shopper has been flagged for potential sanctions review. Manual review by the zerohash compliance team is required.
`rejected`	Terminal state. The shopper is rejected.

Tier Requirements by Transaction Type

The fields required on a Shopper Participant vary by transaction type. Transaction type (Perishable vs Non-Transferable vs Transferable) is determined by the Platform's (or Merchant's) MCC code. The sections below describe what must be present on the shopper record before a transaction at each tier can be processed.

Example: If a Shopper’s total payment volume exceeds $50,000 within a 24-hour period, you must meet Tier 3 requirements before any further payments can be processed.

See more detail on permitted jurisdictions here.

Perishables

Perishable goods and services (e.g. items consumed at point-of-sale like food or transit) have a single tier with minimal diligence requirements and a $50 daily spend limit.

Tier 1: Perishables

Required fields:

phone_number OR email

Spend limits: $50/day

Example: create a shopper for a perishable transaction using POST /participants/customers/new

{
  "onboarding_profile": "shopper",
  "email": "+13125550100"
}

Non-Transferables

Non-Transferable goods and services (e.g. haircuts, airline flights, or store credit that cannot be withdrawn or transferred off-platform) follow a four-tier model. Each tier unlocks higher value transactions for Non-Transferable goods and services.

Tier 1: Non-Transferables

Transaction size: $0 < purchase amount < $1,000

Lifetime Spend: ≤ $30,000

Required fields:

phone_number OR email
first_name
last_name
address_one
city
zip
jurisdiction_code
date_of_birth

Tier 2: Non-Transferables

Transaction size: $1,000 ≤ purchase amount < $50,000

Lifetime Spend: ≤ $150,000

All Tier 1 fields, plus:

tax_id
id_number
id_number_type
liveness_check

Document submission required: Yes. Submit corresponding IDV documents via POST /participants/documents/.

Tier 3: Non-Transferables

Transaction size: $50,000 ≤ purchase amount < $500,000

Lifetime Spend: ≤ $150,000

All Tier 2 fields, plus:

source_of_funds
employment_status
industry

Document submission required: Yes. Submit corresponding IDV documents via POST /participants/documents/.

Tier 4: Non-Transferables

Transaction size: $500,000 ≤ purchase amount

Lifetime Spend: >= $500,000

All Tier 3 fields. Additionally, the following supporting documents must be submitted via POST /participants/documents/:

Document Type	`document_type` Value
Source of funds documentation	`source_of_funds_for_purchase`
Proof of employment status	`proof_of_employment_status`
Proof of industry	`proof_of_industry`
Any additional relevant purchase documentation (e.g. bill of sale)	`miscellaneous`

Spend limits: No limit. Lifetime spend resets after a tier 4 transaction is manually approved.
Manual approval of transaction: Always required — every Tier 4 transaction must be manually approved by zerohash before it is processed. When a shopper's lifetime spend reaches $500,000 or more, manual approval is required for that transaction.

Examples:

A returning shopper has spent $490,000 via zerohash payins over 5 years. Today, the shopper initiates a transaction that is $20, bringing that transaction to the Tier 4 threshold.
A net new shopper has $0 in lifetime spend, and is onboarding to initiate a first time transaction of $750,000. This transaction will require Tier 4 diligence.

Transferables

Transferable goods and services (e.g. collectors items, watches, retail) follow the same four-tier structure as Non-Transferables, with identical field requirements and minor variation in spend limits.

Tier 1: Transferables

Transaction size: $0 < purchase amount < $2,100

Lifetime Spend: ≤ $30,000

Required fields:

phone_number OR email
first_name
last_name
address_one
city
zip
jurisdiction_code
date_of_birth

Tier 2: Transferables

Transaction size: $2,100 ≤ purchase amount < $50,000

Lifetime Spend: ≤ $150,000

All Tier 1 fields, plus:

tax_id
id_number
id_number_type
liveness_check

Document submission required: Yes. Submit corresponding IDV documents via POST /participants/documents/.

Tier 3: Transferables

Transaction size: $50,000 ≤ purchase amount < $500,000

Lifetime Spend: ≤ $150,000

All Tier 2 fields, plus:

source_of_funds
employment_status
industry

Document submission required: Yes. Submit corresponding IDV documents via POST /participants/documents/.

Tier 4: Transferables

Transaction size: $500,000 ≤ purchase amount

Lifetime Spend: >= $500,000

All Tier 3 fields. Additionally, the following supporting documents must be submitted via POST /participants/documents/:

Document Type	`document_type` Value
Source of funds documentation	`source_of_funds_for_purchase`
Proof of employment status	`proof_of_employment_status`
Proof of industry	`proof_of_industry`
Any additional relevant purchase documentation (e.g. bill of sale)	`miscellaneous`

Examples:

A returning shopper has spent $490,000 via zerohash payins over 5 years. Today, the shopper initiates a transaction that is $20, bringing that transaction to the Tier 4 threshold.
A net new shopper has $0 in lifetime spend, and is onboarding to initiate a first time transaction of $750,000. This transaction will require Tier 4 diligence.

Error Handling (Self Serve Shopper Onboarding)

Insufficient Shopper Diligence (409)
Returned by POST /pay/rfq or at invocation of the Payins SDK when a shopper does not yet have the data required to transact at the requested tier.

Sample Response:

{
  "error": "Shopper diligence requirements for this transaction are not met",
  "missing_requirements": [
    "first_name",
    "last_name",
    "address_one",
    "zip",
    "city",
    "jurisdiction_code",
    "email_or_phone_number",
    "date_of_birth"
  ]
}

Use the missing_requirements array to determine which fields need to be collected and submitted via PATCH /participants/customers/{participant_code} before retrying the transaction.

Unsupported Jurisdiction (422)
Returned by POST /pay/rfq or at invocation of the Payins SDK when the shopper's jurisdiction is not supported for the requested transaction type.

Sample Response:

{
  "error": "Shopper jurisdiction not supported for this transaction"
}

Daily Spend Limit Reached (422)
Returned by POST /pay/rfq or at invocation of the Payins SDK when the shopper has hit their daily spend limit for Perishables transactions.

Sample Response:

{
  "error": "Shopper's Daily Spend Limit for this type of transaction have been hit."
}

There is only one Tier available for Perishables transactions with a daily maximum spend of $50.

Error Handling (zerohash Managed Shopper Onboarding)

When a transaction is initiated by POST /pay/rfq or at invocation of the Payins SDK, if the Platform is on zerohash Managed Shopper Onboarding, the onboarding SDK will dynamically render to collect missing requirements.

Unsupported Jurisdiction (422)
Returned by POST /pay/rfq or at invocation of the Payins SDK when the shopper's jurisdiction is not supported for the requested transaction type.

Sample Response:

{
  "error": "Shopper jurisdiction not supported for this transaction"
}

Daily Spend Limit Reached (422)
Returned by POST /pay/rfq or at invocation of the Payins SDK when the shopper has hit their daily spend limit for Perishables transactions.

Sample Response:

{
  "error": "Shopper's Daily Spend Limit for this type of transaction have been hit."
}

There is only one Tier available for Perishables transactions with a daily maximum spend of $50.