Skip to main content

Platform UI Initialisation

The following definitions are specifications for the request and responses that can be made as part of the Payen Platform transaction process. All the requests defined here are required to fully complete a transaction and are documented in sequence according to the message flow documented earlier in this document.

The Payen Platform initialisation message is a server to server request and response. The purpose of this message is to transfer the necessary information about this transaction to the platform to initialise a transaction. The Payen Platform will in turn respond in successful scenarios with a response key required for the next stage in processing.

Initialisation Request Example​

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​

Validates the card and cardholder as a standalone request which forces the user through 3D Secure authentication. No funds are captured by this request, but if completed successfully, authorisation is given to take funds at a future point. The cardholder must participate in the 3D secure challenge process.

Note:

  • 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 request key for the transaction. 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

Platform Process Message​

To process the request using the request key obtained in the initialisation request, the merchant must integrate an iframe containing a form that submits to the processing URL of the Payen Platform. The form must contain the parameters required to start the payment process and can either have controls for the user to submit manually or can be submitted automatically using JavaScript (take care with users who do not have or have disabled JavaScript).

When the transaction is complete the frame will be returned to the address provided in the initialisation request (responseUrl).

Process Request Form​

The parameters for the process request to the Payen Platform should be inserted as hidden fields in the form. The parameters for processing the request are shown below:

ParameterDescriptionData TypeRequired
merchantIdThe merchant identifier as given in the original initialisation request.Alphanumeric 4-20 CharsYes
requestKeyThe request key obtained from the initialisation response message.Alphanumeric 32 CharsYes
digestThe Base64 encoded SHA-512 message digest of the merchant id and request key concatenated with the merchant's password. For more information please see the digest calculation section.Alphanumeric 1-255 CharsYes

For example, to process the request key from the previous section, the HTML would be as follows:

Request Form
<form action="https://<baseUrl>/ipframe/web/request" method="post">
    <input type="hidden" name="merchantId" value="10000001" />
    <input type="hidden" name="requestKey" value="3b5bee9ffa8a446e8f30161516af1527" />
    <input type="hidden" name="digest" value="OfQw1lNqMlYoXgfNP9rj/0yOolAro8zz0AsDqjdOoiqCppoqwJFDv69NbjvfqJRWu3ldyPtvqUoePqE5OgpN9w==" />
</form>

Third Party Redirected Complete Message​

To complete a third party redirected transaction the third party will send its response containing the result of the transaction to the merchant website. It is the responsibility of the merchant to then make a further call to IP.Frame so that transaction processing can complete. This process involves sending another request to IP.Frame to reopen it inside an iframe. Any parameters sent as part of this request should be forwarded on to the IP.Frame for processing. The merchant must integrate an iframe containing a form that submits to the processing URL of IP.Frame for completing the third party processing. The form must contain the parameters required to complete the third party process and can either have controls for the user to submit manually or can be submitted automatically using JavaScript.

Request​

The parameters for the third party redirected complete process request to IP.Frame should be inserted as hidden fields in the form. The parameters for processing the request are shown below:

ParameterDescriptionData TypeRequired
[All Parameters]Make sure all parameters received in the response message from the third party are included as separate parameters as they were received with their original parameter names.Yes
merchantIdThe merchant identifier as given in the original initialisation request.Alphanumeric 4-20 CharsYes
digestThe Base64 encoded SHA-512 message digest of all received parameters concatenated in alphabetical order with the merchant’s password. For more information please see the digest calculation section.Alphanumeric 1-255 CharsYes

UI Integration​

As mentioned previously, the Fusion 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 is loaded dynamically and supports consistent behavior across desktop, tablet, and mobile devices.

Fusion provides CSS and JavaScript assets that must be included on the merchant’s webpage. These assets are responsible for rendering and controlling the iframe experience. Please contact your integration manager to obtain the correct file URLs and access credentials.

Required Assets​

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

Launching Fusion​

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

<script type="text/javascript">
    document.dispatchEvent(new CustomEvent('openFusion', {
    detail: {
    baseUrl: 'https://pripframev2.trustpayglobal.com/fusion/ui',
    merchantId: '{merchantId}',
    requestKey: '{requestKey}',
    digest: '{digest}'
}
}));
</script>

In addition to including the required assets and triggering the (openFusion) event, the merchant’s webpage must also include the <fusion-element> tag. This custom web component acts as the container for the Fusion iframe 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>
note

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

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

warning

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

Additionally, JavaScript must be enabled in the browser; otherwise, the Fusion app 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:

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

Closing Fusion​

On returning to the merchant website from the Payen platform, the iFrame automatically shuts itself down once the process is complete.

However, it is the merchant’s responsibility to dispatch a close event to the <fusion-element> in order to remove it from the DOM. For example:

<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.

Process Response Form​

When the processing of the transaction is complete, the iframe 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

Merchant Initiated Transactions​

A Merchant Initiated Transaction (MIT) is a payment initiated by the merchant instead of the cardholder. These transactions are initiated on behalf of the customer based on an agreement between the merchant and the cardholder. Unlike customer-initiated transactions, cardholder authentication is not needed to make a payment.

For example, a customer may consent to future payments being collected for variable amounts on a one-off or recurring basis.

IMPORTANT

Before initiating a MIT, the merchant must:

  • Have performed a previous successful CardValidation or fully 3D Secure authenticated (including a 3DS challenge) Authorisation transaction.
  • Have consent from the customer in the form of an agreement that complies with the card scheme rules.

The MIT can then be performed by referencing the previous Card Validation Initialisation Request Example or Authorisation.