SDK Events & Commands

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().

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, which are signed and retried.

Subscribing

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

// 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.

`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

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.

Domain whitelisting required: For security, the widget only accepts commands from whitelisted origins. To whitelist your domain, contact Rampnow. Commands sent from non-whitelisted origins are silently ignored.

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:

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)
})

Build with AI

Learn about Rampnow

What's Supported

Integrations

Help

Subscribing

Events

`CryptoTxnInfo`

Example: full event handling

Commands

Example: submit a transaction hash from your wallet

Next steps

Webhooks

Sandbox Testing

​Subscribing

​Events

​CryptoTxnInfo

​Example: full event handling

​Commands

​Example: submit a transaction hash from your wallet

​Next steps

Webhooks

Sandbox Testing

Subscribing

Events

`CryptoTxnInfo`

Example: full event handling

Commands

Example: submit a transaction hash from your wallet

Next steps