Getting Started

In order to initialize Checkout Embedded, two parameters are required: the provided session id and, optionally, the id of the parent HTML element where the embedded component will appear.

• Include the Billwerk+ JavaScript SDK
  HTML
  <script src="https://checkout.reepay.com/checkout.js"></script>
• Insert the Billwerk+ Payments JavaScript SDK
  Embedded Initialise
  var rp = new Reepay.EmbeddedCheckout(' YOUR SESSION ID HERE ', { html_element: 'rp_container' } );

You can test if the script is properly loaded by inspecting the Billwerk+ object in the console.

Notice that for Subscription sessions, the method name is EmbeddedSubscription.

Embedded initialize for subscription sessions

var rp = new Reepay.EmbeddedSubscription(' YOUR SESSION ID HERE ', { html_element: 'rp_container' } );

Embedded Initialise HTML

<div id='rp_container' style="width: 500px; height: 730px;"></div>

If the custom parent element id is not given, it will default to searching for 'rp_container'. If that is not found either, an error will be thrown.

The parent HTML element can be given any size so as best to fit your page - the content will automatically adjust to fill the width given. It is however important to specify a non-zero width and height for the element, whether inline or through different CSS styling techniques.

The parent element must be empty once the embedded window is initialized.

Events

Similar to the modal initialization, the embedded window fires a number of events which your application may subscribe to. In order to set up an event handler use the .addEventHandler function, and pass it the type of event and the callback function:

Embedded Events

/* var rp = new Reepay.EmbeddedCheckout(' YOUR SESSION ID HERE ', 'rp_container'); */

rp.addEventHandler(Reepay.Event.Accept, function(data) {
	console.log('Success');
});

The possible event types which may be subscribed to are:

Embedded Event Types

Reepay.Event.Accept
Reepay.Event.Error
Reepay.Event.Close

Each event responds with a signature of type:

Embedded Response Signature

{
  id: string;			// The current session id
  invoice: string;		// Invoice/charge handle
  customer: string;		// Customer handle
  subscription: string;		// Subscription handle
  payment_method: string;	// Payment method if a new one is created
  error: string;		// The error code
}

To unsubscribe to events, use the .removeEventHandler method with the given event handler:

Embedded Remove Event Handler

/* var rp = new Reepay.EmbeddedCheckout(' YOUR SESSION ID HERE ', 'rp_container'); */

rp.removeEventHandler(Reepay.Event.Accept);

🚧

Caution

It is not mandatory to subscribe to events, however we strongly encourage it. The SDK will show helpful warnings in console if an un-handled even is fired (with the exception of the Reepay.Event.Error).

Once you have set up the Reepay.EmbeddedCheckout object, with the event hanlders necessary, you are good to go!

Preloading the Embedded Window

As an alternative to both initializing and loading the embedded window only once the backend to backend call is done and a session id is available, the two steps may be done separately and at different times in your code.

By calling the constructor without a session id, the embedded window is initialized in the background, however will remain hidden until the .show function is called and passed the required session id.

Embedded Preload

// Step 1: Initialize
// if {html_element: 'container'} is skipped the sdk will assume 'rp_container' as your target container
var rp = new Reepay.EmbeddedCheckout(null,  {html_element: 'my_container'});	// No session id given

// ... Backend to backend call ... 

// Step 2: Load the modal 
rp.show(' YOUR SESSION ID HERE ');	// Call the .show function with the session id

Destroy the Embedded Window

You also have the option of programmatically closing the modal by calling the .destroy function:

Embedded Destroy

/* var rp = new Reepay.EmbeddedCheckout(' YOUR SESSION ID HERE ', 'rp_container'); */

rp.destroy();

This function call will also fire the Reepay.Event.Close event. This is the only method to close the embedded window. You could, for instance call this method as soon as an Accept event occurs or after a predefined amount of time.

Hide the receipt page

The embedded mode supports replacing the receipt page displayed at the end of a successful payment with a blank page. As seen below, to make use of this feature, add showReceipt: false to the options object.

var rp = new Reepay.EmbeddedCheckout(' YOUR SESSION ID HERE ', { html_element: 'rp_container', showReceipt: false } );

When preloading the embedded checkout, the showReceipt flag can be sent both on the show and on the initialisation. Passing the parameter in both places will result in the value passed in the show to override the initial one.

rp.show(' YOUR SESSION ID HERE ', {showReceipt: false});

var rp = new Reepay.EmbeddedCheckout(null, {html_element: 'rp_container', showReceipt: false});

Error Handling

The Billwerk+ Payments Checkout SDK throws a number of possible errors, described below. All the errors extend the global Error object.