Events

Ramp Instant allows you to track the various events that occur during an end-user's journey through our app. Here's a write-up of ones that might help you.

Event types

Events fall into two major categories - widget status events and purchase status events.

Widget status events

Those events are dispatched to your SDK instance - they aren't available via webhooks.

WIDGET_CLOSE

Sent when the widget is closed.

{
type: 'WIDGET_CLOSE',
payload: null,
widgetInstanceId: string,
}

WIDGET_CONFIG_DONE

Sent when the widget is done fetching the internal configuration and can be displayed. This is when the loader hides.

NOTE: this is done automatically, you can call .show() immediately without waiting for this event.

{
type: 'WIDGET_CONFIG_DONE',
payload: null,
widgetInstanceId: string,
}

WIDGET_CONFIG_FAILED

Sent when the widget has failed fetching the internal configuration. This is when the loader hides.

NOTE: it's done automatically, you can call .show() immediately without waiting for this event.

{
type: 'WIDGET_CONFIG_FAILED',
payload: null,
widgetInstanceId: string,
}

WIDGET_CLOSE_REQUEST

Sent when a user wants to close the widget and a confirmation modal is displayed.

{
type: 'WIDGET_CLOSE_REQUEST',
payload: null,
widgetInstanceId?: string,
}

WIDGET_CLOSE_REQUEST_CANCELLED

Sent when a user cancels closing the widget window.

{
type: 'WIDGET_CLOSE_REQUEST_CANCELLED',
payload: null,
}

WIDGET_CLOSE_REQUEST_CONFIRMED

Sent when a user confirms closing the widget - this ends the flow.

{
type: 'WIDGET_CLOSE_REQUEST_CONFIRMED',
payload: null,
}

Purchase status events

Those events are dispatched when a purchase is initiated or changes its status. They are available via both SDK and webhooks.

PURCHASE_CREATED

Sent when a purchase is created, but not yet fulfilled.

{
type: 'PURCHASE_CREATED',
payload: {
purchase: RampInstantPurchase,
purchaseViewToken: string,
apiUrl: string,
},
widgetInstanceId: string,
}

PURCHASE_SUCCESSFUL

Sent when the user receives their crypto.

{
type: 'PURCHASE_SUCCESSFUL',
payload: {
purchase: RampInstantPurchase,
},
widgetInstanceId: string,
}

PURCHASE_FAILED

Sent when a purchase fails (for any reason).

{
type: 'PURCHASE_FAILED',
payload: null,
widgetInstanceId: string,
}

Subscribing to events

We provide two ways of subscribing to events - via our SDK and via webhooks.

Subscribing via SDK

Let's see how to subscribe to Ramp Instant events using our SDK.

A basic integration of Ramp Instant via our SDK looks like this.

new RampInstantSDK({
hostAppName: 'Maker DAO',
hostLogoUrl: 'https://cdn-images-1.medium.com/max/2600/1*nqtMwugX7TtpcS-5c3lRjw.png',
variant: 'auto',
}).show();

In order to subscribe to events, call the .on(eventType, callback) method of the SDK instance.

new RampInstantSDK({
hostAppName: 'Maker DAO',
hostLogoUrl: 'https://cdn-images-1.medium.com/max/2600/1*nqtMwugX7TtpcS-5c3lRjw.png',
variant: 'auto',
})
.on('*', (event) => console.log(event))
.show();

You can subscribe to all events by using '*' as the first argument to .on() or subscribe to particular event types by passing their name, like so.

new RampInstantSDK({
hostAppName: 'Maker DAO',
hostLogoUrl: 'https://cdn-images-1.medium.com/max/2600/1*nqtMwugX7TtpcS-5c3lRjw.png',
variant: 'auto',
})
.on('WIDGET_CLOSE', (event) => console.log(event))
.show();

In order to unsubscribe from a given event type, just call .unsubscribe() using the same params you called .on() with.

Subscribing via webhooks

Subscribing to events via webhooks depends on how you've integrated Ramp Instant into your app.

Integration via SDK

If you've integrated Ramp Instant via our SDK, you just need to provide a URL to be used for webhook status updates.

new RampInstantSDK({
hostAppName: 'Maker DAO',
hostLogoUrl: 'https://cdn-images-1.medium.com/max/2600/1*nqtMwugX7TtpcS-5c3lRjw.png',
variant: 'auto',
webhookStatusUrl: 'https://my.domain/callback/123/', // <- that's it!
}).show();

Integration via URL - hosted mode only

If you've chosen to integrate Ramp Instant via URL, you'll need to provide a URL for webhook status updates via a webhookStatusUrl query param.

Example:

https://buy.ramp.network/?webhookStatusUrl=https://example.com/webhook/