@yossidavid/cardcom-sdk

Unofficial TypeScript SDK for the Cardcom API.

Disclaimer: This is a community package — not affiliated with or endorsed by Cardcom.

Install

pnpm add @yossidavid/cardcom-sdk
# or
npm install @yossidavid/cardcom-sdk

Setup

import { Cardcom } from "@yossidavid/cardcom-sdk"

const cardcom = new Cardcom({
  terminalNumber: 1000,
  apiName: "your-api-name",
  // baseUrl: "https://secure.cardcom.solutions", // optional, this is the default
})

Examples

lowProfile.create — create payment page

Basic charge:

import { Cardcom, Currency } from "@yossidavid/cardcom-sdk"

const payment = await cardcom.lowProfile.create({
  Operation: "ChargeOnly",
  Amount: 100.5,
  ReturnValue: "order-123",           // your order id — returned in webhook
  SuccessRedirectUrl: "https://shop.com/success",
  FailedRedirectUrl: "https://shop.com/fail",
  WebHookUrl: "https://shop.com/api/cardcom/webhook",
  Language: "he",
  ISOCoinId: Currency.ILS,
  ProductName: "הזמנה #123",
})

// Redirect the customer to the payment page
console.log(payment.Url)
console.log(payment.LowProfileId)

Charge + save token for future billing:

const payment = await cardcom.lowProfile.create({
  Operation: "ChargeAndCreateToken",
  Amount: 50,
  ReturnValue: "sub-456",
  SuccessRedirectUrl: "https://shop.com/success",
  FailedRedirectUrl: "https://shop.com/fail",
  WebHookUrl: "https://shop.com/api/cardcom/webhook",
  Language: "he",
  ISOCoinId: Currency.ILS,
})

Token only (no charge):

const payment = await cardcom.lowProfile.create({
  Operation: "CreateTokenOnly",
  Amount: 1, // J2 validation amount
  ReturnValue: "user-789",
  SuccessRedirectUrl: "https://shop.com/success",
  FailedRedirectUrl: "https://shop.com/fail",
  WebHookUrl: "https://shop.com/api/cardcom/webhook",
  Language: "he",
  AdvancedDefinition: {
    JValidateType: 2, // J2 — card check only
  },
})

Suspended deal (J5 frame capture):

const payment = await cardcom.lowProfile.create({
  Operation: "SuspendedDeal",
  Amount: 200,
  ReturnValue: "hold-001",
  SuccessRedirectUrl: "https://shop.com/success",
  FailedRedirectUrl: "https://shop.com/fail",
  WebHookUrl: "https://shop.com/api/cardcom/webhook",
  Language: "he",
  AdvancedDefinition: {
    JValidateType: 5, // J5 — frame capture
  },
})

With invoice document:

const payment = await cardcom.lowProfile.create({
  Operation: "ChargeOnly",
  Amount: 100,
  ReturnValue: "order-123",
  SuccessRedirectUrl: "https://shop.com/success",
  FailedRedirectUrl: "https://shop.com/fail",
  WebHookUrl: "https://shop.com/api/cardcom/webhook",
  Language: "he",
  ISOCoinId: Currency.ILS,
  Document: {
    DocumentTypeToCreate: "TaxInvoiceAndReceipt",
    Name: "ישראל ישראלי",
    Email: "[email protected]",
    TaxId: "040617640",
    IsSendByEmail: true,
    Products: [
      {
        Description: "מוצר לדוגמה",
        UnitCost: 100,
        Quantity: 1,
      },
    ],
  },
})

lowProfile.getResult — fetch transaction result

Call after payment completes. Never trust the redirect page alone.

const result = await cardcom.lowProfile.getResult({
  lowProfileId: "9e26b925-9040-4f06-8644-8f92e036f3f8",
})

console.log(result.ResponseCode)    // 0 = API call succeeded
console.log(result.ReturnValue)     // your order id
console.log(result.TranzactionId)   // Cardcom transaction id
console.log(result.TokenInfo?.Token) // saved token (if created)

lowProfile.verifyPayment — verify webhook end-to-end

Recommended flow: parse webhook → fetch from Cardcom → check success.

// Express / Next.js / Hono webhook handler
export async function POST(request: Request) {
  const body = await request.json()

  const { result, successful, orderId, lowProfileId } =
    await cardcom.lowProfile.verifyPayment(body)

  if (successful) {
    // TODO: check DB idempotency — skip if already fulfilled
    await fulfillOrder(orderId!, result)
  }

  return new Response("OK", { status: 200 }) // Cardcom retries on non-200
}

With query-string webhook payload:

import { parseWebhookPayload } from "@yossidavid/cardcom-sdk"

const params = new URL(request.url).searchParams
const { lowProfileId } = parseWebhookPayload(params)

const verification = await cardcom.lowProfile.verifyPayment(lowProfileId)

Or pass the LowProfileId directly:

const verification = await cardcom.lowProfile.verifyPayment(
  "9e26b925-9040-4f06-8644-8f92e036f3f8",
)

cardcom.isPaymentSuccessful — check if payment completed

const result = await cardcom.lowProfile.getResult({ lowProfileId })

if (cardcom.isPaymentSuccessful(result)) {
  console.log("Paid:", result.TranzactionId)
} else {
  console.log("Not paid:", result.Description)
}

Standalone helper (without client instance):

import { isPaymentSuccessful } from "@yossidavid/cardcom-sdk"

if (isPaymentSuccessful(result)) { /* ... */ }

cardcom.isSuccess — check API response code

Works on any Cardcom API response (ResponseCode === 0):

const payment = await cardcom.lowProfile.create({ /* ... */ })

if (cardcom.isSuccess(payment)) {
  console.log("Payment page created:", payment.Url)
}

transactions.chargeToken — charge a saved token

import { generateTransactionId } from "@yossidavid/cardcom-sdk"

const charge = await cardcom.transactions.chargeToken({
  token: "4cf8e168-261e-4613-8d20-000332986b24",
  cardExpirationMMYY: "0628",       // MMYY format
  amount: 99,
  externalUniqTranId: generateTransactionId("order-123"), // prevents duplicates
  numOfPayments: 1,
})

console.log(charge.TranzactionId)

With invoice:

const charge = await cardcom.transactions.chargeToken({
  token: "4cf8e168-261e-4613-8d20-000332986b24",
  cardExpirationMMYY: "0628",
  amount: 200,
  externalUniqTranId: generateTransactionId("inv-001"),
  document: {
    DocumentTypeToCreate: "TaxInvoiceAndReceipt",
    Name: "ישראל ישראלי",
    Email: "[email protected]",
    TaxId: "040617640",
    Products: [{ Description: "מנוי חודשי", UnitCost: 200, Quantity: 1 }],
  },
})

transactions.chargeFrame — charge a captured J5 frame

Use after a SuspendedDeal in step 1. Requires ApprovalNumber from the original transaction.

const charge = await cardcom.transactions.chargeFrame({
  token: "4cf8e168-261e-4613-8d20-000332986b24",
  cardExpirationMMYY: "1225",
  amount: 200,
  approvalNumber: 204394904,        // from TokenInfo.TokenApprovalNumber
  externalUniqTranId: generateTransactionId("frame-001"),
})

transactions.releaseFrame — release a captured J5 frame

const release = await cardcom.transactions.releaseFrame({
  token: "4cf8e168-261e-4613-8d20-000332986b24",
  cardExpirationMMYY: "1225",
  amount: 200,
  approvalNumber: 204394904,
  externalUniqTranId: generateTransactionId("release-001"),
  mti: 420, // default — do not change unless Cardcom instructs
})

transactions.chargeCard — direct card charge (PCI required)

For closed/native apps with PCI compliance only. Not for regular websites — use lowProfile.create instead.

const charge = await cardcom.transactions.chargeCard({
  cardNumber: "4580000000000000",
  cardExpirationMMYY: "0628",
  cvv2: "569",
  amount: 200,
  externalUniqTranId: generateTransactionId("direct-001"),
  numOfPayments: 1,
  cardOwnerInformation: {
    FullName: "ישראל ישראלי",
    Phone: "0522222222",
    CardOwnerEmail: "[email protected]",
  },
})

transactions.doTransaction — low-level API call

Full control over the Do Transaction request body:

const result = await cardcom.transactions.doTransaction({
  Amount: 100,
  Token: "4cf8e168-261e-4613-8d20-000332986b24",
  CardExpirationMMYY: "0628",
  ExternalUniqTranId: generateTransactionId("raw-001"),
  NumOfPayments: 3,
  ISOCoinId: 1,
  Advanced: {
    IsRefund: false,
    IsCreateToken: true,
  },
})

generateTransactionId — idempotency key

Prevents duplicate charges (Cardcom returns error 608 on duplicate ExternalUniqTranId):

import { generateTransactionId } from "@yossidavid/cardcom-sdk"

const id = generateTransactionId("order-123")
// → "order-123-a1b2c3d4-..."

const id2 = generateTransactionId()
// → random UUID

Error handling

import { Cardcom, CardcomError, CardcomHttpError } from "@yossidavid/cardcom-sdk"

try {
  await cardcom.lowProfile.create({ /* ... */ })
} catch (err) {
  if (err instanceof CardcomError) {
    // Cardcom returned ResponseCode !== 0
    console.error(err.responseCode, err.description)
    console.error(err.raw)
  } else if (err instanceof CardcomHttpError) {
    // HTTP 4xx/5xx
    console.error(err.status, err.body)
  } else {
    throw err
  }
}

Full payment flow

1. lowProfile.create()     → redirect customer to payment.Url
2. Customer pays           → Cardcom sends webhook to your server
3. lowProfile.verifyPayment() → fetch + verify from Cardcom servers
4. fulfillOrder()          → mark order as paid in your DB
5. transactions.chargeToken() → (optional) recurring charges with saved token

Important:

• Never mark an order as paid based on the success redirect page
• Always verify via getResult / verifyPayment
• Return HTTP 200 from webhook handler (Cardcom retries up to 7 times on failure)
• Store TranzactionId and check idempotency before fulfilling

API reference

| Resource | Method | Description | |----------|--------|-------------| | lowProfile | create() | Create iframe/redirect payment page | | lowProfile | getResult() | Fetch authoritative transaction result | | lowProfile | verifyPayment() | Parse webhook + getResult + success check | | transactions | chargeToken() | Charge a saved token | | transactions | chargeFrame() | Charge a captured J5 frame | | transactions | releaseFrame() | Release a captured J5 frame | | transactions | chargeCard() | Direct card charge (PCI required) | | transactions | doTransaction() | Low-level Do Transaction API | | Cardcom | isSuccess() | ResponseCode === 0 | | Cardcom | isPaymentSuccessful() | Payment actually completed | | — | generateTransactionId() | Idempotency key helper | | — | parseWebhookPayload() | Extract LowProfileId from webhook | | — | isPaymentSuccessful() | Standalone success check |

Local development

cp .env.example .env
pnpm install
pnpm build
pnpm example                                          # create payment page
pnpm example:result -- --lowProfileId <id>            # fetch result

Publish

See PUBLISHING.md for the release checklist.