npm package: @henrylabs-interview/payments
Description: A lightweight payments SDK for creating and confirming checkouts, with built-in webhook support and an embeddable checkout UI.
Latest version: 0.2.27

# Henry Labs – Interview: Payment Processor

A lightweight payments SDK for creating and confirming checkouts, with built-in webhook support and an embeddable checkout UI.

This SDK simulates a real-world payment processing system, including:

- Fraud detection
- Transient system errors
- Retry scenarios
- Asynchronous authorization flows

It is designed to test robustness, error handling, and webhook integration.

---

## Installation

```bash
bun install
```

Build:

```bash
bun run build
```

---

# Overview

The SDK provides:

- Checkout creation
- Checkout confirmation
- Webhook endpoint registration
- Embeddable checkout UI (frontend)
- API key validation

The system performs internal validation, fraud screening, and simulated load conditions.

Operations may:

- Succeed immediately
- Resolve asynchronously
- Require retries
- Fail due to fraud controls
- Fail due to temporary system overload

---

# Usage

---

## Initialize (Backend)

```ts
import { PaymentProcessor } from '@henrylabs-interview/payments';

const processor = new PaymentProcessor({
	apiKey: ...,
});
```

# Checkout API

Available under:

```ts
processor.checkout;
```

---

## Create a Checkout

```ts
const response = await processor.checkout.create({
	amount: 1000,
	currency: 'USD',
	customerId: 'cust_123',
});
```

---

## Confirm a Checkout (Backend)

```ts
const response = await processor.checkout.confirm({
	checkoutId: ...,
	type: 'raw-card',
	data: {
		number: ...,
		expMonth: XX,
		expYear: XXXX,
		cvc: XXX,
	},
});
```

# Embedded Checkout (Frontend)

The SDK provides an optional embeddable checkout UI for collecting card details in the browser.

---

## Initialize Embedded Checkout

```ts
import { EmbeddedCheckout } from '@henrylabs-interview/payments';

const embedded = new EmbeddedCheckout({
	checkoutId: 'chk_123',
});
```

---

## Render Embedded Checkout

```ts
embedded.render('#checkout-container', (paymentToken) => {
	console.log('Received payment token:', paymentToken);

	// Send token to backend for confirmation
});
```

### Parameters

| Parameter            | Description                           |
| -------------------- | ------------------------------------- |
| `containerElementId` | ID of DOM element to render into      |
| `callbackFn`         | Called with a generated payment token |

### Behavior

- Renders a secure card collection UI
- Collects card number, expiry, and CVC
- Generates a payment token
- Returns the token via callback
- Token should be sent to your backend for confirmation

The embedded checkout is intended for **browser environments only**.

---

# Webhooks

Available under:

```ts
processor.webhooks;
```

---

## Register Webhook Endpoint

```ts
processor.webhooks.createEndpoint({
	url: 'https://example.com/webhooks',
	event: 'checkout.confirm',
	secret: 'whsec_...',
});
```

---

## Webhook Events

Events may be emitted for:

- `checkout.create`
- `checkout.confirm`
- `checkout.success`
- `checkout.failure`

Events are triggered for:

- Immediate outcomes
- Asynchronous resolutions
- Retry scenarios

---

## Webhook Security

If a secret is provided:

- Deliveries are signed
- Consumers must verify signatures
- Handlers must be idempotent

Retries may occur if delivery fails.

---

# Disclaimer

This SDK is intended for evaluation and sandbox purposes only.

It does **not** process real payments and should not be used in production.