Use Case Document

Pay-Per-Use Recurring Payments

Use Case Document
Version 1.2
Version Date: 08/03/2018

© UniversalPay Page 1 of 10 22/01/2018

Confidential Version 1.2
 Use Case Document

Notice: The Company Confidential label signifies that the information in this document is
confidential and proprietary to UniversalPay, and is only intended for use by merchant customers of
UniversalPay, internal staff, and authorised business partners of UniversalPay.
This document is protected by copyright restricting its use, replication in any format, and distribution.
No part of this document may be reproduced in any form by any means without the express
permission of UniversalPay.
UniversalPay reserves the right to amend, delete or add to the contents of the document, at any
time, and to make improvements and/or changes to the products and/or programmes described in
this document.
Every reasonable attempt will be made to ensure that the contents of the document are accurate,
and a true reflection of the products and programmes described herein. However, UniversalPay will
not be held liable for any inaccuracies of any nature, however communicated by UniversalPay.
UniversalPay and other trademarks are trademarks or registered trademarks of their respective
owners.
All other product names mentioned in this document are the trademarks of their respective owners.
© UniversalPay 2018

© UniversalPay Page 2 of 10 22/01/2018

Confidential Version 1.2
 Use Case Document
Document Control
Version Control
Version Date Author Description of Change
0.1 22/01/17 Blair Avellino Initial draft
0.2 24/01/17 Blair Avellino Review of changes
1.0 25/01/17 Blair Avellino Version for Release
1.1 01/03/18 Jean Carl Grech Revised Release for Pay-Per-Use Recurring Payments
1.2 08/03/18 Jean Carl Grech Added Simple Examples

© UniversalPay Page 3 of 10 22/01/2018

Confidential Version 1.2
 Use Case Document
Contents
Document Control .......................................................................................................................................................... 3
Version Control ........................................................................................................................................................... 3
Contents........................................................................................................................................................................... 4
1. Introduction .............................................................................................................................................................. 5
1.1. Document Purpose ........................................................................................................................................ 5
1.2. Assumptions .................................................................................................................................................... 5
2. Typical Scenario for Pay-Per-Use Recurring Payments .................................................................................. 6
3. Use Case Diagram ............................................................................................................................................... 10

© UniversalPay Page 4 of 10 22/01/2018

Confidential Version 1.2
 Use Case Document
1. Introduction
1.1. Document Purpose
The purpose of this document is to outline the necessary process that is required to be performed by
merchants to implement the first customer authorisation with 3D Secure on the hosted payment page, as well
as to enable merchants to store the card tokens and customer IDs to self-initiate pay-per-use recurring
payments without the customer’s intervention.

1.2. Assumptions
In this document it is assumed that merchants will handle the scheduling of the recurring payments.
It is also assumed that the merchant is referring to the UniversalPay API Specification Document Version
2.0 for integration.
It is also assumed that merchants will take the first customer authorisation via the hosted payment pages –
using channel ECOM with 3D Secure Authentication.
It is also assumed that after the first customer authorisation the merchants will store the card token in relation
to the customer ID for subsequent pay-per-use recurring payments.
It is also assumed that merchants will perform the subsequent recurring payments for the same customer via
Server-Server HTTP Requests to the UniversalPay API using the card token provided after the completion
of the first transaction.

© UniversalPay Page 5 of 10 22/01/2018

Confidential Version 1.2
 Use Case Document
2. Typical Scenario for Pay-Per-Use Recurring Payments
Procedures:
1. The merchant will take the first payment directly from the customer via the hosted payment page using
the ECOM channel and applying full 3D Secure Authentication and CVV (Section 2.1 on the API
Specification) – this is basic example of integration and further fields are available for
implementation on UniversalPay API Specification Document Version 2.0.

Standard Example:
1) Session Token Request (Server-Server HTTP POST call from Merchant Web-Service):
(ECOM Channel, with CVV and with 3D Secure)

POST https://api.test.universalpay.es/token
POST data:
merchantId={Merchant_ID}&action=PURCHASE&password={API_Password}&allowOriginUrl=
{Server_URL}&timestamp={Milliseconds}&channel=ECOM&amount=10&currency=EUR&countr
y=ES&merchantNotificationUrl={Listener_URL}&merchantLandingPageUrl={Web_URL}&bra
ndId={Brand_ID}&specinProcessWithoutCvv2=false&forceSecurePayment=true

2) Session Token Response:

{"result":"success","resultId":"97d8a6fb-834d-4c79-b4a2-
42b0a8a1a89b","merchantId":"{Merchant_ID}&","additionalDetails":{},"processingTi
me":5,"token":"{Session_Token}"}

3) Load Hosted Payment Page Request:

i. Example1 – Redirection Based Integration:
(Input Merchant_ID and Session_Token provided in the previous call)
<!DOCTYPE html>
<html><head>
<script type="text/javascript">
window.onerror = function myErrorHandler (errorMsg, url, lineNumber) {
alert ("Error occured: " + errorMsg + "\nurl: "+ url + "\nline: " + lineNumber); return false;
}
</script>
<style>
label {
width: 10em;
display: inline-block;
margin: 0 0 0.5em 0;
}
input {
width: 15em;
}
</style>
</head>
<body>
<h3>Redirection example</h3>

© UniversalPay Page 6 of 10 22/01/2018

Confidential Version 1.2
 Use Case Document
<h4>redirectedFullWindow</h4>
<form method="get" action="https://cashierui.test.universalpay.es/ui/cashier">
<label>token:</label><input name="token"/><br/>
<label>merchantId:</label><input name="merchantId"/><br/>
<label>paymentSolutionId:</label><input name="paymentSolutionId" value="500"/><br/>
<input type="hidden" name="integrationMode" value="standalone"/>
<button type="submit" >Pay </button>
</form>
</body>
</html>

ii. Example 2: JavaScript Integration:

(Input Merchant_ID and Session_Token provided in the previous call)
<!DOCTYPE html>
<html><head>
<style>
#ipgCashierDiv{
width: 600px;
height: 400px;
border: 1px solid gray;
margin: 10px;
}
label {
width: 10em;
display: inline-block;
margin: 0 0 0.5em 0;
}
input {
width: 15em;
}
</style>
<script>document.write ('<script src="https://cashierui.test.universalpay.es/js/api.js?ts=' + Date.now
() + '"\><\/script>');</script>
<script type="text/javascript">
var cashier = com.myriadpayments.api.cashier();
cashier.init (
{ baseUrl:'https://cashierui.test.universalpay.es/ui/cashier' }
);
function handleResult (data){
alert (JSON.stringify (data));
}
function pay (){
var token = document.getElementById ("tokenIn").value;
var merchantId = document.getElementById ("merchantIdIn").value;
cashier.show (
{
containerId:"ipgCashierDiv",
merchantId: merchantId,
token:token,
successCallback: handleResult,
failureCallback: handleResult,
cancelCallback: handleResult,
© UniversalPay Page 7 of 10 22/01/2018
Confidential Version 1.2
 Use Case Document
styleSheetUrl: "/cashier/css/optional-customisation.css"
}
);
};
</script>
</head>
<body>
<h3>Simple Javascript integration example</h3>
<h4>simpleJsIntegration</h4>
<div>
<label>token:</label><input id="tokenIn"/><br/>
<label>merchantId:</label><input id="merchantIdIn"/><br/>
<button onclick="pay ()">Pay</button>
</div>
<div id="ipgCashierDiv"></div>
</body>
</html>

4) Result Call to Merchant Notification URL:

At the end of the above payment – if the merchant would have provided the merchantNotificationUrl
parameter in the Session Token Request, the UniversalPay gateway will post a transaction result call
with the following elements:

POST http://{Merchant_Notification_URL}
POST data:
acquirer=UniversalPay&acquirerAmount=10.00&acquirerCurrency=EUR&acquirerTxId=F72DF1
CF3CF7463DAFFE1C4FD18A3B51&action=PURCHASE&amount=10.00&brandId={Brand_ID}&country=
ES&currency=EUR&customerId={Customer_ID}&merchantId={Merchant_ID}&merchantTxId=lnwx
P5ap0UnGeKV8x0ts&pan=3674506345311111&paymentSolutionDetails=authCode%3DApprov&paym
entSolutionId=500&status=CAPTURED&txId=11543444

The merchant needs to store the pan (card token), and the customerId parameter to which it is related
to perform subsequent transactions without the intervention of the customer.

© UniversalPay Page 8 of 10 22/01/2018

Confidential Version 1.2
 Use Case Document

2. Subsequent Pay-Per-Use Server to Server Requests (HTTP POST Form)

Depending on when merchant wants to take the next payment – either monthly, weekly, ad-hoc, etc.., the
merchant would need to take a further payment from the same customerId using the card token stored
(from the pan field) – but initiated automatically from the merchant’s web-service.

Standard Example:

1) Session Token Request (Server-Server HTTP POST call from Merchant Web-Service):
(MOTO Channel, without CVV and without 3D Secure)
POST https://api.test.universalpay.es/token
POST data:
merchantId={Merchant_ID}&action=PURCHASE&password={API_Password}&allowOriginUrl={Se
rver_URL}&timestamp={Milliseconds}&channel=MOTO&amount=20&currency=EUR&country=ES&p
aymentSolutionId=500&specinCreditCardToken={pan}&customerId={Customer_ID}&brandId={
Brand_ID}&merchantNotificationUrl={Listener_URL}&specinProcessWithoutCvv2=true&forc
eSecurePayment=false

2) Session Token Response:

{"result":"success","resultId":"3ec5a53b-1f58-47be-b60e-
89af95575a72","merchantId":"{Merchant_ID}&","additionalDetails":{},"processingTime"
:15,"token":"{Session_Token}&"}

Then submit the confirmation of the payment using the session token obtained in the previous request
without the CVV. (Section 6.9 on the API Specification).

3) Confirm Payment Request (Server-Server HTTP POST call from Merchant Web-Service):
POST https://api.test.universalpay.es/payments
POST data:
token={Session_Token}&merchantId={Merchant_ID}

4) Confirm Payment Response:

{"amount":"20","resultId":"7d5466d6-b169-401d-b959-
2212420efb2f","merchantLandingPageUrl":null,"acquirerTxId":"F92EEFB512BA454684AE613
41885944E","txId":"11543461","language":null,"paymentSolutionDetails":{"authCode":"
8IU7BK"},"additionalDetails":{},"acquirerAmount":null,"processingTime":2675,"result
":"success","merchantId":"400006","brandId":"400006000","freeText":null,"merchantTx
Id":"jmkJciAshBSPNInN2hl1","customerId":"IPG864497","acquirerCurrency":null,"action
":"PURCHASE","paymentSolutionId":"500","currency":"EUR","pan":"8562201006531111","e
rrors":null}

5) Merchant Notification:
If the merchant would have provided the merchantNotificationUrl parameter in the Session Token
Request, the UniversalPay gateway will post a transaction result call as described on point 4, page 8 on
this document.

© UniversalPay Page 9 of 10 22/01/2018

Confidential Version 1.2
 Use Case Document
3. Use Case Diagram

UniversalPay
Customer Merchant Gateway

Session Token request with

Checkout Notification URL

Session Token

Hosted Page
request

Display hosted page Hosted Page

Fill in Card Details

(Number, CVV, Expiry date), 3D Secure and confirm

Result
Call

Display Result Page

Recurring Payment
Session Token Request, Customer ID,
Card Token, no CVV

Session Token

Confirm Payment

Response

© UniversalPay Page 10 of 10 22/01/2018

Confidential Version 1.2