API Reference

PaymentProvider

The PaymentProvider interface — the contract every payment gateway implements.

The PaymentProvider interface defines the contract for payment gateways. Every provider — Tap, Stripe, PayPal — implements these four methods.

Interface Definition

interface PaymentProvider {
  createSession(input: CreatePaymentSessionInput): Promise<PaymentSession>
  confirmSession(sessionId: string): Promise<PaymentSession>
  refund(input: RefundInput): Promise<PaymentSession>
  verifyWebhook(event: PaymentWebhookEvent): Promise<boolean>
}

createSession

Creates a payment session (charge) with the provider.

Parameters:

interface CreatePaymentSessionInput {
  amount: number                // Total to charge
  currency: string             // ISO currency code
  sourceToken?: string         // Tokenized card from client SDK
  idempotencyKey?: string      // Prevent duplicate charges
  orderId?: string             // External order reference
  customerId?: string          // Customer ID in provider system
  customer?: {                 // Customer details for new charges
    email: string
    firstName: string
    lastName: string
    phone?: string
  }
  returnUrl?: string           // 3DS redirect return URL
  cancelUrl?: string           // Payment cancellation URL
  webhookUrl?: string          // Per-transaction webhook URL
  metadata?: Record<string, unknown>
}

Returns: Promise<PaymentSession>

Behavior:

Creates a charge or payment intent with the provider
Returns a redirectUrl if 3DS/SCA is required
Returns null for redirectUrl if payment is captured directly

confirmSession

Confirms a payment after 3DS redirect or async completion.

Parameters:

sessionId (string) — The provider's charge/payment intent ID

Returns: Promise<PaymentSession>

Behavior:

Retrieves the payment status from the provider
Returns the updated PaymentSession with final status

refund

Creates a refund for a captured payment.

Parameters:

interface RefundInput {
  sessionId: string           // Original payment session ID
  amount?: number             // Partial refund amount (full if omitted)
  reason?: string             // Refund reason
}

Returns: Promise<PaymentSession> with status 'refunded'

verifyWebhook

Verifies the authenticity of a webhook event from the provider.

Parameters:

interface PaymentWebhookEvent {
  headers: Record<string, string>  // Request headers
  body: unknown                     // Raw request body
  rawBody?: string                  // Raw body string for signature verification
}

Returns: Promise<boolean> — true if the webhook is authentic

PaymentSession

The payment session tracks the lifecycle of a single payment:

interface PaymentSession {
  id: string                       // Provider's charge/intent ID
  providerId: string               // Provider identifier ('tap', 'stripe')
  status: PaymentSessionStatus     // Current payment status
  amount: number                   // Charged amount
  currency: string                 // ISO currency code
  redirectUrl: string | null       // 3DS/SCA redirect URL
  providerData?: Record<string, unknown>  // Raw provider response
  createdAt: string                // ISO timestamp
}

PaymentSessionStatus

type PaymentSessionStatus =
  | 'pending'           // Created, not yet processed
  | 'processing'        // Being processed by provider
  | 'requires_action'   // Customer action needed (3DS)
  | 'captured'          // Payment captured
  | 'failed'            // Payment declined or failed
  | 'cancelled'         // Payment cancelled
  | 'refunded'          // Payment refunded

Implementations

Package	Provider
`@commercejs/payment-tap`	Tap Payments

See the Payment Integration guide to build your own PaymentProvider implementation.

Multi-Adapter Composition

How to compose domains from multiple commerce platforms and auto-fill gaps with fallback adapters.

CommerceAdapter

The CommerceAdapter interface — the contract every eCommerce platform implements.