Overview
PFI-A allows the AJAX style of updating the users payment page rather than re-directing.
PFI-A also has more flexibility for a merchant and more features than any other flow
Mandatory HTTP Headers
On the content site of the merchant, the site must at all times provide back the below headers
| Value | Description |
|---|---|
| X-PFI-MerchantToken | Unique GUID Will be provided to you by IMI on setup completion |
| X-PFI-SessionToken | A unique (dynamic in some cases) GUID |
Content Site Layout
The merchant site can have any suitable layout and can redirect the user as often as required. Any given page does not need to include any PFI elements if that page will not need to make any PFI purchase – it is possible to create a simple index page allowing users to browse content using conventional redirects without invoking a PFI purchase.
Please note that MerchantToken and SessionToken GUIDs must be included in all responses to PFI Ajax requests, regardless of whether a PFI purchase is being invoked on the page or not. This is to allow a stateless communication between the PFI Ajax server and the merchant content server.
AJAX calls direct to the Source Host are permitted on any page that does not invoke a PFI purchase, however be advised that no AJAX calls should be made if the page will be used for PFI purchases. For this reason the merchant may wish to keep their PFI purchases on small pages specifically for that purpose.
PFI DOM Elements and Call To Action
The merchant should render either a call-to-action button containing the necessary PFI data, or execute a script that tells PFI Ajax to begin the purchase process.
To begin a purchase using a call-to-action button, render a div or other element with the following attributes:
| Value | Description |
|---|---|
| data-pfi-button | Value must be ‘true’ for the click event to be recognised |
| data-pfi-button-id | Unique value for this button (passed to merchant as ‘CallerID’ – see Ajax By Proxy below) |
| data-pfi-service-id | Integer value, ID of Service or product |
| data-pfi-reference | String value, unique reference for this transaction |
| data-pfi-content-url | URL where user will be redirected on successful purchase. Can be local URL |
| data-pfi-content-id | Unique value for the content/subscription service being purchased (note that PFI will use this value to determine if a user has previously purchased this content within the rebilling period |
Example HTML:
<div
class="merchant-button btn1"
id="JShideme_1"
data-pfi-button="true"
data-pfi-button-id="hidebutton"
data-pfi-service-id="326"
data-pfi-reference="0000001"
data-pfi-content-url="/success.php"
data-pfi-content-id="sub1">
Click to Buy Me!
</div>
Note that the div does not need to be ‘clickable’ or trigger any event or post-back. PFI Ajax captures the click event of any element with the data-pfi-button=’true’ attribute.
JavaScript Call To Action
Alternatively a JS call can initiate the same call and be called from any element clickable or time-based etc.
merchantCall(hidebutton, serviceId, reference, contentUrl, contentId)
Example:
merchantCall(hidebutton, 326, '00000001', '/success.php', sub1)
InProcess CallBack
If the merchant provides an InProcessURL in the response header on page load (see Request Headers section), the PFI Ajax application will make GET requests to this URL containing information about the current status of the transaction (see Request Headers section for details of supplied data).
As well as returning the appropriate header data on the response, the merchant site should also include a JSON object in the following format:
| Value | Description |
|---|---|
| Script | JavaScript to execute on user’s browser |
| ShowMarketingOptIn | Merchant Choice to show and active opt-in for marketing messages tick box on confirm page or not |
{
"Error":null,
"Script":"displayPurchaseButton()",
"InProcessUrl":null
}
Using in-process calls, it is possible not only to continually update the user throughout the purchase process but also to refresh and rearrange the user’s DOM before a PFI purchase begins. For example, a merchant may wish the user to click through several buttons to determine the best product or service for them before inviting them to purchase. This may be done by showing and hiding a series of buttons using scripts in the JSON object detailed above.
The in-process must be used if a merchant wishes to update content as the user progresses. without this certain compliance elements will fail and the service will be deactivated.
The script can be as complex as adding entire new elements to the DOM
Sessions
Because it is not possible to maintain an active in-process session between the initial page load, subsequent in-process calls and final delivery to content, it is necessary to pass a token in order that PFI Ajax and the merchant site can communicate data about the current session. To do this, PFI Ajax uses a GUID stored in the X-PFI-SessionToken header.
When a user initially lands on the Request Host to start a new session, a get request is made to the Source Host without passing an X-PFI-SessionToken header. The merchant must generate a new GUID at this time and pass it back in the X-PFI-SessionToken on the response. This token can then be used for the duration of that user’s session.
Note that for verification purposes, the SessionToken MUST match on any InProcess calls – sending an incorrect token on an InProcess call will cause an error to be thrown in PFI Ajax and the user to be redirected to an error page.
It is possible to process multiple transactions under a single SessionToken – PFI Ajax will reset the session status during the session if necessary (see Status Descriptions below).
If the merchant site requires the starting of a new session, this can be done during the response to the Source Host request, by specifying a new X-PFI-SessionToken header, and setting a new header called X-PFI-ResetSession to ‘true’.
Request Headers
Supplied to merchant on page load / redirect request
| Header | Type | Description |
|---|---|---|
| X-PFI-SessionToken | GUID | Supplied to merchant if not a new session |
| X-PFI-Status | String | Session status (see list below) |
| X-PFI-RequestTime | Time | Time of request |
| X-PFI-Hash | Hash | MD5 hash of request time and merchant token |
| X-PFI-Alias | String | Encrypted alias of user’s MSISDN (if known) |
| X-PFI-NetInfo | String | Network identifying code (if known) |
| X-PFI-Reference | String | Reference of product (if returning from successful purchase) |
| X-PFI-OPTINSTATUS | String | Will contain optinstatus of last Confirm page selection |
| X-PFI-TRANSACTIONID | String | Will contain the last successful transaction ID of a user’s last purchase |
To be returned by merchant on page load / redirect response
| Header | Type | Description |
|---|---|---|
| X-PFI-SessionToken | GUID | Supplied to merchant if not a new session |
| X-PFI-ResetSession | Bool | (optional) return ‘true’ if a new session is required |
| X-PFI-MerchanToken | GUID | Merchant Token. Supplied to you from IMI |
| X-PFI-InProcessUrl | Hash | (optional) URL for PFI to call if in-process calls are required |
Supplied to merchant on InProcess request
| Header | Type | Description |
|---|---|---|
| X-PFI-SessionToken | GUID | |
| X-PFI-Status | String | |
| X-PFI-RequestTime | Time | |
| X-PFI-Hash | Hash | |
| X-PFI-Alias | String | |
| X-PFI-NetInfo | String | |
| X-PFI-CallerId | String | |
| X-PFI-OPTINSTATUS | String | |
| X-PFI-TRANSACTIONID | String |
To be returned by merchant on all page requests from IMI and InProcess response
| Header | Type | Description |
|---|---|---|
| X-PFI-SessionToken | GUID | Supplied to merchant if not a new session |
| X-PFI-Status | String | Session status (see list below) |
X-PFI-Status Descriptions
The following statuses may be returned in the X-PFI-Status header and can be used to determine what script to return during an in-process call, for example, to show a “your payment is being processed” text or image during the PfiProcessing status:
| Header | Description |
|---|---|
| Initiated | A user has landed on the page with no current active session |
| PfiPurchaseButtonShown | The user has been presented with the first PFI call-to-action |
| PfiConfirmButtonShown | The user has been presented with the second PFI call-to-action |
| PfiProcessing | The user has agreed to the purchase and payment confirmation is in progress |
| PfiAlreadySubscribed | This is a subscription service, and the user’s MSISDN already has an active subscription |
| PfiPreviousPurchase | This is a non-subscription service, and the user has previously purchased this product within the rebilling period |
| PfiPurchaseSuccess | The user has agreed to the purchase and the payment has been successful |
| PfiPurchaseFailed | The user has agreed to the purchase but the payment has not been successful |
| PfiExit | The user clicked the Exit button on the PFI header box |
Styling Ajax Elements
PFI Ajax allows mandated PFI elements to be seamlessly rendered with merchant content. It may be desirable for the merchant to restyle the PFI elements in order to create a seamless image.
NOTE: It is the responsibility of the merchant to ensure the PFI Scheme Rules are not breached in any way by changing the PFI element styling. In particular, font and button size, alignment, colour, decoration and contrast should agree to the scheme rules.
All PFI classes are prefixed with “PFI-“. The merchant should refrain from using the PFI- prefix on merchant-specific content classes but can add new styling rules to existing classes in order to restyle the PFI elements accordingly.
Competition Flow
PFI-A Competition Flow setup and integration is no different than standard PFI-A
at the time of setup the merchant should specify if the site will be for completion. At IMI side we will configure it for the competition flow. All aspect as available and the same under the competition flow including parameters to initiate the payment Flow.
The only mechanism that change is the mandated wording for competitions will be rendered by IMI on the stages of the payment flow
Abandonment SMS
One feature available to AJAX clients (optional) is to send a one off customisable SMS to a user who validates during the payment flow but does not complete.
After 5 minutes the user will be sent a SMS containing custom text, and a link to grant access back to complete the payment (as if on data)
E.g.
FreeMsg: We appear to have lost you. Click on xxxxxxxxx.com/PfiHome/Reconnect?token=8Xzp8QCwkv2I to get back to xxxxxxx.com Help? 03330031903