# 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.

- 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.
- Default settlement target for the MVP is USDT on Polygon. Hosted checkout may orchestrate supported source tokens or chains, but the merchant receives the invoice amount in the configured settlement wallet.
- Base API URL: https://api.payclave.com. Hosted checkout URLs look like https://pay.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_*`) are only for limited browser checkout creation.
- 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.
- Always send an `Idempotency-Key` for create operations that may be retried. Reuse an idempotency key only with the same request 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.paid`, `invoice.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.
- 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 independently reading a confirmed payment/invoice status from the API.

## Primary Documentation

- [Payclave API docs](https://payclave.com/developers/docs): Human-readable documentation for checkout sessions, invoices, payments, webhooks, authentication, SDKs, and errors.
- [Quickstart](https://payclave.com/developers/docs#quickstart): Create a checkout session from a merchant backend and redirect the customer to hosted checkout.
- [Authentication](https://payclave.com/developers/docs#authentication): API key formats, supported headers, and when to use publishable versus secret keys.
- [Errors](https://payclave.com/developers/docs#errors): Error response envelope, retry guidance, request IDs, API error codes, SDK errors, and webhook verification failures.

## API Resources

- [Create checkout sessions](https://payclave.com/developers/docs#checkout-sessions): POST /v1/checkout-sessions creates a Payclave-hosted checkout URL and linked invoice.
- [Create invoices](https://payclave.com/developers/docs#invoices): POST /v1/invoices creates a durable server-side invoice record without immediately returning hosted checkout UI.
- [Retrieve payments](https://payclave.com/developers/docs#payments): GET /v1/payments/:id reads detected and verified onchain payment records.
- [Webhook overview](https://payclave.com/developers/docs#webhooks): Signed payment lifecycle events, webhook security headers, and server SDK verification.
- [Webhook endpoints](https://payclave.com/developers/docs#webhook-endpoints): POST /v1/webhook-endpoints registers merchant endpoints and subscribed event types.
- [Webhook deliveries](https://payclave.com/developers/docs#webhook-deliveries): GET /v1/webhook-deliveries inspects webhook delivery status, attempts, responses, and retry state.

## SDKs

- [Official libraries](https://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://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://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://payclave.com/developers/docs#webhook-verification-errors): Verify `X-Payclave-Signature` and timestamp tolerance before fulfilling orders from webhook events.
- [API error codes](https://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://payclave.com/): Product positioning and high-level explanation of Payclave hosted stablecoin checkout.
- [SDK installation commands](https://payclave.com/developers/docs#sdks): Package-manager install commands for npm, pnpm, yarn, and Bun.
- [API key guidance](https://payclave.com/developers/docs#authentication): Secondary reference for key prefixes, accepted auth headers, and browser-versus-server key usage.