> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperwisor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Widget

> Charge a user for a paid action or unlock inside a dashboard.

<Info>
  **Category:** Controls · **Charges:** users · **Fires:** paymentSuccess / paymentFailed
</Info>

## Mental model

A **Payment Widget is a checkout button.** It presents a paid action; when the user
pays, it unlocks or triggers what it gates — turning a dashboard into a place you
can earn.

## When to use it

* Charge for a premium action, unlock, or one-off operation
* Monetize an action inside an otherwise free dashboard

## Settings

### General

* **Widget Title / ID**
* **Action type** — what the payment unlocks/does
* **Amount** · **currency** · **currency position**
* **Button label** · **button variant**
* **Command endpoint** — the action invoked on success
* **Description**

### Style

Amount styling (color / size / weight), description styling, alignment, background,
border. Error state: **error icon / title / message**.

### Triggers

| Event            | Fires when                                                |
| ---------------- | --------------------------------------------------------- |
| `paymentSuccess` | Payment completes                                         |
| `paymentFailed`  | Payment fails                                             |
| *(common)*       | `load`, `ready`, `destroy`, `update`, `visible`, `hidden` |

## Example — unlock on success

```
WHEN     paymentSuccess
SEND TO  Current Device
EXECUTE  Premium
Action   UNLOCK   params: {}
```

## Related

Payments feed your product's earnings — see the monetization docs for the fee
model and settlement.

## Script API example

The same interactions from a [dashboard script](/script/overview):

```js theme={null}
widget.on('unlockPay', 'paymentSuccess', () => widget.show('premiumPanel'));
widget.on('unlockPay', 'paymentFailed',  () => widget.setText('payStatus', 'Payment failed'));
```

<CardGroup cols={2}>
  <Card title="Payment Widget (monetization)" icon="credit-card" href="/monetization/payment-widget">
    The business side.
  </Card>

  <Card title="Revenue & fees" icon="hand-holding-dollar" href="/monetization/revenue-sharing">
    3% flat fee, 97% to you.
  </Card>
</CardGroup>