# Payclave

> Payclave is non-custodial crypto checkout for modern merchants, letting businesses accept stablecoin payments directly to their settlement wallet through hosted checkout, onchain verification, and signed webhooks.

- SDK release note: @payclave/sdk-server@0.1.1 supports basic checkout/invoice creation and reads, payment reads, webhook endpoint creation, test delivery and delivery listing. Use direct HTTP for itemized drafts/actions, payment links, endpoint rotation/replay, reconciliation and diagnostics. Repository source includes methods not yet in that npm release.
- Payclave is non-custodial crypto checkout orchestration software for merchants.
- Primary positioning: Payclave -- non-custodial crypto checkout for modern merchants. Accept stablecoin payments directly to your wallet.
- Core money movement: customer wallet -> merchant wallet. Payclave creates checkout sessions, records invoices and payments, verifies settlement independently, and sends signed webhooks.
- Merchants settle to a configured USDC or USDT on Polygon receiving wallet. Hosted checkout may orchestrate supported source tokens or chains, but the merchant receives the net settlement -- the invoice amount minus the Payclave platform fee -- in the configured settlement wallet.
- Base API URL: https://api.payclave.com. Hosted checkout URLs look like https://www.payclave.com/checkout/{checkoutId}.
- Use server-side secret keys (`sk_test_*` or `sk_live_*`) from the merchant backend for production checkout-session and invoice creation. Publishable keys (`pk_test_*` or `pk_live_*`) can create and read checkout sessions only. Publishable-key creation accepts only `amount` and `externalReference`.
- Send secret keys with `Authorization: Bearer sk_...` or API keys with `X-API-Key`. Never expose secret keys, webhook secrets, Trails credentials, provider credentials, or private keys to browsers.
- Use an Idempotency-Key for supported checkout, invoice, payment-link and mutation retries. Public checkout submissions and webhook replay require it. Webhook endpoint creation and synthetic test delivery do not support idempotent replay; do not blindly retry those operations. Reuse a key only for the same operation and payload.
- All normal API responses use a JSON envelope with `success`, `data`, optional `error`, and `meta.requestId`.
- Checkout-session creation returns a public `checkoutId`, linked `invoiceNumber`, `checkoutUrl`, amount fields, settlement wallet, token, chain, expiry, status, and request metadata.
- Invoice statuses: `pending`, `processing`, `paid`, `underpaid`, `overpaid`, `expired`, `failed`, `cancelled`.
- Payment statuses: `detected`, `validating`, `confirmed`, `failed`, `duplicate`, `underpaid`, `overpaid`.
- Supported webhook event types: invoice.issued, invoice.paid, invoice.partially_paid, invoice.past_due, invoice.overpaid, invoice.voided, invoice.uncollectible, invoice.refund_recorded, invoice.payment_received_after_void, invoice.payment_received_after_uncollectible, invoice.expired, payment_link.completed, payment_link.expired, payment.failed, payment.underpaid, payment.overpaid.
- Webhook delivery statuses: `pending`, `delivering`, `delivered`, `retry_scheduled`, `failed`.
- Webhook requests include `X-Payclave-Signature`, `X-Payclave-Timestamp`, `X-Payclave-Delivery`, and `X-Payclave-Event` headers.
- Verify the exact raw webhook request body before parsing JSON. Raw-body remediation: https://www.payclave.com/developers/docs#webhooks.
- Any 2xx response acknowledges a webhook delivery. Failed deliveries retry after 1 minute, 5 minutes, 30 minutes, and 2 hours. A fifth failed attempt ends automatic retries.
- Payclave must not mark invoices paid based only on the browser or a payment-orchestration response. Paid state requires independent onchain verification of transaction hash, recipient wallet, token contract, chain ID, amount received, invoice expiry, confirmation/finality, duplicate transaction usage, underpayment, and overpayment.
- Fulfill merchant orders only after receiving and verifying a signed Payclave webhook such as `invoice.paid`, or after reading the API and confirming that cumulative verified customer payments cover the full invoice total. A confirmed individual payment may cover only part of an invoice. Persist webhook acceptance and fulfillment enqueue atomically, deduplicate event.id and order fulfillment, validate mode and commercial order facts, and ignore synthetic events with data.test=true.
- Use total for the commercial invoice total, customerAmountPaid and customerAmountRemaining for cumulative customer credit, expectedMerchantSettlement/netAmount for expected net receipts, and merchantAmountSettled for actual verified receipts. Checkout amountDue can represent a remaining installment. Keep platformFee separate and do not equate customer credit with merchant receipts.
- Before going live, finish the test checkout and webhook flow, configure a Polygon USDC or USDT settlement wallet, create separate live credentials, use HTTPS return URLs you control, send a small live payment, and reconcile the API record with the wallet receipt.

## Primary Documentation

- [About Payclave](https://www.payclave.com/about): Learn how Payclave helps merchants accept stablecoin payments directly into their own settlement wallets.
- [Contact Payclave](https://www.payclave.com/contact): Contact Payclave about product questions, integrations, privacy requests, security reports, and legal notices.
- [Payclave Developer Portal](https://www.payclave.com/developers): Find Payclave API documentation, authentication guides, the OpenAPI specification, SDKs, rate limits, and the Payclave MCP server.
- [Payclave API Authentication Documentation](https://www.payclave.com/developers/authentication): Authenticate Payclave API requests with secret or publishable keys and keep test and live integrations separate.
- [Payclave OpenAPI Specification](https://www.payclave.com/developers/openapi): Download Payclave's OpenAPI 3.1 specification for checkout sessions, invoices, payments, authentication, and webhooks.
- [Payclave MCP Server](https://www.payclave.com/developers/mcp): Connect an AI assistant to the public Payclave documentation MCP server using Streamable HTTP.
- [Payclave API Rate Limits and Retry Headers](https://www.payclave.com/developers/rate-limits): Understand Payclave RateLimit, RateLimit-Policy, and Retry-After headers so integrations and agents can throttle API requests.
- [Payclave MCP endpoint](https://www.payclave.com/mcp): Public read-only documentation MCP over Streamable HTTP. POST protocol messages; GET returns 405.
- [Payclave Privacy Policy](https://www.payclave.com/privacy): Privacy practices and contacts.
- [Payclave OpenAPI specification](https://www.payclave.com/openapi.json): OpenAPI 3.1 core merchant API contracts with typed inputs, responses and errors.
- [API versioning and rate limits](https://www.payclave.com/api-policy.md): Versioning, deprecation, typed errors, quotas and retry conventions.
- [Payclave API docs](https://www.payclave.com/developers/docs): Human-readable documentation for checkout sessions, invoices, payments, webhooks, authentication, SDKs, and errors.
- [Quickstart](https://www.payclave.com/developers/docs#quickstart): Create a checkout session from a merchant backend and redirect the customer to hosted checkout.
- [Authentication](https://www.payclave.com/developers/docs#authentication): API key formats, supported headers, and when to use publishable versus secret keys.
- [Errors](https://www.payclave.com/developers/docs#errors): Error response envelope, retry guidance, request IDs, API error codes, SDK errors, and webhook verification failures.

## Product Guides

- [Stablecoin checkout](https://www.payclave.com/stablecoin-checkout): How Payclave connects hosted checkout sessions, direct wallet settlement, independent verification, and merchant fulfillment.
- [Accept USDT payments](https://www.payclave.com/accept-usdt-payments): Merchant guide to order-linked USDT checkout and configured USDT on Polygon settlement.
- [Accept USDC payments](https://www.payclave.com/accept-usdc-payments): Merchant guide to hosted USDC checkout, payment status, reconciliation, and signed events.
- [Non-custodial checkout](https://www.payclave.com/non-custodial-crypto-checkout): Explanation of Payclave's direct-to-wallet settlement model and independent onchain verification.
- [Stablecoin payment API](https://www.payclave.com/stablecoin-payment-api): Integration overview for checkout sessions, hosted redirects, verified payment status, and HMAC-signed webhooks.
- [Pricing](https://www.payclave.com/pricing): Payclave test-mode and live-payment pricing, included checkout features, and fee reconciliation.

## API Resources

- [Complete HTTP reference](https://www.payclave.com/developers/docs#api-reference): Methods, paths, inputs, success codes and response shapes for merchant APIs and public invoice/payment-link checkout.
- [API basics](https://www.payclave.com/developers/docs#api-basics): Modes, amounts, idempotency exceptions, pagination and rate limits.
- [Reconciliation](https://www.payclave.com/developers/docs#reference-reconciliation): Summary filters, asynchronous exports, schema versions and downloads.
- [Checkout diagnostics](https://www.payclave.com/developers/docs#reference-diagnostics): Checkout funnel, reasons, sessions and taxonomy.
- [Create checkout sessions](https://www.payclave.com/developers/docs#checkout-sessions): POST /v1/checkout-sessions creates a Payclave-hosted checkout URL and linked invoice.
- [Create invoices](https://www.payclave.com/developers/docs#invoices): POST /v1/invoices with lines creates an itemized draft; issue it with its current version to obtain the hosted invoice URL. The amount-only legacy form creates a payable invoice directly.
- [Retrieve payments](https://www.payclave.com/developers/docs#payments): GET /v1/payments/:id reads detected and verified onchain payment records.
- [Webhook overview](https://www.payclave.com/developers/docs#webhooks): Signed payment lifecycle events, webhook security headers, and server SDK verification.
- [Webhook endpoints](https://www.payclave.com/developers/docs#webhook-endpoints): POST /v1/webhook-endpoints registers merchant endpoints and subscribed event types.
- [Webhook deliveries](https://www.payclave.com/developers/docs#webhook-deliveries): GET /v1/webhook-deliveries inspects delivery status, attempt count, the latest response summary, and retry state.

## Technical Guides

- [How to create a stablecoin checkout session](https://www.payclave.com/guides/create-stablecoin-checkout-session): Create a Payclave stablecoin checkout session from your backend, use idempotency correctly, redirect to hosted checkout, and confirm payment safely.
- [How to verify stablecoin payment webhook signatures](https://www.payclave.com/guides/verify-payclave-webhook-signatures): Verify Payclave webhook signatures against the raw request body, reject stale deliveries, deduplicate event IDs, and fulfill each stablecoin order once.
- [Stablecoin payment reconciliation guide for merchants](https://www.payclave.com/guides/reconcile-stablecoin-payments): Reconcile Payclave invoices, payment records, platform fees, and direct wallet settlement without treating a transaction hash as the complete order record.
- [How Payclave verifies onchain stablecoin payments](https://www.payclave.com/guides/onchain-payment-verification): Learn how Payclave verifies stablecoin settlement, confirmation state, recipient, token, amount, expiry policy, and duplicate transaction use before paid status.
- [Stablecoin checkout vs manual wallet transfers](https://www.payclave.com/guides/stablecoin-checkout-vs-wallet-transfers): Compare hosted stablecoin checkout with manual wallet payment instructions across customer experience, order matching, verification, settlement, and fulfillment.

## SDKs

- [Official libraries](https://www.payclave.com/developers/docs#official-libraries): Payclave JavaScript, React, and TypeScript server SDK overview.
- [@payclave/sdk-server](https://www.npmjs.com/package/@payclave/sdk-server): TypeScript server SDK for backend checkout-session and invoice creation, payment reads, API errors, and webhook signature verification.
- [@payclave/sdk-js](https://www.npmjs.com/package/@payclave/sdk-js): Browser SDK for publishable-key checkout creation, redirects, and payment buttons.
- [@payclave/sdk-react](https://www.npmjs.com/package/@payclave/sdk-react): React SDK with checkout button and hooks for client-side checkout UI.

## Implementation Checklist

- [Checkout-session API](https://www.payclave.com/developers/docs#checkout-sessions): Use a merchant backend, pass amount and merchant reference, include success/cancel URLs when needed, and persist the returned checkoutId and invoiceNumber.
- [Payment status API](https://www.payclave.com/developers/docs#payments): Use payment reads for reconciliation and support; do not treat unverified provider or browser callbacks as final settlement.
- [Webhook verification](https://www.payclave.com/developers/docs#webhook-verification-errors): Verify `X-Payclave-Signature` and timestamp tolerance before fulfilling orders from webhook events.
- [API error codes](https://www.payclave.com/developers/docs#api-error-codes): Handle validation, idempotency, rate limit, wallet setup, state mismatch, webhook, and upstream provider errors explicitly.

## Optional

- [Payclave home](https://www.payclave.com/): Product positioning and high-level explanation of Payclave hosted stablecoin checkout.
- [SDK installation commands](https://www.payclave.com/developers/docs#sdks): Package-manager install commands for npm, pnpm, yarn, and Bun.
- [API key guidance](https://www.payclave.com/developers/docs#authentication): Secondary reference for key prefixes, accepted auth headers, and browser-versus-server key usage.