Integration methods

Depending on your website setup, you may have a specific preference for how to open the payment flow. The simplest method is to direct your consumer fully to a Fortumo hosted website, either in the same frame where the payment button was clicked or maybe even in a blank new window or tab.

Iframe

In case you do not wish to direct consumer away from your website while they are completing their subscription or payment, you can also embed Fortumo payment flow inside an iframe. For that, you can simply add the following iframe tag to your website:

1
2
3
<iframe src="https://dcb.fortumo.com/{merchant_id}/?token={header.payload.signature}" width="{customizable width}" height="{customizable height}">
  <p>Your browser does not support iframes.</p>
</iframe>

In case you have embedded the Fortumo payment flow inside an iframe, you may also wish to dynamically present your users custom information on the parent page during or after the payment has been completed. For that Fortumo provides you means for cross-document communication, so that on front end side you would not need to rely solely on the information that is exchanged via server-to-server communication.

In order to handle postMessages Fortumo sends, you will firstly need to specify the postmessage_target URL when generating the JWT for a specific payment. Fortumo will then make sure messages are sent only to the correct domain. Always specify an exact target origin, for example:

1
2
3
4
5
{
  "urls": {
    "postmessage_target": "https://page-where-iframe-is-located.com"
  }
}

For getting the messages sent by Fortumo HDCB, you will need to add a JavaScript event listener with handler to your website. For example:

1
window.addEventListener("message", receiveMessage, false);

Once that's done, the event handler function takes a parameter for the message event and uses that event.data:

1
2
3
4
5
6
7
8
function receiveMessage(event)
{
  // Check if message originates from HDCB
  if (event.origin == "https://dcb.fortumo.com/") {
  // Process messages as you wish:
    console.log(event.data);
 }
}

Please note that support for cross-document communication is only meant for simplifying the development of your service's front end.

In terms of providing the actual service to users, you should always rely on server-to-server requests, not on JavaScript postMessages.

In case you wish to have an alternative way to open the payment flow on your site you can use Hosted DCB widget inside a lightbox overlay. For that you would have to include the following on your website:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<head>
  <script src="https://unpkg.com/@fortumo/hdcb-lightbox@latest/dist/HdcbLightbox.min.js"></script> 
</head>
 
<body>
  <div id="myCustomId"></div>
  <script>
    var my_config_opts = {
      merchant_id: 'your-merchant-id',
      token: 'your-jwt-token'
    }
    HdcbLightbox.addPaymentButton('myCustomId', my_config_opts);
  </script> 
</body>

Besides merchant_id and token there are additional parameters which you can set during payment button initialization. All of the possible parameters are described here.

Help us improve our Merchants Portal. Was this article helpful?