API Documentation

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"
    }
  }'

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

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

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

{
  "success": false,
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Amount must be a positive USDT value with up to 6 decimals.",
    "details": {
      "field": "amount"
    }
  },
  "meta": {
    "requestId": "req_..."
  }
}

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
}

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"]
  }'

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

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!,
  })

  if (event.type === "invoice.paid") {
    // Fulfill the order referenced by event.data.
  }

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

curl https://api.payclave.com/v1/invoices \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice_8431" \
  -d '{
    "amount": "25.00",
    "externalReference": "invoice_8431",
    "metadata": {
      "plan": "pro"
    }
  }'