{"success":true,"data":{"schemaVersion":1,"contentType":"documentation","activeVersionCode":"v1.0.0","versions":[{"versionCode":"v1.0.0","versionLabel":"v1.0.0","isDefault":true,"publishedAt":"2026-05-29T17:29:40.660Z","updatedAt":"2026-07-09T06:09:39.486Z"}],"sections":[{"section":"Start","pages":[{"slug":"start/overview","title":"Overview","description":"Start with the basics of how Stafiel works.","navOrder":100,"searchText":"start overview Overview Start with the basics of how Stafiel works. Start Overview Stafiel helps merchants accept USDT and USDC payments through hosted checkout, embedded checkout experiences with QR-based payment details, and payment APIs. It is designed for merchants that want stablecoin payment collection without asking Stafiel to hold their merchant wallet private keys. What Stafiel Does Stafiel provides the payment layer between your checkout flow and supported blockchain payment rails. You create a checkout, show the customer a payment experience, and track the order as the payment is detected, confirmed, settled, or marked as an exception. Merchants can use Stafiel to: Create checkout sessions for USDT or USDC payments. Send customers to a hosted checkout page. Embed payment experiences with the checkout snippet or widget. Let customers pay by scanning a QR code or copying the payment address. Track order, payment, settlement, invoice, receipt, refund, and event status. Who It Is For Stafiel is built for merchants, especially online businesses, that want to add stablecoin checkout to an existing sales flow. It can support direct checkout links, embedded payment areas, API-driven checkout creation, and operational workflows in the Merchant Dashboard. The product is useful when your team needs: A stablecoin payment experience that can fit into an existing checkout. Clear order status instead of manually checking blockchain explorers. A way to separate testing activity from real payment activity. Merchant-controlled receiving wallets. Wallet Boundary Stafiel does not ask for your merchant wallet private keys. Your merchant wallet configuration determines where supported payment flows settle. Supported chains use contracts or on-chain programs to enforce payment and settlement behavior, but your merchant wallet remains your responsibility. For operational details, see Wallet Settings and Security and Wallet Boundary . Where To Go Next Start with Quickstart to create your first checkout. Review Supported Assets and Networks for supported tokens, networks, and checkout payment options. Read Mainnet vs Testnet to understand how Stafiel provides testnet as a sandbox for integration and payment testing.","section":"Start"},{"slug":"start/quickstart","title":"Quickstart","description":"Create your first checkout with Stafiel.","navOrder":110,"searchText":"start quickstart Quickstart Create your first checkout with Stafiel. Start Quickstart Use this guide to create your first checkout through the simplest path in the Merchant Dashboard. It avoids API setup so you can confirm the core payment flow first. Before You Start You need: A Google or GitHub account for signing in to Stafiel. A browser extension crypto wallet for the network you plan to enable, used to verify your merchant settlement wallet address. An MFA device, such as a smartphone with an authenticator app installed. Use a wallet that supports the network you plan to enable, such as an EVM-compatible, Solana, or Tron wallet. Centralized exchange deposit addresses are not supported as merchant settlement wallets. 1. Sign In And Create A Merchant After signing in to the Stafiel Merchant Dashboard with the Google or GitHub account you want to use, create a merchant for the business or storefront that will accept payments. For more detail, see Dashboard Navigation and Account and MFA . 2. Set Up Merchant Complete the required merchant setup steps: Enable MFA for your account. Connect the wallet that will receive merchant funds for settlement. Enable at least one supported token and network for checkout. For more detail, see Wallet Settings . 3. Create A Checkout Session Create a checkout session from the Merchant Dashboard. The session represents one payment attempt for a specific amount, token, network, and merchant. For more detail, see Dashboard Navigation . 4. Verify The Checkout Session Open the hosted checkout page and confirm that it shows the expected amount, token, network, payment address or QR code, and payment status. If you want to complete the payment yourself, use a payer wallet that matches the selected token and network. You can check the payment status on the hosted checkout page or in the Merchant Dashboard. For more detail, see Orders . Next Steps Read Mainnet vs Testnet to understand how sandbox testing stays separate from real payments. Review Checkout Sessions to understand what a checkout represents and how to choose the customer-facing surface. Use Go-Live Checklist before accepting real customer payments.","section":"Start"},{"slug":"start/supported-assets-and-networks","title":"Supported Assets and Networks","description":"Review the tokens and networks Stafiel supports.","navOrder":120,"searchText":"start supported assets and networks Supported Assets and Networks Review the tokens and networks Stafiel supports. Start Supported Assets and Networks This page lists the public network names, chain IDs, token standards, and token contract or mint addresses used by Stafiel checkout. Supported Assets Stafiel checkout currently supports: USDT (Tether USD) USDC (USD Coin) Availability depends on network support and the merchant's enabled tokens and networks. Supported Networks The supported networks are listed below. Ethereum, Base, BNB Smart Chain, and Polygon are EVM-compatible networks. Network Chain ID Token Standard USDT USDC Ethereum 1 ERC20 0xdac17f958d2ee523a2206206994597c13d831ec7 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 BNB Smart Chain 56 BEP20 0x55d398326f99059ff775485246999027b3197955 0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d Base 8453 ERC20 Not supported 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 Polygon 137 ERC20 0xc2132d05d31c914a87c6611c10748aeb04b58e8f 0x3c499c542cef5e3811e1192ce70d8cc03d5c3359 Solana 101 SPL token Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v Tron 728126428 TRC20 TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t Not supported EVM addresses are token contract addresses. Solana addresses are SPL token mint addresses. Tron addresses are TRC20 contract addresses. Testnet Assets and Networks The testnet token entries below are mock tokens for integration and payment testing. For mode separation, see Mainnet vs Testnet . Network Chain ID Token Standard USDT (mock) USDC (mock) Ethereum Sepolia 11155111 ERC20 0xdCc868F9a7e7F8A14D0db1a3bD42c4d7e712C056 0x13E58CCaaE29942313A770C87dD3e3C82aE4f713 BNB Smart Chain Testnet 97 BEP20 0xbaB0F59Da37F84c622551E4c8Dc368B16847656e 0x3739CDB86c0F01243E60429365bE11D12363e855 Base Sepolia 84532 ERC20 Not supported 0xA20522a4523b7C318113F5a3a4Abd45f8ef975f9 Polygon Amoy 80002 ERC20 0x1FC44447F7Da0D4Ff640dAC8E76Bf3710999dAab 0x4Fa85E82062156E0f5cc461E08d034272C1b9ff1 Solana Devnet 103 SPL token H9S1iQctoUVktffkPSqqfzxfZsugxgSFV296gVEbCNFB A1nyNv8LH6wcvydBMCNMrWy5HeLAxLYN7KG7Cf9HW9zg Tron Nile 3448148188 TRC20 TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf Not supported Testnet Faucets Use the Testnet Faucet in the Merchant Dashboard to claim Stafiel mock USDT and USDC for supported EVM testnets and Solana Devnet. These testnet tokens are intended for testing and experiencing the full payment, receiving, and settlement flow before going live on mainnet. Native Testnet Tokens Native testnet tokens are needed for network fees when test flows submit on-chain transactions. Obtain the required gas token from the faucet for the target testnet before testing.","section":"Start"},{"slug":"start/mainnet-vs-testnet","title":"Mainnet vs Testnet","description":"Learn how mainnet and testnet stay separate.","navOrder":130,"searchText":"start mainnet vs testnet Mainnet vs Testnet Learn how mainnet and testnet stay separate. Start Mainnet vs Testnet Stafiel keeps mainnet and testnet activity separate. This page explains the difference so your team can decide when to use each mode. Mainnet Mainnet is for real payments. A mainnet checkout can involve real USDT or USDC, real customer orders, real wallet settlement, live webhook delivery, production reporting, and merchant records that may be used for business operations. Merchants may choose to use mainnet when their wallet, payment surfaces, customer notices, event handling, and support workflow are ready for real payments. Testnet Testnet is for testing. It lets your team create checkout sessions, complete test payments, inspect order states, and validate event handling without treating the activity as real customer payment activity. Testnet USDT and USDC are mock tokens. They are not real USDT or USDC and should not be used for accounting, reconciliation, settlement, customer fulfillment, tax records, or production support decisions. What Stays Separate Mainnet and testnet use separate merchant and payment records, including: Merchant profiles, merchant IDs, and merchant settings. API keys and API client mode. Wallet configuration and chain or token enablement. Orders and checkout sessions. Payment, refund, settlement, and contract or on-chain program records. Webhook endpoints, signing secrets, event IDs, and delivery logs. Customer-facing order references. Order reports, exports, invoices, receipts, and settlement records. Treat testnet order IDs, payment records, and webhook events as testing data. What May Be Shared You may use the same Stafiel sign-in account and MFA setup to access both modes. This separation applies to merchant and payment activity, not to creating separate Stafiel user accounts. Mainnet-Only Features Some account-level pages in the Merchant Dashboard, such as plan or billing information, may be available only in mainnet. Testnet is intended for integration and payment-flow testing. Mainnet Readiness Before accepting real payments, it is usually useful to confirm that: You are using the live merchant profile intended for the business. The live merchant wallet is configured and approved for the networks you plan to use. Live API keys are stored on your backend, not in browser code. Live chain labels are used in checkout creation. Live webhook configuration is separate from testnet. Your team can identify Underpaid, Overpaid, Expired, refunded, and Settled orders. For the full operational checklist, see Go-Live Checklist .","section":"Start"}]},{"section":"Accept Payments","pages":[{"slug":"accept-payments/checkout-sessions","title":"Checkout Sessions","description":"Learn how checkout sessions create payment requests.","navOrder":200,"searchText":"accept payments checkout sessions Checkout Sessions Learn how checkout sessions create payment requests. Accept Payments Checkout Sessions A checkout session is the payment request for one merchant order, invoice, or internal reference. It defines the amount, token, network, checkout display, and return path for that payment. Each checkout session maps to one payment request in the merchant system. Before Creating A Checkout Session Before creating a checkout session, set the payment details for the request: Information Requirement What it means Payment amount Required The USDT or USDC amount shown to the customer. Token and network Required A supported USDT or USDC option from Supported Assets and Networks . Metadata Recommended Product name, description, quantity, order ID, invoice ID, booking ID, or customer reference. Return URL Recommended A metadata value that sends the customer back after completing or leaving checkout. Payment window Optional How long the checkout remains usable. If omitted, the default payment window applies. Only supported token and network combinations enabled for the merchant account should be offered to customers. Merchant order or invoice references help match payment status, settlement, invoice, receipt, refund, and support records later. Fixed After Creation After checkout session creation, its payment terms are fixed for that order. Later merchant setting changes apply only to future checkout sessions. Checkout Surfaces After creating a checkout session, choose how customers open it. Hosted Checkout (Redirect) Hosted checkout opens a Stafiel-hosted payment page as a separate browser page or tab. It is best for a complete payment page without building the payment screen inside the merchant site. Customers see the session amount, token, network, payment status, QR code, payment address, payment window, and checkout metadata such as product title, description, and quantity. Redirect: opens the hosted checkout page in a separate browser page or tab. Widget (Modal/Inline/Lite/Micro) Widget places Stafiel checkout inside the merchant site. It is best when customers should open checkout from the merchant page or keep checkout embedded inside that page. Widget modes use the same session amount, token, network, and payment window. Widget has four customer-facing modes: Modal: opens checkout in an overlay above the page. Inline: shows checkout in a larger embedded area inside the page layout. Lite: shows checkout in a compact embedded area. Micro: shows checkout in the smallest embedded area. Use either Checkout Snippet or Embedded Widget with any of these four modes. For checkout snippet and widget implementation details, see Widget Integration . How To Choose A Surface Choose based on where checkout should appear and how much control is needed: Need Recommended surface Why Separate browser page or tab Hosted checkout Use a complete Stafiel-hosted payment page. Fast setup inside the merchant site Checkout snippet Attach checkout to a button, link, or simple page element with fewer setup choices. More control inside the merchant site Embedded widget Use more layout and behavior options for inline areas, compact blocks, or custom storefront layouts. Checkout snippet and Embedded widget are two ways to add Widget checkout to a merchant site. Both can use Modal, Inline, Lite, or Micro mode with a similar checkout appearance and the same core checkout information; the difference is setup simplicity and page control, while the mode should fit the available page space and checkout flow. Next Steps For how customers complete a payment, see Payment Flow . To create sessions from the backend, see Checkout Sessions API .","section":"Accept Payments"},{"slug":"accept-payments/payment-flow","title":"Payment Flow","description":"Understand the customer-facing Stafiel payment flow.","navOrder":220,"searchText":"accept payments payment flow Payment Flow Understand the customer-facing Stafiel payment flow. Accept Payments Payment Flow The payment flow explains what customers see on the Stafiel payment page or widget and how they complete payment after a checkout session is created. 1. Pay From A Wallet The customer sees a checkout waiting for payment: Awaiting Payment: the checkout is open and waiting for payment. The customer can scan the QR code or copy the payment address into a mobile wallet, browser extension wallet, or centralized exchange. Payment must use the selected USDT or USDC token, selected network, and payment address shown on the page or widget. A changed amount, different token, wrong network, or address from another checkout can create a payment exception and may result in lost funds. Important: Customers should not send payment after the payment window expires. Late on-chain transfers are not credited to the order balance and do not enter the settlement flow. For the supported token and network list, see Supported Assets and Networks . For exchange-related refund limitations, see Refund Basics and Payment and Refund Risks . 2. Payment Detected Soon after payment is sent, the customer may see that payment activity has started: Payment Detected: Incoming payment activity appears. The final payment amount and order status are not confirmed yet. Some networks may skip this stage. 3. Payment Received The customer sees the received payment result after the payment receives initial on-chain confirmation. Timing varies by network: Fullpaid: the received amount matches the requested amount. Overpaid: the received amount is above the requested amount; the extra amount can be reviewed for refund once the after-sales window opens, when refunds are available on the selected network. Underpaid: the received amount is below the requested amount; the customer can send an additional payment to the same address during the payment window. Note: For Overpaid or Underpaid orders, the merchant decides the next step: fulfill, hold, review refund availability for the extra amount, request the missing amount during the payment window, or follow up with the customer. 4. Payment Confirmed This stage means the payment has reached the required block confirmation count. Customers do not need to go through this stage directly. It runs in the background and can be viewed in order details in the Merchant Dashboard. Payment Completion Confidence Stage Corresponding order status Completion confidence Customer impression Pay From A Wallet Awaiting Payment Not recorded yet The customer is sending or preparing to send payment. Payment Detected Awaiting Payment Seen on-chain The customer may see that payment activity has started. Payment Received Fullpaid, Overpaid, or Underpaid Amount recorded on-chain The customer sees that the payment has been received and recorded for the order. Payment Confirmed Fullpaid, Overpaid, or Underpaid Confirmed for fulfillment review This runs in the background and can be viewed in Merchant Dashboard order details. For lifecycle details, see Order Lifecycle and Payment Status . 5. Return To Merchant Site After payment is received, the customer can return to the merchant store, order page, invoice flow, or support path via the configured Return URL when it is set correctly.","section":"Accept Payments"},{"slug":"accept-payments/order-lifecycle-and-payment-status","title":"Order Lifecycle and Payment Status","description":"Understand the order lifecycle, payment statuses, and exceptions.","navOrder":230,"searchText":"accept payments order lifecycle and payment status Order Lifecycle and Payment Status Understand the order lifecycle, payment statuses, and exceptions. Accept Payments Order Lifecycle and Payment Status Order lifecycle shows each business stage of a checkout as it moves from an open payment request to an operational outcome. Order Lifecycle Most orders follow this sequence from checkout creation to settlement: Checkout session created: the payment request is ready for the customer to open. This is the start point of the timeline. See Checkout Sessions . Payment window: the checkout waits for payment, and the payment page or widget displays payment progress. Payment activity during this window determines whether the order is Fullpaid, Underpaid, or Overpaid. If no payment is recorded before the window closes, the order can expire. See Payment Flow . Payment setup: the order's on-chain setup is completed through smart contract or on-chain program deployment, with required KYT/AML and related compliance checks. This process is automatic and requires no merchant action. After-sales window: this window starts when payment setup is complete. Refund handling can branch into Partial Refunded or Full Refunded. See Refund Basics . Settlement processing: eligible paid orders move through settlement after the configured after-sales window. Settlement records are available for review. See Settlement Basics . Order Statuses Status Business meaning Awaiting Payment The checkout is open and waiting for the customer to pay. *Payment Detected Incoming payment activity is detected before the final payment result. Fullpaid The recorded payment matches the expected amount. Underpaid The customer sent less than the expected amount. Overpaid The customer sent more than the expected amount. *Payment Confirmed The payment has reached the required network confirmation threshold. Expired The payment window closed while the order was still Awaiting Payment. Settled The order has a recorded settlement. *Partial Refunded A partial refund has been recorded for the order. Full Refunded A full refund has been recorded for the order. Closed The order is closed and no longer acts as an active payment request. Compliance Hold Risk, abuse, security, or compliance controls hold the order for review. Notes: Payment Detected shows that payment activity has started before the final payment result is known. It may appear on the payment page, widget, or webhook events. Payment Confirmed shows that the payment reached the required network confirmations. It appears in Merchant Dashboard order details or webhook events. Partial Refunded shows that part of the payment has been refunded. It appears in Merchant Dashboard order list and order details. When the full payment has been refunded, the order status becomes Full Refunded. This table is a status reference, not the order sequence. For the customer-facing payment flow, see Payment Flow . Expired Orders Or Late Payments An order expires when the payment window closes while it is still Awaiting Payment. Partial payments become Underpaid, not Expired. Do not present an expired checkout as payable. If funds arrive late, review the order, payment records, and support context before deciding whether to fulfill, refund, or take further action. For payment-window guidance, see Payment Flow . For help with a late-payment case, contact Stafiel support . Compliance Hold An order enters Compliance Hold when KYT/AML, risk, abuse, security, or compliance review requires the order to be held. Do not treat a held order as ready for fulfillment, refund, or settlement until the hold is resolved. Where To Observe Status Order status is visible through the Merchant Dashboard , webhook events, or other payment notifications. For technical order fields, see Orders API . For notification delivery, see Webhooks and Events .","section":"Accept Payments"},{"slug":"accept-payments/settlement-basics","title":"Settlement Basics","description":"Understand how customer payments settle to merchant wallets.","navOrder":235,"searchText":"accept payments settlement basics Settlement Basics Understand how customer payments settle to merchant wallets. Accept Payments Settlement Basics Settlement is the step after payment and after-sales handling where eligible paid orders move toward the merchant settlement wallet. Settlement Destination Settlement destination means the merchant wallet and network used when an eligible order settles. Merchant Wallet Boundary Merchant wallet configuration sets the settlement destination. Stafiel does not ask for merchant wallet private keys or custody of the merchant wallet. Captured At Checkout Creation The settlement destination is captured when the checkout session is created. Later wallet configuration changes apply to future checkout sessions, not to existing orders. Network-Specific Settlement Settlement value is not aggregated across networks. Each eligible order settles on the network used by that order to the merchant wallet configured for that network. Normal Settlement Flow After an eligible paid order passes the configured after-sales window, settlement moves the merchant amount through the supported payment rail to the configured merchant wallet. There is no manual merchant claim or withdrawal step in the normal settlement flow. For wallet setup and security boundaries, see Wallet Settings and Security and Wallet Boundary . Platform Fee When a platform fee applies, it is handled as part of the same on-chain settlement transaction. Settlement records show the merchant amount and the platform fee amount separately, so the breakdown is clear. For fee concepts, see Fees and Plan Usage . For operational settlement review, see Settlement Review . For integration details, see Settlements API . Refund Impact Refunds during the after-sales window can change what later settles. A partial refund can leave a remaining amount for settlement. A full refund ends the payment value for that order instead of continuing to settlement. For refund rules, see Refund Basics . Network Differences Settlement behavior can vary by network. Timing, transaction format, transaction costs, and confirmation behavior may not look identical across supported payment rails. These differences do not change the settlement rule: each order settles on the network selected for that order. Settlement Completion Settlement completion means the order's settlement record shows a settled result. Before that, Merchant Dashboard may show the order as waiting for settlement or pending settlement verification. Settlement is not instant. It follows payment confirmation, the configured after-sales window, required KYT/AML and related compliance checks, network processing, and platform settlement processing.","section":"Accept Payments"},{"slug":"accept-payments/refund-basics","title":"Refund Basics","description":"Understand refund availability and original-route refunds.","navOrder":240,"searchText":"accept payments refund basics Refund Basics Understand refund availability and original-route refunds. Accept Payments Refund Basics Refund Basics explains when a Stafiel checkout can use a supported original-route refund based on the network, order state, configured after-sales window, refundable amount, and how the customer originally paid. Original-Route Refunds Supported refunds return value to the original on-chain payment source, not to a new payout address. In plain terms, the original payment source is the wallet address that sent the payment on-chain. This keeps the refund path aligned with the payment path for anti-abuse, AML, and operational traceability. Refunds are not a general-purpose payout tool. They are used to unwind a supported payment when the original payment source can receive returned value. After-Sales Window Merchant-initiated refunds use the configured after-sales window captured when the checkout session is created. Later merchant setting changes apply to future checkout sessions, not to existing orders. After the payment window ends, Stafiel completes payment setup automatically. The after-sales window opens when payment setup is complete. Refund availability still depends on network support, refundable amount, and whether a refund has already been recorded. Once the after-sales window closes, the order is no longer eligible for a merchant-initiated on-chain refund. For the larger order timeline, see Order Lifecycle and Payment Status . Refund Amount And Status The refund amount cannot exceed the payment value actually received for the order. For original-route refunds, each payment source can receive back no more than it paid. Note: A merchant-initiated refund can be performed only once for a checkout. A partial refund counts as that one merchant-initiated refund. After a partial refund, the remaining payment value determines the order status: Fullpaid when it matches the requested amount, Underpaid when it is below the requested amount, and Overpaid when it remains above the requested amount. The remaining value can continue through the normal downstream flow when the order is otherwise eligible. Merchant Dashboard may also show Partial Refunded to indicate that a partial refund was recorded. When the full payment has been refunded, the order becomes Full Refunded and no remaining payment value continues to settlement. For settlement impact, see Settlement Basics . Network Support Only supported networks can use Stafiel's on-chain refund flow. Refund capabilities differ by network and payment rail. The table below describes network-level support only; each refund still depends on order state, the after-sales window, refundable amount, and refund history. Network On-chain refund support Notes Ethereum Supported Original-route refunds can be used when the order is eligible. Base Supported Original-route refunds can be used when the order is eligible. BNB Chain Supported Original-route refunds can be used when the order is eligible. Polygon Supported Original-route refunds can be used when the order is eligible. Solana Supported Original-route refunds can be used when the order is eligible. Tron Not supported Stafiel's on-chain refund flow is not available on Tron. Businesses that accept Tron payments should account for that limitation in refund policy and customer support. Centralized Exchange And Custodial Wallet Risk If a customer pays from a centralized exchange withdrawal flow or some custodial wallet flows, the original on-chain source address is usually not controlled by the customer. An original-route refund returns value to that on-chain source, which may not return the value to the customer's account. These customer-side recovery cases are outside Stafiel's refund scope. For more detail, see Payment and Refund Risks . Merchant Policy The merchant remains responsible for refund approval, customer communication, refund policy, and handling cases where an on-chain refund is unavailable or where a centralized exchange or custodial wallet payment creates customer-side recovery issues. Note: Merchant-initiated on-chain refunds require the merchant to pay the applicable network transaction cost, such as a gas fee or transaction fee. For Merchant Dashboard steps, see Refund Operations . For integration refund status and history checks, see Refunds API . Platform-Initiated Refunds Stafiel may, where appropriate or required, perform a platform-initiated refund for legal, regulatory, sanctions, compliance, risk, security, dispute resolution, service integrity, or operational reasons.","section":"Accept Payments"}]},{"section":"Merchant Operations","pages":[{"slug":"merchant-operations/dashboard","title":"Dashboard Navigation","description":"Find where core Merchant Dashboard workflows live.","navOrder":300,"searchText":"merchant operations dashboard Dashboard Navigation Find where core Merchant Dashboard workflows live. Merchant Operations Dashboard Navigation This page maps the main Merchant Dashboard navigation to the workflows merchants use most often. Main Navigation Navigation item Use it to Dashboard Review key payment metrics, order status mix, and recent activity at a glance. Merchants Create merchants and configure wallets, chains, API keys, order defaults, webhooks, and return URLs. Orders Find checkout sessions, review Order Details, and export records. Statistics Compare order, amount, chain, token, weekly, and recent activity statistics. Settings Open Profile, Subscription Plan & Tiers, Configuration, or Network Mode. Check The Current Mode Confirm the selected mode before making changes. Mainnet is for real payments, while testnet is visually marked in the dashboard and works as a sandbox for setup and testing. Actions apply only to the selected mode, and merchant, wallet, API key, order, and payment data remain separate between the two modes. For the product-level differences, see Mainnet vs Testnet . Dashboard Summary The Dashboard is the landing view. Its Recent Activity panel shows only the last 7 days of account activity. Continue with Merchant Setup before accepting the first payment.","section":"Merchant Operations"},{"slug":"merchant-operations/merchant-setup","title":"Merchant Setup","description":"Prepare a merchant profile before accepting payments.","navOrder":310,"searchText":"merchant operations merchant setup Merchant Setup Prepare a merchant profile before accepting payments. Merchant Operations Merchant Setup Create a merchant to configure wallets and accept payments. Each merchant has its own profile, settings, orders, and mainnet or testnet records. Create A Merchant Open Merchants , then select Create Merchant . Field Requirement Purpose Merchant Name Required Internal merchant name used in Merchant Dashboard. Public Display Name Recommended Customer-facing name shown on payment pages, receipts, and invoices. Description Optional Internal description for identifying the merchant. Supported Chains Required Select the chains the merchant plans to use. Available options can depend on the current plan and mode. After creation, open the merchant to review its Merchant ID, current status, and setup tabs. Merchant ID The Merchant ID identifies the merchant in the selected mode. Use it when an integration, support request, or dashboard record needs a merchant reference. Mainnet and testnet Merchant IDs are separate. Confirm the current mode before copying an ID. Merchant Status The merchant card shows the current operational status: Status Meaning Configuration Required Required setup is not complete. Partial Active Some approved chains are ready to accept payments, while other selected chains still need setup or review. Active All approved chains for the merchant are ready to accept payments. Suspended New orders are disabled until the merchant is reactivated and its wallets and chains are verified again. Terminated The merchant is permanently unavailable. Merchant Details Setup Open a merchant to view Merchant Details . The tabs separate profile review, payment setup, and integration settings: Tab Use it to Basic Info Review or update the merchant name, public display name, description, and Merchant ID. API Key Management Create and revoke API keys for server-side API integration. Wallet Settings Connect and verify settlement wallet addresses for the required chains. Merchant Settings Set return URL rules, webhook delivery settings, order defaults, and status actions. Chains & Tokens Review enabled networks, approval status, token standard, supported tokens, and minimum order amount. Wallet settings are covered in Wallet Settings . API keys and webhooks are covered in API Keys and Authentication and Webhooks and Events . Basic Info Open Basic Info to update the merchant name, public display name, or description. The Merchant ID remains the stable identifier for integrations, support requests, and dashboard records. API Key Management Open Merchants > select merchant > API Key Management . API Key Management is available when the merchant status is Partial Active or Active . To create a key, select Create Key , enter a key name, and complete MFA when requested. Important: Save the full API key securely when it is created. It is shown only once, and later views show only a preview. Revoke a key when it is no longer used or may have been exposed. Revocation is immediate, and integrations using that key stop working. The allowed number of active keys varies by plan. Wallet Settings Wallet Settings connects the merchant settlement wallet address for each required chain. A verified wallet address is required before that chain can accept new orders for the merchant. For setup steps, verification rules, wallet address changes, and limitations, see Wallet Settings . Return URL Settings Open Merchants > select merchant > Merchant Settings > Return URL Settings to control where customers can return after paying on the Stafiel checkout page. Allowed Return Origins accepts exact HTTPS origins and supported wildcard patterns for subdomains. For example, https://*.example.com allows return URLs from subdomains such as https://shop.example.com . Allow all URLs allows return URLs supplied with checkout sessions without requiring a match against the allowed origins list. If Allow all URLs is off and no allowed origin is configured, checkout does not use the metadata.returnToUrl value. See Metadata Reserved Fields and Rules . Webhook Configuration Open Merchants > select merchant > Merchant Settings > Webhook Configuration to add the HTTPS endpoint that receives payment lifecycle notifications. When a webhook URL is saved for the first time, a signing secret is generated automatically. Use Test URL to check whether the HTTPS endpoint is reachable. This check does not send a webhook event. The secret signs webhook requests for verification. Rotating it replaces the current secret immediately, so update the receiving system at the same time. Order Defaults Open Merchants > select merchant > Merchant Settings > Order Defaults to set the default payment window and after-sales window for new checkout sessions. Setting What it controls Payment window How long a checkout session stays payable before it expires. This value can be changed when creating a checkout session. After-sales window How long the merchant can handle refunds before settlement. Merchant Dashboard shows the allowed range for each setting. Changes apply only to future checkout sessions. Existing orders keep their saved values. Merchant Status Actions Open Merchants > select merchant > Merchant Settings > Danger Zone to suspend, reactivate, or terminate a merchant. Suspend disables new orders. Existing orders continue using their recorded settlement data. All enabled-chain wallet bindings are revoked. Reactivation requires wallet reconnection, ownership verification, and review. Terminate permanently disables the merchant. All API keys are revoked. Termination is allowed only when no live orders remain. Note: Review the confirmation message before continuing. Termination cannot be undone.","section":"Merchant Operations"},{"slug":"merchant-operations/account-access","title":"Account and MFA","description":"Manage sign-in, account profile, and MFA controls.","navOrder":320,"searchText":"merchant operations account access Account and MFA Manage sign-in, account profile, and MFA controls. Merchant Operations Account and MFA Merchant Dashboard supports account sign-in through Google or GitHub. Use this page to understand the account profile and MFA controls. Account Profile Open Settings > Profile to review account information and MFA status. The Profile tab shows the User ID, account name, email address, and MFA status. Copy the User ID when support or an account-specific operation asks for it. Enable MFA Merchant Dashboard may ask for a fresh six-digit MFA code before sensitive operations. Select Enable MFA and complete the setup: Scan the QR code with an authenticator app, or enter the displayed setup key. Enter the six-digit authentication code. Save the backup code securely. Important: The backup code can be used for account recovery or MFA reset. Do not store it in shared notes, source code, or public issue trackers. Reset MFA Select Reset MFA from the Profile tab. Reset can require either: A current authenticator code The saved backup code After reset, bind a new authenticator device and save the new backup code. The previous backup code becomes invalid after reset or regeneration. Temporary cooldowns may apply after repeated or recovery-sensitive actions. For wallet-specific security boundaries, see Security and Wallet Boundary .","section":"Merchant Operations"},{"slug":"merchant-operations/wallet-settings","title":"Wallet Settings","description":"Configure the wallet addresses that receive merchant funds.","navOrder":330,"searchText":"merchant operations wallet settings Wallet Settings Configure the wallet addresses that receive merchant funds. Merchant Operations Wallet Settings Wallet Settings configures the self-custodial wallet addresses that receive settlement funds and shows whether each supported chain is ready for new checkout sessions. The merchant must control each wallet and be able to sign with it for ownership verification. Supported Wallet Types Merchant Dashboard uses one wallet address for each supported wallet type: Wallet type Used for EVM Ethereum, Base, Polygon, BNB Smart Chain, and other supported EVM-compatible chains. Solana Solana payments using supported SPL tokens. Tron Tron payments using supported TRC-20 tokens. Use self-custodial browser extension crypto wallets for wallet verification. A multi-chain wallet that supports EVM, Solana, and Tron, such as Binance Wallet or OKX Wallet, can cover all three wallet types. Alternatively, use separate wallets for the chains being enabled, such as MetaMask for EVM, Phantom for Solana, and TronLink for Tron. Connect And Verify A Wallet Address Connect and verify each settlement wallet in Wallet Settings : Open Merchants > select merchant > Wallet Settings . Choose the chain and start the wallet connection. Connect a supported browser extension crypto wallet. Review the wallet address shown in Merchant Dashboard. Sign the ownership verification message in the wallet. Important: The signature only verifies control of the wallet address. It does not authorize transactions or access to funds, approve token spending by a smart contract or on-chain program, trigger an on-chain transfer, or charge a network transaction fee. Stafiel does not request or store the merchant wallet private key. Wallet verification and wallet changes are sensitive operations and require MFA verification. See Account and MFA . Submit Wallet Address For Review And Check Chain Readiness After wallet ownership is verified: Select Submit for Review for that chain. The verified wallet address and merchant information undergo Know Your Wallet (KYW) screening, Anti-Money Laundering (AML) screening, and related compliance and risk checks. Wallet Settings shows PENDING REVIEW while review is in progress. After the wallet address is APPROVED , new checkout sessions can be created for that chain when it is activated and allowed by the current plan. A rejected review must be resolved and submitted again before that chain can be used for new checkout sessions. Activate Or Suspend A Chain EVM is enabled by default and cannot be suspended from Wallet Settings. Solana and Tron can be activated or suspended when allowed by the current plan. Suspending Solana or Tron prevents new checkout sessions from using that wallet type, revokes its current wallet address, and resets its approval status. Reactivation requires reconnecting the wallet, verifying ownership, and submitting the chain for review again. Existing orders retain the wallet and payment configuration saved when they were created. Change A Settlement Wallet A newly verified wallet applies to future checkout sessions. Existing orders keep the settlement wallet recorded when the checkout was created. After a wallet address is approved, binding a different address is subject to a wallet-change cooldown. Rebinding the same address does not require that cooldown. A changed address requires a new ownership signature and chain review. Important: Centralized exchange deposit addresses are not supported as merchant settlement wallets. For settlement behavior, see Settlement Basics . For the security model, see Security and Wallet Boundary .","section":"Merchant Operations"},{"slug":"merchant-operations/orders","title":"Orders","description":"Review and filter orders, create checkout sessions, and export records.","navOrder":340,"searchText":"merchant operations orders Orders Review and filter orders, create checkout sessions, and export records. Merchant Operations Orders Use Orders to review and filter orders, create checkout sessions, export records, and test API requests. Order List Switch between Card View for grouped orders and Table View for compact rows. Review key payment details and available actions in either view. A Partial Refunded marker can appear alongside the main order status. Available actions depend on the order data and selected view. Action Purpose Open Order Details Review the complete order record and available operations. Copy Order ID Copy the full order identifier. Copy Payment Address Copy the address assigned to the order. Open Explorer View the payment address on the relevant blockchain explorer. Open Payment Page Open the customer payment page. For status meanings, see Order Lifecycle and Payment Status . Filter And Export Orders Filter and sort orders to narrow the list. Remember filters saves the current filters and view settings in this browser when functional preferences are enabled. Use Export CSV to download filtered orders for reconciliation or record review. Exports contain records from the selected mode only, so keep mainnet and testnet exports separate. Order Details Open Order Details from either Card View or Table View . The dialog includes these tabs: Tab Information shown Basic Information Requested amount, chain, token, payment address, payment timing, received and refunded totals, payment page, and QR codes. Payment Records Detected payment transactions, amounts, payment status, transaction hashes, and timing. Contract Deployment Payment setup status, payment address, token address, processing time, and explorer links. Fee Details Fee Rate, Min Fee, and Max Fee saved for the order. See Fees and Plan Usage . Refund Refund eligibility, available amount, payment sources, refund action, and refund history. See Refund Operations . Settlement Settlement availability, merchant amount, platform fee, destination address, settlement time, and transaction reference. See Settlement Review . Metadata Metadata saved with the checkout session. Invoice & Receipt Invoice and receipt status, files, and document actions. Create A Checkout Session Use Create Checkout Session to generate a payment request from the dashboard for a specific merchant, network, token, and amount. The resulting payment page can be shared with the payer and tracked as an order. The selected merchant determines the available networks, tokens, amount limits, and payment-window limits. The new checkout session appears in the order list for monitoring and follow-up. For checkout behavior, payment surfaces, and field details, see Checkout Sessions . API Request Tester Use API Request Tester to send real merchant API requests from the dashboard before implementing a backend integration. Requests use the selected mode, and creating a checkout session creates an order in that mode. Switching between mainnet and testnet clears entered values and previous responses. Use the links below for implementation details: Checkout Session : Checkout Sessions API Query Order : Orders API Payments : Payments API Contract Status : Contract Status API Refund Status : Refunds API Refund History : Refunds API Settlement History : Settlements API Invoice & Receipt : Invoice and Receipt API For shared authentication requirements, see API Keys and Authentication .","section":"Merchant Operations"},{"slug":"merchant-operations/settlement","title":"Settlement Review","description":"Review settlement records in the Merchant Dashboard.","navOrder":350,"searchText":"merchant operations settlement Settlement Review Review settlement records in the Merchant Dashboard. Merchant Operations Settlement Review Use Settlement Review to understand what the Settlement tab shows for an order in Merchant Dashboard. Before A Settlement Result Appears Open Order Details , then open the Settlement tab. Before a completed settlement result is available, the tab can show these notices depending on the settlement flow: Notice Meaning Contract Not Ready Required order preparation is not complete. Sweep unlock scheduled The order has not reached the displayed settlement availability time. Settlement is in queue Settlement processing is waiting for a completed result. Settlement Pending Verification A settlement record exists and is still being verified. These notices do not mean settlement is complete. Completed Settlement Details When settlement is complete and verified, the tab can show: Field Meaning Settlement Status Settlement result displayed for the order. A Verified badge appears beside it after verification succeeds. Received Actual token amount sent to the merchant settlement wallet. Platform Fee Token amount handled as the platform fee in the same settlement transaction. Settlement Time Recorded completion time. Merchant Address Destination wallet saved for the order. Transaction Hash Blockchain transaction for the settlement; use it to open the transaction in an explorer. After the result appears, compare the settlement details with the order's Basic Information. If the order had a partial refund, the Received value reflects the remaining settlement amount sent to the merchant wallet after the refund and platform fee split, not the original checkout amount. For the fee rules saved at order creation, see Fees and Plan Usage . For the business flow, see Settlement Basics . For API records, see Settlements API .","section":"Merchant Operations"},{"slug":"merchant-operations/fees-and-plan-usage","title":"Fees and Plan Usage","description":"Review order-level fee details, platform fees, and plan usage.","navOrder":360,"searchText":"merchant operations fees and plan usage Fees and Plan Usage Review order-level fee details, platform fees, and plan usage. Merchant Operations Fees and Plan Usage Use Fees and Plan Usage to review the Fee Details tab for an order and the Subscription Plan & Tiers page in Merchant Dashboard. Order Fee Details Open Order Details , then open the Fee Details tab to review the Fee Rate, Min Fee, and Max Fee saved for that order. These values are saved when the order is created. Later plan or fee changes apply to new orders and do not rewrite an existing order. Fee Details shows the saved fee rules. Open the Settlement tab to review the platform fee amount recorded after settlement is complete. To read the Settlement tab itself, see Settlement Review . For the settlement flow, see Settlement Basics . Subscription Overview Open Settings > Subscription Plan & Tiers to review current period plan usage. In mainnet mode, the Subscription Overview can show: Area Meaning Plan and tier Current active plan and tier, when available. Time period Current period and next billing date. Fee rates by chain Chain, Fee Rate, Min Fee, and Max Fee. Quota Remaining order creation and order deployment quota. Settled volume USD settled and Orders settled in the current period. Higher tiers unlock lower fee rates. Move up when settled volume and settled order count both reach the next tier's requirements. The tier is recalculated each period. Where the dashboard labels values in USD, USDT and USDC are valued one-to-one with the US dollar. Testnet Usage In testnet mode, Subscription Plan & Tiers shows testnet usage quotas separately from mainnet subscription plan usage: Active merchants: testnet merchants counted against the active merchant limit. Live orders: open and unfinished testnet orders counted against the live order limit. Testnet usage does not count as mainnet billing or settled payment volume.","section":"Merchant Operations"},{"slug":"merchant-operations/refund-operations","title":"Refund Operations","description":"Operate supported refunds from the Merchant Dashboard.","navOrder":370,"searchText":"merchant operations refund operations Refund Operations Operate supported refunds from the Merchant Dashboard. Merchant Operations Refund Operations Use Refund Operations to review the Refund tab in Order Details and execute a merchant-initiated refund when the order supports it. Check Refund Availability Open Order Details , then open the Refund tab to review refund readiness: Contract Status : shows Deployment Status , Refund Window , Refundable , and Refund window closes at when available. In this tab, Refund Window means the order's after-sales window. Merchant Details : order ID and merchant wallet address saved for the order. User Payments : payer addresses, received amounts, payment timing, and payment transactions. Refund History : merchant refund records and platform-initiated refunds, when available. If refund is unavailable, the tab can show notices such as Contract Not Ready , Refund Not Ready , Refund Not Supported , or No Payments Found . Note: The Refund tab permits only one merchant-initiated refund for a checkout. A partial refund uses that one refund action. Execute The Refund When the refund action is available: Open Order Details , then open the Refund tab. Complete merchant wallet verification if Merchant Dashboard asks for it. Use the User Payments table to review From Address , Original , Refund , Date , and Transaction , then select the payment sources and refund amounts. Use Refund This , Refund All , Clear , or Clear All as needed, then review Selected Payments and Total Amount . The total refund amount cannot be higher than the order's remaining refundable amount. Complete any network switch prompt shown by Merchant Dashboard. Select Execute Refund , review Confirm Refund Execution , then select Confirm & Execute . Confirm the transaction in the wallet, then keep Merchant Dashboard open until Refund Transaction Submitted or a current refund status appears. Note: Merchant-initiated on-chain refunds require the merchant to pay the applicable network transaction cost, such as a gas fee or transaction fee. Refund History The tab can show Refund History for merchant refund records and Platform Refund History for platform-initiated refunds. Platform-initiated refunds do not require merchant action. Entries can show: Refund amount Refund recipients Transaction hash Attempt time Current status If the refund transaction fails on-chain or is reverted, Retry Refund can create a new refund transaction. If the refund has succeeded on-chain, do not execute another merchant refund. Centralized Exchange Payments Refunds return to the original payment address. If that address belongs to a centralized exchange, the refund may not appear in the customer's exchange account. Customer-side exchange account recovery is outside Stafiel's refund scope. For the business rules and network support table, see Refund Basics . For operational risks, see Payment and Refund Risks .","section":"Merchant Operations"},{"slug":"merchant-operations/statistics","title":"Statistics","description":"Review merchant, order, amount, chain, token, and activity statistics.","navOrder":380,"searchText":"merchant operations statistics Statistics Review merchant, order, amount, chain, token, and activity statistics. Merchant Operations Statistics Use Statistics to review Merchant Dashboard totals for merchants, orders, order amounts, chains, tokens, and recent activity. Key Metrics Overview Key Metrics Overview provides a quick status check across: Total Merchants Total Orders Orders (24h) Settled (24h) Live Orders Filter Statistics Use the merchant filter to view statistics for all accessible merchants or one merchant. Most sections support Card View , Table View , or Chart View . Recent Activity supports Table View and Chart View . The selected view changes the presentation, not the underlying totals. Merchant Overview Merchant Overview groups merchant profiles by current status: Active Pending Suspended Terminated Order Overview Order Overview shows total orders and current status distribution (see Order Lifecycle and Payment Status for status meanings), with merchant comparison when all merchants are selected: Awaiting Payment Paid Settled Expired Full Refunded Compliance Hold Closed Order Amounts (USD) Order Amounts (USD) summarizes dollar-denominated order values by chain and status; values labeled in USD treat USDT and USDC one-to-one with the US dollar: Total Awaiting Payment Paid Settled Weekly Order Trends Weekly Order Trends compares Orders by Day and Amounts by Day (USD) for the selected week across: Created Paid Settled Chain Breakdown Chain Breakdown compares chain-level order totals: Total Orders Orders (24h) Settled (24h) Live Orders Token Mix Token Mix compares USDC and USDT recorded order distribution, not wallet balances, across: Total Mix By Chain Recent Activity Recent Activity lists recent account and merchant operations and can filter by: Action Target Merchant For order-level review, exports, and reconciliation, see Orders .","section":"Merchant Operations"}]},{"section":"Developer Integration","pages":[{"slug":"developer-integration/api-keys-and-authentication","title":"API Keys and Authentication","description":"Authenticate server-side merchant API requests with API keys.","navOrder":400,"searchText":"developer integration api keys and authentication API Keys and Authentication Authenticate server-side merchant API requests with API keys. Developer Integration API Keys and Authentication Use API keys for server-to-server merchant API calls. Keep keys on your backend only. Do not place them in browser JavaScript, mobile apps, checkout pages, or client-side widget configuration. Base URL https://api.stafiel.com Request Headers Every API key request must include the authentication and client-mode headers. Requests with JSON bodies must also include Content-Type: application/json . Header Required Default Description X-API-Key Yes None Merchant API key created in the Merchant Dashboard. Keep this value server-side only. X-App-Client Yes None Request mode identifier. Use merchant-client for live API keys. Content-Type Required for requests with a body None Use application/json when sending a JSON request body, such as checkout session creation. Live API keys must use X-App-Client: merchant-client . Test API keys must use X-App-Client: merchant-client-testnet . If the key mode and header mode do not match, Stafiel returns 401 AUTH_FAILED . Header Example X-API-Key: mk_live_your_api_key X-App-Client: merchant-client Content-Type: application/json Merchant ID Most order endpoints require merchantId . The value must match the merchant bound to the API key. Requests for another merchant are rejected. Rate Limits API key requests are rate limited. Limits may vary by endpoint, merchant, request mode, plan, traffic pattern, and operational risk controls. When a request is rate limited, the API returns 429 RATE_LIMIT_EXCEEDED . If the response includes Retry-After or rate-limit reset headers, wait for the indicated time before retrying. Design your integration to retry with backoff, avoid tight polling loops, and reuse idempotency keys when retrying checkout session creation. Key Management Create, rotate, and revoke API keys from the Merchant Dashboard. Store API keys in a secret manager or server environment variable. Rotate a key immediately if it may have been exposed.","section":"Developer Integration"},{"slug":"developer-integration/checkout-api","title":"Checkout Sessions API","description":"Create checkout sessions from your backend.","navOrder":410,"searchText":"developer integration checkout api Checkout Sessions API Create checkout sessions from your backend. Developer Integration Checkout Sessions API Create a checkout session from your backend when your customer is ready to pay. The response contains a hosted checkout URL that you can redirect to, open in a new tab, or pass to the Stafiel widget. Endpoint POST /api/v1/checkout/sessions Request Fields Field Required Default Description merchantId Yes None Must match the merchant bound to the API key. chainName Yes None Mainnet chain label. See Chain Labels . tokenSymbol Yes None Use USDC or USDT , subject to the selected chain and merchant configuration. amountUsd Yes None Dollar-denominated checkout amount as a string. Use at most 2 decimal places, such as 49 , 49.9 , or 49.90 ; extra decimal places are rejected. expiresIn No Merchant default Payment window in seconds. The value must be inside the merchant's configured allowed range. idempotencyKey No None Recommended. Use your internal order ID so retries do not create duplicate checkout sessions. metadata No None Your own order reference, customer reference, return URL, or other non-sensitive metadata. See Metadata Reserved Fields and Rules . Chain Labels Use these mainnet chainName values when creating live checkout sessions: chainName Chain ID Description eth 1 Ethereum mainnet for USDT and USDC payments. base 8453 Base mainnet for lower-cost EVM payments. bsc 56 BNB Smart Chain mainnet for EVM payments. polygon 137 Polygon mainnet for EVM payments. solana 101 Solana mainnet for SPL stablecoin payments. tron 728126428 Tron mainnet for TRC20 stablecoin payments. Available chains and tokens depend on merchant configuration. Request Example The example includes the currently supported reserved metadata fields. curl -X POST https://api.stafiel.com/api/v1/checkout/sessions \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"merchantId\": \"mch_your_merchant_id\", \"chainName\": \"base\", \"tokenSymbol\": \"USDC\", \"amountUsd\": \"49.00\", \"expiresIn\": 1800, \"idempotencyKey\": \"order_10001\", \"metadata\": { \"returnToUrl\": \"https://merchant.example.com/orders/10001\", \"productName\": \"Annual Pro Plan\", \"productDescription\": \"One-year subscription for the merchant workspace.\", \"quantity\": \"1\", \"unitLabel\": \"year\", \"customerReference\": \"CUS-8842\" } }' Success Response { \"success\": true, \"data\": { \"orderId\": \"ord_your_order_id\", \"status\": \"awaiting_payment\", \"checkoutSessionUrl\": \"https://pay.stafiel.com/pay/ps_live_example\", \"expiresAt\": \"2026-05-19T12:00:00.000Z\", \"amountUsd\": \"49.00\", \"chainName\": \"base\", \"tokenSymbol\": \"USDC\", \"tokenAddress\": \"0x...\" } } Response Fields Field Type Description orderId string Stafiel order ID for later order, payment, refund, settlement, and document lookups. status string Initial order status. New checkout sessions return awaiting_payment . checkoutSessionUrl string Hosted checkout URL. Treat it as opaque and use it exactly as returned. expiresAt string ISO 8601 timestamp when the checkout session expires. amountUsd string Accepted checkout amount, stored with up to 2 decimal places. chainName string Canonical public chain label used for the checkout session. tokenSymbol string Token symbol selected for the checkout session. tokenAddress string Token contract or mint address used for the selected chain. Treat checkoutSessionUrl as opaque. Do not build payment URLs yourself. Idempotency Key idempotencyKey provides short-window duplicate protection for checkout session creation retries. A stable internal order ID is a good key because it maps one merchant-side order attempt to one checkout creation attempt. Rules: Use 1-128 visible ASCII characters. Reuse the same key when retrying the same request. Do not reuse the same key for a different checkout payload. If the same key is already being processed, or if the key is reused with a conflicting payload, the API returns 409 CHECKOUT_SESSION_CREATE_FAILED . Do not use idempotency keys as a permanent order lookup mechanism. Metadata Reserved Fields and Rules metadata is an optional JSON object for merchant business context, such as your internal order ID or customer reference. Do not put secrets, private keys, access tokens, full payment credentials, or unnecessary sensitive personal data in metadata. Stafiel currently interprets these reserved metadata fields for checkout return behavior, hosted checkout display, and generated documents: Field Required Default Description metadata.returnToUrl No None Checkout return URL, used only when allowed by the merchant return URL policy. metadata.productName No None Product or service name for hosted checkout and documents. metadata.productDescription No None Short product or order description for hosted checkout and documents. metadata.quantity No None Product quantity for hosted checkout and documents. metadata.unitLabel No None Unit label after quantity, such as seat , month , or year . General metadata rules: Use a flat object. Nested objects and arrays are ignored. Stafiel stores up to 20 accepted top-level fields, processed in request object order. Invalid fields are ignored and do not count toward the limit. Keys must be 1-100 characters and may use ASCII letters, numbers, dots, underscores, and hyphens. Values may be strings, finite numbers, booleans, or null . Objects, arrays, invalid values, and unsupported value types are ignored. String values may be up to 1,000 characters and may contain letters, numbers, punctuation, spaces, and line breaks. metadata.returnToUrl rules: The value must be an absolute https:// URL. Unsafe or blocklisted URLs are rejected. If the URL is not allowed by merchant return URL policy, it will not be used. Error Responses Error responses use this shape: { \"success\": false, \"error\": { \"code\": \"VALIDATION_ERROR\", \"message\": \"Invalid request\" } } HTTP Status Code Meaning 400 CHECKOUT_SESSION_CREATE_FAILED / ORDER_EXPIRES_IN_OUT_OF_RANGE Requ","section":"Developer Integration"},{"slug":"developer-integration/orders-api","title":"Orders API","description":"Query order lists and order details through the API.","navOrder":420,"searchText":"developer integration orders api Orders API Query order lists and order details through the API. Developer Integration Orders API Use the Orders API to list orders and retrieve a single order's current business state. List Orders Endpoint GET /api/v1/orders Query Parameters Field Required Default Description merchantId Yes None Merchant ID bound to the API key. page No 1 Page number. Starts from 1 . pageSize No 20 Number of orders per page. Maximum 100 . status No None Comma-separated order statuses, such as awaiting_payment , underpaid , fullpaid , overpaid , expired , settled , full_refunded , closed , or compliance_hold . chainName No None Comma-separated chain labels. orderId No None Search by Stafiel order ID or merchant business order reference. contractAddress No None Filter by payment contract or payment address. createdAtFrom No None ISO 8601 lower bound for order creation time. createdAtTo No None ISO 8601 upper bound for order creation time. sortBy No createdAt Use createdAt , status , or amount . sortOrder No desc Use asc or desc . Request Example curl \"https://api.stafiel.com/api/v1/orders?merchantId=mch_your_merchant_id&page=1&pageSize=20&status=fullpaid,settled&chainName=base,eth\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" List Success Response { \"success\": true, \"data\": { \"items\": [ { \"orderId\": \"ord_your_order_id\", \"merchantId\": \"mch_your_merchant_id\", \"status\": \"fullpaid\", \"amountUsd\": \"49.00\", \"totalPaidAmountUsd\": \"49.00\", \"chainName\": \"base\", \"chainId\": 8453, \"tokenSymbol\": \"USDC\", \"tokenAddress\": \"0x...\", \"tokenDecimals\": 6, \"orderAddress\": \"0x2222222222222222222222222222222222222222\", \"paymentUrl\": \"https://pay.stafiel.com/pay/ps_live_example\", \"expiresAt\": \"2026-05-19T12:30:00.000Z\", \"createdAt\": \"2026-05-19T12:00:00.000Z\", \"updatedAt\": \"2026-05-19T12:05:00.000Z\", \"metadata\": { \"customerReference\": \"CUS-8842\" } } ], \"chains\": [], \"total\": 1, \"page\": 1, \"pageSize\": 20, \"hasMore\": false, \"createdAtFrom\": null, \"createdAtTo\": null, \"merchantId\": \"mch_your_merchant_id\" } } List Response Fields Field Type Description items array Orders visible to the API key for the requested merchant and filters. chains array Chain metadata included for filter or display context. API integrations may ignore it. total number Total matching order count. page number Current page number. pageSize number Number of orders requested per page. hasMore boolean Whether another page of results is available. createdAtFrom string or null Applied lower creation-time filter. createdAtTo string or null Applied upper creation-time filter. merchantId string Merchant ID for single-merchant API key responses. Pagination Notes List responses use page-based pagination. For batch syncs, set createdAtTo at the start of the sync and keep that value while reading subsequent pages. This prevents newly created orders from changing the result window while your sync is in progress. Order Item Fields Field Type Description orderId string Stafiel order ID. merchantId string Merchant ID that owns the order. status string Current business status of the order. amountUsd string or null Original checkout amount. totalPaidAmountUsd string or null Total recorded payment amount when token decimals are known. chainName string or null Canonical public chain label. chainId number or null Numeric chain ID when available. tokenSymbol string or null Token symbol for the order. tokenAddress string or null Token contract or mint address. tokenDecimals number or null Token decimals used for amount formatting. orderAddress string or null Payment contract or payment address. paymentUrl string or omitted Hosted checkout URL, if still available for the order. expiresAt string ISO 8601 expiration timestamp. createdAt string ISO 8601 creation timestamp. updatedAt string ISO 8601 update timestamp. metadata object or null Sanitized order metadata. Get Order Details Endpoint GET /api/v1/orders/{orderId} Parameters Field Required Default Description orderId Yes None Path parameter. Stafiel order ID or supported order reference. merchantId Yes None Query parameter. Merchant ID bound to the API key. Request Example curl \"https://api.stafiel.com/api/v1/orders/ord_your_order_id?merchantId=mch_your_merchant_id\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" Detail Success Response { \"success\": true, \"data\": { \"orderId\": \"ord_your_order_id\", \"merchantId\": \"mch_your_merchant_id\", \"status\": \"fullpaid\", \"amountUsd\": \"49.00\", \"totalPaidAmountUsd\": \"49.00\", \"chainName\": \"base\", \"chainId\": 8453, \"tokenSymbol\": \"USDC\", \"tokenAddress\": \"0x...\", \"tokenDecimals\": 6, \"orderAddress\": \"0x2222222222222222222222222222222222222222\", \"paymentUrl\": \"https://pay.stafiel.com/pay/ps_live_example\", \"expiresAt\": \"2026-05-19T12:30:00.000Z\", \"createdAt\": \"2026-05-19T12:00:00.000Z\", \"updatedAt\": \"2026-05-19T12:05:00.000Z\", \"metadata\": { \"customerReference\": \"CUS-8842\" } } } Detail Response Fields Field Type Description orderId string Stafiel order ID. merchantId string Merchant ID that owns the order. status string Current business status of the order. amountUsd string Original checkout amount. totalPaidAmountUsd string Total recorded payment amount displayed to 2 decimals. chainName string Canonical public chain label. chainId number or null Numeric chain ID when available. tokenSymbol string Token symbol for the order. tokenAddress string or null Token contract or mint address. tokenDecimals number or null Token decimals used for amount formatting. orderAddress string or null Payment contract or payment address. paymentUrl string or omitted Hosted checkout URL, if still available for the order. expiresAt string ISO 8601 expiration timestamp. createdAt string ISO 8601 creation timestamp. updatedAt string ISO 8601 update timestamp. metadata object or null Sanitized order metadata. Order Statuses The status field can use these values. Do not assume status changes are strictly linear; use webhooks or repeated API r","section":"Developer Integration"},{"slug":"developer-integration/payments-api","title":"Payments API","description":"Query payment transactions recorded for an order.","navOrder":430,"searchText":"developer integration payments api Payments API Query payment transactions recorded for an order. Developer Integration Payments API Use the Payments API to inspect on-chain payment transactions recorded for an order. Endpoint GET /api/v1/orders/{orderId}/payments Parameters Field Required Default Description orderId Yes None Path parameter. Stafiel order ID. merchantId Yes None Query parameter. Merchant ID bound to the API key. Request Example curl \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/payments?merchantId=mch_your_merchant_id\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" Success Response { \"success\": true, \"data\": [ { \"orderId\": \"ord_your_order_id\", \"txHash\": \"0xabc123...\", \"fromAddress\": \"0x1111111111111111111111111111111111111111\", \"toAddress\": \"0x2222222222222222222222222222222222222222\", \"tokenAddress\": \"0x...\", \"amountUsd\": \"49.00\", \"confirmations\": 24, \"isConfirmed\": true, \"blockNumber\": \"12345678\", \"txLogIndex\": \"0\", \"createdAt\": \"2026-05-19T12:05:00.000Z\", \"updatedAt\": \"2026-05-19T12:06:00.000Z\" } ] } Response Fields Field Type Description orderId string Stafiel order ID associated with the payment record. txHash string or null On-chain transaction hash. fromAddress string or null Customer source address when available. toAddress string or null Order payment address or contract address. tokenAddress string or null Token contract or mint address. amountUsd string or null Recorded stablecoin payment amount displayed to 2 decimals. confirmations number Confirmation count currently recorded by Stafiel. isConfirmed boolean Whether Stafiel currently treats the payment as confirmed. blockNumber string or null Block number as a string when available. txLogIndex string or null Log index as a string when available. createdAt string ISO 8601 creation timestamp. updatedAt string ISO 8601 update timestamp. Confirmation isConfirmed indicates whether Stafiel currently considers the recorded payment confirmed. Do not treat an early detected payment as final until order status and confirmation state meet your business requirements. Chain Address Formats EVM addresses use 0x... . Solana addresses use base58 public keys. Tron addresses use base58 T... . Error Responses HTTP Status Code Meaning 400 VALIDATION_ERROR Query parameter is invalid or unsupported. 401 AUTH_FAILED API key is missing, invalid, or cannot access the requested merchant or order. 403 AUTHORIZATION_ERROR Request is authenticated but not allowed. 404 NOT_FOUND Order does not exist or is not visible. 429 RATE_LIMIT_EXCEEDED Too many requests. Retry after the indicated time.","section":"Developer Integration"},{"slug":"developer-integration/contract-status-api","title":"Contract Status API","description":"Query contract or payment address deployment status.","navOrder":440,"searchText":"developer integration contract status api Contract Status API Query contract or payment address deployment status. Developer Integration Contract Status API Use the Contract Status API to inspect the payment contract or payment address state for an order. Endpoint GET /api/v1/orders/{orderId}/contract Parameters Field Required Default Description orderId Yes None Path parameter. Stafiel order ID. merchantId Yes None Query parameter. Merchant ID bound to the API key. Request Example curl \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/contract?merchantId=mch_your_merchant_id\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" Success Response { \"success\": true, \"data\": { \"contractAddress\": \"0x2222222222222222222222222222222222222222\", \"deploymentStatus\": \"deployed\", \"deploymentTxHash\": \"0xabc123...\", \"deployedAt\": \"2026-05-19T12:03:00.000Z\", \"chainId\": 8453, \"chainName\": \"base\", \"addressVerificationStatus\": \"verified\", \"isInitialized\": true, \"sweepOpenAt\": \"2026-05-21T12:00:00.000Z\", \"sweepExtendMaxAt\": \"2026-05-23T12:00:00.000Z\", \"createdAt\": \"2026-05-19T12:00:00.000Z\", \"updatedAt\": \"2026-05-19T12:03:00.000Z\" } } Response Fields Field Type Description contractAddress string or null Payment contract or payment address. May be predicted before deployment. deploymentStatus string Standardized deployment status. See Deployment Statuses . deploymentTxHash string or null Deployment transaction hash when available. deployedAt string or null ISO 8601 deployment timestamp when available. chainId number Numeric chain ID. chainName string Canonical public chain label. addressVerificationStatus string Address verification status: verified , pending , or failed . isInitialized boolean Whether the payment contract or program state is initialized. sweepOpenAt string or null Time when settlement can become available for the order. sweepExtendMaxAt string or null Latest time to which the sweep window can be extended, when applicable. createdAt string ISO 8601 creation timestamp. updatedAt string ISO 8601 update timestamp. How To Use It Use this endpoint for operational diagnostics and support workflows. It is not required for a basic hosted checkout integration. sweepOpenAt describes when settlement can become available. With isInitialized , it also helps diagnose refund eligibility; amount, network support, and refund history still apply. Deployment Statuses Status Meaning not_started Deployment has not started. not_deployed No deployed payment contract or address is available. pending_deployment Deployment or provisioning is in progress. on_hold Deployment or provisioning is on hold. deployed Payment contract or payment address is ready. deployment_failed Deployment failed. deployment_cancelled Deployment was cancelled. Error Responses HTTP Status Code Meaning 400 VALIDATION_ERROR Query parameter is invalid or unsupported. 401 AUTH_FAILED API key is missing, invalid, or cannot access the requested merchant or order. 403 AUTHORIZATION_ERROR Request is authenticated but not allowed. 404 NOT_FOUND Order does not exist or is not visible. 429 RATE_LIMIT_EXCEEDED Too many requests. Retry after the indicated time.","section":"Developer Integration"},{"slug":"developer-integration/refund-api","title":"Refunds API","description":"Check refund status and refund history for an order.","navOrder":450,"searchText":"developer integration refund api Refunds API Check refund status and refund history for an order. Developer Integration Refunds API Use the Refunds API to check refund availability and inspect verified refund records for an order. Refund Status Endpoint GET /api/v1/orders/{orderId}/refund-status Parameters Field Required Default Description orderId Yes None Path parameter. Stafiel order ID. merchantId Yes None Query parameter. Merchant ID bound to the API key. Request Example curl \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/refund-status?merchantId=mch_your_merchant_id\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" Success Response { \"success\": true, \"data\": { \"hasMerchantRefunded\": false, \"hasAnyRefunded\": false, \"isWithinWindow\": true, \"windowEndsAt\": \"2026-05-21T12:00:00.000Z\", \"refundableAmountUsd\": \"49.00\", \"hasPlatformRefunded\": false, \"isInitialized\": true, \"canRefund\": true, \"totalMerchantRefundAmountUsd\": \"0.00\", \"totalPlatformRefundAmountUsd\": \"0.00\" } } Status Response Fields Field Type Description hasMerchantRefunded boolean Whether a merchant refund has been recorded. hasAnyRefunded boolean Whether any successful refund has been recorded. isWithinWindow boolean Whether the merchant after-sales window is still open. windowEndsAt string or omitted ISO 8601 after-sales window end time when still inside the window. refundableAmountUsd string or omitted Current refundable amount displayed to 2 decimals. hasPlatformRefunded boolean Whether a platform-initiated refund has been recorded. isInitialized boolean Whether the payment contract or program state is initialized. canRefund boolean Whether refund is currently available after initialization, window, amount, network, and refund-history checks. totalMerchantRefundAmountUsd string Total merchant refund amount displayed to 2 decimals. totalPlatformRefundAmountUsd string Total platform-initiated refund amount displayed to 2 decimals. Use canRefund as the API signal for whether a refund can currently be submitted through Stafiel. Do not infer refund eligibility from order status alone. Refund History Endpoint GET /api/v1/orders/{orderId}/refund-history Parameters Field Required Default Description orderId Yes None Path parameter. Stafiel order ID. merchantId Yes None Query parameter. Merchant ID bound to the API key. Request Example curl \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/refund-history?merchantId=mch_your_merchant_id\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" The response lists successful refund records, including refund amount, transaction hash, refund initiator, verification status, and refund metadata where available. The endpoint returns all successful refund records for the order in one array. No pagination parameters apply. Success Response { \"success\": true, \"data\": { \"refundHistory\": [ { \"refundAmountUsd\": \"10.00\", \"transactionHash\": \"0xabc123...\", \"txHash\": \"0xabc123...\", \"refundMeta\": [ { \"recipient\": \"0x1111111111111111111111111111111111111111\", \"amountUsd\": \"10.00\", \"originalPaymentHash\": \"0xpayment...\" } ], \"refundBy\": \"merchant\", \"isVerified\": true, \"verifiedAt\": \"2026-05-19T12:12:00.000Z\", \"status\": \"refunded\", \"createdAt\": \"2026-05-19T12:10:00.000Z\" } ], \"status\": \"refunded\", \"chainName\": \"base\", \"chainId\": 8453 } } History Response Fields Field Type Description refundHistory array Successful refund records for the order. status string Latest refund status when refund history exists. chainName string Canonical public chain label. chainId number Numeric chain ID. refundAmountUsd string Refunded amount displayed to 2 decimals. txHash string or omitted On-chain refund transaction hash. Use this field for new integrations. transactionHash string or omitted Compatibility alias for txHash . refundMeta array Per-recipient refund allocation details when available. refundBy string or null Refund initiator, such as merchant or platform . isVerified boolean Whether the refund has been verified on-chain. verifiedAt string or omitted ISO 8601 verification timestamp. createdAt string or omitted ISO 8601 creation timestamp. API Boundaries The public Refunds API exposes refund status and successful refund history for an order. It does not submit refunds. Use the Merchant Dashboard to operate supported refunds. See Refund Operations . Error Responses HTTP Status Code Meaning 400 VALIDATION_ERROR Query parameter is invalid or unsupported. 401 AUTH_FAILED API key is missing, invalid, or cannot access the requested merchant or order. 403 AUTHORIZATION_ERROR Request is authenticated but not allowed. 404 NOT_FOUND Order or refund record does not exist or is not visible. 409 REFUND_NOT_SUPPORTED Refund is not supported for this chain. 429 RATE_LIMIT_EXCEEDED Too many requests. Retry after the indicated time.","section":"Developer Integration"},{"slug":"developer-integration/settlement-history-api","title":"Settlements API","description":"Query settlement records for an order.","navOrder":460,"searchText":"developer integration settlement history api Settlements API Query settlement records for an order. Developer Integration Settlements API Use the Settlements API to query settlement records for an order. Endpoint GET /api/v1/orders/{orderId}/settlement Parameters Field Required Default Description orderId Yes None Path parameter. Stafiel order ID. merchantId Yes None Query parameter. Merchant ID bound to the API key. Request Example curl \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/settlement?merchantId=mch_your_merchant_id\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" If no settlement record exists yet, data can be null . Success Response { \"success\": true, \"data\": { \"txHash\": \"0xabc123...\", \"merchantAmount\": \"48.51\", \"platformAmount\": \"0.49\", \"status\": \"settled\", \"isVerified\": true, \"merchantAddress\": \"0x3333333333333333333333333333333333333333\", \"createdAt\": \"2026-05-19T12:20:00.000Z\", \"updatedAt\": \"2026-05-19T12:20:30.000Z\" } } Response Fields Field Type Description txHash string or null Settlement transaction hash. merchantAmount string or null Amount settled to the merchant wallet, displayed to 2 decimals. platformAmount string or null Platform fee amount, displayed to 2 decimals. status string or null Settlement status: pending , settled , or failed . isVerified boolean or null Whether the settlement record has been verified. merchantAddress string or null Merchant settlement address snapshot for the order. createdAt string ISO 8601 creation timestamp. updatedAt string or null ISO 8601 update timestamp. Settlement Address Snapshot The merchant settlement address is taken from the order's creation snapshot. A later wallet configuration change does not rewrite the settlement address for an existing order. Error Responses HTTP Status Code Meaning 400 VALIDATION_ERROR Query parameter is invalid or unsupported. 401 AUTH_FAILED API key is missing, invalid, or cannot access the requested merchant or order. 403 AUTHORIZATION_ERROR Request is authenticated but not allowed. 404 NOT_FOUND Order does not exist or is not visible. 429 RATE_LIMIT_EXCEEDED Too many requests. Retry after the indicated time.","section":"Developer Integration"},{"slug":"developer-integration/invoice-and-receipt-api","title":"Invoice and Receipt API","description":"Query and download order invoice and receipt documents.","navOrder":470,"searchText":"developer integration invoice and receipt api Invoice and Receipt API Query and download order invoice and receipt documents. Developer Integration Invoice and Receipt API Use the Invoice and Receipt API to query document status and download generated PDFs for an order. Get Documents Endpoint GET /api/v1/orders/{orderId}/documents Parameters Field Required Default Description orderId Yes None Path parameter. Stafiel order ID. merchantId Yes None Query parameter. Merchant ID bound to the API key. Request Example curl \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/documents?merchantId=mch_your_merchant_id\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" Success Response { \"success\": true, \"data\": { \"orderId\": \"ord_your_order_id\", \"documents\": { \"invoice\": { \"type\": \"invoice\", \"status\": \"ready\", \"documentNumber\": \"INV-2026-0001\", \"issuedAt\": \"2026-05-19T12:00:00.000Z\", \"canDownloadPdf\": true, \"pdf\": { \"contentType\": \"application/pdf\", \"downloadUrl\": \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/documents/invoice/pdf?merchantId=mch_your_merchant_id\" } }, \"receipt\": { \"type\": \"receipt\", \"status\": \"ready\", \"documentNumber\": \"RCT-2026-0001\", \"issuedAt\": \"2026-05-19T12:05:00.000Z\", \"canDownloadPdf\": true, \"pdf\": { \"contentType\": \"application/pdf\", \"downloadUrl\": \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/documents/receipt/pdf?merchantId=mch_your_merchant_id\" } } } } } Response Fields Field Type Description orderId string Stafiel order ID. documents object Document objects keyed by invoice and receipt . type string Document type, either invoice or receipt . status string or null Document generation status. documentNumber string or null Generated invoice or receipt number. issuedAt string or null ISO 8601 issue timestamp. canDownloadPdf boolean Whether the PDF is currently available for download. pdf.contentType string PDF content type when available. pdf.downloadUrl string Authenticated PDF download URL when available. Download PDF Endpoint GET /api/v1/orders/{orderId}/documents/invoice/pdf GET /api/v1/orders/{orderId}/documents/receipt/pdf Parameters Field Required Default Description orderId Yes None Path parameter. Stafiel order ID. documentType Yes None Path value. Use invoice or receipt . merchantId Yes None Query parameter. Merchant ID bound to the API key. Request Example curl \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/documents/invoice/pdf?merchantId=mch_your_merchant_id\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" Success Response The PDF download endpoint does not return the standard JSON envelope. HTTP/1.1 200 OK Content-Type: application/pdf Content-Disposition: inline; filename=\"invoice-ord_your_order_id.pdf\" Document Status Document status may be queued , generating , ready , failed , voided , or null . A document becoming ready is not the source of truth for payment completion. Use order status and payment records for payment state. Error Responses HTTP Status Code Meaning 400 VALIDATION_ERROR Query parameter is invalid or document type is unsupported. 401 AUTH_FAILED API key is missing, invalid, or cannot access the requested merchant or order. 403 AUTHORIZATION_ERROR Request is authenticated but not allowed. 404 NOT_FOUND Order or document does not exist or is not visible. 409 ORDER_DOCUMENT_NOT_READY / ORDER_DOCUMENT_VOIDED PDF is not available or the document is voided. 429 RATE_LIMIT_EXCEEDED Too many requests. Retry after the indicated time.","section":"Developer Integration"},{"slug":"developer-integration/webhooks-and-events","title":"Webhooks and Events","description":"Receive signed webhook events from Stafiel.","navOrder":480,"searchText":"developer integration webhooks and events Webhooks and Events Receive signed webhook events from Stafiel. Developer Integration Webhooks and Events Use webhooks to receive asynchronous order events from Stafiel. Configure your webhook endpoint in the Merchant Dashboard. Receiver Endpoint In the Merchant Dashboard, set a public HTTPS endpoint for Stafiel events. Use a dedicated route so your application can verify the raw request body before any framework middleware modifies it. Delivery Headers Stafiel deliveries include these headers: Header Description X-Webhook-Signature HMAC-SHA256 signature for the raw request body, formatted as sha256=<hex> . X-Webhook-Event-Id Unique event ID for idempotency and duplicate detection. X-Webhook-Event-Type Canonical event type, such as order.payment.received_fullpaid . X-Webhook-Timestamp Delivery timestamp used for replay checks. X-Webhook-Delivery-Attempt Delivery attempt number for this event. X-App-Network Event network: mainnet or testnet . Signature Verification Verify the signature against the raw request body. Do not parse the JSON and then stringify it again before verification. The signature uses HMAC-SHA256 and is sent in X-Webhook-Signature as sha256=<hex> . A typical signature verification flow includes: Read X-Webhook-Signature and validate the sha256=<hex> format. Verify against the exact raw request body bytes received by your server. Compute HMAC-SHA256 with your webhook signing secret and compare the digest using a constant-time comparison. Check X-Webhook-Timestamp against your replay tolerance before accepting the event. Webhook Payload Example { \"event\": \"order.payment.received_fullpaid\", \"eventId\": \"evt_your_event_id\", \"timestamp\": \"2026-05-19T12:05:00.000Z\", \"network\": \"mainnet\", \"data\": { \"order\": { \"id\": \"ord_your_order_id\", \"merchantId\": \"mch_your_merchant_id\", \"chainId\": 8453, \"chainName\": \"base\", \"tokenAddress\": \"0x...\", \"tokenSymbol\": \"USDC\", \"amountUsd\": \"49.00\", \"orderAddress\": \"0x...\", \"status\": \"fullpaid\", \"totalPaidAmountUsd\": \"49.00\", \"expiresAt\": \"2026-05-19T12:30:00.000Z\", \"createdAt\": \"2026-05-19T12:00:00.000Z\", \"metadata\": { \"customerReference\": \"CUS-8842\" } }, \"oldBalance\": \"0.00\", \"newBalance\": \"49.00\", \"delta\": \"49.00\" } } Webhook Payload Fields Field Type Description event string Canonical event type. See Event Types . eventId string Unique webhook event ID. Use this for idempotency. timestamp string ISO 8601 time when the webhook event payload was created. network string mainnet or testnet . data object Event payload. Order-related events include data.order . Some events also include event-specific objects or fields. data.order.id string Stafiel order ID. data.order.merchantId string Merchant ID that owns the order. data.order.chainId number or null Numeric chain ID when available. data.order.chainName string or null Public chain label. data.order.tokenAddress string or null Token contract or mint address. data.order.tokenSymbol string or null Token symbol. data.order.amountUsd string or null Original checkout amount. data.order.orderAddress string or null Payment contract or payment address. data.order.status string Order status for this event. data.order.totalPaidAmountUsd string or null Total recorded payment amount when token decimals are known. data.order.expiresAt string or null ISO 8601 expiration timestamp. data.order.createdAt string or null ISO 8601 order creation timestamp. data.order.metadata object or null Sanitized order metadata. Event-specific fields: Field Events Description data.oldBalance Payment amount change events Previous detected order balance. data.newBalance Payment amount change events New detected order balance. data.delta Payment amount change events Balance change amount. data.confirmation order.payment.confirmed Confirmation details, including transaction hash, block number, confirmation count, and confirmation time. data.contract order.contract.ready Contract readiness details, including contract address, transaction hash, and contract status. data.settlement order.settled Settlement details, including merchant amount, platform fee, transaction hash, chain ID, settlement time, and settlement status. data.refund Refund events Refund details, including refund type, amount, transaction hash, recipients, chain ID, and notes. Webhook payloads can include event context that is not returned by every query API response for the same order. Treat each API chapter's response field table as the contract for that endpoint. Event Types Handle event types as exact strings. Event Type When It Is Sent order.payment.detected Stafiel detects an incoming payment for the order. order.payment.received_fullpaid Recorded payment reaches the expected order amount. order.payment.received_underpaid Recorded payment is below the expected order amount. order.payment.received_overpaid Recorded payment is above the expected order amount. order.payment.confirmed A recorded payment reaches Stafiel's confirmation threshold. order.contract.ready The payment contract or payment address is ready. order.settled Settlement for the order is recorded. order.expired The order expires before full payment. order.closed The order is closed. order.compliance_hold The order is held by risk or compliance controls. order.refund.by_merchant A merchant refund is recorded. order.refund.by_platform A platform-initiated refund is recorded. Event Handling and Retries Use eventId for idempotency. A typical receiver returns a 2xx response after the event has been recorded or identified as already processed. Failed deliveries are retried, so integrations generally treat webhook delivery as at-least-once and design for duplicate or out-of-order events.","section":"Developer Integration"},{"slug":"developer-integration/widget-integration","title":"Widget Integration","description":"Embed hosted checkout with the browser widget runtime.","navOrder":485,"searchText":"developer integration widget integration Widget Integration Embed hosted checkout with the browser widget runtime. Developer Integration Widget Integration Use the widget runtime when your frontend needs to launch a Stafiel checkout session. Create the checkout session first on your server, then pass the checkoutSessionUrl from the response data to the browser. Important: Do not put API keys in frontend or browser code. Runtime Scripts Load one of the browser runtimes from the widget domain for your network mode. The stable paths are: Runtime Script Global Use when Checkout snippet https://widget.stafiel.com/widget/v1/checkout.js window.StafielCheckout You want a smaller helper for button binding or declarative HTML binding. Widget runtime https://widget.stafiel.com/widget/v1/widget.js window.StafielWidget You want direct control over create, open, mount, events, and cleanup. Checkout vs Widget Use Checkout snippet for quick development and deployment. It is best for payment buttons, simple modal checkout, and declarative HTML binding. Use Widget runtime when you need direct control over the checkout instance. It is best for inline checkout areas, custom lifecycle handling, event subscriptions, theme changes, or cleanup in single-page applications. Both runtimes consume the same checkoutSessionUrl . The checkoutSessionUrl is an opaque hosted checkout URL. Do not parse, rebuild, or modify it. Checkout Snippet Example Use checkout.js when you want to bind checkout behavior to a button or DOM node without managing the lower-level widget instance yourself. <button id=\"pay-now\">Pay now</button> <script src=\"https://widget.stafiel.com/widget/v1/checkout.js\"></script> <script> window.StafielCheckout.bind('#pay-now', { checkoutSessionUrl: 'https://pay.stafiel.com/pay/ps_your_session_token', mode: 'modal', theme: 'light' }); </script> Checkout Snippet API Method Returns Description open(options) Promise<CheckoutSnippetBinding> Opens checkout immediately. bind(target, options) CheckoutSnippetBinding Binds checkout to a CSS selector or HTMLElement . bindAll(root?, defaults?) CheckoutSnippetBinding[] Binds every [data-stafiel-checkout] node under root . setTheme(target, theme) void Updates the theme for an existing binding. unbind(target) void Removes the click trigger listener for one binding. destroy(target?) void Removes one binding, or all bindings when no target is provided. Checkout Snippet Binding open() , bind() , and bindAll() return binding instances. Method Returns Description open() Promise<void> Opens the bound checkout. close() void Closes the current checkout surface when supported. destroy() void Removes the binding and its runtime state. setTheme(theme) void Switches the binding between light and dark . update(options) void Updates the binding with new checkout snippet options. Checkout Snippet Options Option Required Default Description checkoutSessionUrl Yes None Hosted checkout URL returned by your server. mode Yes None One of the values listed in Widget Modes . container No Bound target Optional container selector or element for mounted modes. openInNewTab No true for redirect Controls redirect mode tab behavior. scale No 1 Widget scale for non-redirect modes, clamped between 0.8 and 2.5 . borderRadius No 24 for modal , 16 otherwise Frame border radius in pixels, clamped between 0 and 24 . theme No light One of light or dark . autoFallback No false Allows fallback to another mode when needed. onOpen No None Called when checkout opens. onClose No None Called when checkout closes. onError No None Called when checkout fails to initialize or open. onFallback No None Called when the runtime falls back to another mode. Declarative Binding checkout.js can bind elements declared in HTML. <div data-stafiel-checkout data-checkout-session-url=\"https://pay.stafiel.com/pay/ps_your_session_token\" data-mode=\"lite\" data-theme=\"light\" data-scale=\"1\" data-border-radius=\"16\" ></div> <script src=\"https://widget.stafiel.com/widget/v1/checkout.js\"></script> <script> window.StafielCheckout.bindAll(); </script> Supported data attributes: Attribute Required Description data-stafiel-checkout Yes Marks the element for bindAll() . data-checkout-session-url Yes, unless supplied in bindAll defaults Hosted checkout URL. data-mode Yes One of the values listed in Widget Modes . data-container No Selector for a separate mounted container. data-scale No Widget scale for non-redirect modes. data-border-radius No Frame border radius in pixels. data-theme No light or dark . data-auto-fallback No Boolean value: true , false , 1 , or 0 . data-open-in-new-tab No Boolean value used by redirect mode. Widget Runtime Example <div id=\"stafiel-payment\"></div> <script src=\"https://widget.stafiel.com/widget/v1/widget.js\"></script> <script> const widget = window.StafielWidget.create({ checkoutSessionUrl: 'https://pay.stafiel.com/pay/ps_your_session_token', mode: 'inline', container: document.getElementById('stafiel-payment'), theme: 'light' }); widget.mount(); </script> Use open() for redirect and modal mode. Use on() to subscribe to widget events, and clean up subscriptions or widget instances when your page no longer needs them. <script> const widget = window.StafielWidget.create({ checkoutSessionUrl: 'https://pay.stafiel.com/pay/ps_your_session_token', mode: 'modal', theme: 'light' }); const unsubscribe = widget.on('order.payment.received_fullpaid', function (event) { console.log('Order paid', event); }); await widget.open(); // Later, for example when leaving a single-page app route: unsubscribe(); widget.destroy(); </script> Widget Options Option Required Default Description checkoutSessionUrl Yes None Hosted checkout URL returned by your server after creating a checkout session. mode Yes None One of the values listed in Widget Modes . container Required for mounted modes None HTMLElement used by inline , lite , or micro . You may also pass it to mount(container) . openInNewTab No true for redirect Controls whether redirec","section":"Developer Integration"},{"slug":"developer-integration/testnet","title":"Testnet","description":"Test integrations with test API keys and test networks.","navOrder":490,"searchText":"developer integration testnet Testnet Test integrations with test API keys and test networks. Developer Integration Testnet Testnet uses the same public API endpoints and request formats as live integrations. Only the mode-specific parameters change. Keep the endpoint path and request body shape the same as the corresponding API reference. Request Parameters Field Required Default Description X-API-Key Yes None Use a test API key, for example mk_test_your_api_key . X-App-Client Yes None Use merchant-client-testnet . Content-Type Required for JSON requests None Use application/json when sending a JSON request body. merchant-client-testnet tells Stafiel that the request belongs to testnet. It must be used with mk_test_ keys. A test key with merchant-client , or a live key with merchant-client-testnet , is rejected with 401 AUTH_FAILED . Data Isolation Testnet and live data are separate. Keep testnet activity isolated from live customer payments, accounting, reconciliation, webhook handling, and operational records in your own system. Do not treat a successful testnet payment as a real customer payment. Chain Labels Testnet chain names use explicit labels: Chain Label Testnet Chain ID eth-sepolia Ethereum Sepolia 11155111 base-sepolia Base Sepolia 84532 bsc-testnet BNB Smart Chain Testnet 97 polygon-amoy Polygon Amoy 80002 solana-devnet Solana Devnet 103 tron-nile Tron Nile 3448148188 Use the chain and token options shown in your Merchant Dashboard as the source of truth for what your account can create. Webhooks Use separate webhook configuration for testnet. Treat testnet event IDs, signing secrets, and delivery logs as separate from live deliveries. Go-Live Checklist Before going live, replace: Merchant ID: use your live merchant ID in API requests. API key: use a live API key with the mk_live_ prefix. X-App-Client : change merchant-client-testnet to merchant-client . Chain labels: switch from testnet labels to mainnet chain labels. Webhook configuration: use the live webhook endpoint and signing secret.","section":"Developer Integration"}]},{"section":"Risk and Reference","pages":[{"slug":"risk-and-reference/security-and-wallet-boundary","title":"Security and Wallet Boundary","description":"Understand merchant key custody and wallet boundaries.","navOrder":500,"searchText":"risk and reference security and wallet boundary Security and Wallet Boundary Understand merchant key custody and wallet boundaries. Risk and Reference Security and Wallet Boundary Stafiel does not ask for merchant wallet private keys or seed phrases, and it does not take custody of merchant wallets. The configured settlement wallet remains under merchant control. Use this page to understand what Stafiel verifies and where the wallet boundary is. Merchant Wallet Control The merchant settlement wallet is the address configured to receive merchant funds after eligible settlement. Stafiel records that address for checkout and settlement, but the wallet itself remains under merchant control. Do not share private keys, recovery phrases, or signing devices with Stafiel, customers, vendors, or support channels. For setup steps, see Wallet Settings . Wallet Verification Signatures Merchant Dashboard can ask the merchant to connect a browser extension wallet and sign a verification message. The signature verifies that the merchant can sign for the wallet address being configured. That verification signature: Does not transfer funds. Does not create an on-chain transaction. Does not grant token approval, contract permission, or program authority. Does not give Stafiel access to the wallet's private key or seed phrase. Does not charge a network transaction fee. Important: Always read the wallet prompt before signing. A wallet verification message should identify address verification, not token spending approval or fund movement. What Stafiel Provides Stafiel provides the checkout, order tracking, payment status, refund availability and records, settlement records, and integration surfaces used by the merchant. Supported blockchain payment rails enforce payment, refund, and settlement behavior for each checkout flow. These services do not make Stafiel the custodian of the merchant settlement wallet. The merchant remains responsible for wallet access, signer security, and recovery materials. For how settlement reaches the merchant wallet, see Settlement Basics . Wallet Boundary Notes For merchant settlement wallets: Use a browser extension wallet or hardware wallet that supports the selected network. Keep wallet recovery phrases and backup codes in a secure private location. Do not use centralized exchange deposit addresses as merchant settlement wallets. For account security and MFA settings, see Account and MFA . Customer Payment Wallets The merchant settlement wallet is different from the customer's payment wallet. Customers pay from their own wallets, exchange withdrawal flows, or custodial wallets. Those payment sources can affect refund reachability and support handling. For payment-source risks, see Payment and Refund Risks .","section":"Risk and Reference"},{"slug":"risk-and-reference/payment-and-refund-risks","title":"Payment and Refund Risks","description":"Understand payment-source, compliance-review, and refund-limit risks.","navOrder":510,"searchText":"risk and reference payment and refund risks Payment and Refund Risks Understand payment-source, compliance-review, and refund-limit risks. Risk and Reference Payment and Refund Risks Payment and refund risk depends on where the customer pays from, the selected network, the order status, KYT/AML and compliance review, and the refund rules for that checkout. Use this page to understand when payment source, compliance review, and refund limits can affect support, fulfillment, refund, or settlement decisions. Payment Source And Refund Reachability Customers can pay from self-custodial wallets, browser extension wallets, mobile wallets, centralized exchange withdrawal flows, or other custodial wallet flows. The payment source is the on-chain wallet address that paid the checkout. Original-route refunds return value to that same source. They cannot be redirected to an unrelated wallet chosen after payment. Payments from centralized exchanges and custodial wallets can still complete a checkout when the selected token, network, and payment address are used. Refund reachability can differ because these providers may use payment source addresses controlled by the exchange or wallet provider, not by the customer's personal account. Stafiel can record the on-chain payment, but a later refund to an exchange-controlled source may not appear in the customer's exchange account. Those customer-side recovery cases are outside Stafiel's refund scope. For the business refund model, see Refund Basics . KYT/AML And Compliance Review Stafiel applies Know Your Transaction (KYT), Anti-Money Laundering (AML), and related compliance checks across payment monitoring, on-chain payment setup, and settlement processing. These checks can affect whether an order continues normally, enters Compliance Hold, or becomes available for refund or settlement. A held order should not be treated as ready for fulfillment, refund, or settlement until the hold is resolved. For status handling, see Order Lifecycle and Payment Status . Merchant-Initiated Refund Limits Merchant-initiated on-chain refunds have limits: A checkout can have only one merchant-initiated refund action. A partial refund counts as that one refund action. The refund amount cannot exceed the remaining refundable amount for the order. Availability depends on the after-sales window, selected network, order status, and refundable amount. Merchant-initiated on-chain refunds require the merchant to pay the applicable network transaction cost, such as a gas fee or transaction fee. Tron orders do not support merchant-initiated on-chain refunds through Stafiel. For dashboard steps, see Refund Operations . Refund Outcomes And Settlement Refund outcome affects what can continue downstream: A partial refund can leave remaining paid value on the order. That remaining value can continue through the normal order and settlement flow when the order is otherwise eligible. A full refund leaves no remaining payment value to settle. For settlement behavior, see Settlement Basics . Platform-Initiated Refunds Stafiel may perform a platform-initiated refund for compliance, legal, risk, or operational reasons. These refunds do not require a merchant refund submission, and Merchant Dashboard can show the records when available. Customer Guidance Points Customer-facing checkout or support text often needs to account for these risk points: Pay only with the selected token, network, and payment address. Do not send payment after the payment window expires. Explain that a customer-controlled wallet usually gives a clearer refund path when refund reachability matters. Explain that centralized exchange or custodial wallet payments can complete an order, but refunds may not reach the customer's exchange account automatically.","section":"Risk and Reference"},{"slug":"risk-and-reference/go-live-checklist","title":"Go-Live Checklist","description":"Review the merchant checklist before using mainnet.","navOrder":530,"searchText":"risk and reference go live checklist Go-Live Checklist Review the merchant checklist before using mainnet. Risk and Reference Go-Live Checklist Use this checklist before accepting real customer payments on mainnet. It helps confirm that merchant setup, payment configuration, integrations, and record review are ready for live use. Merchant And Mode Confirm the Merchant ID belongs to the mainnet merchant that will accept real payments. Confirm Merchant Dashboard is using mainnet mode before copying settings, wallet addresses, checkout links, or records. For mode separation, see Mainnet vs Testnet . Wallet Settings Review approved settlement wallet addresses for every chain used for live checkout. Review enabled tokens and networks against the payment options the merchant plans to offer. For wallet setup, see Wallet Settings . For key custody boundaries, see Security and Wallet Boundary . Checkout Configuration Confirm live checkout sessions use the intended amount, token, network, payment window, metadata, and Return URL. Make customer-facing copy clear that customers should pay only with the selected token, selected network, and displayed payment address. Test hosted checkout, checkout snippet, or widget behavior against the production checkout flow. For checkout behavior, see Checkout Sessions . API And Front-End Integration Replace test API keys with mainnet API keys on the backend. Set X-App-Client to merchant-client for mainnet API requests. Keep API keys out of browser code, mobile apps, checkout pages, and widget configuration. Important: API keys belong on the server side only. Do not put API keys in front-end code. For API authentication, see API Keys and Authentication . Webhooks And Events If the live integration uses webhooks: Use a public HTTPS endpoint for live webhook delivery. Save the live webhook signing secret in the receiving system. Verify signatures against the raw request body. Make event handling idempotent and tolerant of retries. For event delivery, see Webhooks and Events . Refund And Support Readiness Review which live networks support merchant-initiated refunds. Make sure the merchant team understands one-time merchant refund behavior. Review centralized exchange and custodial wallet refund limitations for support planning. Know where to review refund history and platform-initiated refunds. For refund operations, see Refund Operations . For payment-source risk, see Payment and Refund Risks . Records And Reconciliation Know where to review orders, payment records, settlement details, fee details, refunds, invoices, and receipts. Keep exports and dashboard views separate between mainnet and testnet mode. Review settlement records for merchant amount, platform fee, settlement address, transaction hash, and settlement result. For order review, see Orders . For settlement review, see Settlement Review . For fee details, see Fees and Plan Usage .","section":"Risk and Reference"}]}],"pages":[{"slug":"start/overview","title":"Overview","description":"Start with the basics of how Stafiel works.","navOrder":100,"searchText":"start overview Overview Start with the basics of how Stafiel works. Start Overview Stafiel helps merchants accept USDT and USDC payments through hosted checkout, embedded checkout experiences with QR-based payment details, and payment APIs. It is designed for merchants that want stablecoin payment collection without asking Stafiel to hold their merchant wallet private keys. What Stafiel Does Stafiel provides the payment layer between your checkout flow and supported blockchain payment rails. You create a checkout, show the customer a payment experience, and track the order as the payment is detected, confirmed, settled, or marked as an exception. Merchants can use Stafiel to: Create checkout sessions for USDT or USDC payments. Send customers to a hosted checkout page. Embed payment experiences with the checkout snippet or widget. Let customers pay by scanning a QR code or copying the payment address. Track order, payment, settlement, invoice, receipt, refund, and event status. Who It Is For Stafiel is built for merchants, especially online businesses, that want to add stablecoin checkout to an existing sales flow. It can support direct checkout links, embedded payment areas, API-driven checkout creation, and operational workflows in the Merchant Dashboard. The product is useful when your team needs: A stablecoin payment experience that can fit into an existing checkout. Clear order status instead of manually checking blockchain explorers. A way to separate testing activity from real payment activity. Merchant-controlled receiving wallets. Wallet Boundary Stafiel does not ask for your merchant wallet private keys. Your merchant wallet configuration determines where supported payment flows settle. Supported chains use contracts or on-chain programs to enforce payment and settlement behavior, but your merchant wallet remains your responsibility. For operational details, see Wallet Settings and Security and Wallet Boundary . Where To Go Next Start with Quickstart to create your first checkout. Review Supported Assets and Networks for supported tokens, networks, and checkout payment options. Read Mainnet vs Testnet to understand how Stafiel provides testnet as a sandbox for integration and payment testing.","section":"Start"},{"slug":"start/quickstart","title":"Quickstart","description":"Create your first checkout with Stafiel.","navOrder":110,"searchText":"start quickstart Quickstart Create your first checkout with Stafiel. Start Quickstart Use this guide to create your first checkout through the simplest path in the Merchant Dashboard. It avoids API setup so you can confirm the core payment flow first. Before You Start You need: A Google or GitHub account for signing in to Stafiel. A browser extension crypto wallet for the network you plan to enable, used to verify your merchant settlement wallet address. An MFA device, such as a smartphone with an authenticator app installed. Use a wallet that supports the network you plan to enable, such as an EVM-compatible, Solana, or Tron wallet. Centralized exchange deposit addresses are not supported as merchant settlement wallets. 1. Sign In And Create A Merchant After signing in to the Stafiel Merchant Dashboard with the Google or GitHub account you want to use, create a merchant for the business or storefront that will accept payments. For more detail, see Dashboard Navigation and Account and MFA . 2. Set Up Merchant Complete the required merchant setup steps: Enable MFA for your account. Connect the wallet that will receive merchant funds for settlement. Enable at least one supported token and network for checkout. For more detail, see Wallet Settings . 3. Create A Checkout Session Create a checkout session from the Merchant Dashboard. The session represents one payment attempt for a specific amount, token, network, and merchant. For more detail, see Dashboard Navigation . 4. Verify The Checkout Session Open the hosted checkout page and confirm that it shows the expected amount, token, network, payment address or QR code, and payment status. If you want to complete the payment yourself, use a payer wallet that matches the selected token and network. You can check the payment status on the hosted checkout page or in the Merchant Dashboard. For more detail, see Orders . Next Steps Read Mainnet vs Testnet to understand how sandbox testing stays separate from real payments. Review Checkout Sessions to understand what a checkout represents and how to choose the customer-facing surface. Use Go-Live Checklist before accepting real customer payments.","section":"Start"},{"slug":"start/supported-assets-and-networks","title":"Supported Assets and Networks","description":"Review the tokens and networks Stafiel supports.","navOrder":120,"searchText":"start supported assets and networks Supported Assets and Networks Review the tokens and networks Stafiel supports. Start Supported Assets and Networks This page lists the public network names, chain IDs, token standards, and token contract or mint addresses used by Stafiel checkout. Supported Assets Stafiel checkout currently supports: USDT (Tether USD) USDC (USD Coin) Availability depends on network support and the merchant's enabled tokens and networks. Supported Networks The supported networks are listed below. Ethereum, Base, BNB Smart Chain, and Polygon are EVM-compatible networks. Network Chain ID Token Standard USDT USDC Ethereum 1 ERC20 0xdac17f958d2ee523a2206206994597c13d831ec7 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 BNB Smart Chain 56 BEP20 0x55d398326f99059ff775485246999027b3197955 0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d Base 8453 ERC20 Not supported 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 Polygon 137 ERC20 0xc2132d05d31c914a87c6611c10748aeb04b58e8f 0x3c499c542cef5e3811e1192ce70d8cc03d5c3359 Solana 101 SPL token Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v Tron 728126428 TRC20 TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t Not supported EVM addresses are token contract addresses. Solana addresses are SPL token mint addresses. Tron addresses are TRC20 contract addresses. Testnet Assets and Networks The testnet token entries below are mock tokens for integration and payment testing. For mode separation, see Mainnet vs Testnet . Network Chain ID Token Standard USDT (mock) USDC (mock) Ethereum Sepolia 11155111 ERC20 0xdCc868F9a7e7F8A14D0db1a3bD42c4d7e712C056 0x13E58CCaaE29942313A770C87dD3e3C82aE4f713 BNB Smart Chain Testnet 97 BEP20 0xbaB0F59Da37F84c622551E4c8Dc368B16847656e 0x3739CDB86c0F01243E60429365bE11D12363e855 Base Sepolia 84532 ERC20 Not supported 0xA20522a4523b7C318113F5a3a4Abd45f8ef975f9 Polygon Amoy 80002 ERC20 0x1FC44447F7Da0D4Ff640dAC8E76Bf3710999dAab 0x4Fa85E82062156E0f5cc461E08d034272C1b9ff1 Solana Devnet 103 SPL token H9S1iQctoUVktffkPSqqfzxfZsugxgSFV296gVEbCNFB A1nyNv8LH6wcvydBMCNMrWy5HeLAxLYN7KG7Cf9HW9zg Tron Nile 3448148188 TRC20 TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf Not supported Testnet Faucets Use the Testnet Faucet in the Merchant Dashboard to claim Stafiel mock USDT and USDC for supported EVM testnets and Solana Devnet. These testnet tokens are intended for testing and experiencing the full payment, receiving, and settlement flow before going live on mainnet. Native Testnet Tokens Native testnet tokens are needed for network fees when test flows submit on-chain transactions. Obtain the required gas token from the faucet for the target testnet before testing.","section":"Start"},{"slug":"start/mainnet-vs-testnet","title":"Mainnet vs Testnet","description":"Learn how mainnet and testnet stay separate.","navOrder":130,"searchText":"start mainnet vs testnet Mainnet vs Testnet Learn how mainnet and testnet stay separate. Start Mainnet vs Testnet Stafiel keeps mainnet and testnet activity separate. This page explains the difference so your team can decide when to use each mode. Mainnet Mainnet is for real payments. A mainnet checkout can involve real USDT or USDC, real customer orders, real wallet settlement, live webhook delivery, production reporting, and merchant records that may be used for business operations. Merchants may choose to use mainnet when their wallet, payment surfaces, customer notices, event handling, and support workflow are ready for real payments. Testnet Testnet is for testing. It lets your team create checkout sessions, complete test payments, inspect order states, and validate event handling without treating the activity as real customer payment activity. Testnet USDT and USDC are mock tokens. They are not real USDT or USDC and should not be used for accounting, reconciliation, settlement, customer fulfillment, tax records, or production support decisions. What Stays Separate Mainnet and testnet use separate merchant and payment records, including: Merchant profiles, merchant IDs, and merchant settings. API keys and API client mode. Wallet configuration and chain or token enablement. Orders and checkout sessions. Payment, refund, settlement, and contract or on-chain program records. Webhook endpoints, signing secrets, event IDs, and delivery logs. Customer-facing order references. Order reports, exports, invoices, receipts, and settlement records. Treat testnet order IDs, payment records, and webhook events as testing data. What May Be Shared You may use the same Stafiel sign-in account and MFA setup to access both modes. This separation applies to merchant and payment activity, not to creating separate Stafiel user accounts. Mainnet-Only Features Some account-level pages in the Merchant Dashboard, such as plan or billing information, may be available only in mainnet. Testnet is intended for integration and payment-flow testing. Mainnet Readiness Before accepting real payments, it is usually useful to confirm that: You are using the live merchant profile intended for the business. The live merchant wallet is configured and approved for the networks you plan to use. Live API keys are stored on your backend, not in browser code. Live chain labels are used in checkout creation. Live webhook configuration is separate from testnet. Your team can identify Underpaid, Overpaid, Expired, refunded, and Settled orders. For the full operational checklist, see Go-Live Checklist .","section":"Start"},{"slug":"accept-payments/checkout-sessions","title":"Checkout Sessions","description":"Learn how checkout sessions create payment requests.","navOrder":200,"searchText":"accept payments checkout sessions Checkout Sessions Learn how checkout sessions create payment requests. Accept Payments Checkout Sessions A checkout session is the payment request for one merchant order, invoice, or internal reference. It defines the amount, token, network, checkout display, and return path for that payment. Each checkout session maps to one payment request in the merchant system. Before Creating A Checkout Session Before creating a checkout session, set the payment details for the request: Information Requirement What it means Payment amount Required The USDT or USDC amount shown to the customer. Token and network Required A supported USDT or USDC option from Supported Assets and Networks . Metadata Recommended Product name, description, quantity, order ID, invoice ID, booking ID, or customer reference. Return URL Recommended A metadata value that sends the customer back after completing or leaving checkout. Payment window Optional How long the checkout remains usable. If omitted, the default payment window applies. Only supported token and network combinations enabled for the merchant account should be offered to customers. Merchant order or invoice references help match payment status, settlement, invoice, receipt, refund, and support records later. Fixed After Creation After checkout session creation, its payment terms are fixed for that order. Later merchant setting changes apply only to future checkout sessions. Checkout Surfaces After creating a checkout session, choose how customers open it. Hosted Checkout (Redirect) Hosted checkout opens a Stafiel-hosted payment page as a separate browser page or tab. It is best for a complete payment page without building the payment screen inside the merchant site. Customers see the session amount, token, network, payment status, QR code, payment address, payment window, and checkout metadata such as product title, description, and quantity. Redirect: opens the hosted checkout page in a separate browser page or tab. Widget (Modal/Inline/Lite/Micro) Widget places Stafiel checkout inside the merchant site. It is best when customers should open checkout from the merchant page or keep checkout embedded inside that page. Widget modes use the same session amount, token, network, and payment window. Widget has four customer-facing modes: Modal: opens checkout in an overlay above the page. Inline: shows checkout in a larger embedded area inside the page layout. Lite: shows checkout in a compact embedded area. Micro: shows checkout in the smallest embedded area. Use either Checkout Snippet or Embedded Widget with any of these four modes. For checkout snippet and widget implementation details, see Widget Integration . How To Choose A Surface Choose based on where checkout should appear and how much control is needed: Need Recommended surface Why Separate browser page or tab Hosted checkout Use a complete Stafiel-hosted payment page. Fast setup inside the merchant site Checkout snippet Attach checkout to a button, link, or simple page element with fewer setup choices. More control inside the merchant site Embedded widget Use more layout and behavior options for inline areas, compact blocks, or custom storefront layouts. Checkout snippet and Embedded widget are two ways to add Widget checkout to a merchant site. Both can use Modal, Inline, Lite, or Micro mode with a similar checkout appearance and the same core checkout information; the difference is setup simplicity and page control, while the mode should fit the available page space and checkout flow. Next Steps For how customers complete a payment, see Payment Flow . To create sessions from the backend, see Checkout Sessions API .","section":"Accept Payments"},{"slug":"accept-payments/payment-flow","title":"Payment Flow","description":"Understand the customer-facing Stafiel payment flow.","navOrder":220,"searchText":"accept payments payment flow Payment Flow Understand the customer-facing Stafiel payment flow. Accept Payments Payment Flow The payment flow explains what customers see on the Stafiel payment page or widget and how they complete payment after a checkout session is created. 1. Pay From A Wallet The customer sees a checkout waiting for payment: Awaiting Payment: the checkout is open and waiting for payment. The customer can scan the QR code or copy the payment address into a mobile wallet, browser extension wallet, or centralized exchange. Payment must use the selected USDT or USDC token, selected network, and payment address shown on the page or widget. A changed amount, different token, wrong network, or address from another checkout can create a payment exception and may result in lost funds. Important: Customers should not send payment after the payment window expires. Late on-chain transfers are not credited to the order balance and do not enter the settlement flow. For the supported token and network list, see Supported Assets and Networks . For exchange-related refund limitations, see Refund Basics and Payment and Refund Risks . 2. Payment Detected Soon after payment is sent, the customer may see that payment activity has started: Payment Detected: Incoming payment activity appears. The final payment amount and order status are not confirmed yet. Some networks may skip this stage. 3. Payment Received The customer sees the received payment result after the payment receives initial on-chain confirmation. Timing varies by network: Fullpaid: the received amount matches the requested amount. Overpaid: the received amount is above the requested amount; the extra amount can be reviewed for refund once the after-sales window opens, when refunds are available on the selected network. Underpaid: the received amount is below the requested amount; the customer can send an additional payment to the same address during the payment window. Note: For Overpaid or Underpaid orders, the merchant decides the next step: fulfill, hold, review refund availability for the extra amount, request the missing amount during the payment window, or follow up with the customer. 4. Payment Confirmed This stage means the payment has reached the required block confirmation count. Customers do not need to go through this stage directly. It runs in the background and can be viewed in order details in the Merchant Dashboard. Payment Completion Confidence Stage Corresponding order status Completion confidence Customer impression Pay From A Wallet Awaiting Payment Not recorded yet The customer is sending or preparing to send payment. Payment Detected Awaiting Payment Seen on-chain The customer may see that payment activity has started. Payment Received Fullpaid, Overpaid, or Underpaid Amount recorded on-chain The customer sees that the payment has been received and recorded for the order. Payment Confirmed Fullpaid, Overpaid, or Underpaid Confirmed for fulfillment review This runs in the background and can be viewed in Merchant Dashboard order details. For lifecycle details, see Order Lifecycle and Payment Status . 5. Return To Merchant Site After payment is received, the customer can return to the merchant store, order page, invoice flow, or support path via the configured Return URL when it is set correctly.","section":"Accept Payments"},{"slug":"accept-payments/order-lifecycle-and-payment-status","title":"Order Lifecycle and Payment Status","description":"Understand the order lifecycle, payment statuses, and exceptions.","navOrder":230,"searchText":"accept payments order lifecycle and payment status Order Lifecycle and Payment Status Understand the order lifecycle, payment statuses, and exceptions. Accept Payments Order Lifecycle and Payment Status Order lifecycle shows each business stage of a checkout as it moves from an open payment request to an operational outcome. Order Lifecycle Most orders follow this sequence from checkout creation to settlement: Checkout session created: the payment request is ready for the customer to open. This is the start point of the timeline. See Checkout Sessions . Payment window: the checkout waits for payment, and the payment page or widget displays payment progress. Payment activity during this window determines whether the order is Fullpaid, Underpaid, or Overpaid. If no payment is recorded before the window closes, the order can expire. See Payment Flow . Payment setup: the order's on-chain setup is completed through smart contract or on-chain program deployment, with required KYT/AML and related compliance checks. This process is automatic and requires no merchant action. After-sales window: this window starts when payment setup is complete. Refund handling can branch into Partial Refunded or Full Refunded. See Refund Basics . Settlement processing: eligible paid orders move through settlement after the configured after-sales window. Settlement records are available for review. See Settlement Basics . Order Statuses Status Business meaning Awaiting Payment The checkout is open and waiting for the customer to pay. *Payment Detected Incoming payment activity is detected before the final payment result. Fullpaid The recorded payment matches the expected amount. Underpaid The customer sent less than the expected amount. Overpaid The customer sent more than the expected amount. *Payment Confirmed The payment has reached the required network confirmation threshold. Expired The payment window closed while the order was still Awaiting Payment. Settled The order has a recorded settlement. *Partial Refunded A partial refund has been recorded for the order. Full Refunded A full refund has been recorded for the order. Closed The order is closed and no longer acts as an active payment request. Compliance Hold Risk, abuse, security, or compliance controls hold the order for review. Notes: Payment Detected shows that payment activity has started before the final payment result is known. It may appear on the payment page, widget, or webhook events. Payment Confirmed shows that the payment reached the required network confirmations. It appears in Merchant Dashboard order details or webhook events. Partial Refunded shows that part of the payment has been refunded. It appears in Merchant Dashboard order list and order details. When the full payment has been refunded, the order status becomes Full Refunded. This table is a status reference, not the order sequence. For the customer-facing payment flow, see Payment Flow . Expired Orders Or Late Payments An order expires when the payment window closes while it is still Awaiting Payment. Partial payments become Underpaid, not Expired. Do not present an expired checkout as payable. If funds arrive late, review the order, payment records, and support context before deciding whether to fulfill, refund, or take further action. For payment-window guidance, see Payment Flow . For help with a late-payment case, contact Stafiel support . Compliance Hold An order enters Compliance Hold when KYT/AML, risk, abuse, security, or compliance review requires the order to be held. Do not treat a held order as ready for fulfillment, refund, or settlement until the hold is resolved. Where To Observe Status Order status is visible through the Merchant Dashboard , webhook events, or other payment notifications. For technical order fields, see Orders API . For notification delivery, see Webhooks and Events .","section":"Accept Payments"},{"slug":"accept-payments/settlement-basics","title":"Settlement Basics","description":"Understand how customer payments settle to merchant wallets.","navOrder":235,"searchText":"accept payments settlement basics Settlement Basics Understand how customer payments settle to merchant wallets. Accept Payments Settlement Basics Settlement is the step after payment and after-sales handling where eligible paid orders move toward the merchant settlement wallet. Settlement Destination Settlement destination means the merchant wallet and network used when an eligible order settles. Merchant Wallet Boundary Merchant wallet configuration sets the settlement destination. Stafiel does not ask for merchant wallet private keys or custody of the merchant wallet. Captured At Checkout Creation The settlement destination is captured when the checkout session is created. Later wallet configuration changes apply to future checkout sessions, not to existing orders. Network-Specific Settlement Settlement value is not aggregated across networks. Each eligible order settles on the network used by that order to the merchant wallet configured for that network. Normal Settlement Flow After an eligible paid order passes the configured after-sales window, settlement moves the merchant amount through the supported payment rail to the configured merchant wallet. There is no manual merchant claim or withdrawal step in the normal settlement flow. For wallet setup and security boundaries, see Wallet Settings and Security and Wallet Boundary . Platform Fee When a platform fee applies, it is handled as part of the same on-chain settlement transaction. Settlement records show the merchant amount and the platform fee amount separately, so the breakdown is clear. For fee concepts, see Fees and Plan Usage . For operational settlement review, see Settlement Review . For integration details, see Settlements API . Refund Impact Refunds during the after-sales window can change what later settles. A partial refund can leave a remaining amount for settlement. A full refund ends the payment value for that order instead of continuing to settlement. For refund rules, see Refund Basics . Network Differences Settlement behavior can vary by network. Timing, transaction format, transaction costs, and confirmation behavior may not look identical across supported payment rails. These differences do not change the settlement rule: each order settles on the network selected for that order. Settlement Completion Settlement completion means the order's settlement record shows a settled result. Before that, Merchant Dashboard may show the order as waiting for settlement or pending settlement verification. Settlement is not instant. It follows payment confirmation, the configured after-sales window, required KYT/AML and related compliance checks, network processing, and platform settlement processing.","section":"Accept Payments"},{"slug":"accept-payments/refund-basics","title":"Refund Basics","description":"Understand refund availability and original-route refunds.","navOrder":240,"searchText":"accept payments refund basics Refund Basics Understand refund availability and original-route refunds. Accept Payments Refund Basics Refund Basics explains when a Stafiel checkout can use a supported original-route refund based on the network, order state, configured after-sales window, refundable amount, and how the customer originally paid. Original-Route Refunds Supported refunds return value to the original on-chain payment source, not to a new payout address. In plain terms, the original payment source is the wallet address that sent the payment on-chain. This keeps the refund path aligned with the payment path for anti-abuse, AML, and operational traceability. Refunds are not a general-purpose payout tool. They are used to unwind a supported payment when the original payment source can receive returned value. After-Sales Window Merchant-initiated refunds use the configured after-sales window captured when the checkout session is created. Later merchant setting changes apply to future checkout sessions, not to existing orders. After the payment window ends, Stafiel completes payment setup automatically. The after-sales window opens when payment setup is complete. Refund availability still depends on network support, refundable amount, and whether a refund has already been recorded. Once the after-sales window closes, the order is no longer eligible for a merchant-initiated on-chain refund. For the larger order timeline, see Order Lifecycle and Payment Status . Refund Amount And Status The refund amount cannot exceed the payment value actually received for the order. For original-route refunds, each payment source can receive back no more than it paid. Note: A merchant-initiated refund can be performed only once for a checkout. A partial refund counts as that one merchant-initiated refund. After a partial refund, the remaining payment value determines the order status: Fullpaid when it matches the requested amount, Underpaid when it is below the requested amount, and Overpaid when it remains above the requested amount. The remaining value can continue through the normal downstream flow when the order is otherwise eligible. Merchant Dashboard may also show Partial Refunded to indicate that a partial refund was recorded. When the full payment has been refunded, the order becomes Full Refunded and no remaining payment value continues to settlement. For settlement impact, see Settlement Basics . Network Support Only supported networks can use Stafiel's on-chain refund flow. Refund capabilities differ by network and payment rail. The table below describes network-level support only; each refund still depends on order state, the after-sales window, refundable amount, and refund history. Network On-chain refund support Notes Ethereum Supported Original-route refunds can be used when the order is eligible. Base Supported Original-route refunds can be used when the order is eligible. BNB Chain Supported Original-route refunds can be used when the order is eligible. Polygon Supported Original-route refunds can be used when the order is eligible. Solana Supported Original-route refunds can be used when the order is eligible. Tron Not supported Stafiel's on-chain refund flow is not available on Tron. Businesses that accept Tron payments should account for that limitation in refund policy and customer support. Centralized Exchange And Custodial Wallet Risk If a customer pays from a centralized exchange withdrawal flow or some custodial wallet flows, the original on-chain source address is usually not controlled by the customer. An original-route refund returns value to that on-chain source, which may not return the value to the customer's account. These customer-side recovery cases are outside Stafiel's refund scope. For more detail, see Payment and Refund Risks . Merchant Policy The merchant remains responsible for refund approval, customer communication, refund policy, and handling cases where an on-chain refund is unavailable or where a centralized exchange or custodial wallet payment creates customer-side recovery issues. Note: Merchant-initiated on-chain refunds require the merchant to pay the applicable network transaction cost, such as a gas fee or transaction fee. For Merchant Dashboard steps, see Refund Operations . For integration refund status and history checks, see Refunds API . Platform-Initiated Refunds Stafiel may, where appropriate or required, perform a platform-initiated refund for legal, regulatory, sanctions, compliance, risk, security, dispute resolution, service integrity, or operational reasons.","section":"Accept Payments"},{"slug":"merchant-operations/dashboard","title":"Dashboard Navigation","description":"Find where core Merchant Dashboard workflows live.","navOrder":300,"searchText":"merchant operations dashboard Dashboard Navigation Find where core Merchant Dashboard workflows live. Merchant Operations Dashboard Navigation This page maps the main Merchant Dashboard navigation to the workflows merchants use most often. Main Navigation Navigation item Use it to Dashboard Review key payment metrics, order status mix, and recent activity at a glance. Merchants Create merchants and configure wallets, chains, API keys, order defaults, webhooks, and return URLs. Orders Find checkout sessions, review Order Details, and export records. Statistics Compare order, amount, chain, token, weekly, and recent activity statistics. Settings Open Profile, Subscription Plan & Tiers, Configuration, or Network Mode. Check The Current Mode Confirm the selected mode before making changes. Mainnet is for real payments, while testnet is visually marked in the dashboard and works as a sandbox for setup and testing. Actions apply only to the selected mode, and merchant, wallet, API key, order, and payment data remain separate between the two modes. For the product-level differences, see Mainnet vs Testnet . Dashboard Summary The Dashboard is the landing view. Its Recent Activity panel shows only the last 7 days of account activity. Continue with Merchant Setup before accepting the first payment.","section":"Merchant Operations"},{"slug":"merchant-operations/merchant-setup","title":"Merchant Setup","description":"Prepare a merchant profile before accepting payments.","navOrder":310,"searchText":"merchant operations merchant setup Merchant Setup Prepare a merchant profile before accepting payments. Merchant Operations Merchant Setup Create a merchant to configure wallets and accept payments. Each merchant has its own profile, settings, orders, and mainnet or testnet records. Create A Merchant Open Merchants , then select Create Merchant . Field Requirement Purpose Merchant Name Required Internal merchant name used in Merchant Dashboard. Public Display Name Recommended Customer-facing name shown on payment pages, receipts, and invoices. Description Optional Internal description for identifying the merchant. Supported Chains Required Select the chains the merchant plans to use. Available options can depend on the current plan and mode. After creation, open the merchant to review its Merchant ID, current status, and setup tabs. Merchant ID The Merchant ID identifies the merchant in the selected mode. Use it when an integration, support request, or dashboard record needs a merchant reference. Mainnet and testnet Merchant IDs are separate. Confirm the current mode before copying an ID. Merchant Status The merchant card shows the current operational status: Status Meaning Configuration Required Required setup is not complete. Partial Active Some approved chains are ready to accept payments, while other selected chains still need setup or review. Active All approved chains for the merchant are ready to accept payments. Suspended New orders are disabled until the merchant is reactivated and its wallets and chains are verified again. Terminated The merchant is permanently unavailable. Merchant Details Setup Open a merchant to view Merchant Details . The tabs separate profile review, payment setup, and integration settings: Tab Use it to Basic Info Review or update the merchant name, public display name, description, and Merchant ID. API Key Management Create and revoke API keys for server-side API integration. Wallet Settings Connect and verify settlement wallet addresses for the required chains. Merchant Settings Set return URL rules, webhook delivery settings, order defaults, and status actions. Chains & Tokens Review enabled networks, approval status, token standard, supported tokens, and minimum order amount. Wallet settings are covered in Wallet Settings . API keys and webhooks are covered in API Keys and Authentication and Webhooks and Events . Basic Info Open Basic Info to update the merchant name, public display name, or description. The Merchant ID remains the stable identifier for integrations, support requests, and dashboard records. API Key Management Open Merchants > select merchant > API Key Management . API Key Management is available when the merchant status is Partial Active or Active . To create a key, select Create Key , enter a key name, and complete MFA when requested. Important: Save the full API key securely when it is created. It is shown only once, and later views show only a preview. Revoke a key when it is no longer used or may have been exposed. Revocation is immediate, and integrations using that key stop working. The allowed number of active keys varies by plan. Wallet Settings Wallet Settings connects the merchant settlement wallet address for each required chain. A verified wallet address is required before that chain can accept new orders for the merchant. For setup steps, verification rules, wallet address changes, and limitations, see Wallet Settings . Return URL Settings Open Merchants > select merchant > Merchant Settings > Return URL Settings to control where customers can return after paying on the Stafiel checkout page. Allowed Return Origins accepts exact HTTPS origins and supported wildcard patterns for subdomains. For example, https://*.example.com allows return URLs from subdomains such as https://shop.example.com . Allow all URLs allows return URLs supplied with checkout sessions without requiring a match against the allowed origins list. If Allow all URLs is off and no allowed origin is configured, checkout does not use the metadata.returnToUrl value. See Metadata Reserved Fields and Rules . Webhook Configuration Open Merchants > select merchant > Merchant Settings > Webhook Configuration to add the HTTPS endpoint that receives payment lifecycle notifications. When a webhook URL is saved for the first time, a signing secret is generated automatically. Use Test URL to check whether the HTTPS endpoint is reachable. This check does not send a webhook event. The secret signs webhook requests for verification. Rotating it replaces the current secret immediately, so update the receiving system at the same time. Order Defaults Open Merchants > select merchant > Merchant Settings > Order Defaults to set the default payment window and after-sales window for new checkout sessions. Setting What it controls Payment window How long a checkout session stays payable before it expires. This value can be changed when creating a checkout session. After-sales window How long the merchant can handle refunds before settlement. Merchant Dashboard shows the allowed range for each setting. Changes apply only to future checkout sessions. Existing orders keep their saved values. Merchant Status Actions Open Merchants > select merchant > Merchant Settings > Danger Zone to suspend, reactivate, or terminate a merchant. Suspend disables new orders. Existing orders continue using their recorded settlement data. All enabled-chain wallet bindings are revoked. Reactivation requires wallet reconnection, ownership verification, and review. Terminate permanently disables the merchant. All API keys are revoked. Termination is allowed only when no live orders remain. Note: Review the confirmation message before continuing. Termination cannot be undone.","section":"Merchant Operations"},{"slug":"merchant-operations/account-access","title":"Account and MFA","description":"Manage sign-in, account profile, and MFA controls.","navOrder":320,"searchText":"merchant operations account access Account and MFA Manage sign-in, account profile, and MFA controls. Merchant Operations Account and MFA Merchant Dashboard supports account sign-in through Google or GitHub. Use this page to understand the account profile and MFA controls. Account Profile Open Settings > Profile to review account information and MFA status. The Profile tab shows the User ID, account name, email address, and MFA status. Copy the User ID when support or an account-specific operation asks for it. Enable MFA Merchant Dashboard may ask for a fresh six-digit MFA code before sensitive operations. Select Enable MFA and complete the setup: Scan the QR code with an authenticator app, or enter the displayed setup key. Enter the six-digit authentication code. Save the backup code securely. Important: The backup code can be used for account recovery or MFA reset. Do not store it in shared notes, source code, or public issue trackers. Reset MFA Select Reset MFA from the Profile tab. Reset can require either: A current authenticator code The saved backup code After reset, bind a new authenticator device and save the new backup code. The previous backup code becomes invalid after reset or regeneration. Temporary cooldowns may apply after repeated or recovery-sensitive actions. For wallet-specific security boundaries, see Security and Wallet Boundary .","section":"Merchant Operations"},{"slug":"merchant-operations/wallet-settings","title":"Wallet Settings","description":"Configure the wallet addresses that receive merchant funds.","navOrder":330,"searchText":"merchant operations wallet settings Wallet Settings Configure the wallet addresses that receive merchant funds. Merchant Operations Wallet Settings Wallet Settings configures the self-custodial wallet addresses that receive settlement funds and shows whether each supported chain is ready for new checkout sessions. The merchant must control each wallet and be able to sign with it for ownership verification. Supported Wallet Types Merchant Dashboard uses one wallet address for each supported wallet type: Wallet type Used for EVM Ethereum, Base, Polygon, BNB Smart Chain, and other supported EVM-compatible chains. Solana Solana payments using supported SPL tokens. Tron Tron payments using supported TRC-20 tokens. Use self-custodial browser extension crypto wallets for wallet verification. A multi-chain wallet that supports EVM, Solana, and Tron, such as Binance Wallet or OKX Wallet, can cover all three wallet types. Alternatively, use separate wallets for the chains being enabled, such as MetaMask for EVM, Phantom for Solana, and TronLink for Tron. Connect And Verify A Wallet Address Connect and verify each settlement wallet in Wallet Settings : Open Merchants > select merchant > Wallet Settings . Choose the chain and start the wallet connection. Connect a supported browser extension crypto wallet. Review the wallet address shown in Merchant Dashboard. Sign the ownership verification message in the wallet. Important: The signature only verifies control of the wallet address. It does not authorize transactions or access to funds, approve token spending by a smart contract or on-chain program, trigger an on-chain transfer, or charge a network transaction fee. Stafiel does not request or store the merchant wallet private key. Wallet verification and wallet changes are sensitive operations and require MFA verification. See Account and MFA . Submit Wallet Address For Review And Check Chain Readiness After wallet ownership is verified: Select Submit for Review for that chain. The verified wallet address and merchant information undergo Know Your Wallet (KYW) screening, Anti-Money Laundering (AML) screening, and related compliance and risk checks. Wallet Settings shows PENDING REVIEW while review is in progress. After the wallet address is APPROVED , new checkout sessions can be created for that chain when it is activated and allowed by the current plan. A rejected review must be resolved and submitted again before that chain can be used for new checkout sessions. Activate Or Suspend A Chain EVM is enabled by default and cannot be suspended from Wallet Settings. Solana and Tron can be activated or suspended when allowed by the current plan. Suspending Solana or Tron prevents new checkout sessions from using that wallet type, revokes its current wallet address, and resets its approval status. Reactivation requires reconnecting the wallet, verifying ownership, and submitting the chain for review again. Existing orders retain the wallet and payment configuration saved when they were created. Change A Settlement Wallet A newly verified wallet applies to future checkout sessions. Existing orders keep the settlement wallet recorded when the checkout was created. After a wallet address is approved, binding a different address is subject to a wallet-change cooldown. Rebinding the same address does not require that cooldown. A changed address requires a new ownership signature and chain review. Important: Centralized exchange deposit addresses are not supported as merchant settlement wallets. For settlement behavior, see Settlement Basics . For the security model, see Security and Wallet Boundary .","section":"Merchant Operations"},{"slug":"merchant-operations/orders","title":"Orders","description":"Review and filter orders, create checkout sessions, and export records.","navOrder":340,"searchText":"merchant operations orders Orders Review and filter orders, create checkout sessions, and export records. Merchant Operations Orders Use Orders to review and filter orders, create checkout sessions, export records, and test API requests. Order List Switch between Card View for grouped orders and Table View for compact rows. Review key payment details and available actions in either view. A Partial Refunded marker can appear alongside the main order status. Available actions depend on the order data and selected view. Action Purpose Open Order Details Review the complete order record and available operations. Copy Order ID Copy the full order identifier. Copy Payment Address Copy the address assigned to the order. Open Explorer View the payment address on the relevant blockchain explorer. Open Payment Page Open the customer payment page. For status meanings, see Order Lifecycle and Payment Status . Filter And Export Orders Filter and sort orders to narrow the list. Remember filters saves the current filters and view settings in this browser when functional preferences are enabled. Use Export CSV to download filtered orders for reconciliation or record review. Exports contain records from the selected mode only, so keep mainnet and testnet exports separate. Order Details Open Order Details from either Card View or Table View . The dialog includes these tabs: Tab Information shown Basic Information Requested amount, chain, token, payment address, payment timing, received and refunded totals, payment page, and QR codes. Payment Records Detected payment transactions, amounts, payment status, transaction hashes, and timing. Contract Deployment Payment setup status, payment address, token address, processing time, and explorer links. Fee Details Fee Rate, Min Fee, and Max Fee saved for the order. See Fees and Plan Usage . Refund Refund eligibility, available amount, payment sources, refund action, and refund history. See Refund Operations . Settlement Settlement availability, merchant amount, platform fee, destination address, settlement time, and transaction reference. See Settlement Review . Metadata Metadata saved with the checkout session. Invoice & Receipt Invoice and receipt status, files, and document actions. Create A Checkout Session Use Create Checkout Session to generate a payment request from the dashboard for a specific merchant, network, token, and amount. The resulting payment page can be shared with the payer and tracked as an order. The selected merchant determines the available networks, tokens, amount limits, and payment-window limits. The new checkout session appears in the order list for monitoring and follow-up. For checkout behavior, payment surfaces, and field details, see Checkout Sessions . API Request Tester Use API Request Tester to send real merchant API requests from the dashboard before implementing a backend integration. Requests use the selected mode, and creating a checkout session creates an order in that mode. Switching between mainnet and testnet clears entered values and previous responses. Use the links below for implementation details: Checkout Session : Checkout Sessions API Query Order : Orders API Payments : Payments API Contract Status : Contract Status API Refund Status : Refunds API Refund History : Refunds API Settlement History : Settlements API Invoice & Receipt : Invoice and Receipt API For shared authentication requirements, see API Keys and Authentication .","section":"Merchant Operations"},{"slug":"merchant-operations/settlement","title":"Settlement Review","description":"Review settlement records in the Merchant Dashboard.","navOrder":350,"searchText":"merchant operations settlement Settlement Review Review settlement records in the Merchant Dashboard. Merchant Operations Settlement Review Use Settlement Review to understand what the Settlement tab shows for an order in Merchant Dashboard. Before A Settlement Result Appears Open Order Details , then open the Settlement tab. Before a completed settlement result is available, the tab can show these notices depending on the settlement flow: Notice Meaning Contract Not Ready Required order preparation is not complete. Sweep unlock scheduled The order has not reached the displayed settlement availability time. Settlement is in queue Settlement processing is waiting for a completed result. Settlement Pending Verification A settlement record exists and is still being verified. These notices do not mean settlement is complete. Completed Settlement Details When settlement is complete and verified, the tab can show: Field Meaning Settlement Status Settlement result displayed for the order. A Verified badge appears beside it after verification succeeds. Received Actual token amount sent to the merchant settlement wallet. Platform Fee Token amount handled as the platform fee in the same settlement transaction. Settlement Time Recorded completion time. Merchant Address Destination wallet saved for the order. Transaction Hash Blockchain transaction for the settlement; use it to open the transaction in an explorer. After the result appears, compare the settlement details with the order's Basic Information. If the order had a partial refund, the Received value reflects the remaining settlement amount sent to the merchant wallet after the refund and platform fee split, not the original checkout amount. For the fee rules saved at order creation, see Fees and Plan Usage . For the business flow, see Settlement Basics . For API records, see Settlements API .","section":"Merchant Operations"},{"slug":"merchant-operations/fees-and-plan-usage","title":"Fees and Plan Usage","description":"Review order-level fee details, platform fees, and plan usage.","navOrder":360,"searchText":"merchant operations fees and plan usage Fees and Plan Usage Review order-level fee details, platform fees, and plan usage. Merchant Operations Fees and Plan Usage Use Fees and Plan Usage to review the Fee Details tab for an order and the Subscription Plan & Tiers page in Merchant Dashboard. Order Fee Details Open Order Details , then open the Fee Details tab to review the Fee Rate, Min Fee, and Max Fee saved for that order. These values are saved when the order is created. Later plan or fee changes apply to new orders and do not rewrite an existing order. Fee Details shows the saved fee rules. Open the Settlement tab to review the platform fee amount recorded after settlement is complete. To read the Settlement tab itself, see Settlement Review . For the settlement flow, see Settlement Basics . Subscription Overview Open Settings > Subscription Plan & Tiers to review current period plan usage. In mainnet mode, the Subscription Overview can show: Area Meaning Plan and tier Current active plan and tier, when available. Time period Current period and next billing date. Fee rates by chain Chain, Fee Rate, Min Fee, and Max Fee. Quota Remaining order creation and order deployment quota. Settled volume USD settled and Orders settled in the current period. Higher tiers unlock lower fee rates. Move up when settled volume and settled order count both reach the next tier's requirements. The tier is recalculated each period. Where the dashboard labels values in USD, USDT and USDC are valued one-to-one with the US dollar. Testnet Usage In testnet mode, Subscription Plan & Tiers shows testnet usage quotas separately from mainnet subscription plan usage: Active merchants: testnet merchants counted against the active merchant limit. Live orders: open and unfinished testnet orders counted against the live order limit. Testnet usage does not count as mainnet billing or settled payment volume.","section":"Merchant Operations"},{"slug":"merchant-operations/refund-operations","title":"Refund Operations","description":"Operate supported refunds from the Merchant Dashboard.","navOrder":370,"searchText":"merchant operations refund operations Refund Operations Operate supported refunds from the Merchant Dashboard. Merchant Operations Refund Operations Use Refund Operations to review the Refund tab in Order Details and execute a merchant-initiated refund when the order supports it. Check Refund Availability Open Order Details , then open the Refund tab to review refund readiness: Contract Status : shows Deployment Status , Refund Window , Refundable , and Refund window closes at when available. In this tab, Refund Window means the order's after-sales window. Merchant Details : order ID and merchant wallet address saved for the order. User Payments : payer addresses, received amounts, payment timing, and payment transactions. Refund History : merchant refund records and platform-initiated refunds, when available. If refund is unavailable, the tab can show notices such as Contract Not Ready , Refund Not Ready , Refund Not Supported , or No Payments Found . Note: The Refund tab permits only one merchant-initiated refund for a checkout. A partial refund uses that one refund action. Execute The Refund When the refund action is available: Open Order Details , then open the Refund tab. Complete merchant wallet verification if Merchant Dashboard asks for it. Use the User Payments table to review From Address , Original , Refund , Date , and Transaction , then select the payment sources and refund amounts. Use Refund This , Refund All , Clear , or Clear All as needed, then review Selected Payments and Total Amount . The total refund amount cannot be higher than the order's remaining refundable amount. Complete any network switch prompt shown by Merchant Dashboard. Select Execute Refund , review Confirm Refund Execution , then select Confirm & Execute . Confirm the transaction in the wallet, then keep Merchant Dashboard open until Refund Transaction Submitted or a current refund status appears. Note: Merchant-initiated on-chain refunds require the merchant to pay the applicable network transaction cost, such as a gas fee or transaction fee. Refund History The tab can show Refund History for merchant refund records and Platform Refund History for platform-initiated refunds. Platform-initiated refunds do not require merchant action. Entries can show: Refund amount Refund recipients Transaction hash Attempt time Current status If the refund transaction fails on-chain or is reverted, Retry Refund can create a new refund transaction. If the refund has succeeded on-chain, do not execute another merchant refund. Centralized Exchange Payments Refunds return to the original payment address. If that address belongs to a centralized exchange, the refund may not appear in the customer's exchange account. Customer-side exchange account recovery is outside Stafiel's refund scope. For the business rules and network support table, see Refund Basics . For operational risks, see Payment and Refund Risks .","section":"Merchant Operations"},{"slug":"merchant-operations/statistics","title":"Statistics","description":"Review merchant, order, amount, chain, token, and activity statistics.","navOrder":380,"searchText":"merchant operations statistics Statistics Review merchant, order, amount, chain, token, and activity statistics. Merchant Operations Statistics Use Statistics to review Merchant Dashboard totals for merchants, orders, order amounts, chains, tokens, and recent activity. Key Metrics Overview Key Metrics Overview provides a quick status check across: Total Merchants Total Orders Orders (24h) Settled (24h) Live Orders Filter Statistics Use the merchant filter to view statistics for all accessible merchants or one merchant. Most sections support Card View , Table View , or Chart View . Recent Activity supports Table View and Chart View . The selected view changes the presentation, not the underlying totals. Merchant Overview Merchant Overview groups merchant profiles by current status: Active Pending Suspended Terminated Order Overview Order Overview shows total orders and current status distribution (see Order Lifecycle and Payment Status for status meanings), with merchant comparison when all merchants are selected: Awaiting Payment Paid Settled Expired Full Refunded Compliance Hold Closed Order Amounts (USD) Order Amounts (USD) summarizes dollar-denominated order values by chain and status; values labeled in USD treat USDT and USDC one-to-one with the US dollar: Total Awaiting Payment Paid Settled Weekly Order Trends Weekly Order Trends compares Orders by Day and Amounts by Day (USD) for the selected week across: Created Paid Settled Chain Breakdown Chain Breakdown compares chain-level order totals: Total Orders Orders (24h) Settled (24h) Live Orders Token Mix Token Mix compares USDC and USDT recorded order distribution, not wallet balances, across: Total Mix By Chain Recent Activity Recent Activity lists recent account and merchant operations and can filter by: Action Target Merchant For order-level review, exports, and reconciliation, see Orders .","section":"Merchant Operations"},{"slug":"developer-integration/api-keys-and-authentication","title":"API Keys and Authentication","description":"Authenticate server-side merchant API requests with API keys.","navOrder":400,"searchText":"developer integration api keys and authentication API Keys and Authentication Authenticate server-side merchant API requests with API keys. Developer Integration API Keys and Authentication Use API keys for server-to-server merchant API calls. Keep keys on your backend only. Do not place them in browser JavaScript, mobile apps, checkout pages, or client-side widget configuration. Base URL https://api.stafiel.com Request Headers Every API key request must include the authentication and client-mode headers. Requests with JSON bodies must also include Content-Type: application/json . Header Required Default Description X-API-Key Yes None Merchant API key created in the Merchant Dashboard. Keep this value server-side only. X-App-Client Yes None Request mode identifier. Use merchant-client for live API keys. Content-Type Required for requests with a body None Use application/json when sending a JSON request body, such as checkout session creation. Live API keys must use X-App-Client: merchant-client . Test API keys must use X-App-Client: merchant-client-testnet . If the key mode and header mode do not match, Stafiel returns 401 AUTH_FAILED . Header Example X-API-Key: mk_live_your_api_key X-App-Client: merchant-client Content-Type: application/json Merchant ID Most order endpoints require merchantId . The value must match the merchant bound to the API key. Requests for another merchant are rejected. Rate Limits API key requests are rate limited. Limits may vary by endpoint, merchant, request mode, plan, traffic pattern, and operational risk controls. When a request is rate limited, the API returns 429 RATE_LIMIT_EXCEEDED . If the response includes Retry-After or rate-limit reset headers, wait for the indicated time before retrying. Design your integration to retry with backoff, avoid tight polling loops, and reuse idempotency keys when retrying checkout session creation. Key Management Create, rotate, and revoke API keys from the Merchant Dashboard. Store API keys in a secret manager or server environment variable. Rotate a key immediately if it may have been exposed.","section":"Developer Integration"},{"slug":"developer-integration/checkout-api","title":"Checkout Sessions API","description":"Create checkout sessions from your backend.","navOrder":410,"searchText":"developer integration checkout api Checkout Sessions API Create checkout sessions from your backend. Developer Integration Checkout Sessions API Create a checkout session from your backend when your customer is ready to pay. The response contains a hosted checkout URL that you can redirect to, open in a new tab, or pass to the Stafiel widget. Endpoint POST /api/v1/checkout/sessions Request Fields Field Required Default Description merchantId Yes None Must match the merchant bound to the API key. chainName Yes None Mainnet chain label. See Chain Labels . tokenSymbol Yes None Use USDC or USDT , subject to the selected chain and merchant configuration. amountUsd Yes None Dollar-denominated checkout amount as a string. Use at most 2 decimal places, such as 49 , 49.9 , or 49.90 ; extra decimal places are rejected. expiresIn No Merchant default Payment window in seconds. The value must be inside the merchant's configured allowed range. idempotencyKey No None Recommended. Use your internal order ID so retries do not create duplicate checkout sessions. metadata No None Your own order reference, customer reference, return URL, or other non-sensitive metadata. See Metadata Reserved Fields and Rules . Chain Labels Use these mainnet chainName values when creating live checkout sessions: chainName Chain ID Description eth 1 Ethereum mainnet for USDT and USDC payments. base 8453 Base mainnet for lower-cost EVM payments. bsc 56 BNB Smart Chain mainnet for EVM payments. polygon 137 Polygon mainnet for EVM payments. solana 101 Solana mainnet for SPL stablecoin payments. tron 728126428 Tron mainnet for TRC20 stablecoin payments. Available chains and tokens depend on merchant configuration. Request Example The example includes the currently supported reserved metadata fields. curl -X POST https://api.stafiel.com/api/v1/checkout/sessions \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"merchantId\": \"mch_your_merchant_id\", \"chainName\": \"base\", \"tokenSymbol\": \"USDC\", \"amountUsd\": \"49.00\", \"expiresIn\": 1800, \"idempotencyKey\": \"order_10001\", \"metadata\": { \"returnToUrl\": \"https://merchant.example.com/orders/10001\", \"productName\": \"Annual Pro Plan\", \"productDescription\": \"One-year subscription for the merchant workspace.\", \"quantity\": \"1\", \"unitLabel\": \"year\", \"customerReference\": \"CUS-8842\" } }' Success Response { \"success\": true, \"data\": { \"orderId\": \"ord_your_order_id\", \"status\": \"awaiting_payment\", \"checkoutSessionUrl\": \"https://pay.stafiel.com/pay/ps_live_example\", \"expiresAt\": \"2026-05-19T12:00:00.000Z\", \"amountUsd\": \"49.00\", \"chainName\": \"base\", \"tokenSymbol\": \"USDC\", \"tokenAddress\": \"0x...\" } } Response Fields Field Type Description orderId string Stafiel order ID for later order, payment, refund, settlement, and document lookups. status string Initial order status. New checkout sessions return awaiting_payment . checkoutSessionUrl string Hosted checkout URL. Treat it as opaque and use it exactly as returned. expiresAt string ISO 8601 timestamp when the checkout session expires. amountUsd string Accepted checkout amount, stored with up to 2 decimal places. chainName string Canonical public chain label used for the checkout session. tokenSymbol string Token symbol selected for the checkout session. tokenAddress string Token contract or mint address used for the selected chain. Treat checkoutSessionUrl as opaque. Do not build payment URLs yourself. Idempotency Key idempotencyKey provides short-window duplicate protection for checkout session creation retries. A stable internal order ID is a good key because it maps one merchant-side order attempt to one checkout creation attempt. Rules: Use 1-128 visible ASCII characters. Reuse the same key when retrying the same request. Do not reuse the same key for a different checkout payload. If the same key is already being processed, or if the key is reused with a conflicting payload, the API returns 409 CHECKOUT_SESSION_CREATE_FAILED . Do not use idempotency keys as a permanent order lookup mechanism. Metadata Reserved Fields and Rules metadata is an optional JSON object for merchant business context, such as your internal order ID or customer reference. Do not put secrets, private keys, access tokens, full payment credentials, or unnecessary sensitive personal data in metadata. Stafiel currently interprets these reserved metadata fields for checkout return behavior, hosted checkout display, and generated documents: Field Required Default Description metadata.returnToUrl No None Checkout return URL, used only when allowed by the merchant return URL policy. metadata.productName No None Product or service name for hosted checkout and documents. metadata.productDescription No None Short product or order description for hosted checkout and documents. metadata.quantity No None Product quantity for hosted checkout and documents. metadata.unitLabel No None Unit label after quantity, such as seat , month , or year . General metadata rules: Use a flat object. Nested objects and arrays are ignored. Stafiel stores up to 20 accepted top-level fields, processed in request object order. Invalid fields are ignored and do not count toward the limit. Keys must be 1-100 characters and may use ASCII letters, numbers, dots, underscores, and hyphens. Values may be strings, finite numbers, booleans, or null . Objects, arrays, invalid values, and unsupported value types are ignored. String values may be up to 1,000 characters and may contain letters, numbers, punctuation, spaces, and line breaks. metadata.returnToUrl rules: The value must be an absolute https:// URL. Unsafe or blocklisted URLs are rejected. If the URL is not allowed by merchant return URL policy, it will not be used. Error Responses Error responses use this shape: { \"success\": false, \"error\": { \"code\": \"VALIDATION_ERROR\", \"message\": \"Invalid request\" } } HTTP Status Code Meaning 400 CHECKOUT_SESSION_CREATE_FAILED / ORDER_EXPIRES_IN_OUT_OF_RANGE Requ","section":"Developer Integration"},{"slug":"developer-integration/orders-api","title":"Orders API","description":"Query order lists and order details through the API.","navOrder":420,"searchText":"developer integration orders api Orders API Query order lists and order details through the API. Developer Integration Orders API Use the Orders API to list orders and retrieve a single order's current business state. List Orders Endpoint GET /api/v1/orders Query Parameters Field Required Default Description merchantId Yes None Merchant ID bound to the API key. page No 1 Page number. Starts from 1 . pageSize No 20 Number of orders per page. Maximum 100 . status No None Comma-separated order statuses, such as awaiting_payment , underpaid , fullpaid , overpaid , expired , settled , full_refunded , closed , or compliance_hold . chainName No None Comma-separated chain labels. orderId No None Search by Stafiel order ID or merchant business order reference. contractAddress No None Filter by payment contract or payment address. createdAtFrom No None ISO 8601 lower bound for order creation time. createdAtTo No None ISO 8601 upper bound for order creation time. sortBy No createdAt Use createdAt , status , or amount . sortOrder No desc Use asc or desc . Request Example curl \"https://api.stafiel.com/api/v1/orders?merchantId=mch_your_merchant_id&page=1&pageSize=20&status=fullpaid,settled&chainName=base,eth\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" List Success Response { \"success\": true, \"data\": { \"items\": [ { \"orderId\": \"ord_your_order_id\", \"merchantId\": \"mch_your_merchant_id\", \"status\": \"fullpaid\", \"amountUsd\": \"49.00\", \"totalPaidAmountUsd\": \"49.00\", \"chainName\": \"base\", \"chainId\": 8453, \"tokenSymbol\": \"USDC\", \"tokenAddress\": \"0x...\", \"tokenDecimals\": 6, \"orderAddress\": \"0x2222222222222222222222222222222222222222\", \"paymentUrl\": \"https://pay.stafiel.com/pay/ps_live_example\", \"expiresAt\": \"2026-05-19T12:30:00.000Z\", \"createdAt\": \"2026-05-19T12:00:00.000Z\", \"updatedAt\": \"2026-05-19T12:05:00.000Z\", \"metadata\": { \"customerReference\": \"CUS-8842\" } } ], \"chains\": [], \"total\": 1, \"page\": 1, \"pageSize\": 20, \"hasMore\": false, \"createdAtFrom\": null, \"createdAtTo\": null, \"merchantId\": \"mch_your_merchant_id\" } } List Response Fields Field Type Description items array Orders visible to the API key for the requested merchant and filters. chains array Chain metadata included for filter or display context. API integrations may ignore it. total number Total matching order count. page number Current page number. pageSize number Number of orders requested per page. hasMore boolean Whether another page of results is available. createdAtFrom string or null Applied lower creation-time filter. createdAtTo string or null Applied upper creation-time filter. merchantId string Merchant ID for single-merchant API key responses. Pagination Notes List responses use page-based pagination. For batch syncs, set createdAtTo at the start of the sync and keep that value while reading subsequent pages. This prevents newly created orders from changing the result window while your sync is in progress. Order Item Fields Field Type Description orderId string Stafiel order ID. merchantId string Merchant ID that owns the order. status string Current business status of the order. amountUsd string or null Original checkout amount. totalPaidAmountUsd string or null Total recorded payment amount when token decimals are known. chainName string or null Canonical public chain label. chainId number or null Numeric chain ID when available. tokenSymbol string or null Token symbol for the order. tokenAddress string or null Token contract or mint address. tokenDecimals number or null Token decimals used for amount formatting. orderAddress string or null Payment contract or payment address. paymentUrl string or omitted Hosted checkout URL, if still available for the order. expiresAt string ISO 8601 expiration timestamp. createdAt string ISO 8601 creation timestamp. updatedAt string ISO 8601 update timestamp. metadata object or null Sanitized order metadata. Get Order Details Endpoint GET /api/v1/orders/{orderId} Parameters Field Required Default Description orderId Yes None Path parameter. Stafiel order ID or supported order reference. merchantId Yes None Query parameter. Merchant ID bound to the API key. Request Example curl \"https://api.stafiel.com/api/v1/orders/ord_your_order_id?merchantId=mch_your_merchant_id\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" Detail Success Response { \"success\": true, \"data\": { \"orderId\": \"ord_your_order_id\", \"merchantId\": \"mch_your_merchant_id\", \"status\": \"fullpaid\", \"amountUsd\": \"49.00\", \"totalPaidAmountUsd\": \"49.00\", \"chainName\": \"base\", \"chainId\": 8453, \"tokenSymbol\": \"USDC\", \"tokenAddress\": \"0x...\", \"tokenDecimals\": 6, \"orderAddress\": \"0x2222222222222222222222222222222222222222\", \"paymentUrl\": \"https://pay.stafiel.com/pay/ps_live_example\", \"expiresAt\": \"2026-05-19T12:30:00.000Z\", \"createdAt\": \"2026-05-19T12:00:00.000Z\", \"updatedAt\": \"2026-05-19T12:05:00.000Z\", \"metadata\": { \"customerReference\": \"CUS-8842\" } } } Detail Response Fields Field Type Description orderId string Stafiel order ID. merchantId string Merchant ID that owns the order. status string Current business status of the order. amountUsd string Original checkout amount. totalPaidAmountUsd string Total recorded payment amount displayed to 2 decimals. chainName string Canonical public chain label. chainId number or null Numeric chain ID when available. tokenSymbol string Token symbol for the order. tokenAddress string or null Token contract or mint address. tokenDecimals number or null Token decimals used for amount formatting. orderAddress string or null Payment contract or payment address. paymentUrl string or omitted Hosted checkout URL, if still available for the order. expiresAt string ISO 8601 expiration timestamp. createdAt string ISO 8601 creation timestamp. updatedAt string ISO 8601 update timestamp. metadata object or null Sanitized order metadata. Order Statuses The status field can use these values. Do not assume status changes are strictly linear; use webhooks or repeated API r","section":"Developer Integration"},{"slug":"developer-integration/payments-api","title":"Payments API","description":"Query payment transactions recorded for an order.","navOrder":430,"searchText":"developer integration payments api Payments API Query payment transactions recorded for an order. Developer Integration Payments API Use the Payments API to inspect on-chain payment transactions recorded for an order. Endpoint GET /api/v1/orders/{orderId}/payments Parameters Field Required Default Description orderId Yes None Path parameter. Stafiel order ID. merchantId Yes None Query parameter. Merchant ID bound to the API key. Request Example curl \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/payments?merchantId=mch_your_merchant_id\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" Success Response { \"success\": true, \"data\": [ { \"orderId\": \"ord_your_order_id\", \"txHash\": \"0xabc123...\", \"fromAddress\": \"0x1111111111111111111111111111111111111111\", \"toAddress\": \"0x2222222222222222222222222222222222222222\", \"tokenAddress\": \"0x...\", \"amountUsd\": \"49.00\", \"confirmations\": 24, \"isConfirmed\": true, \"blockNumber\": \"12345678\", \"txLogIndex\": \"0\", \"createdAt\": \"2026-05-19T12:05:00.000Z\", \"updatedAt\": \"2026-05-19T12:06:00.000Z\" } ] } Response Fields Field Type Description orderId string Stafiel order ID associated with the payment record. txHash string or null On-chain transaction hash. fromAddress string or null Customer source address when available. toAddress string or null Order payment address or contract address. tokenAddress string or null Token contract or mint address. amountUsd string or null Recorded stablecoin payment amount displayed to 2 decimals. confirmations number Confirmation count currently recorded by Stafiel. isConfirmed boolean Whether Stafiel currently treats the payment as confirmed. blockNumber string or null Block number as a string when available. txLogIndex string or null Log index as a string when available. createdAt string ISO 8601 creation timestamp. updatedAt string ISO 8601 update timestamp. Confirmation isConfirmed indicates whether Stafiel currently considers the recorded payment confirmed. Do not treat an early detected payment as final until order status and confirmation state meet your business requirements. Chain Address Formats EVM addresses use 0x... . Solana addresses use base58 public keys. Tron addresses use base58 T... . Error Responses HTTP Status Code Meaning 400 VALIDATION_ERROR Query parameter is invalid or unsupported. 401 AUTH_FAILED API key is missing, invalid, or cannot access the requested merchant or order. 403 AUTHORIZATION_ERROR Request is authenticated but not allowed. 404 NOT_FOUND Order does not exist or is not visible. 429 RATE_LIMIT_EXCEEDED Too many requests. Retry after the indicated time.","section":"Developer Integration"},{"slug":"developer-integration/contract-status-api","title":"Contract Status API","description":"Query contract or payment address deployment status.","navOrder":440,"searchText":"developer integration contract status api Contract Status API Query contract or payment address deployment status. Developer Integration Contract Status API Use the Contract Status API to inspect the payment contract or payment address state for an order. Endpoint GET /api/v1/orders/{orderId}/contract Parameters Field Required Default Description orderId Yes None Path parameter. Stafiel order ID. merchantId Yes None Query parameter. Merchant ID bound to the API key. Request Example curl \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/contract?merchantId=mch_your_merchant_id\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" Success Response { \"success\": true, \"data\": { \"contractAddress\": \"0x2222222222222222222222222222222222222222\", \"deploymentStatus\": \"deployed\", \"deploymentTxHash\": \"0xabc123...\", \"deployedAt\": \"2026-05-19T12:03:00.000Z\", \"chainId\": 8453, \"chainName\": \"base\", \"addressVerificationStatus\": \"verified\", \"isInitialized\": true, \"sweepOpenAt\": \"2026-05-21T12:00:00.000Z\", \"sweepExtendMaxAt\": \"2026-05-23T12:00:00.000Z\", \"createdAt\": \"2026-05-19T12:00:00.000Z\", \"updatedAt\": \"2026-05-19T12:03:00.000Z\" } } Response Fields Field Type Description contractAddress string or null Payment contract or payment address. May be predicted before deployment. deploymentStatus string Standardized deployment status. See Deployment Statuses . deploymentTxHash string or null Deployment transaction hash when available. deployedAt string or null ISO 8601 deployment timestamp when available. chainId number Numeric chain ID. chainName string Canonical public chain label. addressVerificationStatus string Address verification status: verified , pending , or failed . isInitialized boolean Whether the payment contract or program state is initialized. sweepOpenAt string or null Time when settlement can become available for the order. sweepExtendMaxAt string or null Latest time to which the sweep window can be extended, when applicable. createdAt string ISO 8601 creation timestamp. updatedAt string ISO 8601 update timestamp. How To Use It Use this endpoint for operational diagnostics and support workflows. It is not required for a basic hosted checkout integration. sweepOpenAt describes when settlement can become available. With isInitialized , it also helps diagnose refund eligibility; amount, network support, and refund history still apply. Deployment Statuses Status Meaning not_started Deployment has not started. not_deployed No deployed payment contract or address is available. pending_deployment Deployment or provisioning is in progress. on_hold Deployment or provisioning is on hold. deployed Payment contract or payment address is ready. deployment_failed Deployment failed. deployment_cancelled Deployment was cancelled. Error Responses HTTP Status Code Meaning 400 VALIDATION_ERROR Query parameter is invalid or unsupported. 401 AUTH_FAILED API key is missing, invalid, or cannot access the requested merchant or order. 403 AUTHORIZATION_ERROR Request is authenticated but not allowed. 404 NOT_FOUND Order does not exist or is not visible. 429 RATE_LIMIT_EXCEEDED Too many requests. Retry after the indicated time.","section":"Developer Integration"},{"slug":"developer-integration/refund-api","title":"Refunds API","description":"Check refund status and refund history for an order.","navOrder":450,"searchText":"developer integration refund api Refunds API Check refund status and refund history for an order. Developer Integration Refunds API Use the Refunds API to check refund availability and inspect verified refund records for an order. Refund Status Endpoint GET /api/v1/orders/{orderId}/refund-status Parameters Field Required Default Description orderId Yes None Path parameter. Stafiel order ID. merchantId Yes None Query parameter. Merchant ID bound to the API key. Request Example curl \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/refund-status?merchantId=mch_your_merchant_id\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" Success Response { \"success\": true, \"data\": { \"hasMerchantRefunded\": false, \"hasAnyRefunded\": false, \"isWithinWindow\": true, \"windowEndsAt\": \"2026-05-21T12:00:00.000Z\", \"refundableAmountUsd\": \"49.00\", \"hasPlatformRefunded\": false, \"isInitialized\": true, \"canRefund\": true, \"totalMerchantRefundAmountUsd\": \"0.00\", \"totalPlatformRefundAmountUsd\": \"0.00\" } } Status Response Fields Field Type Description hasMerchantRefunded boolean Whether a merchant refund has been recorded. hasAnyRefunded boolean Whether any successful refund has been recorded. isWithinWindow boolean Whether the merchant after-sales window is still open. windowEndsAt string or omitted ISO 8601 after-sales window end time when still inside the window. refundableAmountUsd string or omitted Current refundable amount displayed to 2 decimals. hasPlatformRefunded boolean Whether a platform-initiated refund has been recorded. isInitialized boolean Whether the payment contract or program state is initialized. canRefund boolean Whether refund is currently available after initialization, window, amount, network, and refund-history checks. totalMerchantRefundAmountUsd string Total merchant refund amount displayed to 2 decimals. totalPlatformRefundAmountUsd string Total platform-initiated refund amount displayed to 2 decimals. Use canRefund as the API signal for whether a refund can currently be submitted through Stafiel. Do not infer refund eligibility from order status alone. Refund History Endpoint GET /api/v1/orders/{orderId}/refund-history Parameters Field Required Default Description orderId Yes None Path parameter. Stafiel order ID. merchantId Yes None Query parameter. Merchant ID bound to the API key. Request Example curl \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/refund-history?merchantId=mch_your_merchant_id\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" The response lists successful refund records, including refund amount, transaction hash, refund initiator, verification status, and refund metadata where available. The endpoint returns all successful refund records for the order in one array. No pagination parameters apply. Success Response { \"success\": true, \"data\": { \"refundHistory\": [ { \"refundAmountUsd\": \"10.00\", \"transactionHash\": \"0xabc123...\", \"txHash\": \"0xabc123...\", \"refundMeta\": [ { \"recipient\": \"0x1111111111111111111111111111111111111111\", \"amountUsd\": \"10.00\", \"originalPaymentHash\": \"0xpayment...\" } ], \"refundBy\": \"merchant\", \"isVerified\": true, \"verifiedAt\": \"2026-05-19T12:12:00.000Z\", \"status\": \"refunded\", \"createdAt\": \"2026-05-19T12:10:00.000Z\" } ], \"status\": \"refunded\", \"chainName\": \"base\", \"chainId\": 8453 } } History Response Fields Field Type Description refundHistory array Successful refund records for the order. status string Latest refund status when refund history exists. chainName string Canonical public chain label. chainId number Numeric chain ID. refundAmountUsd string Refunded amount displayed to 2 decimals. txHash string or omitted On-chain refund transaction hash. Use this field for new integrations. transactionHash string or omitted Compatibility alias for txHash . refundMeta array Per-recipient refund allocation details when available. refundBy string or null Refund initiator, such as merchant or platform . isVerified boolean Whether the refund has been verified on-chain. verifiedAt string or omitted ISO 8601 verification timestamp. createdAt string or omitted ISO 8601 creation timestamp. API Boundaries The public Refunds API exposes refund status and successful refund history for an order. It does not submit refunds. Use the Merchant Dashboard to operate supported refunds. See Refund Operations . Error Responses HTTP Status Code Meaning 400 VALIDATION_ERROR Query parameter is invalid or unsupported. 401 AUTH_FAILED API key is missing, invalid, or cannot access the requested merchant or order. 403 AUTHORIZATION_ERROR Request is authenticated but not allowed. 404 NOT_FOUND Order or refund record does not exist or is not visible. 409 REFUND_NOT_SUPPORTED Refund is not supported for this chain. 429 RATE_LIMIT_EXCEEDED Too many requests. Retry after the indicated time.","section":"Developer Integration"},{"slug":"developer-integration/settlement-history-api","title":"Settlements API","description":"Query settlement records for an order.","navOrder":460,"searchText":"developer integration settlement history api Settlements API Query settlement records for an order. Developer Integration Settlements API Use the Settlements API to query settlement records for an order. Endpoint GET /api/v1/orders/{orderId}/settlement Parameters Field Required Default Description orderId Yes None Path parameter. Stafiel order ID. merchantId Yes None Query parameter. Merchant ID bound to the API key. Request Example curl \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/settlement?merchantId=mch_your_merchant_id\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" If no settlement record exists yet, data can be null . Success Response { \"success\": true, \"data\": { \"txHash\": \"0xabc123...\", \"merchantAmount\": \"48.51\", \"platformAmount\": \"0.49\", \"status\": \"settled\", \"isVerified\": true, \"merchantAddress\": \"0x3333333333333333333333333333333333333333\", \"createdAt\": \"2026-05-19T12:20:00.000Z\", \"updatedAt\": \"2026-05-19T12:20:30.000Z\" } } Response Fields Field Type Description txHash string or null Settlement transaction hash. merchantAmount string or null Amount settled to the merchant wallet, displayed to 2 decimals. platformAmount string or null Platform fee amount, displayed to 2 decimals. status string or null Settlement status: pending , settled , or failed . isVerified boolean or null Whether the settlement record has been verified. merchantAddress string or null Merchant settlement address snapshot for the order. createdAt string ISO 8601 creation timestamp. updatedAt string or null ISO 8601 update timestamp. Settlement Address Snapshot The merchant settlement address is taken from the order's creation snapshot. A later wallet configuration change does not rewrite the settlement address for an existing order. Error Responses HTTP Status Code Meaning 400 VALIDATION_ERROR Query parameter is invalid or unsupported. 401 AUTH_FAILED API key is missing, invalid, or cannot access the requested merchant or order. 403 AUTHORIZATION_ERROR Request is authenticated but not allowed. 404 NOT_FOUND Order does not exist or is not visible. 429 RATE_LIMIT_EXCEEDED Too many requests. Retry after the indicated time.","section":"Developer Integration"},{"slug":"developer-integration/invoice-and-receipt-api","title":"Invoice and Receipt API","description":"Query and download order invoice and receipt documents.","navOrder":470,"searchText":"developer integration invoice and receipt api Invoice and Receipt API Query and download order invoice and receipt documents. Developer Integration Invoice and Receipt API Use the Invoice and Receipt API to query document status and download generated PDFs for an order. Get Documents Endpoint GET /api/v1/orders/{orderId}/documents Parameters Field Required Default Description orderId Yes None Path parameter. Stafiel order ID. merchantId Yes None Query parameter. Merchant ID bound to the API key. Request Example curl \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/documents?merchantId=mch_your_merchant_id\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" Success Response { \"success\": true, \"data\": { \"orderId\": \"ord_your_order_id\", \"documents\": { \"invoice\": { \"type\": \"invoice\", \"status\": \"ready\", \"documentNumber\": \"INV-2026-0001\", \"issuedAt\": \"2026-05-19T12:00:00.000Z\", \"canDownloadPdf\": true, \"pdf\": { \"contentType\": \"application/pdf\", \"downloadUrl\": \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/documents/invoice/pdf?merchantId=mch_your_merchant_id\" } }, \"receipt\": { \"type\": \"receipt\", \"status\": \"ready\", \"documentNumber\": \"RCT-2026-0001\", \"issuedAt\": \"2026-05-19T12:05:00.000Z\", \"canDownloadPdf\": true, \"pdf\": { \"contentType\": \"application/pdf\", \"downloadUrl\": \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/documents/receipt/pdf?merchantId=mch_your_merchant_id\" } } } } } Response Fields Field Type Description orderId string Stafiel order ID. documents object Document objects keyed by invoice and receipt . type string Document type, either invoice or receipt . status string or null Document generation status. documentNumber string or null Generated invoice or receipt number. issuedAt string or null ISO 8601 issue timestamp. canDownloadPdf boolean Whether the PDF is currently available for download. pdf.contentType string PDF content type when available. pdf.downloadUrl string Authenticated PDF download URL when available. Download PDF Endpoint GET /api/v1/orders/{orderId}/documents/invoice/pdf GET /api/v1/orders/{orderId}/documents/receipt/pdf Parameters Field Required Default Description orderId Yes None Path parameter. Stafiel order ID. documentType Yes None Path value. Use invoice or receipt . merchantId Yes None Query parameter. Merchant ID bound to the API key. Request Example curl \"https://api.stafiel.com/api/v1/orders/ord_your_order_id/documents/invoice/pdf?merchantId=mch_your_merchant_id\" \\ -H \"X-API-Key: mk_live_your_api_key\" \\ -H \"X-App-Client: merchant-client\" Success Response The PDF download endpoint does not return the standard JSON envelope. HTTP/1.1 200 OK Content-Type: application/pdf Content-Disposition: inline; filename=\"invoice-ord_your_order_id.pdf\" Document Status Document status may be queued , generating , ready , failed , voided , or null . A document becoming ready is not the source of truth for payment completion. Use order status and payment records for payment state. Error Responses HTTP Status Code Meaning 400 VALIDATION_ERROR Query parameter is invalid or document type is unsupported. 401 AUTH_FAILED API key is missing, invalid, or cannot access the requested merchant or order. 403 AUTHORIZATION_ERROR Request is authenticated but not allowed. 404 NOT_FOUND Order or document does not exist or is not visible. 409 ORDER_DOCUMENT_NOT_READY / ORDER_DOCUMENT_VOIDED PDF is not available or the document is voided. 429 RATE_LIMIT_EXCEEDED Too many requests. Retry after the indicated time.","section":"Developer Integration"},{"slug":"developer-integration/webhooks-and-events","title":"Webhooks and Events","description":"Receive signed webhook events from Stafiel.","navOrder":480,"searchText":"developer integration webhooks and events Webhooks and Events Receive signed webhook events from Stafiel. Developer Integration Webhooks and Events Use webhooks to receive asynchronous order events from Stafiel. Configure your webhook endpoint in the Merchant Dashboard. Receiver Endpoint In the Merchant Dashboard, set a public HTTPS endpoint for Stafiel events. Use a dedicated route so your application can verify the raw request body before any framework middleware modifies it. Delivery Headers Stafiel deliveries include these headers: Header Description X-Webhook-Signature HMAC-SHA256 signature for the raw request body, formatted as sha256=<hex> . X-Webhook-Event-Id Unique event ID for idempotency and duplicate detection. X-Webhook-Event-Type Canonical event type, such as order.payment.received_fullpaid . X-Webhook-Timestamp Delivery timestamp used for replay checks. X-Webhook-Delivery-Attempt Delivery attempt number for this event. X-App-Network Event network: mainnet or testnet . Signature Verification Verify the signature against the raw request body. Do not parse the JSON and then stringify it again before verification. The signature uses HMAC-SHA256 and is sent in X-Webhook-Signature as sha256=<hex> . A typical signature verification flow includes: Read X-Webhook-Signature and validate the sha256=<hex> format. Verify against the exact raw request body bytes received by your server. Compute HMAC-SHA256 with your webhook signing secret and compare the digest using a constant-time comparison. Check X-Webhook-Timestamp against your replay tolerance before accepting the event. Webhook Payload Example { \"event\": \"order.payment.received_fullpaid\", \"eventId\": \"evt_your_event_id\", \"timestamp\": \"2026-05-19T12:05:00.000Z\", \"network\": \"mainnet\", \"data\": { \"order\": { \"id\": \"ord_your_order_id\", \"merchantId\": \"mch_your_merchant_id\", \"chainId\": 8453, \"chainName\": \"base\", \"tokenAddress\": \"0x...\", \"tokenSymbol\": \"USDC\", \"amountUsd\": \"49.00\", \"orderAddress\": \"0x...\", \"status\": \"fullpaid\", \"totalPaidAmountUsd\": \"49.00\", \"expiresAt\": \"2026-05-19T12:30:00.000Z\", \"createdAt\": \"2026-05-19T12:00:00.000Z\", \"metadata\": { \"customerReference\": \"CUS-8842\" } }, \"oldBalance\": \"0.00\", \"newBalance\": \"49.00\", \"delta\": \"49.00\" } } Webhook Payload Fields Field Type Description event string Canonical event type. See Event Types . eventId string Unique webhook event ID. Use this for idempotency. timestamp string ISO 8601 time when the webhook event payload was created. network string mainnet or testnet . data object Event payload. Order-related events include data.order . Some events also include event-specific objects or fields. data.order.id string Stafiel order ID. data.order.merchantId string Merchant ID that owns the order. data.order.chainId number or null Numeric chain ID when available. data.order.chainName string or null Public chain label. data.order.tokenAddress string or null Token contract or mint address. data.order.tokenSymbol string or null Token symbol. data.order.amountUsd string or null Original checkout amount. data.order.orderAddress string or null Payment contract or payment address. data.order.status string Order status for this event. data.order.totalPaidAmountUsd string or null Total recorded payment amount when token decimals are known. data.order.expiresAt string or null ISO 8601 expiration timestamp. data.order.createdAt string or null ISO 8601 order creation timestamp. data.order.metadata object or null Sanitized order metadata. Event-specific fields: Field Events Description data.oldBalance Payment amount change events Previous detected order balance. data.newBalance Payment amount change events New detected order balance. data.delta Payment amount change events Balance change amount. data.confirmation order.payment.confirmed Confirmation details, including transaction hash, block number, confirmation count, and confirmation time. data.contract order.contract.ready Contract readiness details, including contract address, transaction hash, and contract status. data.settlement order.settled Settlement details, including merchant amount, platform fee, transaction hash, chain ID, settlement time, and settlement status. data.refund Refund events Refund details, including refund type, amount, transaction hash, recipients, chain ID, and notes. Webhook payloads can include event context that is not returned by every query API response for the same order. Treat each API chapter's response field table as the contract for that endpoint. Event Types Handle event types as exact strings. Event Type When It Is Sent order.payment.detected Stafiel detects an incoming payment for the order. order.payment.received_fullpaid Recorded payment reaches the expected order amount. order.payment.received_underpaid Recorded payment is below the expected order amount. order.payment.received_overpaid Recorded payment is above the expected order amount. order.payment.confirmed A recorded payment reaches Stafiel's confirmation threshold. order.contract.ready The payment contract or payment address is ready. order.settled Settlement for the order is recorded. order.expired The order expires before full payment. order.closed The order is closed. order.compliance_hold The order is held by risk or compliance controls. order.refund.by_merchant A merchant refund is recorded. order.refund.by_platform A platform-initiated refund is recorded. Event Handling and Retries Use eventId for idempotency. A typical receiver returns a 2xx response after the event has been recorded or identified as already processed. Failed deliveries are retried, so integrations generally treat webhook delivery as at-least-once and design for duplicate or out-of-order events.","section":"Developer Integration"},{"slug":"developer-integration/widget-integration","title":"Widget Integration","description":"Embed hosted checkout with the browser widget runtime.","navOrder":485,"searchText":"developer integration widget integration Widget Integration Embed hosted checkout with the browser widget runtime. Developer Integration Widget Integration Use the widget runtime when your frontend needs to launch a Stafiel checkout session. Create the checkout session first on your server, then pass the checkoutSessionUrl from the response data to the browser. Important: Do not put API keys in frontend or browser code. Runtime Scripts Load one of the browser runtimes from the widget domain for your network mode. The stable paths are: Runtime Script Global Use when Checkout snippet https://widget.stafiel.com/widget/v1/checkout.js window.StafielCheckout You want a smaller helper for button binding or declarative HTML binding. Widget runtime https://widget.stafiel.com/widget/v1/widget.js window.StafielWidget You want direct control over create, open, mount, events, and cleanup. Checkout vs Widget Use Checkout snippet for quick development and deployment. It is best for payment buttons, simple modal checkout, and declarative HTML binding. Use Widget runtime when you need direct control over the checkout instance. It is best for inline checkout areas, custom lifecycle handling, event subscriptions, theme changes, or cleanup in single-page applications. Both runtimes consume the same checkoutSessionUrl . The checkoutSessionUrl is an opaque hosted checkout URL. Do not parse, rebuild, or modify it. Checkout Snippet Example Use checkout.js when you want to bind checkout behavior to a button or DOM node without managing the lower-level widget instance yourself. <button id=\"pay-now\">Pay now</button> <script src=\"https://widget.stafiel.com/widget/v1/checkout.js\"></script> <script> window.StafielCheckout.bind('#pay-now', { checkoutSessionUrl: 'https://pay.stafiel.com/pay/ps_your_session_token', mode: 'modal', theme: 'light' }); </script> Checkout Snippet API Method Returns Description open(options) Promise<CheckoutSnippetBinding> Opens checkout immediately. bind(target, options) CheckoutSnippetBinding Binds checkout to a CSS selector or HTMLElement . bindAll(root?, defaults?) CheckoutSnippetBinding[] Binds every [data-stafiel-checkout] node under root . setTheme(target, theme) void Updates the theme for an existing binding. unbind(target) void Removes the click trigger listener for one binding. destroy(target?) void Removes one binding, or all bindings when no target is provided. Checkout Snippet Binding open() , bind() , and bindAll() return binding instances. Method Returns Description open() Promise<void> Opens the bound checkout. close() void Closes the current checkout surface when supported. destroy() void Removes the binding and its runtime state. setTheme(theme) void Switches the binding between light and dark . update(options) void Updates the binding with new checkout snippet options. Checkout Snippet Options Option Required Default Description checkoutSessionUrl Yes None Hosted checkout URL returned by your server. mode Yes None One of the values listed in Widget Modes . container No Bound target Optional container selector or element for mounted modes. openInNewTab No true for redirect Controls redirect mode tab behavior. scale No 1 Widget scale for non-redirect modes, clamped between 0.8 and 2.5 . borderRadius No 24 for modal , 16 otherwise Frame border radius in pixels, clamped between 0 and 24 . theme No light One of light or dark . autoFallback No false Allows fallback to another mode when needed. onOpen No None Called when checkout opens. onClose No None Called when checkout closes. onError No None Called when checkout fails to initialize or open. onFallback No None Called when the runtime falls back to another mode. Declarative Binding checkout.js can bind elements declared in HTML. <div data-stafiel-checkout data-checkout-session-url=\"https://pay.stafiel.com/pay/ps_your_session_token\" data-mode=\"lite\" data-theme=\"light\" data-scale=\"1\" data-border-radius=\"16\" ></div> <script src=\"https://widget.stafiel.com/widget/v1/checkout.js\"></script> <script> window.StafielCheckout.bindAll(); </script> Supported data attributes: Attribute Required Description data-stafiel-checkout Yes Marks the element for bindAll() . data-checkout-session-url Yes, unless supplied in bindAll defaults Hosted checkout URL. data-mode Yes One of the values listed in Widget Modes . data-container No Selector for a separate mounted container. data-scale No Widget scale for non-redirect modes. data-border-radius No Frame border radius in pixels. data-theme No light or dark . data-auto-fallback No Boolean value: true , false , 1 , or 0 . data-open-in-new-tab No Boolean value used by redirect mode. Widget Runtime Example <div id=\"stafiel-payment\"></div> <script src=\"https://widget.stafiel.com/widget/v1/widget.js\"></script> <script> const widget = window.StafielWidget.create({ checkoutSessionUrl: 'https://pay.stafiel.com/pay/ps_your_session_token', mode: 'inline', container: document.getElementById('stafiel-payment'), theme: 'light' }); widget.mount(); </script> Use open() for redirect and modal mode. Use on() to subscribe to widget events, and clean up subscriptions or widget instances when your page no longer needs them. <script> const widget = window.StafielWidget.create({ checkoutSessionUrl: 'https://pay.stafiel.com/pay/ps_your_session_token', mode: 'modal', theme: 'light' }); const unsubscribe = widget.on('order.payment.received_fullpaid', function (event) { console.log('Order paid', event); }); await widget.open(); // Later, for example when leaving a single-page app route: unsubscribe(); widget.destroy(); </script> Widget Options Option Required Default Description checkoutSessionUrl Yes None Hosted checkout URL returned by your server after creating a checkout session. mode Yes None One of the values listed in Widget Modes . container Required for mounted modes None HTMLElement used by inline , lite , or micro . You may also pass it to mount(container) . openInNewTab No true for redirect Controls whether redirec","section":"Developer Integration"},{"slug":"developer-integration/testnet","title":"Testnet","description":"Test integrations with test API keys and test networks.","navOrder":490,"searchText":"developer integration testnet Testnet Test integrations with test API keys and test networks. Developer Integration Testnet Testnet uses the same public API endpoints and request formats as live integrations. Only the mode-specific parameters change. Keep the endpoint path and request body shape the same as the corresponding API reference. Request Parameters Field Required Default Description X-API-Key Yes None Use a test API key, for example mk_test_your_api_key . X-App-Client Yes None Use merchant-client-testnet . Content-Type Required for JSON requests None Use application/json when sending a JSON request body. merchant-client-testnet tells Stafiel that the request belongs to testnet. It must be used with mk_test_ keys. A test key with merchant-client , or a live key with merchant-client-testnet , is rejected with 401 AUTH_FAILED . Data Isolation Testnet and live data are separate. Keep testnet activity isolated from live customer payments, accounting, reconciliation, webhook handling, and operational records in your own system. Do not treat a successful testnet payment as a real customer payment. Chain Labels Testnet chain names use explicit labels: Chain Label Testnet Chain ID eth-sepolia Ethereum Sepolia 11155111 base-sepolia Base Sepolia 84532 bsc-testnet BNB Smart Chain Testnet 97 polygon-amoy Polygon Amoy 80002 solana-devnet Solana Devnet 103 tron-nile Tron Nile 3448148188 Use the chain and token options shown in your Merchant Dashboard as the source of truth for what your account can create. Webhooks Use separate webhook configuration for testnet. Treat testnet event IDs, signing secrets, and delivery logs as separate from live deliveries. Go-Live Checklist Before going live, replace: Merchant ID: use your live merchant ID in API requests. API key: use a live API key with the mk_live_ prefix. X-App-Client : change merchant-client-testnet to merchant-client . Chain labels: switch from testnet labels to mainnet chain labels. Webhook configuration: use the live webhook endpoint and signing secret.","section":"Developer Integration"},{"slug":"risk-and-reference/security-and-wallet-boundary","title":"Security and Wallet Boundary","description":"Understand merchant key custody and wallet boundaries.","navOrder":500,"searchText":"risk and reference security and wallet boundary Security and Wallet Boundary Understand merchant key custody and wallet boundaries. Risk and Reference Security and Wallet Boundary Stafiel does not ask for merchant wallet private keys or seed phrases, and it does not take custody of merchant wallets. The configured settlement wallet remains under merchant control. Use this page to understand what Stafiel verifies and where the wallet boundary is. Merchant Wallet Control The merchant settlement wallet is the address configured to receive merchant funds after eligible settlement. Stafiel records that address for checkout and settlement, but the wallet itself remains under merchant control. Do not share private keys, recovery phrases, or signing devices with Stafiel, customers, vendors, or support channels. For setup steps, see Wallet Settings . Wallet Verification Signatures Merchant Dashboard can ask the merchant to connect a browser extension wallet and sign a verification message. The signature verifies that the merchant can sign for the wallet address being configured. That verification signature: Does not transfer funds. Does not create an on-chain transaction. Does not grant token approval, contract permission, or program authority. Does not give Stafiel access to the wallet's private key or seed phrase. Does not charge a network transaction fee. Important: Always read the wallet prompt before signing. A wallet verification message should identify address verification, not token spending approval or fund movement. What Stafiel Provides Stafiel provides the checkout, order tracking, payment status, refund availability and records, settlement records, and integration surfaces used by the merchant. Supported blockchain payment rails enforce payment, refund, and settlement behavior for each checkout flow. These services do not make Stafiel the custodian of the merchant settlement wallet. The merchant remains responsible for wallet access, signer security, and recovery materials. For how settlement reaches the merchant wallet, see Settlement Basics . Wallet Boundary Notes For merchant settlement wallets: Use a browser extension wallet or hardware wallet that supports the selected network. Keep wallet recovery phrases and backup codes in a secure private location. Do not use centralized exchange deposit addresses as merchant settlement wallets. For account security and MFA settings, see Account and MFA . Customer Payment Wallets The merchant settlement wallet is different from the customer's payment wallet. Customers pay from their own wallets, exchange withdrawal flows, or custodial wallets. Those payment sources can affect refund reachability and support handling. For payment-source risks, see Payment and Refund Risks .","section":"Risk and Reference"},{"slug":"risk-and-reference/payment-and-refund-risks","title":"Payment and Refund Risks","description":"Understand payment-source, compliance-review, and refund-limit risks.","navOrder":510,"searchText":"risk and reference payment and refund risks Payment and Refund Risks Understand payment-source, compliance-review, and refund-limit risks. Risk and Reference Payment and Refund Risks Payment and refund risk depends on where the customer pays from, the selected network, the order status, KYT/AML and compliance review, and the refund rules for that checkout. Use this page to understand when payment source, compliance review, and refund limits can affect support, fulfillment, refund, or settlement decisions. Payment Source And Refund Reachability Customers can pay from self-custodial wallets, browser extension wallets, mobile wallets, centralized exchange withdrawal flows, or other custodial wallet flows. The payment source is the on-chain wallet address that paid the checkout. Original-route refunds return value to that same source. They cannot be redirected to an unrelated wallet chosen after payment. Payments from centralized exchanges and custodial wallets can still complete a checkout when the selected token, network, and payment address are used. Refund reachability can differ because these providers may use payment source addresses controlled by the exchange or wallet provider, not by the customer's personal account. Stafiel can record the on-chain payment, but a later refund to an exchange-controlled source may not appear in the customer's exchange account. Those customer-side recovery cases are outside Stafiel's refund scope. For the business refund model, see Refund Basics . KYT/AML And Compliance Review Stafiel applies Know Your Transaction (KYT), Anti-Money Laundering (AML), and related compliance checks across payment monitoring, on-chain payment setup, and settlement processing. These checks can affect whether an order continues normally, enters Compliance Hold, or becomes available for refund or settlement. A held order should not be treated as ready for fulfillment, refund, or settlement until the hold is resolved. For status handling, see Order Lifecycle and Payment Status . Merchant-Initiated Refund Limits Merchant-initiated on-chain refunds have limits: A checkout can have only one merchant-initiated refund action. A partial refund counts as that one refund action. The refund amount cannot exceed the remaining refundable amount for the order. Availability depends on the after-sales window, selected network, order status, and refundable amount. Merchant-initiated on-chain refunds require the merchant to pay the applicable network transaction cost, such as a gas fee or transaction fee. Tron orders do not support merchant-initiated on-chain refunds through Stafiel. For dashboard steps, see Refund Operations . Refund Outcomes And Settlement Refund outcome affects what can continue downstream: A partial refund can leave remaining paid value on the order. That remaining value can continue through the normal order and settlement flow when the order is otherwise eligible. A full refund leaves no remaining payment value to settle. For settlement behavior, see Settlement Basics . Platform-Initiated Refunds Stafiel may perform a platform-initiated refund for compliance, legal, risk, or operational reasons. These refunds do not require a merchant refund submission, and Merchant Dashboard can show the records when available. Customer Guidance Points Customer-facing checkout or support text often needs to account for these risk points: Pay only with the selected token, network, and payment address. Do not send payment after the payment window expires. Explain that a customer-controlled wallet usually gives a clearer refund path when refund reachability matters. Explain that centralized exchange or custodial wallet payments can complete an order, but refunds may not reach the customer's exchange account automatically.","section":"Risk and Reference"},{"slug":"risk-and-reference/go-live-checklist","title":"Go-Live Checklist","description":"Review the merchant checklist before using mainnet.","navOrder":530,"searchText":"risk and reference go live checklist Go-Live Checklist Review the merchant checklist before using mainnet. Risk and Reference Go-Live Checklist Use this checklist before accepting real customer payments on mainnet. It helps confirm that merchant setup, payment configuration, integrations, and record review are ready for live use. Merchant And Mode Confirm the Merchant ID belongs to the mainnet merchant that will accept real payments. Confirm Merchant Dashboard is using mainnet mode before copying settings, wallet addresses, checkout links, or records. For mode separation, see Mainnet vs Testnet . Wallet Settings Review approved settlement wallet addresses for every chain used for live checkout. Review enabled tokens and networks against the payment options the merchant plans to offer. For wallet setup, see Wallet Settings . For key custody boundaries, see Security and Wallet Boundary . Checkout Configuration Confirm live checkout sessions use the intended amount, token, network, payment window, metadata, and Return URL. Make customer-facing copy clear that customers should pay only with the selected token, selected network, and displayed payment address. Test hosted checkout, checkout snippet, or widget behavior against the production checkout flow. For checkout behavior, see Checkout Sessions . API And Front-End Integration Replace test API keys with mainnet API keys on the backend. Set X-App-Client to merchant-client for mainnet API requests. Keep API keys out of browser code, mobile apps, checkout pages, and widget configuration. Important: API keys belong on the server side only. Do not put API keys in front-end code. For API authentication, see API Keys and Authentication . Webhooks And Events If the live integration uses webhooks: Use a public HTTPS endpoint for live webhook delivery. Save the live webhook signing secret in the receiving system. Verify signatures against the raw request body. Make event handling idempotent and tolerant of retries. For event delivery, see Webhooks and Events . Refund And Support Readiness Review which live networks support merchant-initiated refunds. Make sure the merchant team understands one-time merchant refund behavior. Review centralized exchange and custodial wallet refund limitations for support planning. Know where to review refund history and platform-initiated refunds. For refund operations, see Refund Operations . For payment-source risk, see Payment and Refund Risks . Records And Reconciliation Know where to review orders, payment records, settlement details, fee details, refunds, invoices, and receipts. Keep exports and dashboard views separate between mainnet and testnet mode. Review settlement records for merchant amount, platform fee, settlement address, transaction hash, and settlement result. For order review, see Orders . For settlement review, see Settlement Review . For fee details, see Fees and Plan Usage .","section":"Risk and Reference"}],"generatedAt":"2026-07-13T12:36:56.965Z","page":{"slug":"developer-integration/testnet","title":"Testnet","description":"Test integrations with test API keys and test networks.","navSection":"Developer Integration","navOrder":490,"html":"<h1>Testnet</h1>\n<p>Testnet uses the same public API endpoints and request formats as live\nintegrations. Only the mode-specific parameters change.</p>\n<p>Keep the endpoint path and request body shape the same as the corresponding API\nreference.</p>\n<h2>Request Parameters</h2>\n<table>\n<thead>\n<tr>\n<th>Field</th>\n<th>Required</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>X-API-Key</code></td>\n<td>Yes</td>\n<td>None</td>\n<td>Use a test API key, for example <code>mk_test_your_api_key</code>.</td>\n</tr>\n<tr>\n<td><code>X-App-Client</code></td>\n<td>Yes</td>\n<td>None</td>\n<td>Use <code>merchant-client-testnet</code>.</td>\n</tr>\n<tr>\n<td><code>Content-Type</code></td>\n<td>Required for JSON requests</td>\n<td>None</td>\n<td>Use <code>application/json</code> when sending a JSON request body.</td>\n</tr>\n</tbody>\n</table>\n<p><code>merchant-client-testnet</code> tells Stafiel that the request belongs to testnet. It\nmust be used with <code>mk_test_</code> keys. A test key with <code>merchant-client</code>, or a live\nkey with <code>merchant-client-testnet</code>, is rejected with <code>401 AUTH_FAILED</code>.</p>\n<h2>Data Isolation</h2>\n<p>Testnet and live data are separate. Keep testnet activity isolated from live\ncustomer payments, accounting, reconciliation, webhook handling, and operational\nrecords in your own system.</p>\n<p>Do not treat a successful testnet payment as a real customer payment.</p>\n<h2>Chain Labels</h2>\n<p>Testnet chain names use explicit labels:</p>\n<table>\n<thead>\n<tr>\n<th>Chain Label</th>\n<th>Testnet</th>\n<th>Chain ID</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>eth-sepolia</code></td>\n<td>Ethereum Sepolia</td>\n<td><code>11155111</code></td>\n</tr>\n<tr>\n<td><code>base-sepolia</code></td>\n<td>Base Sepolia</td>\n<td><code>84532</code></td>\n</tr>\n<tr>\n<td><code>bsc-testnet</code></td>\n<td>BNB Smart Chain Testnet</td>\n<td><code>97</code></td>\n</tr>\n<tr>\n<td><code>polygon-amoy</code></td>\n<td>Polygon Amoy</td>\n<td><code>80002</code></td>\n</tr>\n<tr>\n<td><code>solana-devnet</code></td>\n<td>Solana Devnet</td>\n<td><code>103</code></td>\n</tr>\n<tr>\n<td><code>tron-nile</code></td>\n<td>Tron Nile</td>\n<td><code>3448148188</code></td>\n</tr>\n</tbody>\n</table>\n<p>Use the chain and token options shown in your Merchant Dashboard as the source of\ntruth for what your account can create.</p>\n<h2>Webhooks</h2>\n<p>Use separate webhook configuration for testnet. Treat testnet event IDs,\nsigning secrets, and delivery logs as separate from live deliveries.</p>\n<h2>Go-Live Checklist</h2>\n<p>Before going live, replace:</p>\n<ul>\n<li>Merchant ID: use your live merchant ID in API requests.</li>\n<li>API key: use a live API key with the <code>mk_live_</code> prefix.</li>\n<li><code>X-App-Client</code>: change <code>merchant-client-testnet</code> to <code>merchant-client</code>.</li>\n<li>Chain labels: switch from testnet labels to mainnet chain labels.</li>\n<li>Webhook configuration: use the live webhook endpoint and signing secret.</li>\n</ul>","effectiveDate":null,"lastUpdatedAt":null},"canonicalUrl":"https://stafiel.org/documentation/developer-integration/testnet"}}