Node.js SDK

@tapayadot/checkout is the server-side TypeScript SDK for Tapaya Checkout. This reference describes version 0.1.1.

The package requires Node.js 22.13.0 or newer and uses ES modules. It includes TypeScript declarations. The npm package name is @tapayadot/checkout; the source repository is tapayadot/checkout-node.

npm install @tapayadot/checkout

import { Tapaya } from '@tapayadot/checkout';

const tapaya = new Tapaya();

The client reads TAPAYA_SECRET_KEY from the server environment. It does not load .env files. Keep the key and client in server-only code. The Hosted Checkout guide covers creating an order, redirecting the customer, and verifying payment.

Configuration

const tapaya = new Tapaya(apiKey, {
	environment: 'sandbox',
	timeoutMs: 30_000,
	maxRetries: 2,
})

The client resolves the API key and API environment once, when it is constructed. Use a key that matches the selected environment. API, return, and hosted checkout URLs must use HTTPS, except that HTTP is allowed for localhost, 127.0.0.1, and [::1] outside NODE_ENV=production. The SDK checks the current NODE_ENV each time it validates a local HTTP URL.

timeoutMs must be an integer from 1 to 2,147,483,647. maxRetries must be a nonnegative safe integer. The default retry count allows up to three attempts per call, each with its own timeout.

Each method also accepts signal, timeoutMs, and maxRetries for a single request:

const current = await tapaya.checkout.sessions.get(sessionId, {
	signal: request.signal,
	timeoutMs: 5_000,
})

When the signal aborts, the method stops immediately, without retrying, and rejects with the signal's reason.

Checkout sessions

Create a session

tapaya.checkout.sessions.create(params, options?) requires amount and currency. amount is the final total, including tax and shipping, an integer between 1 and 2,147,483,647 minor units. currency is a three-letter ISO 4217 code. Tapaya stores and returns it uppercase.

Optional fields:

Before sending, the SDK checks types, required fields, integer amounts, the currency format, and a maximum email length of 254 characters. Return URLs must be absolute HTTPS URLs, with the local HTTP exception described under Configuration. Tapaya validates business rules such as email format, address limits, and country codes, and reports problems as TapayaInvalidRequestError. See Checkout Sessions for field rules, tax totals, and customer address limits.

Get a session

tapaya.checkout.sessions.get(id, options?) returns the current state of a session. The ID must be a nonblank string of at most 200 characters; . and .. are invalid. The SDK URL-encodes the ID.

Both methods return Promise<CheckoutSession>:

Handle unknown status and paymentStatus values, for example by treating them as not yet paid. Only paymentStatus: 'successful' proves payment.

A declined card is a payment outcome, not an error. The session stays open with paymentStatus: 'failed', and the customer can try again.

Idempotency and retries

Every create request sends an Idempotency-Key. An explicit key must be a nonblank string of at most 255 printable ASCII characters. If you omit idempotencyKey, the SDK generates a random key for each call. Within that call, retries reuse the key, so a retry never creates a second session.

To stay safe across separate calls and process restarts, store a key with the order and pass it every time you create a session for that attempt, with the same parameters. Tapaya returns the original session instead of creating a new one. Use a new key only for a new checkout attempt, never to retry an uncertain result.

A repeated create returns the original response, including its original payment status. Call tapaya.checkout.sessions.get(session.id) to get the current status before fulfilling the order.

The SDK retries both methods after network errors, timeouts, and HTTP 429, 502, 503, and 504. It also retries a create that fails with HTTP 409 API-0024, which means an earlier request with the same key is still being processed. Retries send the same key and body, so they return the original session once it is ready. The SDK waits between attempts with exponential backoff and jitter, and honors Retry-After up to 10 seconds. When Tapaya asks for a longer wait, the SDK stops retrying and throws the error for that HTTP status: TapayaRateLimitError for 429, TapayaServerError for 502, 503, or 504, or TapayaConflictError for 409. Only TapayaRateLimitError exposes the requested delay as retryAfterMs; other HTTP errors retain the Retry-After header in headers. All retries share the maxRetries budget. Set maxRetries: 0 to turn retries off.

If a create still fails with API-0024 after retries, wait and retry with the same key and parameters. If the conflict persists, stop retrying and contact Tapaya support with the idempotency key, the request time, and the order reference. Never switch to a new key to get past the conflict: the original request may already have created a session, and a new key can create a second one.

Errors

SDK error classes extend TapayaError. An aborted request rejects with the signal's reason.

HTTP errors carry status, the Tapaya error code, fieldErrors ({ field, message, code? }[]), the response headers, and requestId from the X-Request-Id header, when present. The backend does not currently set this header. Include the session ID or order reference and the request time in support requests, along with requestId if available. TapayaResponseError carries status, headers, and requestId too. TapayaValidationError carries fieldErrors too, with field set to the parameter path, such as customer.email.

import { TapayaConnectionError, TapayaError, TapayaValidationError } from '@tapayadot/checkout'

try {
	const session = await tapaya.checkout.sessions.create(params, { idempotencyKey })
	return Response.redirect(session.url, 303)
} catch (error) {
	if (error instanceof TapayaValidationError) {
		console.error(error.fieldErrors)
	} else if (error instanceof TapayaConnectionError) {
		// The outcome is unknown. Retry later with the same idempotency key.
	} else if (error instanceof TapayaError) {
		console.error(error.message)
	}
	throw error
}

Exported types

The package exports TapayaEnvironment, TapayaOptions, RequestOptions, CreateSessionOptions, CreateCheckoutSessionParams, CheckoutSessions, CheckoutSession, CheckoutSessionStatus, CheckoutPaymentStatus, CheckoutItem, TaxBreakdownEntry, CheckoutCustomer, CheckoutContactAddress, and TapayaFieldError.

VERSION contains the SDK version. Types use named imports with import type:

import type { CheckoutSession, CreateCheckoutSessionParams } from '@tapayadot/checkout';