Skip to main content

User Interface Initialisation

To perform a transaction using the IP.Frame UI, it first needs to be initialised via a server to sever API call. The purpose of this message is to transfer the necessary information about this transaction to the platform, such as the amount and customer details etc. The Payen Platform will in turn respond in successful scenarios with a requestKey, required for the next stage in processing.

The UI can be initialised for a card transaction or a card validation, as described below.

Card Transaction Initialisation Request Example​

Initialise the UI in preparation to authorise and capture funds.

Initialisation Request
{
   "requestType": "initialisationRequest",
   "version": 2,
   "merchant": {
      "merchantId": 10000001,
      "accountId": 20000001
   },
   "customer": {
      "customerId": 1,
      "email": "[email protected]",
      "firstName": "Test",
      "surname": "Client",
      "dateOfBirth": "03042000",
      "address": {
         "addressLine1": "123 Street",
         "addressLine2": "",
         "city": "Guildford",
         "province": "Surrey",
         "postcode": "GU2 2YG",
         "country": "GBR",
         "locale": ""
      },
      "mobileNumber": "01234123123"
   },
   "transaction": {
      "amount": 1000,
      "currency": "USD",
      "merchantRef": "Fh8F9fEpeK8qUFMHt0Vl",
      "transactionType": ""
   },
   "url": {
      "responseUrl": "https://www.url.com/ipframe/ipframeresponse.jsp",
      "notificationUrl": "https://www.url.com/ipframe/notification.jsp",
      "thirdPartySuccessUrl": "http://www.url.com/paypalsuccess",
      "thirdPartyCancelUrl": "http://www.url.com/paypalcancel"
   },
   "paymentInfo": {
      "country": "GBR"
   }
}

For details of the message elements see Initialisation Request

Card Validation Initialisation Request Example​

Initialise the UI in preparation to validate a card and cardholder as a standalone request.

info
  • The cardholder will be required to complete a 3D Secure challenge process.
  • No funds will be taken from the cardholder. The amount must be 0. The currency should be valid for the card and merchant account.
  • This request applies to ECommerce transactions only (i.e. not MOTO).
  • No further operations can be processed on these transactions e.g. they cannot be CAPTURED, REVERSED or REFUNDED.
  • These transactions can be referred to when performing a Merchant Initiated Authorisation
test
{
   "requestType": "cardValidationInitialisationRequest",
   "version": 2,
   "merchant": {
      "merchantId": "1000002",
      "accountId": "2000053"
   },
   "customer": {
      "customerId": 20566,
      "email": "[email protected]",
      "firstName": "Shopper",
      "surname": "Client",
      "dateOfBirth": "03041970",
      "address": {
         "houseNameNumber": "5",
         "addressLine1": "The street",
         "addressLine2": "AddressL2",
         "city": "city",
         "province": "CA-ON",
         "postcode": "XXXX XXX",
         "country": "CAN"
      },
      "mobileNumber": "35485962346"
   },
   "transaction": {
      "merchantRef": "HBIRYY7zEhjfLt1QUh6a",
      "amount": 0,
   "currency": "CAD"
   },
   "url": {
      "responseUrl": "https://localhost:8443/PoSSimulator/return/fromMerchant/10",
      "notificationUrl": "https://localhost:8443/PoSSimulator/notification/fromPlatform/10",
      "thirdPartySuccessUrl": "https://localhost:8443/PoSSimulator/return/fromThirdParty/success/10",
      "thirdPartyCancelUrl": "https://localhost:8443/PoSSimulator/return/fromThirdParty/cancel/10"
   },
   "paymentInfo": {
      "country": "CAN",
      "ipAddress": "100.200.11.22"
   }
}

For details of the message elements see Card Validation Initialisation Request

Initialisation Response Message​

The initialisation response from the Payen Platform provides the requestKey for the transaction that has just be initialised. Once you have a valid requestKey, it can be used to start up the IP.Frame UI in the browser.

An example of such a message is shown below:

Initialisation Response
{
   "version": 2,
   "merchant": {
      "merchantId": 10000001,
      "accountId": 20000001
   },
   "transaction": {
      "merchantRef": "Fh8F9fEpeK8qUFMHt0Vl",
      "gatewayRef": "G78GYft76HGJ98IOifT"
   },
   "status": {
      "code": "SUCCESS",
      "timestamp": "2012-06-21T16:56:39.154+01:00"
   },
   "requestKey": "3b5bee9ffa8a446e8f30161516af1527"
}

For details see Initialisation Response

UI Integration​

The IP.Frame payment experience is delivered through a secure HTML <iframe> that sits on top of the merchant’s website via a custom web component called <fusion-element>. This element will create the secure <iframe> and launch the IP.Frame modal within it, in a PCI-DSS compliant manner. Using this element supports consistent behavior across desktop, tablet, and mobile devices.

CSS and JavaScript assets are provided via script links that must be included on the merchant’s webpage. These assets are responsible for rendering and controlling the IP.Frame experience. Please contact your integration manager to obtain the production URLs and access credentials.

Required Assets​

Required assets
<link rel="stylesheet" href="https://pripframev2.ilixium.com/fusion/ui/fusion.css" />
<script type="text/javascript" src="https://pripframev2.ilixium.com/fusion/ui/fusion.min.js"></script>

Launching the UI​

In addition to including the required assets the merchant’s webpage must also include the <fusion-element> tag. This custom web component acts as the container for the IP.Frame experience. It should be placed within the HTML where the payment interface should appear.

There are two supported approaches:

Add the <fusion-element> directly to your HTML where the iframe should appear.

<fusion-element></fusion-element>
warning

This element must exist in the DOM before the (openFusion) event is dispatched. If the element is missing, the UI will not start.

In either approach the web component will now validate the parameters, sanitize the base URL, and automatically render the iframe inside the <fusion-element> tag.

Once the initialisation request has been processed and a transaction request key obtained, the merchant must trigger the UI by dispatching a JavaScript event (openFusion) with the appropriate transaction parameters.

  • baseUrl - The environment specific URL for the UI
  • merchantId - The same merchantId used during initialisation
  • requestKey - The requestKey from the initialisation response
  • digest - The digest value calculated using this merchantId and requestKey. see Browser to Server Digest Calculation
Launch event
<script type="text/javascript">
    document.dispatchEvent(new CustomEvent('openFusion', {
    detail: {
    baseUrl: 'https://pripframev2.ilixium.com/fusion/ui',
    merchantId: '{merchantId}',
    requestKey: '{requestKey}',
    digest: '{digest}'
}
}));
</script>
warning

If parameters are invalid/missing the iframe will fail to launch, then no request will be made to the Payen platform.

Additionally, JavaScript must be enabled in the browser; otherwise, the UI will not load. You may wish to warn your users when their javascript is currently disabled by implementing a <noscript> block.

An example of a noscript block for cases of disabled javascript:

Javascript disabled
<noscript>
   <div class="your-styles">
      Resources on this page require javascript. Please enable it.
   </div>
</noscript>

Closing the UI​

When the processing of the transaction is complete, a response will be sent to the URL provided in the initialise request message based on the outcome (response url). This response will be in the form of a POST message and will contain the following parameters:

ParameterDescriptionData TypeRequired
merchantIdThe merchant identifier as given in the original initialisation request.Alphanumeric 4-20 CharsYes
responseKeyThe response key provided by the Platform required for sending the final status message.Alphanumeric 32 CharsYes
digestThe Base64 encoded SHA-512 message digest of the merchant id and response key concatenated with the merchant’s password. For more information please see the digest calculation section.Alphanumeric 1-255 CharsYes

Once this response has been received, you can dispatch a close event to the <fusion-element> in order to remove it from the DOM.

For example:

Close event
<script>
   document.querySelector('fusion-element').dispatchEvent(new Event('close'));
</script>

Once the <fusion-element> receives the close event, it cleans up any associated resources and becomes ready to handle the next (openFusion) event.