Ramp JavaScript SDK Reference
@ramp-network/ramp-instant-sdk
is a library that allows you to easily integrate the Ramp widget into your web app and communicate with it.
While using an SDK is not necessary, it is strongly recommended.
It's written with TypeScript, so typings come out of the box and are always up-to-date.
Installation
You can find the package here.
Install via Yarn:
Install via npm:
Example usage
Initialization & configuration
@ramp-network/ramp-instant-sdk
exports the RampInstantSDK
class. As a principle, one instance of the class corresponds to one instance of the widget. If a user closes the widget, you need to create a new instance of the RampInstantSDK
class.
Configuration
The RampInstantSDK
constructor accepts a configuration object. A detailed list of the available configurations with examples can be found here.
If any of the supplied config values are invalid, you'll be notified about it via the console in your devtools.
If you fail to supply any of the required config values, the widget will display an error page and won't start.
Initialization
Just call new RampInstantSDK(config)
- this will run some prep work for the widget, but won't display it yet. In order to display the widget, run .show()
on your instance of the RampInstantSDK
class.
.show()
adds the widget to the DOM - specifically, to the body
element - starting from that moment, the semi-transparent overlay with a loader appears and the widget starts booting up.
NOTE: .show()
is chainable.
Events
The Ramp widget sends some events that you can react to in your web app.
Each event has the following fields:
type
- type of the event, i.e. what happened,payload
- any additional info related to the event,widgetInstanceId
- a random number-string - each widget instance has its own. You can use this if you have many instances of the widget and want to distinguish which event came from which instance.
Available events
The package also exports a RampInstantEvents
type which is a type containing all possible events and RampInstantEventTypes
which is an enum of all possible event type
values.
Ramp Purchase object
Webhooks, purchase status API and PURCHASE_CREATED
event expose an object with the following details about the purchase.
Purchase status
States before any payment attempt:
INITIALIZED
: The purchase was initialized.
Payment progress states:
PAYMENT_STARTED
: An automated payment was initiated, eg. via card or open banking.PAYMENT_IN_PROGRESS
: User completed the payment process.PAYMENT_FAILED
: The last payment was cancelled, rejected, or otherwise failed.PAYMENT_EXECUTED
: The last payment was successful.FIAT_SENT
: Outgoing bank transfer was confirmed on the buyer's account.FIAT_RECEIVED
: Payment was confirmed, final checks before crypto transfer.
Final outcome states:
RELEASING
: Crypto release started โ transfer transaction or escrowrelease()
tx was sent.RELEASED
: Crypto asset was confirmed to be transferred to the buyer. A terminal state.EXPIRED
: The time to pay for the purchase was exceeded. A terminal state.CANCELLED
: The purchase was cancelled and won't be continued. A terminal state.
Subscribing to events
In order to subscribe to an event, use the .on(eventType, callback)
method on your SDK instance.
The .on(eventType, callback)
method accepts either a string with the event's type
when you want to subscribe to a specific kind of an event or '*'
for subscribing to any event.
callback
is called each time a given event occurs.
In order to unsubscribe, call the .unsubscribe(eventType, callback)
method with the event type and handler you want to stop receiving updates for.
NOTE: .on(eventType, callback)
and .unsubscribe(eventType, callback)
are chainable.
Widget DOM nodes
The popup widget version (variant: "auto|mobile|desktop"
) RampInstantSDK
instance exposes a domNodes
field that contains body
, iframe
, overlay
, shadowHost
and shadow
elements.
body
is a reference to your app's<body>
element.iframe
is a reference to the widget's<iframe>
.overlay
is a reference to the semi-transparent backdrop for the widget.shadowHost
is a reference to the node where all widget-related elements are kept.shadow
is a reference to the widget's shadow DOM root.
Widget window reference
The hosted widget version (variant
: 'hosted-auto'
| 'hosted-mobile'
| 'hosted-desktop'
) RampInstantSDK
instance exposes a widgetWindow
field that is a reference to the created window.
API Reference
Creates an instance of the SDK.
Params:
Note: this also fetches the Poppins font which will be used by the widget.
Instance methods
on(type: RampInstantEventTypes | '*', callback: (event: RampInstantEvents) => void): sdkInstance
Registers the callback
to be called each time an event with the given type
is dispatched. If type
is '*'
, callback
will be called for every event, regardless of its type.
Returns the instance of the SDK it was called on.
unsubscribe(type: RampInstantEventTypes | '*', callback: (event: RampInstantEvents) => void): sdkInstance
Allows you to unsubscribe from receiving updates for a given event type and handler.
Returns the instance of the SDK it was called on.
show(): sdkInstance
Initializes the widget and adds it to your webapp's DOM.
Note: this can be only called once per SDK instance - if you want to open the widget again, you need to create a new one.