UniPinPaymebnt Gateway

Technical Document

UniPin Payment Gateway

Technical Document
Version 2.0

UniPinPaymebnt Gateway

Technical Document

Contents
Overview ................................................................................................................................................. 3
UniPin Express..................................................................................................................................... 4
UniPin Wallet ...................................................................................................................................... 5
Payment Flow ......................................................................................................................................... 6
Transaction Initiation: Step 1 .............................................................................................................. 7
Transaction Initiation: Step 2 .............................................................................................................. 8
Transaction Initiation: Step 3 ............................................................................................................ 11
Transaction Initiation: Step 4 ............................................................................................................ 11
Transaction Fulfillment: Step 5 ......................................................................................................... 12
Transaction Fulfillment: Step 6 ......................................................................................................... 12
Transaction Fulfillment: Step 7 ......................................................................................................... 12
Transaction Fulfillment: Step 8 ......................................................................................................... 12
Asynchronous Acknowledgement: Step 9 ........................................................................................ 14

UniPinPaymebnt Gateway

Technical Document

Overview
UniPin payment service allows game publishers to monetize virtual goods and services into legal
local currency.
It offers partners with complete flexibility to price goods at any amount, yet providing fast and
secure transaction process.
UniBox are presented in HTML widget. Partners may choose to embed the widget using a HTML
dialog in their website.
Alternatively, partners may also choose to display UniBox in a browser pop up window. Partners may
use any of these methods whichever fits.
UniPin payment service offers two types of payment methods.
UniPin Express
UniPin Wallet

Desktop

Mobile

UniBox will automatically detects client platform and presents proper UI

accordingly. Depends on the payment amount requested, UniPin Express may
not be available.

Although UniBox runs on both PC and mobile platforms, it is UniPin company

policy that we require partners to use seperate merchant account for PC and
Mobile platforms respectively.
Partners are required to inform UniPin if they wish to deploy UniPin payment
channel on mobile platform.

UniPinPaymebnt Gateway

Technical Document

UniPin Express
UniPin Express offers gamers with a faster check out process. Using UniPin Express, gamers can
reload to their preferred in-game currency without having to signupanUniPin account, UniPass. After
obtaining a UniPin voucher from any Indomaret Convenient Store nationwide in Indonesia, gamers
will then enter the Serial and PIN code printed on the voucher in the UI presented below. After
submitting the request, the transaction will be processed and instantaneous result will be returned.
Transaction is completed in one click.

Desktop

Mobile

AltoughUniPin Express offers a faster and more convenient way to check out,UniPin Express does
present a few limitations. All UniPin Express transactions amount are consumed in full. If gamers
reload with UniPin Express using a RP10,000 voucher, once the transaction is complete, the entire
amount is consumed. No balance of the voucher will be kept. Thus, it is advisable for partners to
revise pricing strategy to match the amounts supported by UniPin Express.
UniPin Express supports the following denominations:
RP10,000
RP20,000
RP50,000
RP100,000
RP300,000
RP500,000
Upon UniBox initialization, UniPin Express will check the amounts requested by partner. If any
amounts match up with one or more denominations supported by UniPin Express, gamers will then
be given the option to pay by UniPin Express. If non of the amounts match up, then UniPin Express
will be skipped, in this case, UniPin Wallet will be presented directly.

UniPinPaymebnt Gateway

Technical Document

UniPin Wallet
UniPin Wallet offers gamers with the flexibility to pay with any amount requested. Before using
UniPin Wallet, gamers need to sign up an user account at www.unipin.co.id/registration. In order to
perform transaction using UniPin Wallet, gamers must have enough UniPin Credits (UC) balance in
their account. Gamers can reload UniPin Credits using any of the payment channels available,
including Online banking, ATM transfer, SMS, Mobile payment as well as UniPin voucher.

Desktop

Mobile

There is a Unipass associated with each merchant account in UniPin system.

UniPin will provide free UniPin Credits only to this special account for testing purpose.
You may find the Unipass login name in the Home page of this administrative portal.

UniPinPaymebnt Gateway

Technical Document

Payment Flow
In a normal UniPin transaction, it involve three parties:
Gamers (Client Web Browser)
Developer
UniPin
Take a look at the diagram below and understand the sequence of progressing with a transaction.
Take note of the processes involved in eash step and information required and generated.

Transaction Initiation

1. Gamers click on top up link on game site. The request is sent to developer's server.
2. Developer's server constructs a JSON object and send to UniPin using HTTP POST.
3. UniPin replies with JSON object. Developer's server decode the JSON object and
obtain a URL to UniBox and other transaction information.
4. Developer's server should then perform a redirect at client browser using the
UniBox URL obtained in Step 3.
Transaction Fulfillment 5. Client performs transaction on UniBox, either using UniPin Express or UniPin
Wallet. Confirmation is sent directly from client browser to UniPin.
6. UniPin returns a transaction receipt to client browser. At the receipt page, UniBox
will attempt to callback a Javascript function if the function is defined at the parent
page. Transaction result will be passed into the function.
Beside Javascriptcallback, UniPin will also send an asynchronous notification to
developer server in a seperate connection. This notification is sent in background
without interrupting the communication with client browser.
The parent page is provided by developer to embed UniBox as HTML dialog, or,
parent page of UniBox pop up window.
7. Optional. Upon receiving the callback, developer could write Javascript code to
send the transaction result back to developer's server. Developer is advised NOT
TO rely on this method of getting transaction result. Client to Server
communication is unreliable, because the user might close the browser before the
callback could be sent.
8. Upon getting the Javascriptcallback, client browser could then do a refresh or
direct to a result page designed by developer.
Asynchronous
9. For every completed transaction, developer's server will get a notification from
Acknowledgement
UniPin in a seperate connection. Developer should treat this notification as final
and most reliable acknowledgement of the transaction.
UniPin will only send out notification on successful and completed transaction.
A notification may be delayed for few seconds.
10. Optional. Developer may continue further communication with client brower at
will.

UniPinPaymebnt Gateway

Technical Document

Transaction Initiation: Step 1

A UniPin transaction starts at developer's game reload page. Gamers click on "Reload WithUniPin"
link. The link shall send a HTTP request back to developer's server. The HTML code sample below
illustrate how developer could achieve this.
<link rel="stylesheet" href="/css/thickbox.css" type="text/css" media="screen"/>
<script type="text/javascript" src="/js/jquery/jquery-1.3.2.min.js"></script>
<script type="text/javascript" src="/js/thickbox.js"></script>

<div>UniBox</div>
<br />
<div>
<!-- ---------- UNIBOX ---------- -->
<a href="http://www.example.com/unipin?TB_iframe=true&height=550&width=600"
title="UniBox"
class="thickbox style1">UniPin Reload (Dialog)</a>
<!-- ---------- UNIBOX ---------- -->
</div>
<br />
<div>
<a href="http://www.example.com/unipin" target="_blank">UniPin Reload (Pop UP)</a>
</div>

The first <a> tag is to open UniBox in HTML dialog. To use this feature, you must include the above
Javascript and CSS. You could download them below.
thickbox.css
jquery-1.3.2.min.js
thickbox.js
The second <a> tag is to open UniBox in a browser pop up.

UniPinPaymebnt Gateway

Technical Document

Transaction Initiation: Step 2

On developer's server, there should be a resource /unipin located in the file system to process the
request. In this resource, the developer shall send a JSON object to UniPin server using HTTP POST.
The PHP code below shows a simple example of how to achieve this.
$szSecretKey = "YOUR_SECRET_KEY";
$mapMerchant = array();
$mapMerchant["guid"]
= "YOUR_GUID";
$mapMerchant["reference"]
= "user@example.com";
$mapMerchant["message"]
= "Hello UniPin, Welcome\\nLine 2\\nLine 3";
$mapMerchant["urlAck"] = "http://www.example.com/unipin/notification";
$mapMerchant["urlReturn"]
= "http://www.example.com/unipin/return";
$grDenom =
$grDenom[]
$grDenom[]
$grDenom[]
$grDenom[]
$grDenom[]
$grDenom[]

array();
= array("amount"
= array("amount"
= array("amount"
= array("amount"
= array("amount"
= array("amount"

=>
=>
=>
=>
=>
=>

10000, "description" => "10,000 Chips");

20000, "description" => "20,000 Chips");
50000, "description" => "50,000 Chips");
100000, "description" => "100,000 Chips");
300000, "description" => "300,000 Chips");
500000, "description" => "500,000 Chips");

$hashIn = "";
foreach ($mapMerchant as $val)
$hashIn .= $val;
foreach ($grDenom as $eleDenom)
$hashIn .= $eleDenom["amount"] . $eleDenom["description"];
$hashIn .= $szSecretKey;
$hashOut = md5($hashIn);
$mapJson = array();
$mapJson["merchant"]
$mapJson["denominations"]
$mapJson["signature"]

= $mapMerchant;
= $grDenom;
= $hashOut;

$szJson = json_encode($mapJson);
$fpHttp = curl_init("https://payment.unipin.co.id/unibox/new");
curl_setopt($fpHttp, CURLOPT_POST, 1);
curl_setopt($fpHttp, CURLOPT_HTTPHEADER, array("Content-Type:
application/json"));
curl_setopt($fpHttp, CURLOPT_POSTFIELDS, $szJson);
curl_setopt($fpHttp, CURLOPT_RETURNTRANSFER, 1);
$jsonResult = curl_exec($fpHttp);
curl_close($fpHttp);
$jsnResult = json_decode($jsonResult, true);
if ($jsnResult["status"] != "0")
{
echo var_dump($jsnResult);
return;
}
$this->_redirect($jsnResult["url"]);

UniPinPaymebnt Gateway

Technical Document

The PHP code above will effectively send a JSON object that look like this to UniPin. The URL to POST
the JSON object:
https://payment.unipin.co.id/unibox/new
{

"merchant":
{
"guid"
:"YOUR_GUID",
"reference"
:"user@example.com",
"message"
:"Hello UniPin, Welcome\\nLine 2\\nLine 3",
"urlAck":"http:\/\/www.example.com\/unipin\/notification",
"urlReturn"
:"http:\/\/www.example.com\/unipin\/return"
},
"denominations":
[
{
"amount"
:10000,
"description" :"10,000 Chips"
},
{
"amount"
:20000,
"description" :"20,000 Chips"
},
{
"amount"
:50000,
"description" :"50,000 Chips"
},
{
"amount"
:100000,
"description" :"100,000 Chips"
},
{
"amount"
:300000,
"description" :"300,000 Chips"
},
{
"amount"
:500000,
"description" :"500,000 Chips"
}
],
"signature":"c7c5f2f8c6d18db49f62f0e6e1c505c1"

UniPinPaymebnt Gateway
Parameter

guid

reference

Technical Document

Description
Your unique GUID, given by UniPin. You may find the GUID in the
Home page of this administrative portal.

Your transaction reference.

If your transaction reference is unique (eg: PO number, record
number, etc) throughout your billing system, it is your responsibility
to supply a non-duplicated reference. UniPin system will not check
for duplicated reference.

!
message

During development phase, you will be given a Development GUID. All

transactions generated using this GUID will not be included in final
sales
report.
After development phase is fully tested and ready to publish, you will
then be given a Production GUID. You shall use the Production GUID
for all real live transactions.

In the event that duplicated reference is supplied, developers are

advised to process only the first reference occurrence.

You may supply a short message to be displayed in UniBox. A

maximum of 256 characters, in 3 lines are allowed. Use \\nto specify
a new line character. You may use this to deliver a short message to
your VIP users, eg: special pricing, etc.

You must not specify any advertisement text at all, including hyperlink
and images. All html tags will be stripped off from the text. All
submitted text are kept and logged for future audit.

urlAck
urlReturn

The URL where UniPin shall send the background notification to.
Reserved for further use.
The denominations is an array of amount:descriptionkey value
pair. These amount array will be listed in UniBox to show the users
about items pricing.
In order to utilize UniPin Express, you must match the amount to at
least one or more UniPin Express denominations. UniPin Express
supports the following denominations:
denominations
RP10,000
[amount:description]
RP20,000
RP50,000
RP100,000
RP300,000
RP500,000

signature

The signature is calculated by concatenating all the "values in

appearing sequence" + secret key in the JSON object. secret
keyis given by UniPin. You may find the secret keyin the Home
page of this administrative portal. Run the concatenated string
through MD5 function to get the signature.

10

UniPinPaymebnt Gateway

Technical Document

Transaction Initiation: Step 3

If UniPin successfully parse the incoming JSON object, the following JSON object will be returned.
{
"status"
"message"
"url"
270764f75fb6387",
"signature"
"payload"
}

:0,
:"Success",
:"https:\/\/payment.unipin.co.id\/v2\/unibox\/index\/9
:"ebdd50a750c7b4829edbb766aa8e6b3b",
:"c0cc0c2d17e25ac4fe317e223a374273ce7ad2............"

Parameter
status
message
url

signature

payload

Description
Status code of new generated transaction.
0 indicates no error.
<0indicates error.
Message correspond to the status code.
The URL that you need to redirect the client browser
to display UniBox.
The pattern of this URL may change from time to
time.
MD5 hash result of concatenating all the "value" +
secret keyin the JSON object.
A TripleDES encrypted JSON object in ECB mode
using your secret key.
After decrypting this value, you should get back the
same JSON object with these key-values:
status, message, url, signature
Although not required, you are encouraged to
double check the values in plain JSON and encrypted
JSON for value tempering. You may use these online
tools to test your decrypting function:
http://tripledes.online-domain-tools.com/
http://www.tools4noobs.com/online_tools/decrypt/

Transaction Initiation: Step4

With the returned JSON object from UniPin, redirect client browser using the URL obtained from the
JSON object.

11

UniPinPaymebnt Gateway

Technical Document

Transaction Fulfillment: Step5

Gamers will perform transaction on UniBox, given UniPin Express or UniPin Wallet.

Transaction Fulfillment: Step6

After the transaction is completed, a receipt page will be displayed in UniBox.

Transaction Fulfillment: Step7

Upon receiving the Javascriptcallback, you may also post the transaction result back to developer's
server for record keeping purpose. This step is optional and it is not enforced by UniPin. Further
more, you should not rely solely on this callback to post the result back to developer's server, since
users may close the brower or the connection is interrupted before a callback can take place.

Transaction Fulfillment: Step8

When UniBox display the receipt page, it will attempt to sent transaction result to parent page. To
receive transaction result in Javascript, you must do one of the following:
If you open UniBox using ThickBox Dialog, you must, in addition, define the function
registerUniBoxDialog().This
function
should
then
execute
window.addEventListener()that listens for postMessage()event.
If you open UniBox usingiframethat is embeded in your reload page, then you need to execute
window.addEventListner()to listen for posted message.
If you open UniBox using browser pop up, then
window.addEventListner()to listen for posted message.

you

need

to

execute

Below shows a sample Javascript to receive the transaction result. _unipinResultJavascript

object containing information of transaction outcome will be passed. You can see the available
object attributes from the sample code below.
varm_pInterval = null;
// When open UniBox in ThickBox, you must define "registerUniBoxDialog()"
function that in turn call "window.addEventListener()".
// When open UniBox in Iframe, you must call "window.addEventListener()"
upon page loaded.
// When open UniBox in browser popup, you must call
"window.addEventListener()" upon page loaded.
// Call "window.addEventListener()" if UniBox is opened using Iframe or
browser popup
window.addEventListener("message", function(e) { postMessageHandler(e); },
false);
// This function is only needed if UniBox is opened using ThickBox
function registerUniBoxDialog()
{
window.addEventListener("message", function(e)

12

UniPinPaymebnt Gateway

Technical Document

{ postMessageHandler(e); }, false);
}
function postMessageHandler(e)
{
if (e.origin != "https://payment.unipin.co.id")
return;
unipinCallback(e.data);
}
function unipinCallback(_unipinResult)
{
console.log(_unipinResult.status);
console.log(_unipinResult.type);
console.log(_unipinResult.amount);
console.log(_unipinResult.trxNo);
console.log(_unipinResult.reference);
console.log(_unipinResult.message);
document.getElementById("lblStatus").innerHTML
=
_unipinResult.status;
document.getElementById("lblType").innerHTML = _unipinResult.type;
document.getElementById("lblAmount").innerHTML
=
_unipinResult.amount;
document.getElementById("lblTrxNo").innerHTML = _unipinResult.trxNo;
document.getElementById("lblReference").innerHTML= _unipinResult.reference;
document.getElementById("lblDescription").innerHTML= _unipinResult.message;
m_pInterval = setInterval(timeOut, 10000);
}

// Timout in 10 seconds

function timeOut()
{
clearInterval(m_pInterval);
varpDlg = document.getElementById("TB_closeWindowButton");
if (pDlg)
pDlg.click();
eleDiv = document.getElementById("divUniPinCallback");
eleDiv.style.display = "block";
}

In postMessageHandler()function, you should check the e.originattribute and make sure

the data is posted from https://payment.unipin.co.id.
The timeOut()function is to delay the closure of UniBox. This is because UniBox displays a
transaction receipt, and we shall allow the user to read through it.

The Javascriptcallback is performed mainly to provide a fast response to gamers on client

browser. Although you can, but you should not rely on this callback to update transaction record
at developer's server.
Please see Step 9 for reliable and final transaction notification from UniPin.

13

UniPinPaymebnt Gateway

Technical Document

Asynchronous Acknowledgement: Step9

Upon receiving transaction confirmation from UniBox, UniPin system will schedule a notification to
be sent to developer's server. The notification would be sent to developer's server within few
seconds time. The target URL the notification UniPin will sent to is specified by you in Step 2
urlAck parameter.
For a transaction to be rendered as successful, this URL must at least return HTTP status 200.
If HTTP status 404 (Not Found) is returned, the notification will stop immediately and the transaction
is rendered as fail.
If other HTTP status code is returned, UniPin will keep trying to send the notification:
every 30 seconds for 30 minutes, then
every 60 seconds for 1 hour, then
every 1 hour for 24 hours, then
notification will stop and transaction is rendered fail.

Failed transactions will not be included in monthly sales report.

Below is a sample JSON object which UniPin will send using HTTP POST.
{
"merchant":
{
"guid"
:"YOUR_GUID",
"name"
:"Example",
"url"
:"http:\/\/www.example.com\/unipin\/notification"
},
"transaction":
{
"status"
:0,
"amount"
:10000,
"type"
:"EXPRESS",
"currency"
:"IDR",
"message"
:"IDMB1S00000000 | user@exmaple.com | 10,000
Chips",
"trxNo"
"time"
"reference"
"item"

:"S201400367413",
:1389906321,
:"user@example.com",
:"10,000 Chips"

},
"signature"
:"983674221a17e0c61601e885f0b6b282",
"payload"
:"0e7e6b81bb70c017d929ee7e196a144a7bf............."

14

UniPinPaymebnt Gateway
Parameter
guid

Description
Your unique GUID, given by UniPin. You may find the GUID in the Home page of this
administrative portal.

i
name
url

status

amount

type

Technical Document

During development phase, you will be given a Development GUID. All transactions
generated using this GUID will not be included in final sales report.
After development phase is fully tested and ready to publish, you will then be given a
Production GUID. You shall use the Production GUID for all real live transactions.

Merchant name registered with UniPin. Please contact UniPin if the nameis
incorrect.
The URL which this notification is sent to.
UniPin transaction status.
0 indicates no error.
<0indicates error.
In normal circumstances, UniPin will not send notification if user cancel the
transaction, or user did not complete the transaction.
Amount of the transaction.
Developers are advised to double check this amount before fullfilling a transaction.
Indicates if the transaction is performed using UniPin Express or UniPin Wallet.
May contains the values of:
EXPRESS
WALLET

currency
message

Currency in which the transaction is carried out. This value is always set to IDR.
Contains the description of the transaction.
UniPin unique transaction number. You need this transaction number to refer to any
trxNo
transaction within UniPin.
time
Unix timestamp which the transaction is performed.
reference Reference string specified by developer when the transaction was initiated.
item
Item description provided by developer when the transaction was initiated.
The signature is calculated by concatenating all the "values in appearing sequence" +
secret keyin the JSON object. secret keyis given by UniPin. You may find the
signature secret keyin the Home page of this administrative portal. Run the concatenated
string through MD5 function to get the signature.

payload

A TripleDES encrypted JSON object in ECB mode using your secret key.
After decrypting this value, you should get back the same JSON object with all the
key-values except payload itself.
Although not required, you are encouraged to double check the values in plain JSON
and encrypted JSON for value tempering. You may use these online tools to test your
decrypting function:
http://tripledes.online-domain-tools.com/
http://www.tools4noobs.com/online_tools/decrypt/

15

UniPinPaymebnt Gateway

Technical Document

Upon receiving the notification, developer must at least return HTTP status code 200.
If for whatever reason the transaction fails at developer side, you could return a JSON object like
below:
{
}

"status"
"message"

Parameter
status
message

:0,
:"Reload Successful."

Description
0 indicates item delivery successful.
<0indicates item delivery failed.
Text message that you wish UniPin to record.

16

UniPinPaymebnt Gateway

Technical Document

-END-

17