You are on page 1of 12

IONPay System Development

SYSTEM

Merchant integration

Write Date

2012.08.23

TASK

Document

Version

1.0

PHP Version

2012-08-23

IONPay System Development


SYSTEM

Merchant integration

Write Date

2012.08.23

TASK

Document

Version

1.0

Table of Contents
IonPay PG Integration Guide................................................................................................................................................ 1
I.

Preparation ......................................................................................................................................................................... 3
1.

Merchant Registration ........................................................................................................................................... 3

2.

Select Payment Method ....................................................................................................................................... 3

3.

Files provided............................................................................................................................................................ 3

II.

Merchant Back-Office ..................................................................................................................................................... 4

III.

Payment Flow .................................................................................................................................................................... 5

IV.

Payment Steps and Implementation ....................................................................................................................... 6

V.

1.

Payment Request / Choose Payment Method ........................................................................................... 6

2.

Register Transaction Data .................................................................................................................................... 6

3.

Payment URL Open ................................................................................................................................................ 6

4.

Payment Processing ............................................................................................................................................... 6

5.

Return URL Open .................................................................................................................................................... 6

6.

Payment Result Query .......................................................................................................................................... 6

7.

Payment Result......................................................................................................................................................... 6

API (PHP) ............................................................................................................................................................................. 7

VI. Sample (PHP) .................................................................................................................................................................. 11

IONPay System Development


SYSTEM

Merchant integration

Write Date

2012.08.23

TASK

Document

Version

1.0

I. Preparation
1.

Merchant Registration
Before using IonPay Payment Gateway System, Merchant should register IonPay PG
Service. Contact IonPay representative.

File

Description

MID

Merchant ID

Merchant Key File

Key File for Transaction Message


Authentication

2.

Merchant Admin ID

Merchant Back-Office Login ID

Merchant Admin Password

Merchant Back-Office Login Password

Select Payment Method


During Merchant registration, Merchant should select supported Payment Methods.
IonPay prepare settings for each selected Payment Methods

Payment Method ID

Description

Credit Card (MiGS)

Credit Card (IonPay)


(under construction)

ClickPay Mandiri

ATM Mandiri
(under construction)

3.

Files provided

File

Description

ionpay.php

Payment module

mall-sample.php

Sample files

payment.php
payment-result.php
IonPay PG Guider - PHP.pdf

Documentation (this document)

IONPay System Development


SYSTEM

Merchant integration

Write Date

2012.08.23

TASK

Document

Version

1.0

MerchantID.key

Merchant Key File

II. Merchant Back-Office


URL

https://bo.ionpay.net/IonPayBO/

Merchant can login Merchant Back-Office site (above URL) using Merchant Admin ID and
password issued by IonPay.
Refer Merchant Back-Office User's Guide.

IONPay System Development


SYSTEM

Merchant integration

Write Date

2012.08.23

TASK

Document

Version

1.0

III. Payment Flow

User Browser

Merchant

IonPay PG

1. Payment Request
(Select Payment Method)

2. Register Transaction Data

3. Payment URL open

4. Payment Processing

5. Return URL Open

6. Payment Result Query

7. Payment Result

IONPay System Development


SYSTEM

Merchant integration

Write Date

2012.08.23

TASK

Document

Version

1.0

IV. Payment Steps and Implementation


1.

Payment Request / Choose Payment Method

In Merchant implementation, selecting Payment Method is the first step for payment.
2.

Register Transaction Data

The payment page implements following steps:


IonPay object creation
Setting Transaction data
Call Payment() function
Processing Result
The result contains TID (Transaction ID) and Payment URL if succeeded.
3.

Payment URL Open

Open Payment URL in user browser.


4.

Payment Processing

Customer do payment processing in corresponding payment method UI.


Merchant waits completing payment.

5.

Return URL Open

After completed or canceled IonPay PG open Return URL via user browser.
6.

Payment Result Query

In Return URL implementation, Merchant query Payment Result from IonPay PG and do matching
action for the result.
7.

Payment Result

Complered Payment.
6

IONPay System Development


SYSTEM

Merchant integration

Write Date

2012.08.23

TASK

Document

Version

1.0

V. API (PHP)
IonPay(MID, merchantKeyFilePath)
Description

IonPay class construct


MID

Merchant ID

merchantKeyFilePath

Merchant Key File Path

Parameters

Return Value

IonPay class object

Set(name, value)
Description

Set request values


name

Item name

value

Item value

Parameters

Return Value

none

Before Payment Register, Merchant should set below name, value pairs.

name

value

invoiceNo

Unique ID in Merchant domain

currencyCode

Currency Code
Set 320 for IDR

paymentMethod

Payment Method Number

amount

Total Amount for Payment

returnUrl

Merchant URL for completed Payment

callbackUrl

Merchant Callback URL


Callback URL is opened by IonPay PG Service
when Payment Status changed some reason.
So callback URL should not have UI.

option

If Merchant uses popup window for Payment


UI, should setting "popup" value for closing
popup window after completed.
7

IONPay System Development


SYSTEM

Merchant integration

Write Date

2012.08.23

TASK

Document

Version

1.0

customerFirstName

Customer First Name

customerLastName

Customer Last Name

customerAddress

Customer Address

customerCity

Customer City

customerCountry

Customer Country

customerZipCode

Customer ZIP Code

Before calling PaymentResult(), Merchant should set below name, value pairs.

name

Value

invoiceNo

invoiceNo for Payment query

tid

Transaction ID issued by IonPay for corresponding


Payment

AddOrder(description, quantity, subTotal)


Set ordered Item
Description

Before Payment Register, Merchant should call for each


ordered item.

Parameters

Return Value

description

Item name description

quantity

Quantity for the item

subTotal

Subtotal price for the item

none

Payment()
Description
Parameters
Return Value

Register Payment Transaction


none
True if call success, otherwise false
Success do not mean paid properly, it means no error for calling.

When Payment() function call, IonPay object send request transaction to IonPay PG Server with
values set by Merchant. IonPay PG register payment transaction and issue Transactio ID then send
8

IONPay System Development


SYSTEM

Merchant integration

Write Date

2012.08.23

TASK

Document

Version

1.0

reply to IonPay Object.

Response_Code()
Description
Parameters
Return Value

Response Code from IonPay PG


none
"0000" for no error
Otherwise some error occurs

Response_Msg()
Description
Parameters
Return Value

Response Code from IonPay PG


none
"OK" for no error
Otherwise return human readable error message

Get(name)
Description

Get Response value from IonPay PG

Parameters

name

Item name

Return Value

Response value for name

After Payment Register, Merchant can query below items.

name
url

Value
Payment URL for corresponding payment
Merchant should open this URL for payment.
This URL shows UI for each Payment Method.

tid

Transaction

ID

issued

by

IonPay

for

corresponding Payment
9

IONPay System Development


SYSTEM

Merchant integration

Write Date

2012.08.23

TASK

Document

Version

1.0

After Payment completed, Merchant can query below items.

name

Value

status

Payment Status for corresponding Transaction

resultCode

Payment Transaction Result Code from each


Transaction Method

resultMessage

Payment Transaction Result Message from


each Transaction Method

fraudDecision

The result of Fraud Check

fraudReasonCode

The Reason Code from Fraud Check

fraudReasonMessage

The Reason Message from Fraud Check

Status Code is one of below values:

Status value

Meaning

ok

Payment OK (Paid completed)

init

Payment Canceled

cancel
fail

Payment Failed

wait

Payment Completed but wait Transfer money


(Used Asynchronous Payment Method such as
ATM Mandiri)

Void

Payment Voided

refund

Payment Refunded

PaymentResult()
Description
Parameters

Query Payment Result


none
True if call success, otherwise false

Return Value

Success do not mean paid properly, it means


no error for calling.

10

IONPay System Development


SYSTEM

Merchant integration

Write Date

2012.08.23

TASK

Document

Version

1.0

Query Payment Result in Return URL or Callback URL implementation

VI. Sample (PHP)


1. Payment Request
payment.php
<?php
require_once("ionpay.php");
$ionpay = new IonPay("TESTMALL", "C:\\APM_Setup\\testmall.key");
$ionpay->Set("invoiceNo", $_POST['invoiceNo']);
$ionpay->Set("currencyCode", 320);
$ionpay->Set("amount", $_POST['amount']);
$ionpay->Set("paymentMethod", $_POST['paymentMethod']);
$ionpay->Set("returnUrl", "http://localhost/payment-result.php?invoiceNo=".$_POST['invoiceNo']);
$ionpay->Set("callbackUrl", "http://localhost/payment-callback.php?invoiceNo=".$_POST['invoiceNo']);
$ionpay->Set("option", "popup");
$ionpay->Set("customerFirstName", "John");
$ionpay->Set("customerLastName", "Doe");
$ionpay->Set("customerAddress", "test address");
$ionpay->Set("customerCity", "Jakarta");
$ionpay->Set("customerCountry", "Indonesia");
$ionpay->Set("customerZipCode", "123456");
for ($i = 1; $i < 4; $i++) {
if ($_POST['desc'.$i] == '')
break;
$ionpay->AddOrder($_POST['desc'.$i], $_POST['quan'.$i], $_POST['subtotal'.$i]);
}
$ionpay->Payment();
if ($ionpay->Response_Code() != 0) {
// error
echo "response code = " . $ionpay->Response_Code() . "<p>";
echo "response msg = " . $ionpay->Response_Msg() . "<p>";
echo "response_json = " . $ionpay->Response_Json() . "<p>";
}
else {
// save TID $ionpay->Get("tid")
header("Location: ". $ionpay->Get("url"));
}

11

IONPay System Development


SYSTEM

Merchant integration

Write Date

2012.08.23

TASK

Document

Version

1.0

unset($ionpay);
?>

2. PaymentResult Query
payment-result.php
<?php
require_once("ionpay.php");
$ionpay = new IonPay("TESTMALL", "C:\\APM_Setup\\testmall.key");
$ionpay->Set("invoiceNo", $_GET['invoiceNo']);
$ionpay->Set("tid", $_POST['TID']);
$ionpay->PaymentResult();
if ($ionpay->Response_Code() != 0) {
// error
echo "response code = " . $ionpay->Response_Code() . "<p>";
echo "response msg = " . $ionpay->Response_Msg() . "<p>";
echo "response_json = " . $ionpay->Response_Json() . "<p>";
}
else {
echo "invoiceNo = " . $_GET['invoiceNo'] . "<p>";
echo "tid = " . $_POST['TID'] . "<p>";
echo "result = " . $ionpay->Get("resultCode") . "<p>";
}
unset($ionpay);
?>

12