--- updatedAt: 2026-05-01T14:47:55.000Z agentTools: projectIndex: https://docs.zerohash.com/llms.txt --- # List payin transactions Retrieves a paginated list of pay transactions for the authenticated platform. Results can be filtered by participant, asset, deposit status, and timestamps. Each deposit also emits a `crypto_pay_status_changed` webhook when it settles or fails. **Note:** Some filtering capabilities may not be available for all platforms. Contact support if you need access to additional filters. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "zerohash API", "description": "\n### Authentication\n\nzerohash Uses HMAC SHA-256 verification to ensure the authenticity of API requests, follow instructions by link [https://docs.zerohash.com/reference/api-authentication](https://docs.zerohash.com/reference/api-authentication)\n\nDownload zerohash OpenAPI Schema as JSON\n", "version": "1.7.0" }, "servers": [ { "url": "https://api.cert.zerohash.com", "description": "Certification API server" } ], "x-readme": { "proxy-enabled": false }, "tags": [ { "name": "Payins", "description": "Power your checkout with crypto and stablecoins" } ], "paths": { "/pay/transactions": { "get": { "tags": [ "Payins" ], "summary": "List payin transactions", "description": "\nRetrieves a paginated list of pay transactions for the authenticated platform.\nResults can be filtered by participant, asset, deposit status, and timestamps.\nEach deposit also emits a `crypto_pay_status_changed` webhook when it settles or fails.\n\n**Note:** Some filtering capabilities may not be available for all platforms. Contact support if you need access to additional filters.\n ", "parameters": [ { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/Timestamp" }, { "name": "participant_code", "in": "query", "description": "Filter by participant code (6-character alphanumeric)", "required": false, "schema": { "type": "string" } }, { "name": "transaction_id", "in": "query", "description": "Filter by specific transaction ID (UUID format)", "required": false, "schema": { "type": "string" } }, { "name": "client_reference_id", "in": "query", "description": "Filter by client-provided reference ID. This filter may not be available for all platforms. Contact support if you need access.", "required": false, "schema": { "type": "string" } }, { "name": "pay_asset", "in": "query", "description": "Filter by the underlying crypto asset (e.g., BTC, ETH, USDC)", "required": false, "schema": { "type": "string" } }, { "name": "deposit_address", "in": "query", "description": "Filter by the deposit address provided by zerohash for this payment.", "required": false, "schema": { "type": "string" } }, { "name": "success", "in": "query", "description": "Filters transactions by successful status. This is a boolean field, please specify either `true` or `false`", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "page", "in": "query", "description": "Page number (1-indexed, max 5 digits)", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, { "name": "page_size", "in": "query", "description": "The number of results returned per page, with a maximum of 50 transactions per page", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, { "name": "deposit_timestamp_gte", "in": "query", "description": "Deposit timestamp greater than or equal to this value (inclusive). Unix milliseconds (13-19 digits). This filter may not be available for all platforms. Contact support if you need access.", "required": false, "schema": { "type": "string" } }, { "name": "deposit_timestamp_gt", "in": "query", "description": "Deposit timestamp strictly greater than this value (exclusive). Unix milliseconds (13-19 digits). This filter may not be available for all platforms. Contact support if you need access.", "required": false, "schema": { "type": "string" } }, { "name": "deposit_timestamp_lt", "in": "query", "description": "Deposit timestamp strictly less than this value (exclusive). Unix milliseconds (13-19 digits). This filter may not be available for all platforms. Contact support if you need access.", "required": false, "schema": { "type": "string" } }, { "name": "deposit_timestamp_lte", "in": "query", "description": "Deposit timestamp less than or equal to this value (inclusive). Unix milliseconds (13-19 digits). This filter may not be available for all platforms. Contact support if you need access.", "required": false, "schema": { "type": "string" } }, { "name": "merchant_participant_code", "in": "query", "description": "Filter by merchant participant code.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of pay transactions with pagination metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPayTransactionsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Code400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Code403" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Code404" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Code500" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Code503" } } } } } } } }, "security": [ { "apiKey": [], "apiPassphrase": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "description": "Your API public key. See the [Authentication guide](https://docs.zerohash.com/reference/api-authentication) for how to obtain keys.", "in": "header", "name": "X-SCX-API-KEY" }, "apiPassphrase": { "type": "apiKey", "description": "The passphrase associated with your API key, set when the key was created.", "in": "header", "name": "X-SCX-PASSPHRASE" } }, "parameters": { "Signature": { "name": "X-SCX-SIGNED", "in": "header", "description": "HMAC-SHA256 signature of the request, base64-encoded. See the [Authentication guide](https://docs.zerohash.com/reference/api-authentication) for the exact signing formula.", "required": true, "schema": { "type": "string" } }, "Timestamp": { "name": "X-SCX-TIMESTAMP", "in": "header", "description": "Current Unix timestamp in seconds. Must be within 60 seconds of server time or the request is rejected.", "required": true, "schema": { "type": "string", "example": "1678901234" } } }, "schemas": { "Code400": { "type": "object", "description": "Request was rejected by validation or a downstream service. `errors` is an array of human-readable messages; each entry describes a single validation failure or business-rule violation.", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "string" }, "example": [ "body/amount must be >= 0", "body/asset is required" ] } } }, "Code403": { "type": "object", "description": "Authentication or authorization failed. `error` is always `true`; `message` explains which check failed (missing API key, bad signature, insufficient permission, etc.).", "required": [ "error", "message" ], "properties": { "error": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "This api key does not have write permission to this endpoint" } } }, "Code404": { "type": "object", "description": "The requested resource does not exist or is not visible to the caller.", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Not Found" } } }, "Code500": { "type": "object", "description": "An unexpected error occurred on the server. The request can be retried after a short delay, but the same inputs may reproduce the error.", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Internal Server Error" } } }, "Code503": { "type": "object", "description": "A downstream dependency was unavailable, timed out, or returned a retryable error. Safe to retry; the response carries a `zh-allow-retry: true` header.", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Service Unavailable" } } }, "PayTransaction": { "type": "object", "properties": { "participant_code": { "type": "string", "description": "The shopper participant code.", "example": "ABCDEF" }, "pay_asset": { "type": "string", "description": "Cryptocurrency asset being paid with (e.g., BTC, ETH, USDC).", "example": "BTC" }, "rate": { "type": "string", "description": "Conversion rate applied at execution time.", "example": "65658.42" }, "quoted_currency": { "type": "string", "description": "Fiat currency for the payment.", "example": "USD" }, "source_address": { "type": "string", "description": "Sender's wallet address that originated the deposit.", "example": "0xA32A6aA6a3B87b49BeaB01393e2020C3C191CD61" }, "deposit_address": { "type": "string", "description": "Wallet address where the crypto was sent.", "example": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh" }, "quantity": { "type": "string", "description": "Crypto quantity deposited.", "example": "0.00152307" }, "notional": { "type": "string", "description": "Fiat value of the deposit in `quoted_currency`.", "example": "100.00" }, "success": { "type": "boolean", "description": "Whether the payment completed successfully.", "example": true }, "status_reason": { "type": "string", "description": "Human-readable failure reason. Empty string if successful.", "example": "" }, "status_reason_code": { "type": "string", "description": "Machine-readable code describing the outcome of the payment. Examples: `DEPOSIT_PROCESSED`, `AMOUNT_ABOVE_MAXIMUM`, `AMOUNT_BELOW_MINIMUM`.", "example": "AMOUNT_ABOVE_MAXIMUM" }, "fund_timestamp": { "type": "number", "description": "Unix timestamp in milliseconds indicating when the payment quote was created.", "example": 1712756400000 }, "deposit_timestamp": { "type": "number", "description": "Unix timestamp in milliseconds indicating when the blockchain deposit was detected.", "example": 1712756700000 }, "transaction_id": { "type": "string", "description": "On-chain transaction identifier associated with the deposit.", "example": "0x408482348dcb0e0331a9148d50f8c76db08138f63fb1586fcfc45200a91ccc5f" }, "account_label": { "type": "string", "description": "The account label that received the payment. Defaults to `pay` for pay transactions.", "example": "pay" }, "fund_id": { "type": "string", "format": "uuid", "description": "zerohash-generated unique identifier for this payment event.", "example": "29e6d7b8-d604-4212-86ee-998fef35505e" }, "is_first_deposit": { "type": "boolean", "description": "Indicates whether this was the participant's first deposit (used for first-deposit fee treatment).", "example": false }, "raw_fee_bps": { "type": "string", "description": "Initial fee rate expressed in basis points.", "example": "50" }, "deposit_fee_bps": { "type": "string", "description": "Effective fee rate in basis points that was actually applied after any minimum floors were considered.", "example": "50" }, "raw_fee_notional": { "type": "string", "description": "Initial fee amount calculated directly from `raw_fee_bps`, in `quoted_currency`.", "example": "0.50" }, "deposit_fee_notional": { "type": "string", "description": "Final fee amount actually charged to the participant, in `quoted_currency`.", "example": "0.50" }, "deposited_asset": { "type": "string", "description": "Actual asset deposited on-chain. May differ from `pay_asset` when cross-chain fallback occurred.", "example": "BTC" }, "reference_id": { "type": "string", "description": "The client-provided reference identifier for this payment, or empty string if none was supplied.", "example": "order-12345" }, "source": { "$ref": "#/components/schemas/PayTransactionSource" }, "deposit_fee_type": { "type": "string", "description": "The fee model applied to this transaction.", "enum": [ "flat", "tiered" ], "example": "flat" }, "fee_tier_breakdown": { "type": "array", "description": "Breakdown of how the fee was calculated across tiers. Only present when `deposit_fee_type` is `tiered`.", "items": { "$ref": "#/components/schemas/PayFeeTierBreakdown" } }, "merchant_participant_code": { "type": "string", "description": "The merchant participant code associated with this payment. Only present when a merchant is linked to the transaction.", "example": "MERCH01" } } }, "PayTransactionSource": { "type": "object", "description": "Source of the auth transaction. Only present if Auth Embedded is enabled for the platform.", "properties": { "type": { "type": "string", "description": "Type of transaction source.", "enum": [ "CUSTODIAL", "NON_CUSTODIAL", "MANUAL" ], "example": "CUSTODIAL" }, "integration": { "type": "string", "description": "Integration identifier (if applicable).", "example": "coinbase" } } }, "PayFeeTierBreakdown": { "type": "object", "description": "Breakdown of how the fee was calculated across tiers.", "properties": { "tier": { "type": "number", "description": "The tier number (1-based).", "example": 1 }, "amount_in_tier": { "type": "string", "description": "The deposit amount that fell into this tier.", "example": "100.00" }, "fee_bps": { "type": "string", "description": "The fee rate in basis points applied for this tier.", "example": "40" }, "fee_amount": { "type": "string", "description": "The fee amount calculated for this tier.", "example": "0.40" } } }, "GetPayTransactionsResponse": { "type": "object", "properties": { "message": { "type": "array", "description": "Array of pay transactions", "items": { "$ref": "#/components/schemas/PayTransaction" } }, "page": { "type": "integer", "format": "int32", "description": "Current page number (1-indexed)", "example": 1 }, "page_size": { "type": "integer", "format": "int32", "description": "Number of items per page (capped at 50)", "example": 50 }, "total_pages": { "type": "integer", "format": "int32", "description": "Total number of pages available", "example": 1 } } } } } } ```