Package Exports
- @vonpay/checkout-node
Readme
@vonpay/checkout-node
Node.js / TypeScript SDK for the Von Payments Checkout API. Create hosted checkout sessions, verify webhook signatures, and validate signed return redirects.
Install
npm install @vonpay/checkout-nodeRequires: Node 20+. ESM only. Zero runtime dependencies.
Quick start
import { VonPayCheckout, VonPayError } from "@vonpay/checkout-node";
const vonpay = new VonPayCheckout("vp_sk_test_...");
const session = await vonpay.sessions.create({
amount: 1499,
currency: "USD",
country: "US",
successUrl: "https://example.com/order/123/confirm",
});
console.log(session.checkoutUrl);
// https://checkout.vonpay.com/checkout?session=vp_cs_test_...Discrete-lifecycle API
The paymentIntents, refunds, tokens, and capabilities namespaces give server-side control over payment intents, alongside the existing hosted-checkout sessions flow.
// Create a payment intent (auth + capture)
const intent = await vonpay.paymentIntents.create(
{
amount: 1499,
currency: "usd",
captureMethod: "automatic",
metadata: { orderId: "ord_42" },
},
{ idempotencyKey: "ord_42-charge-1" },
);
console.log(intent.id, intent.status); // "vpi_live_…", "succeeded"
// Auth-only + later capture (fulfillment-on-ship)
const auth = await vonpay.paymentIntents.create({ amount: 1499, currency: "usd", captureMethod: "manual" });
await vonpay.paymentIntents.capture(auth.id, { amountToCapture: 1499 });
// Refund a captured intent (partial or full)
const refund = await vonpay.refunds.create({ paymentIntent: intent.id, amount: 500 });
// Create a reusable token for save-card / MIT flows
const token = await vonpay.tokens.create({ buyerId: "buyer_42", setupForFutureUse: "off_session" });
// Read the merchant's processor capability matrix before invoking optional ops
const caps = await vonpay.capabilities.get();
if (caps.supportedOperations.partialRefund) {
// partial refunds supported — safe to offer partial-refund UI
}The SDK presents a camelCase API and translates to the server's snake_case wire format automatically.
Features
- Typed session / webhook / error objects — full
CheckoutSession,SessionStatus,WebhookEvent,VonPayError, discriminated-unionErrorCode. - Webhook verification — HMAC-SHA256 with ±5 minute timestamp replay protection via
webhooks.constructEvent(). - Signed return URL verification (v1 + v2) —
VonPayCheckout.verifyReturnSignature()supports both legacy v1 signatures and v2 signatures that bindsuccessUrl,keyMode, andiatfreshness. - Auto-retry — exponential backoff on 429 / 5xx with
Retry-Afterheader support. - Request ID tracing — every response includes
X-Request-Idfor support tickets. - Rate-limit info — parsed from response headers into
VonPayError.rateLimit.
Documentation
License
MIT