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

# Widget Callbacks

> JavaScript callbacks fired by the Proof widget inside the browser

Pass callback functions to `proofWidget.run({...})` to react to widget lifecycle and transaction events.

<Warning>
  Callbacks fire in the browser and can be lost if the user closes the tab. Never use them as the authoritative source for business logic. Use [polling](/on-off-ramp/transaction-status#channel-1--polling), [WebSocket](/on-off-ramp/api-websocket), or the [outbound webhook](/on-off-ramp/api-partner-webhook) on your backend for state you depend on.
</Warning>

## `onStatusChange`

Fired each time the transaction status changes inside the widget.

```javascript theme={null}
proofWidget.run({
  // ...
  onStatusChange: (data) => console.log(data)
});
```

### Payload

```json theme={null}
{
  "amount": "0.01336",
  "currency": "BTC",
  "network": "BITCOIN",
  "fiat_amount": "100",
  "fiat_currency": "EUR",
  "merchant_transaction_id": "03b22d25d523a5285",
  "status": "paid",
  "payment_method": "card"
}
```

| Field                     | Type   | Description                                                                                                  |
| ------------------------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| `amount`                  | string | Crypto amount                                                                                                |
| `currency`                | string | Crypto currency ticker                                                                                       |
| `network`                 | string | Blockchain network                                                                                           |
| `fiat_amount`             | string | Fiat amount                                                                                                  |
| `fiat_currency`           | string | Fiat currency code                                                                                           |
| `merchant_transaction_id` | string | Your transaction identifier                                                                                  |
| `status`                  | string | Widget-level status (not the same as the [normalized API enum](/on-off-ramp/transaction-status#status-enum)) |
| `payment_method`          | string | Payment method used (e.g. `"card"`)                                                                          |

***

## `onLoad`

Fired when the widget starts loading.

```javascript theme={null}
proofWidget.run({
  // ...
  onLoad: () => console.log("widget is loading")
});
```

No payload.

***

## `onReady`

Fired when the widget has finished loading and is visible to the user.

```javascript theme={null}
proofWidget.run({
  // ...
  onReady: () => console.log("widget is loaded")
});
```

No payload.

***

## `onPaymentFinished`

Fired in **on-ramp** when the fiat payment and KYC check (if required) have both completed, regardless of outcome.

```javascript theme={null}
proofWidget.run({
  // ...
  onPaymentFinished: (data) => console.log(data)
});
```

### Payload

```json theme={null}
{
  "payment_method": "card"
}
```

| Field            | Type   | Description                                  |
| ---------------- | ------ | -------------------------------------------- |
| `payment_method` | string | Payment method that was used (e.g. `"card"`) |

***

## `onSellTransferEnabled`

Fired in **off-ramp** when the user selects the sell flow and a address is displayed for the crypto transfer.

```javascript theme={null}
proofWidget.run({
  // ...
  onSellTransferEnabled: (data) => console.log(data)
});
```

### Payload

```json theme={null}
{
  "amount": "0.01336",
  "currency": "BTC",
  "network": "BITCOIN",
  "address": "04d3911f3b6de0843",
  "id": "03b22d25d523a5285",
  "flow_id": "payout"
}
```

| Field      | Type   | Description                          |
| ---------- | ------ | ------------------------------------ |
| `amount`   | string | Crypto amount the user must send     |
| `currency` | string | Crypto currency ticker               |
| `network`  | string | Blockchain network                   |
| `address`  | string | Destination address for the transfer |
| `id`       | string | Transaction identifier               |
| `flow_id`  | string | Always `"payout"` for off-ramp       |