Frontend

Next.js SDK

Next.js App Router helpers, route handlers for webhooks and server actions for payments.

Updated Jul 15, 2026SDK v1.0.0API 2026-07-01 Edit on GitHub Report an issue

Next.js App Router helpers, route handlers for webhooks and server actions for payments. This page follows the same layout as every other Korven One SDK reference — install, authenticate, ship your first request, then wire webhooks and production-grade retries.

Overview

Next.js is a first-party integration for the Korven One platform. It ships with typed models, a signed-webhook verifier and idempotent request helpers so you can build reliable payment, wallet and remittance flows.

Installation

API v1

npm install @korvenone/next

Requirements

Next.js 14+
A Korven One account with sandbox and (optionally) live API keys
An HTTPS-reachable webhook endpoint for asynchronous events

Authentication

Every request is authenticated with a bearer token. Use sk_test_... in sandbox and sk_live_... once your merchant account is activated. Never ship secret keys to the browser — use publishable keys (pk_*) for client-side flows.

API v1

export KORVEN_SECRET_KEY=sk_test_...

Quickstart

Create your first payment in under a minute. The snippet below uses the sandbox environment and an idempotency key so retries are safe.

SDK v1.0.0

import Korven from "@korvenone/next";

const korven = new Korven(process.env.KORVEN_SECRET_KEY!);

const payment = await korven.payments.create({
  amount: 250_000,
  currency: "HTG",
  customer: "cus_9a2b",
}, { idempotencyKey: crypto.randomUUID() });

Example response

{
  "id": "pay_01HT3M9QK7ZS9V0AB1CDEFGH",
  "object": "payment",
  "amount": 250000,
  "currency": "HTG",
  "status": "succeeded",
  "customer": "cus_9a2b",
  "receipt_number": "RCP-2026-0000142",
  "livemode": false,
  "created": 1794902400
}

Errors & retries

The Korven One API uses deterministic error codes. Any 5xx response or network failure is safe to retry with the same Idempotency-Key — the API will replay the original result instead of creating a duplicate.

Recommended strategy

Exponential backoff: 250ms, 500ms, 1s, 2s, 4s (max 5 attempts).
Always include an Idempotency-Key on writes.
Surface 4xx validation errors to the user immediately.

Rate limits

Default limits: 100 read requests / second and 25 write requests / second per API key. Response headers X-RateLimit-Remaining and X-RateLimit-Reset expose the current window; a 429 response includes a Retry-After header.

Webhooks

Subscribe to events like payment.succeeded, payment.failed and settlement.paid. Every delivery is signed with HMAC-SHA256 — verify the Korven-Signature header before trusting the payload.

Examples

Hosted checkout for one-off payments
Recurring subscriptions with proration
Marketplace split payments and payouts
Cross-border remittances with locked FX quotes