# @yourasset/ya-checkout-financing

[![License](https://img.shields.io/badge/License-GPL--3.0--or--later-blue.svg)](https://www.gnu.org/licenses/gpl-3.0.html)
[![npm version](https://badge.fury.io/js/@yourasset%2Fya-checkout-financing.svg)](https://badge.fury.io/js/@yourasset%2Fya-checkout-financing)

Add Yourasset financing as a payment method to your website. This package provides the web components that merchants can embed on their product and checkout pages.

## Quick Start

Add one script tag. You get all components.

```html
<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@yourasset/ya-checkout-financing/dist/main.js"
></script>
```

## Components

This package includes three components that work independently or together:

| Component | Purpose | Where to use |
|---|---|---|
| `<ya-checkout-financing placement="product">` | Show monthly financing rate | Product page |
| `<ya-checkout-financing placement="checkout">` | CTA button to start financing | Checkout page |
| `<ya-checkout-financing-info>` | Financing details popup or embedded card | Anywhere |

---

## 1. Product Page Widget

It displays the lowest monthly financing rate, an info button and the Yourasset logo on a single line. There is no CTA button -- it is purely informational.

```html
<ya-checkout-financing
  merchantid="your-merchant-id"
  sku="your-product-sku"
  placement="product"
></ya-checkout-financing>
```

**Renders:** `From CHF xxx/month (i) [Yourasset logo]`

The (i) button opens a modal with all available financing options, details and required legal disclaimer. The header informs the customer to select finance with Yourasset at Checkout.

---

## 2. Checkout Button

CTA button that redirects the customer to the Yourasset financing checkout, co-branded with the merchant's logo.

### Standard button

```html
<ya-checkout-financing
  merchantid="your-merchant-id"
  sku="your-product-sku"
  placement="checkout"
></ya-checkout-financing>
```

**Renders:** `[ Continue with [Yourasset logo] > ]`

### Confirm variant

```html
<ya-checkout-financing
  merchantid="your-merchant-id"
  sku="your-product-sku"
  placement="checkout"
  confirm
></ya-checkout-financing>
```

**Renders:** `[ Confirm and continue with [Yourasset logo] > ]`

### Without arrow

```html
<ya-checkout-financing
  merchantid="your-merchant-id"
  sku="your-product-sku"
  placement="checkout"
  no-arrow
></ya-checkout-financing>
```

**Renders:** `[ Continue with [Yourasset logo] ]`

### Compact (button + monthly rate)

Shows the monthly rate and info button next to the CTA button.

```html
<ya-checkout-financing
  merchantid="your-merchant-id"
  sku="your-product-sku"
  placement="checkout-compact"
></ya-checkout-financing>
```

**Renders:** `From CHF xxx/month (i)  [ with [Yourasset logo] > ]`

---

## 3. Financing Info (Standalone)

The info button and financing details can be placed **anywhere** on the page, independently of the main widget.

### As a button (click to open modal)

```html
<ya-checkout-financing-info
  merchantid="your-merchant-id"
  sku="your-product-sku"
></ya-checkout-financing-info>
```

Clicking opens a modal with all financing durations (12/24/36/48/60 months), monthly payments, interest rates, and the required legal disclaimer.

### As an embedded card

Add the `open` attribute to render the financing details inline -- no button, no popup.

```html
<ya-checkout-financing-info
  merchantid="your-merchant-id"
  sku="your-product-sku"
  open
></ya-checkout-financing-info>
```

The merchant can embed this card in a sidebar, a product details tab, next to payment methods, or anywhere else on their page.

### Custom button size

```html
<ya-checkout-financing-info
  merchantid="your-merchant-id"
  sku="your-product-sku"
  size="24"
></ya-checkout-financing-info>
```

---

## Customization

### Themes

Three built-in themes. Apply to any placement.

```html
<!-- Default (light blue background, dark text) -->
<ya-checkout-financing placement="checkout" ...></ya-checkout-financing>

<!-- Grey -->
<ya-checkout-financing placement="checkout" theme="p-grey" ...></ya-checkout-financing>

<!-- White -->
<ya-checkout-financing placement="checkout" theme="p-white" ...></ya-checkout-financing>
```

### Custom colors

#### Button color

Match the CTA button to your brand.

```html
<ya-checkout-financing
  placement="checkout"
  btn-color="#1a5c2e"
  ...
></ya-checkout-financing>
```

#### Widget background color

```html
<ya-checkout-financing
  placement="checkout"
  bg-color="#f0f0f0"
  ...
></ya-checkout-financing>
```

#### Info card colors

Customize the embedded info card to match your site.

```html
<ya-checkout-financing-info
  open
  bg-color="#f5e6d0"
  text-color="#3d2b1f"
  ...
></ya-checkout-financing-info>
```

### Full width

```html
<ya-checkout-financing placement="checkout" full-width ...></ya-checkout-financing>
```

---

## Properties Reference

### `<ya-checkout-financing>`

You must provide **either** a `sku` (registered in the YourAsset inventory) **or** the trio `brand` + `model` + `price` (no-SKU flow). Without one of those combinations the widget will not render. If you provide **both**, the widget tries the SKU lookup first and transparently falls back to the merchant-provided data on miss — see "SKU fallback behavior" below.

| Property | Type | Required | Default | Description |
|---|---|---|---|---|
| `merchantid` | String | Yes | — | Your merchant ID (provided by Yourasset). |
| `sku` | String | Conditional | — | The product SKU in your system. Required unless using the no-SKU flow. |
| `brand` | String | Conditional | — | Watch brand. Required for no-SKU flow; recommended alongside `sku` to enable fallback. |
| `model` | String | Conditional | — | Watch model name. Required for no-SKU flow; recommended alongside `sku` to enable fallback. |
| `reference` | String | No | — | Watch reference number (no-SKU flow). Defaults to `sku` when the SKU fallback fires. |
| `image` | String | No | — | HTTPS URL to a merchant-hosted image of the watch (no-SKU flow). |
| `product-url` | String | No | — | HTTPS URL of your product page; used as a backlink shown to the buyer (no-SKU flow). |
| `price` | Number | Conditional | — | Watch price. Fallback for SKU flow, required for no-SKU flow. |
| `preowned` | Boolean | No | `false` | Set to `true` when the watch is pre-owned. The SKU lookup routes to a different endpoint based on this flag — leaving it `false` for a pre-owned watch will return a 404 and the widget will hide unless the no-SKU fallback attributes are present. |
| `is-watch` | Boolean | No | omit = neutral | **No-SKU flow only.** Boolean attribute — when *present* the financing application, customer account, and merchant back-office use watch wording ("your watch"); **omit it** for neutral "product/purchase" wording. **Recommended for watch listings.** ⚠️ Don't write `is-watch="false"` (being present, it still counts as `true`) — omit the attribute instead, or set the JS property `isWatch = false`. |
| `language` | String | No | Page `lang` | Language code (`en`, `de`, `fr`, `it`). Auto-detects from page. |
| `placement` | String | No | `product` | `product`, `checkout`, or `checkout-compact`. |
| `theme` | String | No | `default` | `default`, `p-grey`, or `p-white`. |
| `confirm` | Boolean | No | `false` | Use "Confirm and continue with" button text. |
| `no-arrow` | Boolean | No | `false` | Hide the arrow icon on the button. |
| `btn-color` | String | No | — | Custom button background color (CSS). |
| `bg-color` | String | No | — | Custom container background color (CSS). |
| `full-width` | Boolean | No | `false` | Stretch to full container width. |

#### SKU fallback behavior

If you pass both `sku` and the trio `brand` + `model` + `price` and the SKU isn't found in YourAsset's catalogue, the widget transparently falls back to the no-SKU session flow instead of hiding the CTA. The merchant-supplied watch data is used end-to-end (display, financing session, back-office record) and the original SKU is stored as the resulting session's `reference` field — unless you also passed an explicit `reference`, which takes precedence.

This means a merchant whose inventory drifts ahead of YourAsset's catalogue can ship the widget on every product page without coordinating SKU registration. If you'd rather hide the widget when the SKU isn't found (e.g. to detect catalogue drift), omit the `brand`/`model`/`price` triad.

### `<ya-checkout-financing-info>`

Same SKU vs. no-SKU rules as `<ya-checkout-financing>`: provide either `sku` or the `brand` + `model` + `price` triad; pass both to enable the SKU fallback.

| Property | Type | Required | Default | Description |
|---|---|---|---|---|
| `merchantid` | String | Yes | — | Your merchant ID (provided by Yourasset). |
| `sku` | String | Conditional | — | The product SKU in your system. Required unless using the no-SKU flow. |
| `brand` | String | Conditional | — | Watch brand. Required for no-SKU flow; recommended alongside `sku` to enable fallback. |
| `model` | String | Conditional | — | Watch model name. Required for no-SKU flow; recommended alongside `sku` to enable fallback. |
| `reference` | String | No | — | Watch reference number (no-SKU flow). Defaults to `sku` when the fallback fires. |
| `image` | String | No | — | HTTPS URL to a merchant-hosted image of the watch (no-SKU flow). |
| `product-url` | String | No | — | HTTPS URL of your product page; used as a backlink (no-SKU flow). |
| `price` | Number | Conditional | — | Watch price. Fallback for SKU flow, required for no-SKU flow. |
| `preowned` | Boolean | No | `false` | Set to `true` for pre-owned watches. Same caveat as `<ya-checkout-financing>`: a pre-owned SKU lookup will 404 unless this flag is set. |
| `is-watch` | Boolean | No | omit = neutral | **No-SKU flow only.** Boolean attribute — when *present* the financing application, customer account, and merchant back-office use watch wording ("your watch"); **omit it** for neutral "product/purchase" wording. **Recommended for watch listings.** ⚠️ Don't write `is-watch="false"` (being present, it still counts as `true`) — omit the attribute instead, or set the JS property `isWatch = false`. |
| `language` | String | No | Page `lang` | Language code (`en`, `de`, `fr`, `it`). |
| `size` | Number | No | `14` | Info button size in pixels. |
| `open` | Boolean | No | `false` | Render as embedded card instead of button. |
| `bg-color` | String | No | — | Card background color (CSS). Only applies when `open`. |
| `text-color` | String | No | — | Card text color (CSS). Only applies when `open`. |
| `header-before` | String | No | — | Custom header text before the logo. |
| `header-after` | String | No | — | Custom header text after the logo. |

---

## Languages

The widget supports English, German, French, and Italian. It auto-detects the language from your page's `<html lang="...">` attribute, or you can set it explicitly with the `language` property.

---

## Full Integration Example

### Product page

```html
<!-- Financing info line -->
<ya-checkout-financing
  merchantid="your-merchant-id"
  sku="WATCH-123"
  placement="product"
></ya-checkout-financing>

<!-- Detailed financing card in sidebar -->
<ya-checkout-financing-info
  merchantid="your-merchant-id"
  sku="WATCH-123"
  open
></ya-checkout-financing-info>
```

### Checkout page

```html
<!-- Financing payment button -->
<ya-checkout-financing
  merchantid="your-merchant-id"
  sku="WATCH-123"
  placement="checkout"
></ya-checkout-financing>

<!-- Info button next to payment methods -->
<ya-checkout-financing-info
  merchantid="your-merchant-id"
  sku="WATCH-123"
></ya-checkout-financing-info>
```

### Complete checkout with all options

```html
<!-- Compact: monthly rate + button together -->
<ya-checkout-financing
  merchantid="your-merchant-id"
  sku="WATCH-123"
  placement="checkout-compact"
  theme="p-grey"
></ya-checkout-financing>

<!-- Or: standalone button, custom branded -->
<ya-checkout-financing
  merchantid="your-merchant-id"
  sku="WATCH-123"
  placement="checkout"
  btn-color="#1a5c2e"
  confirm
  no-arrow
></ya-checkout-financing>
```

### No-SKU flow (merchant-provided watch data)

If your products are not registered in the YourAsset inventory, you can supply the watch details directly. The widget will create a financing session with the data you provide and route the customer to the YourAsset financing flow without requiring a YourAsset product page.

```html
<ya-checkout-financing
  merchantid="your-merchant-id"
  brand="Rolex"
  model="Day-Date 36"
  reference="128235"
  price="37900"
  image="https://www.your-shop.com/images/rolex-daydate.jpg"
  product-url="https://www.your-shop.com/watches/rolex-daydate"
  is-watch
  placement="checkout"
></ya-checkout-financing>
```

`brand`, `model`, and `price` are required. `reference`, `image`, and `product-url` are optional but recommended — they show up in the customer's transaction history and the merchant back-office.

> ### ⌚ Selling a watch? Add `is-watch`
>
> By default the no-SKU flow uses **neutral wording** — "your purchase", "your selected product" — so it fits any product. **If the item is a watch (as it is for most of our merchants), add the `is-watch` attribute** (as shown above). The customer's financing application, their account, and the merchant back-office will then all use watch-specific wording — "your watch", "your selected watch" — instead of generic "product" copy. We recommend setting it on every watch listing.
>
> `is-watch` is a **boolean attribute**: its mere *presence* means `true`. Add it to enable watch wording; **omit it entirely** for neutral wording. ⚠️ Do **not** write `is-watch="false"` — like every HTML boolean attribute, being present still counts as `true`, so that would give you watch wording. To force neutral, just leave the attribute off (or, from JavaScript, set the property `element.isWatch = false`).

---

## How It Works

1. The merchant embeds the widget on their website.
2. The widget fetches financing options from the Yourasset API based on either the product SKU or the supplied watch data.
3. On the merchant product page, the customer sees that financing as payment option is available and the rates.
4. On the checkout page, the customer clicks the CTA button.
5. The customer is redirected to the Yourasset financing checkout (co-branded with the merchant).
6. The customer chooses their preferred financing term and completes the application.

The customer chooses their preferred financing term in the Yourasset checkout, not on the merchant's site. The widget displays the lowest available rate and (i) button.

---

## License

This project is licensed under the GNU General Public License v3.0 or later - see the LICENSE file for details.

Copyright 2026 Yourasset AG