Stablecoin checkout integration guide

Create a stablecoin checkout session from your backend.

A production checkout starts with a trusted order amount on your server. Your backend creates the Payclave session, stores the returned identifiers, and sends the customer to the hosted checkout URL. Payment confirmation arrives later through a verified webhook or API read.

Maintained by Payclave Product and Engineering. Updated .

Try the API in test modeRead the API reference

Keep price authority on your server

Create production orders with a secret key so the browser cannot replace the amount, return URLs, customer details, or metadata.

Make creation safe to retry

Send one stable Idempotency-Key for each logical order and reuse it only when retrying the same request body.

Wait for verified payment

The customer return URL is navigation, not proof. Fulfill after a verified invoice.paid event or a confirmed API read.

Prepare the merchant and test credentials

Create a Payclave merchant profile, configure a test settlement wallet for USDC or USDT on Polygon, and generate a test secret key. Test and live credentials belong in separate server configuration. Never send a secret key to browser code.

Use a merchant order ID as the external reference. The value should let your backend find the order without placing customer details or sensitive metadata in a URL.

  • Store PAYCLAVE_SECRET_KEY in server-only configuration.
  • Create the order and calculate its amount before calling Payclave.
  • Choose one idempotency key for that order creation attempt.
  • Use HTTPS success and cancel URLs that your business controls.

Send the checkout-session request

POST the trusted amount and external reference to /v1/checkout-sessions. A secret key can also set the customer email, return URLs, metadata, and expiry. Amount strings accept up to six fractional digits.

If the request times out or returns a retryable server error, send the same payload with the same Idempotency-Key. Reusing that key with different input returns an idempotency conflict because it no longer represents the same operation.

Create a test checkout with cURLbash
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": "ada@example.com",
    "externalReference": "order_8431",
    "successUrl": "https://merchant.example/orders/8431/success",
    "cancelUrl": "https://merchant.example/cart"
  }'

Store the response and redirect the customer

A successful response links the checkout session to an invoice and returns the hosted checkout URL. Store the checkout ID, invoice ID, external reference, status, and expiry with the merchant order. Keep meta.requestId in logs so a failed request can be traced without logging credentials.

Return only the hosted checkout URL or another customer-safe value to the frontend. The customer should open the Payclave-branded URL and pay by connecting a supported wallet or following the one-time Scan or copy instructions.

Checkout-session responsejson
{
  "success": true,
  "data": {
    "checkoutId": "chk_pclv_...",
    "invoiceId": "INV-PCLV-...",
    "status": "pending",
    "amountDue": "25.00",
    "tokenSymbol": "USDT",
    "chainId": 137,
    "checkoutUrl": "https://www.payclave.com/checkout/chk_pclv_...",
    "expiresAt": "2026-09-30T23:59:59Z"
  },
  "meta": {
    "requestId": "req_..."
  }
}

Treat the return URL as navigation

A customer can reach a success URL before your backend has reliable payment evidence. Do not mark the order paid from a browser query parameter, client callback, wallet message, or payment-orchestration response.

Payclave marks the invoice paid only after independent onchain verification. Your backend should verify the signed invoice.paid webhook, claim its event ID in durable storage, and then update fulfillment. A confirmed invoice read through the secret-key API is a useful secondary check.

Run the complete flow in test mode

Test the failure path as carefully as the happy path. Retry session creation, reject a payment, exercise underpaid and overpaid outcomes, deliver the same webhook twice, and confirm the order changes state only once.

Move to live mode with separate keys, a live settlement wallet, and an approved small payment. Reconcile the invoice amount, platform fee, merchant settlement, payment record, and wallet receipt before opening checkout to customers.

For the complete request fields, response schemas, error codes, and event types, use the Payclave API reference.

Related guides

Continue with the next implementation decision.

Verify webhook signatures

Verify Payclave webhook signatures against the raw request body, reject stale deliveries, deduplicate event IDs, and fulfill each stablecoin order once.

Read the guide

Onchain payment verification

Learn how Payclave verifies stablecoin settlement, confirmation state, recipient, token, amount, expiry policy, and duplicate transaction use before paid status.

Read the guide

Reconcile stablecoin payments

Reconcile Payclave invoices, payment records, platform fees, and direct wallet settlement without treating a transaction hash as the complete order record.

Read the guide

Test the workflow

Create a checkout before changing your production order flow.

Use test keys and the API playground to verify checkout creation, payment status, and signed webhook handling.

Open API playgroundStart merchant setup