Payclave API Documentation

Quickstart

The recommended production integration starts on your server. Create a checkout session with a secret key, then redirect the customer to the returned hosted checkout URL.

curl https://api.payclave.com/v1/checkout-sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_8431" \
  -d '{
    "amount": "25.00",
    "customerEmail": "customer@example.com",
    "externalReference": "order_8431",
    "successUrl": "https://merchant.example/orders/8431/success",
    "cancelUrl": "https://merchant.example/cart",
    "metadata": { "cartId": "cart_8431" }
  }'

Payclave SDKs

The recommended way to integrate Payclave checkout is by using one of our official SDKs. Browser libraries cover public-key checkout flows, while the TypeScript server SDK supports backend checkout-session and invoice creation with secret keys.

npm install @payclave/sdk-server@0.1.1
npm install @payclave/sdk-js@0.1.1
npm install @payclave/sdk-react@0.1.1

import { createPayclaveClient } from "@payclave/sdk-js"

const payclave = createPayclaveClient({
  publicKey: "pk_test_...",
})

await payclave.redirectToCheckout({
  amount: "25.00",
  reference: "order_8431",
  idempotencyKey: "order_8431",
})

SDK behavior and options

Server SDK methods

The methods below are verified against the published @payclave/sdk-server@0.1.1 package. Reads take an id; create methods take their input object. Send idempotencyKey as an SDK option. listWebhookDeliveries supports only limit in this release. Use HTTP for itemized invoices and their actions, PDFs, payment links, endpoint management, delivery filtering and replay, reconciliation and diagnostics. The published types also omit newer cumulative money fields; read the full HTTP response when you need those fields.

Authentication

Send API keys as a bearer token in theAuthorizationheader or throughX-API-Key. Dashboard sign-up and email verification are separate from API-key authentication. Publishable keys can create and read checkout sessions only. A publishable-key create request may contain onlyamount andexternalReference. Secret keys can set the complete checkout-session request and are required for invoices, payment reads, and webhook endpoints.

curl https://api.payclave.com/v1/invoices/INV-PCLV-17791920002731 \
  -H "Authorization: Bearer sk_test_..."

curl https://api.payclave.com/v1/checkout-sessions/chk_pclv_example \
  -H "X-API-Key: pk_test_..."

API basics

Idempotency and safe retries

Supply an Idempotency-Key when retrying supported create or mutation operations. Use a unique key per business operation and reuse it only for the same method, resource and payload. Keys contain visible ASCII with no spaces and at most 255 characters. Webhook replay requires at least 8 characters. Public invoice and payment-link checkout submissions require a key. Most authenticated mutations accept one optionally. Use HTTP for mutation methods that are not in the published SDK.

The shared mutation replay window is 24 hours. An eligible replay includesIdempotency-Replayed: true. Checkout and invoice creation use resource-specific duplicate detection; do not assume a universal retention period. Changed input returns IDEMPOTENCY_KEY_CONFLICT. If a matching operation is still in progress, wait and retry the same request. Retry transient network failures, 429 responses and 5xx errors with backoff and jitter only when the operation is retry-safe. Respect Retry-After when present. The SDK does not automatically retry requests. Do not retry validation or permission errors unchanged.

Pagination and limits

Invoice, payment-link and export lists return items, hasMore and nextCursor inside data. Send nextCursor as startingAfter and keep the same filters. Use limit between 1 and 100; the default is 25. Other list routes can return arrays without cursors; consult the endpoint reference instead of assuming every list supports pagination. Request bodies have a 1 MiB global ceiling and many mutation routes have smaller limits; 413 indicates an oversized body.

Test the complete integration

1. Create a merchant account and test credentials in the dashboard. Test mode uses simulated payments and needs no real tokens or funded wallet.
2. Create a checkout from your backend using a stored, authorized order and a stable idempotency key. Save the returned invoice and checkout IDs.
3. Open checkoutUrl and test paid, underpaid, overpaid, failed and expired outcomes in the playground. Retry the same creation request to check duplicate handling.
4. Create a test-mode webhook endpoint. Save signingSecret immediately. Verify delivery using /v1/webhooks/test, but reject data.test events from order fulfillment.
5. Complete a simulated checkout to test actual invoice lifecycle events. Verify raw-body signatures and mode, persist event acceptance, and fulfill each order only once.
6. Test duplicate delivery, temporary endpoint failure, replay and secret rotation. Verify that failed acceptance returns a non-2xx response and that retries do not repeat fulfillment.
7. Read the invoice from your server after a redirect. Confirm it matches the order amount, currency and mode. A success-page visit alone must never mark an order paid.

Go-live checklist

Complete the test flow before creating live credentials. Treat test and live modes as separate integrations.

1. Create a test merchant profile and keep the test public and secret keys in separate client and server configuration.
2. Create a test checkout session from your server and open the returned Payclave checkout URL from your customer flow.
3. Verify the raw webhook request body with the endpoint secret before parsing or trusting the event.
4. Accept each webhook event and queue fulfillment in one durable transaction; deduplicate event IDs and order fulfillment.
5. Register a test webhook endpoint, send a test event, and confirm delivery status, retry behavior, and replay handling.
6. Request live activation and configure the live USDC or USDT settlement wallet on Polygon.
7. Create separate live API keys and webhook secrets. Never copy test credentials into live configuration.
8. Use HTTPS success and cancel URLs that you control, and confirm each live redirect destination before launch.
9. Run a small live payment and compare the invoice total, customer credit, platform fee, expected net settlement and actual merchant receipt.
10. Fulfill only after checking a non-synthetic invoice.paid event or authoritative invoice read against your stored order, amount, currency and live mode. Retain meta.requestId for support.

Errors

All API responses include asuccessboolean and a request id inmeta.requestId. Error responses use 400 for invalid input, 401 for missing or invalid credentials, 403 for forbidden key capabilities, 409 for mode or state conflicts, 422 when a valid request cannot be processed, and 429 for rate limits. The same request ID is returned inX-Request-Id.

{
  "success": false,
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Amount must be a positive value with up to 6 decimal places."
  },
  "meta": {
    "requestId": "req_..."
  }
}

Handling errors

Branch on the stableerror.codevalue, logmeta.requestIdfor support, and keeperror.detailsfor field-level context. Retry only timeout, network, 429, and 5xx failures, and reuse the sameIdempotency-Keyfor retrying a checkout-session or invoice creation request.

import {
  createPayclaveServerClient,
  PayclaveError,
} from "@payclave/sdk-server"

const payclave = createPayclaveServerClient({
  secretKey: process.env.PAYCLAVE_SECRET_KEY!,
})

try {
  const session = await payclave.createCheckoutSession({
    amount: "25.00",
    externalReference: "order_8431",
    idempotencyKey: "order_8431",
  })

  return Response.json({ checkoutUrl: session.checkoutUrl })
} catch (error) {
  if (error instanceof PayclaveError) {
    console.error(error.code, error.status, error.requestId, error.details)

    if (error.code === "RATE_LIMIT_EXCEEDED" || error.status >= 500) {
      // Retry later with the same Idempotency-Key.
    }
  }

  throw error
}

API error codes

SDK error codes

Webhook verification errors

Webhooks

Register webhook endpoints to receive signed events such asinvoice.paid. The delivery API returns delivery status, attempt count, the latest response code or error, and retry state.

curl https://api.payclave.com/v1/webhook-endpoints \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://merchant.example/webhooks/payclave",
    "eventTypes": ["invoice.paid", "payment.failed"]
  }'

Supported event types

Security

Each webhook includesX-Payclave-Signature,X-Payclave-Timestamp,X-Payclave-Delivery, andX-Payclave-Event.

A delivery times out after 10 seconds. Return a 2xx only after durably accepting the event, then process fulfillment asynchronously. After the first four failed attempts, Payclave retries after 1 minute, 5 minutes, 30 minutes, and 2 hours. A fifth failed attempt ends automatic retries.

Payclave never follows redirects. Attempt details include duration, a stable failure category, signature-free request-header evidence, and a sanitized response excerpt capped at 4 KB. Repeated failures open one endpoint incident and a later successful delivery resolves it.

Signing-secret rotation keeps the previous secret valid for at most 24 hours. During the overlap,X-Payclave-Signatureis exactlyt=<timestamp>,v1=<new>,v1=<old>. Verify every v1 value and accept the delivery when any value matches the endpoint secret. After a successful test, end the overlap; otherwise it expires automatically.

import { constructPayclaveWebhookEvent } from "@payclave/sdk-server"

type EventStore = {
  processOnce(eventId: string, handler: () => Promise<void>): Promise<void>
}

declare const eventStore: EventStore
declare function queueFulfillment(data: unknown): Promise<void>

export async function verifyPayclaveWebhook(request: Request) {
  const rawBody = await request.text()
  const signature = request.headers.get("X-Payclave-Signature") ?? ""

  const event = constructPayclaveWebhookEvent({
    payload: rawBody,
    signature,
    secret: process.env.PAYCLAVE_WEBHOOK_SECRET!,
  })

  const expectedMode = process.env.PAYCLAVE_MODE
  if (expectedMode !== "test" && expectedMode !== "live") {
    throw new Error("Set PAYCLAVE_MODE to test or live")
  }
  if (event.mode !== expectedMode) {
    return new Response(null, { status: 204 })
  }

  await eventStore.processOnce(event.id, async () => {
    if (event.type === "invoice.paid" && event.data.test !== true) {
      // Validate the invoice against your stored order before fulfillment.
      await queueFulfillment(event.data)
    }
  })

  return new Response(null, { status: 204 })
}

Create a checkout session

Creates a hosted checkout session and a linked invoice. The customer should open the returnedcheckoutUrlto pay through the Payclave-branded checkout.

{
  "success": true,
  "data": {
    "id": "chk_pclv_01HY7W9QK3P9M8Z6A4N2B7C1D9",
    "checkoutId": "chk_pclv_01HY7W9QK3P9M8Z6A4N2B7C1D9",
    "object": "checkout_session",
    "mode": "test",
    "status": "pending",
    "invoiceId": "INV-PCLV-17791920002731",
    "invoiceNumber": "INV-PCLV-17791920002731",
    "amountDue": "25.00",
    "currencyCode": "USDT",
    "chainId": 137,
    "tokenSymbol": "USDT",
    "tokenContract": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "settlementWalletAddress": "0x1111111111111111111111111111111111111111",
    "externalReference": "order_8431",
    "checkoutUrl": "https://www.payclave.com/checkout/chk_pclv_01HY7W9QK3P9M8Z6A4N2B7C1D9",
    "expiresAt": "2026-05-19T12:30:00Z",
    "createdAt": "2026-05-19T12:00:00Z"
  },
  "meta": {
    "requestId": "req_..."
  }
}

Create an invoice

Create an itemized draft from trusted server code. Payclave calculates canonical totals at the settlement token's 6-decimal scale, rounding line multiplication and percentage discounts half-up. Issue the draft to lock its commercial fields, assign an invoice number, and create its hosted invoice and first checkout session.

curl https://api.payclave.com/v1/invoices \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice_8431" \
  -d '{
    "customer": { "name": "Ada Lovelace", "email": "ada@example.com" },
    "lines": [{
      "description": "Implementation",
      "quantity": "2.5",
      "unitAmount": "10.00"
    }],
    "externalReference": "invoice_8431",
    "metadata": { "plan": "pro" }
  }'

Invoice request fields

# Replace the id and version with the values in your draft response.
curl https://api.payclave.com/v1/invoices/inv_example/issue \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: issue_invoice_8431" \
  -d '{ "version": 1, "send": true }'

Payment links

Create a Payclave-hosted public payment page from trusted server code. A customer submission creates a new invoice and checkout session; the invoice and independently verified payment remain the payment source of truth.

curl https://api.payclave.com/v1/payment-links \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: consulting_deposit_123" \
  -d '{
    "title": "Consulting deposit",
    "amountType": "fixed",
    "amount": "250.00",
    "usageType": "single_use",
    "collect": { "email": true, "reference": true },
    "successUrl": "https://merchant.example/orders/paid"
  }'

All editable fields

Public checkout API

GET /v1/public/payment-links/:publicId returns only customer-safe display configuration. It excludes the settlement wallet, token contract, merchant metadata, internal IDs, and counters. POST /v1/public/payment-links/:publicId/checkout accepts the displayed version, an amount only for customer-entered links, and configured customer fields. It requires an Idempotency-Key and returns invoiceId, checkoutSessionId, checkoutUrl, and expiresAt.

Retrieve a payment

Payment records track detected and verified onchain attempts. Payclave still marks invoices paid only after checking the transaction hash, recipient wallet, token contract, chain ID, amount received, expiry, and duplicate usage.

Webhook endpoints

List and retrieve endpoints with GET, change URL, state, subscriptions, or alert preferences with PATCH, and archive with DELETE. Rotate withPOST /v1/webhook-endpoints/:id/rotate-secretand finish migration withPOST /v1/webhook-endpoints/:id/end-secret-overlap. Updates, archival, and rotation accept an optional Idempotency-Key in the HTTP API. These methods are not in the published server SDK 0.1.1. Endpoint creation does not support idempotent replay. A newly generated signing secret is returned once.

Webhook deliveries

HTTP API reference

All paths below are relative to https://api.payclave.com. Replace path placeholders with API-returned identifiers. Success codes describe the HTTP response; JSON results are wrapped in data. PDF and export downloads return file bytes.