### Development Setup and Build

Source: https://github.com/bizup-dev/bizup-pay/blob/main/README.md

Commands for cloning the repository, installing dependencies, building the project, and running unit tests. This section is for developers contributing to the BizUp Pay project.

```bash
git clone https://github.com/bizup-dev/bizup-pay.git
cd bizup-pay
npm install
npm run build
npm test          # 131 unit tests
```

--------------------------------

### Running the Demo Application

Source: https://github.com/bizup-dev/bizup-pay/blob/main/CLAUDE.md

Instructions for setting up and running the BizUp Pay demo application. This involves starting mock payment servers in one terminal and the Next.js demo app in another.

```bash
# Terminal 1: mock payment servers (ports 4100/4200/4300)
node packages/mock-server/dist/standalone.js

# Terminal 2: Next.js demo app (port 3099)
cd examples/checkout-demo && npx next dev -p 3099
```

--------------------------------

### Create Payment Session with iCount (Access Token)

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/providers.html

This code example shows how to initiate a payment session with the iCount provider using an access token for authentication. It requires the company ID, pay page ID, and the access token. The payment details and success/webhook URLs are configured similarly to other providers.

```typescript
import { createProvider, buildWebhookUrl } from '@bizup-pay/core'
import '@bizup-pay/icount'

// Option A: Access token (recommended)
const pay = createProvider('icount', {
  cid: process.env.ICOUNT_CID!,
  paypageId: 2,
  accessToken: process.env.ICOUNT_TOKEN!,
})

const session = await pay.createSession({
  amount: 200,
  currency: 'ILS',
  description: 'Consulting Service',
  customer: { name: 'Israel Israeli', email: 'israel@example.com' },
  successUrl: 'https://yoursite.co.il/thank-you',
  webhookUrl: buildWebhookUrl('https://yoursite.co.il/api/webhook', 'your-secret'),
})

// session.pageUrl → iCount payment page
// After payment: tx.documentUrl → Invoice-receipt PDF
```

--------------------------------

### Install BizUp Pay Client SDK

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/index.html

Installs the BizUp Pay client-side SDK using npm. This package is used for mounting payment pages on the client.

```bash
$ npm install @bizup-pay/client
```

--------------------------------

### Run Demo App with Mock Server

Source: https://github.com/bizup-dev/bizup-pay/blob/main/README.md

Instructions to run the demo application, which involves starting a mock payment server in one terminal and the Next.js demo app in another. This is for testing the integration locally.

```bash
# Terminal 1: mock payment servers
node packages/mock-server/dist/standalone.js

# Terminal 2: Next.js demo
cd examples/checkout-demo && npx next dev -p 3099

Open http://localhost:3099
```

--------------------------------

### Create Grow Payment Session

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/providers.html

Initializes a payment session with Grow, including customer details and success redirection. The session returns a URL to redirect the user to the payment page.

```typescript
import { createProvider, buildWebhookUrl } from '@bizup-pay/core'
import '@bizup-pay/grow'

const pay = createProvider('grow', {
  pageCode: process.env.GROW_PAGE_CODE!,
  userId: process.env.GROW_USER_ID!,
})

const session = await pay.createSession({
  amount: 149.90,
  currency: 'ILS',
  description: 'Premium Plan',
  customer: { name: 'Israel Israeli', email: 'israel@example.com' },
  successUrl: 'https://yoursite.co.il/thank-you',
  webhookUrl: buildWebhookUrl('https://yoursite.co.il/api/webhook', 'your-secret'),
})
```

--------------------------------

### Redirect to Grow.il Payment Page in TypeScript

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/providers.html

Demonstrates how to redirect a user to the Grow.il payment page from a checkout interface. This approach requires no SDK and relies on standard browser navigation.

```typescript
// Simple redirect — no SDK needed for this part
const GROW_PAGE_URL = 'https://secure.meshulam.co.il/pay/your-page-code'

// On checkout button click:
window.location.href = GROW_PAGE_URL
```

--------------------------------

### Install BizUp Pay Core and Cardcom Provider

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/index.html

Installs the core BizUp Pay package along with the Cardcom provider using npm. This is a prerequisite for using the Cardcom payment gateway.

```bash
$ npm install @bizup-pay/core @bizup-pay/cardcom
```

--------------------------------

### Create Cardcom Payment Session

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/providers.html

Initializes a payment session using the Cardcom provider. It requires terminal credentials and generates a URL for the Cardcom Low Profile payment page.

```typescript
import { createProvider, buildWebhookUrl } from '@bizup-pay/core'
import '@bizup-pay/cardcom'

const pay = createProvider('cardcom', {
  terminalNumber: 1000,
  apiName: process.env.CARDCOM_API_NAME!,
  apiPassword: process.env.CARDCOM_API_PASSWORD!,
})

const session = await pay.createSession({
  amount: 100,
  currency: 'ILS',
  description: 'Order #1234',
  customer: { name: 'Israel Israeli', email: 'israel@example.com' },
  successUrl: 'https://yoursite.co.il/thank-you',
  webhookUrl: buildWebhookUrl('https://yoursite.co.il/api/webhook', 'your-secret'),
})
```

--------------------------------

### Install BizUp Pay Client SDK for Browser

Source: https://github.com/bizup-dev/bizup-pay/blob/main/README.md

Installs the client-side SDK for embedding payment pages within a web application using npm. This SDK is optional and used for UI integrations.

```bash
npm install @bizup-pay/client
```

--------------------------------

### Install BizUp Pay Core and Cardcom Provider

Source: https://github.com/bizup-dev/bizup-pay/blob/main/README.md

Installs the core BizUp Pay SDK and the Cardcom provider package using npm. This is the initial step to integrate Cardcom payments.

```bash
npm install @bizup-pay/core @bizup-pay/cardcom
```

--------------------------------

### Create Payment Session with iCount (Username/Password)

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/providers.html

This snippet illustrates how to create a payment session with the iCount provider using username and password for authentication. While functional, this method is not recommended for production due to security considerations. It requires company ID, pay page ID, username, and password.

```typescript
import { createProvider, buildWebhookUrl } from '@bizup-pay/core'
import '@bizup-pay/icount'

// Option B: Username/password
// const pay = createProvider('icount', {
//   cid: 'your-cid', paypageId: 2,
//   user: 'your-user', pass: 'your-pass',
// })

const session = await pay.createSession({
  amount: 200,
  currency: 'ILS',
  description: 'Consulting Service',
  customer: { name: 'Israel Israeli', email: 'israel@example.com' },
  successUrl: 'https://yoursite.co.il/thank-you',
  webhookUrl: buildWebhookUrl('https://yoursite.co.il/api/webhook', 'your-secret'),
})

// session.pageUrl → iCount payment page
// After payment: tx.documentUrl → Invoice-receipt PDF
```

--------------------------------

### Create Payment Session with Green Invoice (Morning)

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/providers.html

This snippet demonstrates how to create a payment session using the BizUp Pay core library with the Green Invoice (Morning) provider. It requires API key and secret for authentication and specifies payment details like amount, currency, and customer information. The webhook URL is built using a helper function.

```typescript
import { createProvider, buildWebhookUrl } from '@bizup-pay/core'
import '@bizup-pay/morning'

const pay = createProvider('morning', {
  apiKey: process.env.MORNING_API_KEY!,
  apiSecret: process.env.MORNING_API_SECRET!,
})

const session = await pay.createSession({
  amount: 79.90,
  currency: 'ILS',
  description: 'T-Shirt',
  customer: { name: 'Israel Israeli', email: 'israel@example.com' },
  successUrl: 'https://yoursite.co.il/thank-you',
  webhookUrl: buildWebhookUrl('https://yoursite.co.il/api/webhook', 'your-secret'),
  language: 'he',  // Hebrew payment page
})

// session.pageUrl → Morning hosted payment page
// After payment: tx.documentUrl → Invoice/receipt PDF
```

--------------------------------

### Build and Test Commands

Source: https://github.com/bizup-dev/bizup-pay/blob/main/CLAUDE.md

Common npm commands for building, testing, linting, and running end-to-end tests for the BizUp Pay project. These commands utilize tsc, vitest, and playwright for development and quality assurance.

```bash
npm run build          # tsc --build (all packages)
npm test               # vitest run (117+ unit tests)
npx playwright test    # 16+ e2e tests (needs mock servers + demo app running)
npm run lint           # eslint
```

--------------------------------

### Create and Use Payment Provider Adapters (TypeScript)

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/plans/2026-03-18-unified-payment-framework-design.md

Demonstrates how to create and use payment provider adapters using the `createProvider` function from `@bizup-pay/core`. It shows registration for 'morning' and 'cardcom' providers with their respective API credentials and provides an example of using the generic `createSession` method.

```typescript
import { createProvider } from '@bizup-pay/core'
import { MorningProvider } from '@bizup-pay/morning'
import { CardcomProvider } from '@bizup-pay/cardcom'

// Register adapters
const provider = createProvider('morning', {
  apiKey: process.env.MORNING_API_KEY,
  apiSecret: process.env.MORNING_API_SECRET,
})

// Same code, different provider
const provider = createProvider('cardcom', {
  terminalNumber: process.env.CARDCOM_TERMINAL,
  apiName: process.env.CARDCOM_API_NAME,
  apiPassword: process.env.CARDCOM_API_PASSWORD,
})

// Usage is identical
const session = await provider.createSession({
  amount: 100,
  currency: 'ILS',
  description: 'Order #1234',
  successUrl: 'https://myshop.co.il/success',
  webhookUrl: 'https://myshop.co.il/api/webhooks/payment',
  customer: { name: 'Israel Israeli', email: 'israel@example.com' },
})
// session.pageUrl → redirect or iframe this

```

--------------------------------

### Handle Grow Webhook with Bizup Pay

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/providers.html

Demonstrates how to verify and parse incoming webhooks from the Grow payment provider. It requires a webhook secret and Grow API credentials to process transaction events.

```typescript
import { createProvider, verifyWebhookSecret } from '@bizup-pay/core'
import '@bizup-pay/grow'

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET!

const pay = createProvider('grow', {
  pageCode: process.env.GROW_PAGE_CODE!,
  userId: process.env.GROW_USER_ID!,
})

export async function POST(req: Request) {
  if (!verifyWebhookSecret(req.url, WEBHOOK_SECRET)) {
    return new Response('Unauthorized', { status: 401 })
  }

  const event = await pay.parseWebhook(await req.json())

  if (event.type === 'payment.completed') {
    const tx = event.transaction
    await fulfillOrder(tx)
  }

  return Response.json({ received: true })
}
```

--------------------------------

### HTTP Client Injection for Providers

Source: https://github.com/bizup-dev/bizup-pay/blob/main/CLAUDE.md

Demonstrates how payment providers in BizUp Pay can optionally accept an `httpClient` instance in their constructor. This pattern facilitates dependency injection, enabling easier testing by allowing mock HTTP clients to be provided.

```typescript
constructor(config: Config, httpClient?: HttpClient)

// Default: globalThis.fetch. Tests inject a mock that returns fixture data.
```

--------------------------------

### Create Next.js Payment Session with Bizup Pay

Source: https://context7.com/bizup-dev/bizup-pay/llms.txt

This TypeScript code snippet demonstrates how to create a payment session on the server-side using Next.js App Router. It calculates the total amount from items, initializes the Bizup Pay provider (Cardcom in this example), and configures session details like currency, URLs, and metadata. It requires environment variables for API credentials and the application URL.

```typescript
// app/api/checkout/route.ts - Create payment session
import { NextRequest, NextResponse } from 'next/server'
import { createProvider } from '@bizup-pay/core'
import '@bizup-pay/cardcom'

export async function POST(request: NextRequest) {
  const { items, customer } = await request.json()

  const total = items.reduce(
    (sum: number, item: { price: number; quantity: number }) =>
      sum + item.price * item.quantity,
    0
  )

  const provider = createProvider('cardcom', {
    terminalNumber: Number(process.env.CARDCOM_TERMINAL),
    apiName: process.env.CARDCOM_API_NAME!,
    apiPassword: process.env.CARDCOM_API_PASSWORD!,
  })

  const session = await provider.createSession({
    amount: total,
    currency: 'ILS',
    description: `Order - ${items.length} items`,
    customer,
    successUrl: `${process.env.APP_URL}/checkout/success`,
    failureUrl: `${process.env.APP_URL}/checkout/failure`,
    webhookUrl: `${process.env.APP_URL}/api/webhook`,
    metadata: {
      items: JSON.stringify(items),
      customerId: customer.id,
    },
  })

  return NextResponse.json({ session })
}
```

--------------------------------

### Document Styling and Layout CSS

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/index.html

Contains the CSS definitions for the BizUp Pay documentation site, including grid layouts for features, step-by-step guides, and styling for code blocks and installation commands.

```css
.how-it-works { padding: 80px 0; background: #f5f7fa; }
.steps { display: grid; grid-template-columns: repeat(3, 1fr); gap: 32px; }
.step-number { width: 36px; height: 36px; border-radius: 50%; background: #4a9d7c; color: #fff; display: flex; align-items: center; justify-content: center; }
.install-cmd { display: flex; align-items: center; gap: 12px; background: #1a1f2e; border-radius: 8px; padding: 16px 20px; }
```

--------------------------------

### Run Unit Tests (Bash)

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/plans/2026-03-21-demo-app-refactor.md

This command sequence first builds the project and then runs the unit tests using Vitest. It's expected that all 116 tests will pass, indicating that the refactoring has not introduced any regressions at the unit level.

```bash
npm run build && npx vitest run
```

--------------------------------

### Creating a Provider Instance

Source: https://context7.com/bizup-dev/bizup-pay/llms.txt

Instantiates a payment provider using the `createProvider` factory function. You need to import the specific adapter for your chosen provider.

```APIDOC
## Creating a Provider Instance

### Description
Instantiates a payment provider with the specified configuration. You must import the adapter package for your chosen provider before calling this function.

### Method
`createProvider(providerName: string, config: ProviderConfig)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { createProvider } from '@bizup-pay/core'
import '@bizup-pay/cardcom' // Register Cardcom adapter

const cardcomProvider = createProvider('cardcom', {
  terminalNumber: 1000,
  apiName: process.env.CARDCOM_API_NAME!,
  apiPassword: process.env.CARDCOM_API_PASSWORD!,
  baseUrl: 'https://secure.cardcom.solutions/api/v11', // optional, uses default
})

// Provider configurations for each adapter:

// Morning (Green Invoice)
import '@bizup-pay/morning'
const morningProvider = createProvider('morning', {
  apiKey: process.env.MORNING_API_KEY!,
  apiSecret: process.env.MORNING_API_SECRET!,
  baseUrl: 'https://api.greeninvoice.co.il/api/v1', // optional
})

// iCount
import '@bizup-pay/icount'
const icountProvider = createProvider('icount', {
  cid: 'your-company-id',
  accessToken: process.env.ICOUNT_ACCESS_TOKEN!,
  paypageId: 1,
  baseUrl: 'https://api.icount.co.il/api/v3.php', // optional
})

// Grow (Meshulam)
import '@bizup-pay/grow'
const growProvider = createProvider('grow', {
  pageCode: process.env.GROW_PAGE_CODE!,
  userId: process.env.GROW_USER_ID!,
  baseUrl: 'https://meshulam.co.il/api/light/server/1.0', // optional
})
```

### Response
#### Success Response (200)
Returns an instance of the specified payment provider.

#### Response Example
```typescript
// Example for Cardcom provider instance
const cardcomProvider = {
  // ... provider specific methods and properties
}
```
```

--------------------------------

### Initialize and Create Payment Session with BizUp Pay

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/index.html

Demonstrates how to initialize a specific payment provider using the BizUp Pay SDK and create a payment session. This requires importing the core library and the specific provider package, then configuring it with terminal credentials.

```typescript
import { createProvider } from '@bizup-pay/core'
import '@bizup-pay/cardcom'  // or morning, icount, grow

const provider = createProvider('cardcom', {
  terminalNumber: 1000,
  apiName: process.env.CARDCOM_API_NAME,
})

const session = await provider.createSession({
  amount: 100,
  currency: 'ILS',
  description: 'Order #1234',
  successUrl: 'https://myshop.co.il/success',
  webhookUrl: 'https://myshop.co.il/api/webhook',
})

// Redirect customer to session.pageUrl — done.
```

--------------------------------

### Get Transaction Details by ID (TypeScript)

Source: https://github.com/bizup-dev/bizup-pay/blob/main/README.md

Retrieves the details of a specific transaction using its unique ID. This is useful for verifying payment status or obtaining transaction-specific information.

```typescript
const tx = await provider.getTransaction('219282004')
// tx.amount, tx.status, tx.cardBrand, tx.documentUrl
```

--------------------------------

### Instantiate Payment Providers with BizUp Pay

Source: https://context7.com/bizup-dev/bizup-pay/llms.txt

Demonstrates how to initialize different payment providers using the createProvider factory function. Each provider requires specific configuration parameters and the registration of its respective adapter package.

```typescript
import { createProvider } from '@bizup-pay/core'
import '@bizup-pay/cardcom'
import '@bizup-pay/morning'
import '@bizup-pay/icount'
import '@bizup-pay/grow'

const cardcomProvider = createProvider('cardcom', {
  terminalNumber: 1000,
  apiName: process.env.CARDCOM_API_NAME!,
  apiPassword: process.env.CARDCOM_API_PASSWORD!
})

const morningProvider = createProvider('morning', {
  apiKey: process.env.MORNING_API_KEY!,
  apiSecret: process.env.MORNING_API_SECRET!
})

const icountProvider = createProvider('icount', {
  cid: 'your-company-id',
  accessToken: process.env.ICOUNT_ACCESS_TOKEN!,
  paypageId: 1
})

const growProvider = createProvider('grow', {
  pageCode: process.env.GROW_PAGE_CODE!,
  userId: process.env.GROW_USER_ID!
})
```

--------------------------------

### Mount payment iframe using Client SDK

Source: https://context7.com/bizup-dev/bizup-pay/llms.txt

Shows how to initialize the BizupPay client and mount a payment session as an inline iframe. It includes event callbacks for lifecycle management and cleanup.

```typescript
import { BizupPay } from '@bizup-pay/client'
import type { BizupPaymentSession } from '@bizup-pay/core'

const session: BizupPaymentSession = await fetch('/api/checkout', {
  method: 'POST',
  body: JSON.stringify({ amount: 99.90, description: 'Order #123' }),
}).then(r => r.json())

const bizupPay = new BizupPay()

const instance = bizupPay.mount(
  session,
  document.getElementById('payment-container')!,
  {
    width: '100%',
    height: '600px',
    onLoad: () => {
      console.log('Payment page loaded')
      document.getElementById('loading')?.remove()
    },
    onSuccess: (event) => {
      console.log('Payment successful!', event.session.id)
      window.location.href = '/thank-you'
    },
    onFailure: (event) => {
      console.error('Payment failed:', event.message)
      showError(event.message || 'Payment was declined')
    },
    onCancel: () => {
      console.log('Payment cancelled')
      showMessage('Payment was cancelled')
    },
  }
)

instance.on('success', (event) => {
  trackConversion(event.session.amount)
})

window.addEventListener('beforeunload', () => {
  instance.destroy()
})
```

--------------------------------

### Display payment modal using Client SDK

Source: https://context7.com/bizup-dev/bizup-pay/llms.txt

Demonstrates opening a payment session in a centered modal overlay. It includes configuration for modal dimensions and event handlers for success, failure, and cancellation.

```typescript
import { BizupPay } from '@bizup-pay/client'

const session = await fetch('/api/checkout', {
  method: 'POST',
  body: JSON.stringify({ amount: 149.90, description: 'Premium Plan' }),
}).then(r => r.json())

const bizupPay = new BizupPay()

document.getElementById('pay-button')!.onclick = () => {
  const modal = bizupPay.openModal(session, {
    width: '500px',
    height: '700px',
    overlayColor: 'rgba(0, 0, 0, 0.7)',
    closeOnOverlayClick: true,
    onSuccess: (event) => {
      modal.destroy()
      showSuccessMessage(`Paid ${event.session.amount} ${event.session.currency}`)
      refreshOrderStatus()
    },
    onFailure: (event) => {
      showError(event.message || 'Payment failed. Please try again.')
    },
    onCancel: () => {
      modal.destroy()
      showMessage('Payment cancelled')
    },
  })
}
```

--------------------------------

### Create Payment Sessions for Hosted Checkout

Source: https://context7.com/bizup-dev/bizup-pay/llms.txt

Shows how to initiate a payment flow by creating a hosted session. The method accepts payment details, customer information, and callback URLs, returning a session object containing the redirect URL for the customer.

```typescript
import { createProvider, type CreateSessionParams, type BizupPaymentSession } from '@bizup-pay/core'
import '@bizup-pay/cardcom'

const provider = createProvider('cardcom', {
  terminalNumber: 1000,
  apiName: process.env.CARDCOM_API_NAME!,
  apiPassword: process.env.CARDCOM_API_PASSWORD!
})

const params: CreateSessionParams = {
  amount: 99.90,
  currency: 'ILS',
  description: 'Premium Subscription',
  customer: {
    name: 'Israel Israeli',
    email: 'israel@example.com',
    phone: '+972-54-1234567'
  },
  successUrl: 'https://myshop.co.il/checkout/success',
  webhookUrl: 'https://myshop.co.il/api/webhook'
}

const session: BizupPaymentSession = await provider.createSession(params)
res.redirect(session.pageUrl)
```

--------------------------------

### BizupProvider Interface Definition

Source: https://github.com/bizup-dev/bizup-pay/blob/main/CLAUDE.md

Defines the core contract for all payment provider adapters within the BizUp Pay system. It outlines the methods required for session creation, transaction retrieval, refunds, and webhook parsing.

```typescript
interface BizupProvider {
  readonly name: ProviderName  // 'morning' | 'cardcom' | 'icount' | 'grow'

  createSession(params: CreateSessionParams): Promise<BizupPaymentSession>
  getTransaction(id: string): Promise<BizupTransaction>
  refund(params: RefundParams): Promise<BizupRefund>
  parseWebhook(body: unknown, headers?: Record<string, string>): Promise<BizupWebhookEvent>
}
```

--------------------------------

### Integrate via CDN script tag

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/plans/2026-03-22-npm-publish-cdn.md

Demonstrates how to consume the published bundle directly in an HTML file without requiring a local build step.

```html
<script src="https://unpkg.com/@bizup-pay/client/dist/bizup-pay.min.js"></script>
<script>
  const bizupPay = new BizupPay.BizupPay()

  bizupPay.mount(session, document.getElementById('payment'), {
    onSuccess: () => window.location.href = '/thank-you',
    onFailure: (e) => alert(e.message),
  })
</script>
```

--------------------------------

### Key BizUp Pay Type Definitions

Source: https://github.com/bizup-dev/bizup-pay/blob/main/CLAUDE.md

Illustrates essential TypeScript types used within the BizUp Pay project for handling payment sessions, transactions, webhooks, and refunds. These types define the structure of data exchanged between the core library and provider adapters.

```typescript
// CreateSessionParams — input to createSession()
{
  amount,
  currency?,
  description,
  customer?,
  successUrl,
  failureUrl?,
  cancelUrl?,
  webhookUrl,
  metadata?,
  installments?,
  language?,
  recurring?
}

// BizupPaymentSession — output of createSession()
{
  id,
  provider,
  amount,
  currency,
  description,
  pageUrl,
  successUrl,
  failureUrl?,
  cancelUrl?,
  webhookUrl,
  metadata,
  status,
  operation?,
  expiresAt?
}

// BizupTransaction — output of getTransaction() and parseWebhook()
{
  id,
  providerTransactionId,
  provider,
  amount,
  currency,
  status,
  paymentMethod,
  cardBrand?,
  cardLastFour?,
  installments,
  documentUrl?,
  customer?,
  createdAt,
  morning?,
  cardcom?,
  icount?,
  grow?,
  raw
}

// BizupWebhookEvent — output of parseWebhook()
{
  type: 'payment.completed' | 'payment.failed' | 'payment.cancelled',
  transaction: BizupTransaction,
  timestamp: Date
}

// BizupRefund — output of refund()
{
  id,
  transactionId,
  amount,
  status,
  createdAt
}
```

--------------------------------

### Creating a Payment Session

Source: https://context7.com/bizup-dev/bizup-pay/llms.txt

Initiates a payment flow by creating a hosted payment page. Returns a `BizupPaymentSession` object containing the URL for redirection.

```APIDOC
## Creating a Payment Session

### Description
The `createSession()` method initiates a payment flow by creating a hosted payment page. It returns a `BizupPaymentSession` containing the URL where customers should be redirected to complete payment.

### Method
`provider.createSession(params: CreateSessionParams): Promise<BizupPaymentSession>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **amount** (number) - Required - The payment amount.
- **currency** (string) - Optional, defaults to 'ILS' - The currency code (e.g., 'ILS').
- **description** (string) - Required - A description of the payment.
- **customer** (object) - Optional - Customer details.
  - **name** (string) - Required - Customer's full name.
  - **email** (string) - Required - Customer's email address.
  - **phone** (string) - Required - Customer's phone number.
  - **taxId** (string) - Optional - Customer's tax identification number.
  - **address** (object) - Optional - Customer's address.
    - **city** (string) - Required - City name.
    - **street** (string) - Required - Street name and number.
    - **zip** (string) - Required - Postal code.
    - **country** (string) - Required - Country code (e.g., 'IL').
- **successUrl** (string) - Required - URL to redirect to upon successful payment.
- **failureUrl** (string) - Optional - URL to redirect to upon failed payment.
- **cancelUrl** (string) - Optional - URL to redirect to if the payment is cancelled.
- **webhookUrl** (string) - Required - URL to send payment status updates to.
- **metadata** (object) - Optional - Custom key-value pairs for additional information.
- **language** (string) - Optional, 'he' or 'en' - The language for the payment page.
- **installments** (object) - Optional - Installment options.
  - **max** (number) - Required - Maximum number of installments allowed.

### Request Example
```typescript
import { createProvider, type CreateSessionParams, type BizupPaymentSession } from '@bizup-pay/core'
import '@bizup-pay/cardcom'

const provider = createProvider('cardcom', {
  terminalNumber: 1000,
  apiName: process.env.CARDCOM_API_NAME!,
  apiPassword: process.env.CARDCOM_API_PASSWORD!,
})

const params: CreateSessionParams = {
  amount: 99.90,
  currency: 'ILS', // optional, defaults to ILS
  description: 'Premium Subscription',
  customer: {
    name: 'Israel Israeli',
    email: 'israel@example.com',
    phone: '+972-54-1234567',
    taxId: '123456789', // optional
    address: { // optional
      city: 'Tel Aviv',
      street: 'Rothschild 1',
      zip: '6688101',
      country: 'IL',
    },
  },
  successUrl: 'https://myshop.co.il/checkout/success',
  failureUrl: 'https://myshop.co.il/checkout/failure', // optional
  cancelUrl: 'https://myshop.co.il/checkout/cancelled', // optional
  webhookUrl: 'https://myshop.co.il/api/webhook',
  metadata: { orderId: 'order_12345', plan: 'premium' }, // optional
  language: 'he', // 'he' or 'en', optional
  installments: { max: 12 }, // optional, allow up to 12 payments
}

const session: BizupPaymentSession = await provider.createSession(params)

// Redirect customer to payment page
// res.redirect(session.pageUrl)
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the payment session.
- **provider** (string) - The payment provider used.
- **amount** (number) - The payment amount.
- **currency** (string) - The currency code.
- **description** (string) - The payment description.
- **pageUrl** (string) - The URL of the hosted payment page.
- **successUrl** (string) - The URL to redirect to on success.
- **failureUrl** (string) - The URL to redirect to on failure.
- **cancelUrl** (string) - The URL to redirect to on cancellation.
- **webhookUrl** (string) - The URL for webhook notifications.
- **metadata** (object) - Any metadata included in the request.
- **status** (string) - The current status of the session (e.g., 'pending').
- **operation** (string) - The type of operation (e.g., 'charge').
- **expiresAt** (Date) - The expiration date and time of the session.

#### Response Example
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "provider": "cardcom",
  "amount": 99.90,
  "currency": "ILS",
  "description": "Premium Subscription",
  "pageUrl": "https://secure.cardcom.solutions/hosted/...".
  "successUrl": "https://myshop.co.il/checkout/success",
  "failureUrl": "https://myshop.co.il/checkout/failure",
  "cancelUrl": "https://myshop.co.il/checkout/cancelled",
  "webhookUrl": "https://myshop.co.il/api/webhook",
  "metadata": { "orderId": "order_12345", "plan": "premium" },
  "status": "pending",
  "operation": "charge",
  "expiresAt": "2023-10-27T10:00:00.000Z"
}
```
```

--------------------------------

### Automate publishing with shell script

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/plans/2026-03-22-npm-publish-cdn.md

A bash script that orchestrates the build process and publishes all packages in the correct dependency order to the npm registry.

```bash
#!/bin/bash
set -e

echo "Building all packages..."
npm run build

echo "Building client bundle..."
npm run build:bundle --workspace=packages/client

echo "Publishing packages (in dependency order)..."
npm publish --workspace=packages/core
npm publish --workspace=packages/morning
npm publish --workspace=packages/cardcom
npm publish --workspace=packages/icount
npm publish --workspace=packages/grow
npm publish --workspace=packages/client
npm publish --workspace=packages/mock-server

echo "Done! Packages published to npm."
```

--------------------------------

### Create Payment Session (Server-side)

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/index.html

Initiates a payment session on the server. Requires amount, currency, and webhook URL. Returns a URL for the hosted payment page. This is the first step in the payment flow.

```javascript
const session = await provider.createSession({
  amount: 100,
  currency: 'ILS',
  webhookUrl: '...'
})
```

--------------------------------

### Initialize Cardcom Provider and Create Session (TypeScript)

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/index.html

Initializes the Cardcom payment provider with terminal details and API credentials, then creates a checkout session with order specifics. Handles webhook confirmation.

```typescript
import { createProvider } from '@bizup-pay/core'
import '@bizup-pay/cardcom'

const pay = createProvider('cardcom', {
  terminalNumber: 1000,
  apiName: process.env.CARDCOM_API_NAME!,
  apiPassword: process.env.CARDCOM_API_PASSWORD!,
})

// Create checkout session
const session = await pay.createSession({
  amount: 149.90,
  currency: 'ILS',
  description: 'Premium Plan',
  customer: { name: 'Israel Israeli' },
  successUrl: 'https://myapp.co.il/thanks',
  webhookUrl: 'https://myapp.co.il/api/webhook',
})

// Handle webhook
const event = await pay.parseWebhook(body)
// event.transaction.amount → 149.90
// event.transaction.status → 'completed'
```

--------------------------------

### Bundle client-side code with esbuild

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/plans/2026-03-22-npm-publish-cdn.md

Configures esbuild to generate an IIFE browser bundle for the client package, enabling direct script-tag usage in web browsers.

```javascript
import { build } from 'esbuild'

await build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  minify: true,
  format: 'iife',
  globalName: 'BizupPay',
  outfile: 'dist/bizup-pay.min.js',
  target: 'es2020',
  external: ['@bizup-pay/core'],
})
```

--------------------------------

### Client SDK - UI Integration

Source: https://context7.com/bizup-dev/bizup-pay/llms.txt

Methods for rendering the payment interface using either inline iframes or modal overlays.

```APIDOC
## UI Integration (mount / openModal)

### Description
Methods to display the payment interface to the user. `mount()` renders an inline iframe, while `openModal()` displays a centered overlay.

### Parameters
- **session** (object) - Required - The session object returned from the backend.
- **options** (object) - Required - Configuration including dimensions and event callbacks (onLoad, onSuccess, onFailure, onCancel).

### Request Example
{
  "width": "500px",
  "height": "700px",
  "onSuccess": "callback_function"
}

### Response
#### Success Response (200)
- **instance** (object) - The UI instance controller with methods like `destroy()` and `on()`.
```

--------------------------------

### Configure package.json for npm publishing

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/plans/2026-03-22-npm-publish-cdn.md

Standardizes package metadata for npm workspaces, including entry points, type definitions, and public access configuration.

```json
{
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "publishConfig": { "access": "public" }
}
```

--------------------------------

### POST /createSession

Source: https://context7.com/bizup-dev/bizup-pay/llms.txt

Initializes a payment session with a specific provider (e.g., Cardcom) to generate a session object for the frontend.

```APIDOC
## POST /createSession

### Description
Initializes a new payment session using the configured provider. This returns a session object required for mounting the payment UI.

### Method
POST

### Request Body
- **amount** (number) - Required - The transaction amount.
- **description** (string) - Required - Description of the payment.
- **successUrl** (string) - Required - URL to redirect after success.
- **webhookUrl** (string) - Required - URL to receive payment webhooks.

### Request Example
{
  "amount": 100,
  "description": "Test",
  "successUrl": "https://example.com/success",
  "webhookUrl": "https://example.com/webhook"
}

### Response
#### Success Response (200)
- **id** (string) - The unique session ID.
- **status** (string) - Current session status.

#### Response Example
{
  "id": "sess_12345",
  "status": "pending"
}
```

--------------------------------

### Create Recurring Payment Sessions with TypeScript

Source: https://context7.com/bizup-dev/bizup-pay/llms.txt

Initializes a payment session configured for recurring billing using the Cardcom provider. It accepts parameters for interval, total payments, and trial periods to automate subscription management.

```typescript
import { createProvider } from '@bizup-pay/core'
import '@bizup-pay/cardcom'

const provider = createProvider('cardcom', {
  terminalNumber: 1000,
  apiName: process.env.CARDCOM_API_NAME!,
  apiPassword: process.env.CARDCOM_API_PASSWORD!,
})

const session = await provider.createSession({
  amount: 49.90,
  currency: 'ILS',
  description: 'Monthly Pro Plan',
  customer: {
    name: 'Israel Israeli',
    email: 'israel@example.com',
  },
  successUrl: 'https://myshop.co.il/subscribe/success',
  webhookUrl: 'https://myshop.co.il/api/webhook',
  recurring: {
    interval: 'monthly',
    totalPayments: 12,
    amount: 49.90,
    firstAmount: 0,
    startDate: '2024-02-01',
  },
})

res.redirect(session.pageUrl)
```

--------------------------------

### Run End-to-End Tests (Bash)

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/plans/2026-03-21-demo-app-refactor.md

This command executes the end-to-end tests using Playwright with a list reporter. It's noted that no e2e changes were needed as the tests interact with the UI through roles and text, making them resilient to implementation details. All 16 tests are expected to pass.

```bash
npx playwright test --reporter=list
```

--------------------------------

### Client-Side Bizup Pay Checkout UI with Next.js

Source: https://context7.com/bizup-dev/bizup-pay/llms.txt

This React code snippet implements a client-side payment UI using Next.js App Router and the Bizup Pay client SDK. It includes a button that, when clicked, initiates a checkout process by calling the server-side API to create a payment session. It then uses the BizupPay SDK to open a payment modal, handling success, failure, and cancellation events. It manages loading and paying states for user feedback.

```typescript
// app/checkout/page.tsx - Client-side payment UI
'use client'
import { useState } from 'react'
import { BizupPay } from '@bizup-pay/client'

export default function CheckoutPage() {
  const [status, setStatus] = useState<'idle' | 'loading' | 'paying'>('idle')

  const handleCheckout = async () => {
    setStatus('loading')

    const res = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        items: [{ name: 'Widget', price: 49.90, quantity: 2 }],
        customer: { name: 'Test User', email: 'test@example.com' },
      }),
    })
    const { session } = await res.json()

    setStatus('paying')

    const bizupPay = new BizupPay()
    bizupPay.openModal(session, {
      onSuccess: () => window.location.href = '/checkout/success',
      onFailure: (e) => {
        setStatus('idle')
        alert(e.message || 'Payment failed')
      },
      onCancel: () => setStatus('idle'),
    })
  }

  return (
    <button onClick={handleCheckout} disabled={status !== 'idle'}>
      {status === 'loading' ? 'Loading...' :
       status === 'paying' ? 'Complete payment...' :
       'Pay Now'}
    </button>
  )
}
```

--------------------------------

### BizUp Pay Client SDK: Mount and Open Modal

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/plans/2026-03-18-unified-payment-framework-design.md

Provider-agnostic browser library for integrating BizUp payments. The `mount` method embeds the payment page in a container, while `openModal` displays it as an overlay. Both methods return an instance with a `destroy` method and event listeners.

```typescript
interface BizupPayClient {
  // Mount hosted payment page in a container
  mount(session: BizupPaymentSession, container: HTMLElement, options?: MountOptions): BizupPayInstance

  // Open as modal overlay
  openModal(session: BizupPaymentSession, options?: ModalOptions): BizupPayInstance
}

interface MountOptions {
  width?: string
  height?: string
  onSuccess?: (event: ClientPaymentEvent) => void
  onFailure?: (event: ClientPaymentEvent) => void
  onCancel?: () => void
  onLoad?: () => void
}

interface BizupPayInstance {
  destroy(): void
  on(event: 'success' | 'failure' | 'cancel' | 'load', handler: Function): void
}

// Browser usage
const bizupPay = new BizupPay()
bizupPay.mount(sessionFromServer, document.getElementById('payment-container'), {
  onSuccess: (event) => { window.location.href = '/thank-you' },
  onFailure: (event) => { showError(event.message) },
})
```

--------------------------------

### Define Global Styles and Layout

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/index.html

Sets up the base CSS for the BizUp Pay documentation site, including font configuration, box-sizing, and responsive container constraints.

```css
*,
*::before,
*::after {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

html {
  scroll-behavior: smooth;
}

body {
  font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
  color: #1a1f2e;
  background: #fff;
  line-height: 1.6;
}

.container {
  max-width: 1080px;
  margin: 0 auto;
  padding: 0 24px;
}
```

--------------------------------

### Commit Changes for Shared UI Components (Bash)

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/plans/2026-03-21-demo-app-refactor.md

This command stages all changes in the shared UI components directory and commits them with a descriptive message. It's a standard Git operation for version control. Dependencies include Git.

```bash
git add examples/checkout-demo/src/components/
git commit -m "refactor(demo): extract shared UI components"

```

--------------------------------

### Create Payment Session with Cardcom Provider (TypeScript)

Source: https://github.com/bizup-dev/bizup-pay/blob/main/README.md

Demonstrates how to create a payment session using the Cardcom provider. It requires provider-specific configuration and payment details. The output is a session object containing a URL to redirect the customer.

```typescript
import { createProvider } from '@bizup-pay/core'
import '@bizup-pay/cardcom'

const provider = createProvider('cardcom', {
  terminalNumber: 1000,
  apiName: process.env.CARDCOM_API_NAME!,
  apiPassword: process.env.CARDCOM_API_PASSWORD!,
})

const session = await provider.createSession({
  amount: 100,
  currency: 'ILS',
  description: 'Order #1234',
  successUrl: 'https://myshop.co.il/success',
  webhookUrl: 'https://myshop.co.il/api/webhook',
  customer: { name: 'Israel Israeli', email: 'israel@example.com' },
})

// Redirect customer to session.pageUrl
```

--------------------------------

### Switch Payment Providers (TypeScript)

Source: https://github.com/bizup-dev/bizup-pay/blob/main/README.md

Illustrates how easily payment providers can be switched by changing the import statement and the `createProvider` configuration. The rest of the integration code remains the same.

```typescript
// Cardcom
import '@bizup-pay/cardcom'
const provider = createProvider('cardcom', { terminalNumber: 1000, apiName: '...', apiPassword: '...' })

// Morning
import '@bizup-pay/morning'
const provider = createProvider('morning', { apiKey: '...', apiSecret: '...' })
```

--------------------------------

### Commit Changes for Shop Page Refactor (Bash)

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/plans/2026-03-21-demo-app-refactor.md

This command stages the modified shop page file and commits the changes with a message indicating the refactoring to use shared provider constants. Dependencies include Git.

```bash
git add examples/checkout-demo/src/app/page.tsx
git commit -m "refactor(demo): shop page uses shared provider constants"

```

--------------------------------

### Create ResultScreen component

Source: https://github.com/bizup-dev/bizup-pay/blob/main/docs/plans/2026-03-21-demo-app-refactor.md

A screen component to display payment outcomes (success, failure, or cancelled). It uses Next.js router to navigate back to the home page.

```tsx
'use client'
import { useRouter } from 'next/navigation'

const RESULT_COLORS = {
  success: { bg: '#f0fdf4', border: '#16a34a', text: '#16a34a', icon: 'V' },
  failure: { bg: '#fef2f2', border: '#dc2626', text: '#dc2626', icon: 'X' },
  cancelled: { bg: '#fefce8', border: '#ca8a04', text: '#ca8a04', icon: '!' },
} as const

export function ResultScreen({ status, message }: { status: 'success' | 'failure' | 'cancelled'; message: string }) {
  const router = useRouter()
  const c = RESULT_COLORS[status]
  const title = status === 'success' ? 'Payment Successful' : status === 'failure' ? 'Payment Failed' : 'Payment Cancelled'

  return (
    <div>
      <div style={{ background: '#f8fafc', borderBottom: '1px solid #e2e8f0', padding: '0.5rem 1rem', textAlign: 'center', fontSize: '0.8rem', color: '#94a3b8' }}>
        BizUp Pay Demo App <span style={{ margin: '0 0.4rem' }}>&mdash;</span> You are back on the merchant&apos;s website
      </div>
      <div style={{ maxWidth: 500, margin: '3rem auto', textAlign: 'center', padding: '2rem' }}>
        <div style={{ width: 64, height: 64, borderRadius: '50%', background: c.bg, border: `2px solid ${c.border}`, display: 'flex', alignItems: 'center', justifyContent: 'center', margin: '0 auto 1.5rem', fontSize: '1.5rem', fontWeight: 700, color: c.text }}>
          {c.icon}
        </div>
        <h1 style={{ color: c.text, marginBottom: '0.5rem' }}>{title}</h1>
        <p style={{ color: '#666', marginBottom: '2rem' }}>{message}</p>
        <button onClick={() => router.push('/')}>Return Home</button>
      </div>
    </div>
  )
}
```