# Libraries and SDKs

## Browser SDK (`@worthypayments/js`)

The browser SDK mounts the Payment Element: a card form served in our iframe that
tokenizes, runs 3-D Secure **when enabled**, and reports the outcome. It is the supported
client library. Apple Pay and Google Pay mount on the **merchant page, directly above the
card iframe** (not inside it) and only when `GET /v1/wallet-config` reports them on.

Load it from the pinned path. Full copy-paste HTML (doctype, CSP, `onSuccess`, handle
methods): [Payment Element](./08b-payment-element.md#2-mount-the-element-browser).

```html
<script src="https://app.worthypayments.com/sdk/v1/worthypayments.umd.js"></script>
<script>
  // Your server created the intent and named the amount:
  //   POST /v1/payment_intents  (sk_)  ->  { client_secret }
  const wp = WorthyPayments('pk_live_xxx');
  const element = wp.mountPaymentElement('#payment', {
    clientSecret,
    onSuccess: (r) => { /* required. r.paymentIntentId, r.transactionId */ },
  });
  // element.update({ clientSecret?, appearance?, locale?, defaultValues? })
  // element.submit()
  // element.destroy()
</script>
```

Use `/sdk/v1/`. The unversioned `/sdk/worthypayments.umd.js` always serves the newest
build, so every deploy of ours would become an untested change to your live checkout.

Full reference: [Embedded SDK](./08-embedded-sdk.md). Walkthrough:
[Payment Element](./08b-payment-element.md).

### There is no npm package yet

`@worthypayments/js` is not on the public registry. `npm install @worthypayments/js`
returns a 404 today, and so does the older `@tailoredpay` scope. Load the script tag
above.

The bundle sets a single global, `WorthyPayments`. Types for that factory live next
to the UMD:

```
https://app.worthypayments.com/sdk/v1/worthypayments.d.ts
```

That file is the ESM default-export shape (`import WorthyPayments from '…'`). For the
REST surface, generate from OpenAPI below. A published npm package may follow.

### How the hosted bundle is built (maintainers)

Source lives in `packages/sdk-js`. The bytes browsers load are the **tracked** copies
under `apps/merchant-dashboard/public/sdk/` (not gitignored `dist/`). After changing
SDK source:

```bash
npm --prefix packages/sdk-js run build
cp packages/sdk-js/dist/worthypayments.umd.js \
  apps/merchant-dashboard/public/sdk/worthypayments.umd.js
cp packages/sdk-js/dist/worthypayments.umd.js \
  apps/merchant-dashboard/public/sdk/v1/worthypayments.umd.js
cp packages/sdk-js/dist/index.d.ts \
  apps/merchant-dashboard/public/sdk/worthypayments.d.ts
cp packages/sdk-js/dist/index.d.ts \
  apps/merchant-dashboard/public/sdk/v1/worthypayments.d.ts
```

While the package is 1.x, keep the floating and `/sdk/v1/` copies identical. A future
2.0 freezes `/sdk/v1/` and adds `/sdk/v2/`. Rebuilding without copying is a known
failure mode: production keeps serving the previous committed UMD.

---

## Server-side

There is no supported server SDK. Call the REST API directly. The surface is small and
conventional, and every endpoint is in the [OpenAPI spec](./openapi.yaml) and the
[Postman collection](./worthypayments.postman_collection.json), so you can generate a
typed client in your language.

> The packages `@worthypayments/sdk` (Node), `worthypayments/sdk` (PHP) and `worthy`
> (Python) in the repo target a legacy internal API, not this `/v1` surface. Do not use
> them.

### Generating a client from OpenAPI

```bash
# Example: a TypeScript client with openapi-typescript
npx openapi-typescript https://app.worthypayments.com/developers/api-reference/openapi.yaml -o worthypayments.d.ts
```

The spec also imports into Postman, Insomnia and Stoplight.

---

## WooCommerce

A drop-in plugin ships the hosted redirect flow with no code. See
[WooCommerce](./09-woocommerce.md).