Bizup Pay Integration

The key value: all providers implement the same interface. Switch providers by changing one import + config line.

Available Providers

Payment Methods by Provider

When Building an Integration

Follow this pattern:

Step 1: Install packages

npm install @bizup-pay/core @bizup-pay/cardcom  # swap provider as needed
npm install @bizup-pay/client                     # only if embedding payment UI

Step 2: Create provider (server-side)

import { createProvider } from '@bizup-pay/core'
import '@bizup-pay/cardcom' // side-effect import registers the provider

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

Step 3: Create payment session (server-side API route)

const session = await provider.createSession({
  amount: 100,
  currency: 'ILS',
  description: 'Order #1234',
  successUrl: 'https://example.com/success',
  webhookUrl: 'https://example.com/api/webhook',
  customer: { name: 'Israel Israeli', email: '[email protected]' },
})
// Return session.pageUrl to the client

Step 4: Handle webhook (server-side API route)

const event = await provider.parseWebhook(req.body)

if (event.type === 'payment.completed') {
  const tx = event.transaction
  // tx.id, tx.amount, tx.status, tx.paymentMethod, tx.cardBrand, tx.cardLastFour, tx.documentUrl
  await fulfillOrder(tx)
}

Step 5: Mount payment UI (browser — optional)

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

const bizupPay = new BizupPay()
bizupPay.mount(session, document.getElementById('payment'), {
  onSuccess: () => window.location.href = '/thank-you',
  onFailure: (err) => console.error(err),
  onCancel: () => console.log('cancelled'),
})

Mounting modes: iframe (embed in container), modal (overlay), redirect (full page).

The 4 API Methods

Every provider implements exactly these methods:

// Create a payment page — returns session with pageUrl
provider.createSession(params: CreateSessionParams): Promise<BizupPaymentSession>

// Look up a completed transaction
provider.getTransaction(id: string): Promise<BizupTransaction>

// Refund a transaction (full or partial)
provider.refund({ transactionId, amount? }): Promise<BizupRefund>

// Parse incoming webhook payload
provider.parseWebhook(body: unknown): Promise<BizupWebhookEvent>

Key Types

CreateSessionParams

{
  amount: number              // required
  currency?: string           // default 'ILS'
  description: string         // required — shown to customer
  customer?: { name?, email?, phone? }
  successUrl: string          // required — redirect after success
  failureUrl?: string
  cancelUrl?: string
  webhookUrl: string          // required — receives payment notifications
  metadata?: Record<string, string>
  installments?: { min?, max? }
  language?: 'he' | 'en' | 'ar'
  recurring?: { interval: 'month' | 'year', count? }
}

BizupTransaction

{
  id: string
  providerTransactionId: string
  provider: 'cardcom' | 'morning' | 'icount' | 'grow'
  amount: number
  currency: string
  status: 'pending' | 'completed' | 'failed' | 'cancelled' | 'refunded'
  paymentMethod: 'credit_card' | 'bit' | 'apple_pay' | 'google_pay' | 'bank_transfer' | 'paypal'
  cardBrand?: 'visa' | 'mastercard' | 'amex' | 'isracard' | 'diners' | 'discover' | 'jcb'
  cardLastFour?: string
  installments?: number
  documentUrl?: string        // invoice/receipt PDF
  customer?: { name?, email?, phone? }
  createdAt: Date
  raw: unknown                // full provider response — escape hatch
}

BizupWebhookEvent

{
  type: 'payment.completed' | 'payment.failed' | 'payment.cancelled'
  transaction: BizupTransaction
  timestamp: Date
}

Error Handling

All errors are BizupPayError:

import { BizupPayError } from '@bizup-pay/core'

try {
  await provider.createSession(params)
} catch (err) {
  if (err instanceof BizupPayError) {
    err.code           // 'AUTHENTICATION_ERROR' | 'VALIDATION_ERROR' | 'PROVIDER_ERROR' | 'NETWORK_ERROR' | 'NOT_FOUND'
    err.provider       // which provider
    err.message        // human-readable
    err.providerError  // raw provider error
  }
}

Switching Providers

This is the key selling point. Change 2 lines, everything else stays identical:

- import '@bizup-pay/cardcom'
- const provider = createProvider('cardcom', { terminalNumber: 1000, apiName: '...' })
+ import '@bizup-pay/morning'
+ const provider = createProvider('morning', { apiKey: '...', apiSecret: '...' })

All calls to createSession, parseWebhook, getTransaction, refund work the same.

Multiple Providers

You can use multiple providers simultaneously:

import '@bizup-pay/cardcom'
import '@bizup-pay/morning'

const cardcom = createProvider('cardcom', { ... })
const morning = createProvider('morning', { ... })

// Route by business logic
const provider = useCase === 'subscription' ? morning : cardcom

Testing

Use @bizup-pay/mock-server for local development and tests:

import { createMockServer } from '@bizup-pay/mock-server'

const mock = createMockServer({ autoComplete: true })
await mock.start()
// Point provider at localhost — runs full payment flow without real API calls
await mock.stop()

Standalone mode for manual testing:

npx bizup-mock-server
# Mock servers on ports 4100 (Morning), 4200 (Cardcom), 4300 (iCount)

Important Notes

• Always store provider credentials in environment variables, never in code
• The webhookUrl must be publicly accessible — use ngrok or similar for local dev
• parseWebhook validates the payload — always use it instead of parsing manually
• The raw field on BizupTransaction gives you the full provider response if you need provider-specific data
• Provider-specific extras are available as typed fields: tx.morning, tx.cardcom, tx.icount, tx.grow
• All HTTP calls use globalThis.fetch — works in Node 20+, Deno, Bun, and edge runtimes