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

# SDK Events & Commands

> Subscribe to widget events and send commands to the widget with the Rampnow SDK

The widget and your page talk in two directions:

* **Events** go from the widget to your app. Subscribe with `sdk.on()`.
* **Commands** go from your app to the widget. Send them with `sdk.send()`.

<Warning>
  Events are for updating your UI. Don't fulfil or credit anything on a browser event alone: confirm the order on your backend with [webhooks](/api-reference/webhook), which are signed and retried.
</Warning>

## Subscribing

`sdk.on(eventType, callback)` returns the instance, so calls chain. `sdk.off(eventType, callback)` unsubscribes and takes the same forms.

```javascript theme={null}
// Single event
sdk.on(RampnowEventType.ORDER_CREATED, callback)

// Multiple events
sdk.on([RampnowEventType.ORDER_CREATED, RampnowEventType.ORDER_COMPLETED], callback)

// All events
sdk.on('*', callback)
```

## Events

Use the `RampnowEventType` enum:

| Event | Payload | Description |
| - | - | - |
| `WIDGET_READY` | — | Widget iframe loaded and ready |
| `WIDGET_CLOSED` | — | Widget was closed |
| `USER_AUTHENTICATED` | — | User signed in |
| `ORDER_CREATED` | `orderUid`, `orderType`, `srcCurrency`, `srcChain`, `srcAmount`, `dstCurrency`, `dstChain`, `paymentMode`, `cryptoTxnInfo?`, `bankTxnInfo?` | Order successfully created |
| `ORDER_PAYMENT_PROCESSING` | `orderUid`, `status`, `paymentStatus` | Payment is being processed |
| `ORDER_PAYMENT_COMPLETED` | `orderUid`, `status`, `paymentStatus` | Payment received by Rampnow |
| `ORDER_PAYMENT_FAILED` | `orderUid`, `status`, `paymentStatus` | Payment failed |
| `ORDER_COMPLETED` | `orderUid`, `status`, `srcCurrency`, `srcChain`, `srcAmount`, `dstCurrency`, `dstChain`, `dstAmount`, `walletAddress`, `transactionHash`, `cryptoTxnInfo?` | Order fully completed, crypto sent |
| `ORDER_FAILED` | `orderUid`, `status` | Order failed or cancelled |
| `KYC_STARTED` | — | User started identity verification |
| `KYC_SUBMITTED` | — | User submitted KYC documents |
| `KYC_APPROVED` | — | KYC approved |
| `KYC_REJECTED` | — | KYC rejected |
| `ERROR` | `message`, `code?` | Error occurred in the widget |

`status` and `paymentStatus` use the same values as the API and webhooks. See [Order Status](/api-reference/order-status).

### `CryptoTxnInfo`

Available in `ORDER_CREATED` and `ORDER_COMPLETED` payloads:

| Field | Type | Description |
| - | - | - |
| `currency` | `string` | Crypto currency code, e.g. `"USDC"` |
| `chain` | `string` | Chain code, e.g. `"ethereum"` |
| `amount` | `string` | Amount credited to the receiver |
| `receiverAddress` | `string` | Address that received the crypto |
| `fillAmount` | `string` | Filled/settled amount (may differ from amount on partial fills) |
| `senderAddress` | `string` | Address that sent the crypto |
| `transactionHash` | `string` | On-chain transaction hash |
| `status` | `string` | Status of the transaction |

### Example: full event handling

```javascript theme={null}
import { RampnowSdk, RampnowEventType } from '@rampnow/sdk'

const sdk = new RampnowSdk({
  apiKey: 'pk_YOUR_API_KEY',
  orderType: 'buy',
  dstCurrency: 'ETH',
  dstChain: 'ethereum',
})

sdk
  .on(RampnowEventType.WIDGET_READY, () => {
    console.log('Widget is ready')
  })
  .on(RampnowEventType.ORDER_CREATED, ({ payload }) => {
    console.log('Order created:', payload.orderUid)
  })
  .on(RampnowEventType.ORDER_COMPLETED, ({ payload }) => {
    console.log('Order completed:', payload.orderUid)
    console.log('Tx hash:', payload.transactionHash)
  })
  .on(RampnowEventType.ERROR, ({ payload }) => {
    console.error('Widget error:', payload.message)
  })
  .init()
```

## Commands

`sdk.send(commandType, payload)` sends a command to the widget iframe and returns the instance. Use the `RampnowCommandType` enum.

<Warning>
  **Domain whitelisting required:** For security, the widget only accepts commands from whitelisted origins. To whitelist your domain, [contact Rampnow](https://rampnow.io/contact-us). Commands sent from non-whitelisted origins are silently ignored.
</Warning>

| Command | Payload | Description |
| - | - | - |
| `UPDATE_PAYMENT_DETAIL` | `{ transactionHash }` | Update payment detail with a crypto transaction hash |

### Example: submit a transaction hash from your wallet

On a sell order, if your wallet sends the crypto for the user, pass the hash to the widget so it can match the transfer:

```javascript theme={null}
import { RampnowSdk, RampnowEventType, RampnowCommandType } from '@rampnow/sdk'

const sdk = new RampnowSdk({ apiKey: 'pk_YOUR_API_KEY' })

// After your wallet completes a crypto transfer, send the hash to the widget
sdk.send(RampnowCommandType.UPDATE_PAYMENT_DETAIL, {
  transactionHash: '0xabc123...',
})

// Listen for confirmation that the payment is being processed
sdk.on(RampnowEventType.ORDER_PAYMENT_PROCESSING, ({ payload }) => {
  console.log('Payment updated:', payload.paymentStatus)
})
```

## Next steps

<div style={{display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '1rem'}}>
  <Card title="Webhooks" icon="bell" href="/api-reference/webhook">
    Confirm order status on your backend
  </Card>

  <Card title="Sandbox Testing" icon="flask" href="/api-reference/sandbox-testing">
    Run every order outcome before going live
  </Card>
</div>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.