Overlay Checkout
Getting Started
Once you have a session id you can simply initialize the Checkout modal by using its constructor :
Include Billwerk+ Javascript SDK.
HTML
<script src="https://checkout.reepay.com/checkout.js"></script>
Open Checkout as modal.
Overlay Initialise
var rp = new Reepay.ModalCheckout(' YOUR SESSION ID HERE ');
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 ModalSubscription
.
Overlay initialize for subscription sessions
var rp = new Reepay.ModalSubscription(' YOUR SESSION ID HERE ');
Events
The modal 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 :
Overlay Events
var rp = new Reepay.ModalCheckout(' YOUR SESSION ID HERE '); rp.addEventHandler(Reepay.Event.Accept, function(data) { console.log('Success', data); });
The possible event types which may be subscribed to are :
Overlay Event Types
Reepay.Event.Accept Reepay.Event.Error Reepay.Event.Cancel Reepay.Event.Close
Accept: fires once the transaction is successfully completed.
Error: whenever an error has occurred in attempting to finalise the transaction.
Cancel: the user presses the cancel button.
Close: fires once the modal is closed. This event is independent of the previous, as none of the above events automatically close the modal - it is only ever done by the user clicking a button, whether the transaction was completed or not.
Each event responds with a signature of type :
Overlay 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 :
Overlay Remove Event Handler
var rp = new Reepay.ModalCheckout(' YOUR SESSION ID HERE '); rp.removeEventHandler(Reepay.Event.Accept);
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've set up the Reepay.ModalCheckout object, with the event handlers necessary, you are good to go.
Preloading the Modal
As an alternative to both initializing and loading the modal 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 modal is initialized in the background, however will remain hidden until the .show function is called and passed the required session id.
Overlay Preloading Modal
// Step 1: Initialize var rp = new Reepay.ModalCheckout(); // 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
For scenarios where the modal is opened automatically, we recommend initializing it directly to avoid potential timing issues.
Destroy the Overlay
Closing the modal is generally done by client interaction, which fires a Reepay.Event.Close event. However, you also have the option of programatically closing the modal by calling the .destroy function :
Overlay Destroy
var rp = new Reepay.ModalCheckout(' YOUR SESSION ID HERE '); rp.destroy();
This function call will also fire the Reepay.Event.Close event.
Hide the receipt page
The overlay mode supports replacing the receipt page displayed at the end of a successful payment with a blank page. As seen bellow, to make use of this feature add "showReceipt: false" to the options object.
JavaScript
var rp = new Reepay.ModalCheckout(' YOUR SESSION ID HERE ', {showReceipt: false});
When preloading, simply pass the options object when calling the show method.
JavaScript
rp.show(' YOUR SESSION ID HERE ', {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.
RP_SessionTokenNotProvidedError
If the .show method is called without sending a session id. For more details on how to obtain a session id see the Introduction to Billwerk+ Payments Checkout Web SDK section
RP_CheckoutNotInitialized
Trying to access the iframe before it was initialised. This may happen when trying to preload the modal and call the .show function while the initialising is still happening.
RP_CallShowWhenAlreadyInitialized
Trying to call .show when the modal is already initialised with a session id, either through constructor or a second call of .show
RP_UnknownEventError
Trying to handle an event that isn't defined. See the event section for a full list of possible events to subscribe to.
RP_HandlerNotAFunction
Passing a handler that isn't of type function to the .addEventHandler function.