ANDROID MOBILE PAYMENT LIBRARY - PaymentOne

tibburfrogtownMobile - Wireless

Dec 14, 2013 (3 years and 10 months ago)

108 views



Last Updated:
June 6, 2012

Page
1

of
29


PayOne Android Library V1.
0













ANDROID

M
OBILE
P
AYMENT
L
IBRARY

D
EVELOPER
G
UIDE
A
ND
R
EFERENCE

V
ERSION
:

1.
0




Last Updated:
June 6, 2012

Page
2

of
29


PayOne Android Library V1.
0



Table of Contents
1.

Preface
................................
................................
................................
................................
.....

3

1.1

Intended Audience

................................
................................
................................
............

3

1.2

OS and Hardware Support

................................
................................
................................

3

1.3

General Information

................................
................................
................................
..........

3

2.

Merchant Service Setup

................................
................................
................................
..........

3

2.1

Basic Merchant Information

................................
................................
.............................

4

2.2

Service Integration with Android Ap
p

................................
................................
.............

4

3

PayOne Android Payments Library

................................
................................
........................

4

3.1

Android Payments Library API Reference

................................
................................
.......

5

Customize Parameters

................................
................................
................................
............

5

3.2

User Permissions needed to enable PayOneHomeActivity

................................
..............

6

3.3

User flow diagram

................................
................................
................................
............

7

4

Android Merchant App Development

................................
................................
....................

8

4.1

Setting up the Android dev environment

................................
................................
..........

8

4.1.1

Adding the P1Library library project in to the Android project

................................
..

8

4.1.2

Declaring the Library and Permissions in AndroidManifest.xml

................................

9

4.2.1

Initialize & create PayOneHomeActivity

................................
................................
..

10

5

Sample Application

................................
................................
................................
...............

10

5.1

Description

................................
................................
................................
......................

10

5.2

Code

Snippets

................................
................................
................................
.................

10

5.3

Sample Application Screen Shots

................................
................................
...................

13

6

Backend I
ntegration

................................
................................
................................
..............

20

6.1

Notification Parameters

................................
................................
................................
..

21

6.2

Notification Callback Response Parameters

................................
................................
...

23

6.3

Example Notification Callbacks

................................
................................
.....................

24

6.4

Daily Transaction File

................................
................................
................................
....

26

6.5

Verifying the Digital Sign
ature

................................
................................
......................

27




Last Updated:
June 6, 2012

Page
3

of
29


PayOne Android Library V1.
0

1.

Preface


The
PayOne

Mobile Payment library provides Android applications an easy way to add
secure, extensible and scalable payment functionality.
This document guides
developers to quickly integrate payment
functionality into their applications, using the
PayOne

SDK for Android.


1.1

Intended Audience

The document is written for merchant Android developers for integrating
PayOne

s
ervices into their applications.


1.2

OS and Hardware Support



The
PayOne

Mobile Payme
nts Library supports all androi
d devices running Android OS
2.1

and higher.


1.3

General Information


Please contact your
PayOne

client service representative for allowed product types and
amounts. Detailed API, integration, and test documents are available on

the
PayOne

test portal:
https://test
-
payconnect.paymentone.com
. To access this portal please
submit the IP address you will use for connectivity to your client services representative.


2.


Merchant S
ervice Setup

To utilize the
PayOne

Payment library
you need to supply your Client Services
Representative with some basic information about your product, pri
ce points, URLs, and
contacts.
You also need to accept
GET

notifications from the
PayOne

servers. T
hese
notifications are sent when a billing event occurs. Please refer to the Backend
Integration Section 6.1 for more details.


XML files are also available in client
-
specific SFTP directories that give detail on all
positive and negative billing events, i
ncluding subscription status.





Last Updated:
June 6, 2012

Page
4

of
29


PayOne Android Library V1.
0

2.1

Basic Merchant Information

Creating a
PayOne

service is simple and straightforward. The following information
should be provided to your Client Services Representative:

1.

Your main website URL (e.g.,
https://www.nintendo.com
)

2.

Notification URL for payment events (e.g.,
https://notify.nintendo.com
)

3.

Product descriptions (e.g., 500 Gaming Credits, 1000 Gaming Credits)

Each product description ca
n be 200 characters.

4.

Product price points (e.g., $4.99 for 500 credits, $9.99 for 1000 Credits)

Please check with your
PayOne

Client Service representative

for

current allowed
mobile price points.

5.

Product SKU identifiers (e.g., GC500 for 500 Gaming Credits
)

Each SKU can be 25 characters.

6.

Terms and conditions information

This information appears fine print and includes corporate name, service name,
support address, toll
-
free number, and email contact.


2.2

Service Integration with Android App

Once the Merchant i
nformation is provided, a
PayOne

customer service representative
will setup the service and will provide a unique Button ID that will be used in your
Application.


3

PayOne

Android Payments Library

This section provides details about the
PayOne

Payments Libr
ary and it provides
instructions and examples for integrating the library with an Android application.



The flo
w of the library is as follows:

1.

The parent application initializes the library.

2.

The library contains the Pay
O
ne
Home
Activity, which process
es

th
e payments.

3.

The
Pay
O
neHomeActivity
can be accessed by calling the

P
ay
O
neHomeActivity
via intent method using startActivity(intent).

4.

Once the user clicks on the purchase button, the processing will start instantly
and the user is
guided through a series of
steps and is
shown the
current stage
or step

of the transaction.

5.

After the transaction is processed, PayOne payment Library
displays

the
transaction details along with the final status of the payment

in a new
activity

which depends on the status of the tra
nsaction
after which user can go back to
the parent activity on button click
.



Last Updated:
June 6, 2012

Page
5

of
29


PayOne Android Library V1.
0

3.1

Android Payments Library API Reference


Call PayOne
Home
Activity:



You have to pass the following parameters to the PayOne
Home

Activity:

Parameter
Name

Parameter ID

Type

Mandato
ry
/ Optional

Generated By

Description

Transaction ID

ai_client_tran

String (25)
1

M

Merchant

Unique transaction
id created to link
transaction to user.

Button ID

button_id

String (32)

M

PayOne

Unique identifier for
merchant’s
payment panel.

SKU ID

sku

String(25)

O

Merchant

Unique SKU id
created by the
merchant to identify
the item being sold.

Amount

amt

String

O

Merchant

Price
at which
desired item is
required to be
purchased at.



1.

Valid characters are
A
-
Z a
-
z 0
-
9
PLUS:
-

space ' # . _ ! @ # $ % ^
( ) /

(
PLUS:
hyphen, space, single quote, pound, period, underscore, exclamation, at sign,

pound, dollar, percent, carrot, left paren, right paren, forward slash).

Customize Parameters

Transaction ID

(ai_client_tran) should contain a value that helps your
server lin
k the
transaction with a user
.

SKU ID

(sku) should contain a value that determines the item being sold to the user.

If the sku is not passed to PayOne
Home
Activity then the user will be shown with the list
of items to select and purchase the sel
ected item.

Amount

(amt)

should contain a value that determines the price at which the item is being
sold to the user
. This is an optional parameter.

Button ID

(button_id) is a constant value that links a merchant specific payment panel
with a
PayOne

Payme
nt Library. This value should not be changed.

Note:

Country code is not need to be passed as it will be picked from the installed SIM
card.



Last Updated:
June 6, 2012

Page
6

of
29


PayOne Android Library V1.
0


3.2

User Per
missions needed to enable Pay
One
Home
Activity

Since the Mobile Payments Library
has

Activit
es
,
they

must be

declared in the
AndroidManifest.xml file of the application.



<activity



android:name
=
"com.payone.
ui
.PayOne
Home
Activity"



android:launchMode=
"
singleTop
"



android:windowSoftInputMode=
"
stateHidden|adjustResize
"



android:theme
=
"
@and
roid:style/Theme.NoTitleBar.Fullscreen
"



android:configChanges
=
"orientation"
/>





<activity



android:name
=
"com.payone.ui.TransactionSuccessActivity"



android:windowSoftInputMode=
"
stateHidden|adjust
Pan
"



android:theme
=
"
@androi
d:style/Theme.NoTitleBar.Fullscreen
"



android:configChanges
=
"orientation"
/>




<activity



android:name
=
"com.payone.ui.TransactionFailur
e
Activity"



android:windowSoftInputMode=
"
stateHidden|adjust
Pan
"



android:theme
=
"
@android:style/
Theme.NoTitleBar.Fullscreen
"



android:configChanges
=
"orientation"
/>




Since the SDK uses some of the system resources for processing, additional <uses
-
permission> tags must be declared in the AndroidManifest.xml file of the application.
Internet and
Phone State permissions required by the Library must also be declared.



Below is an example AndroidManifest.xml. Add these after the <application> tag.




<
uses
-
sdk

android:minSdkVersion
="
7
"

/>



<
uses
-
permission

android:name
=
"
android.permission.I
NTERNET"

/>


<
uses
-
permission

android:name
=
"android.permission.READ_PHONE_STATE
"
/>


<
uses
-
permission

android:name
=
"
android.permission.ACCESS_NETWORK_STATE
"
/>


<
uses
-
permission

android:name
=
"
android.permission.SEND_SMS
"
/>


<
uses
-
permission

andro
id:name
=
"
android.permission.RECEIVE_SMS
"
/>


<
uses
-
permission

android:name
=
"
android.permission.ACCESS_NETWORK_STATE
"
/>



<
uses
-
permission

android:name
=
"android.permission.ACCESS_WIFI_STATE
"
/>




Last Updated:
June 6, 2012

Page
7

of
29


PayOne Android Library V1.
0

3.3

User flow diagram

This diagram shows the user flow from Me
rchant Par
ent Application to
PayOne
.





Last Updated:
June 6, 2012

Page
8

of
29


PayOne Android Library V1.
0

4

Android Merchant App Development

4.1

Setting up the Android dev environment

The following code snippet illustrates how to integrate the PayOne SDK into any
application:


1.

Add the

P
1L
ibrary


library
project

to the
merchan
t
project as explained in section
4.1.1


2.

Add the permissions in the AndroidManifest.xml file as explained in section 4.1.2


3.

Use the following lines of code with the corresponding parameters in your
application:




// start the intent

Intent payOneIntent =

new Intent(
this
, PayOne
Home
Activity.
class
);

payOneIntent
.putExtra(
Constants
.
BUTTON_ID
, “<button_id>”);

payOneIntent
.putExtra(
Constants
.
SKU
_ID
, “<sku>”);

payOneIntent.putExtra(Constants.
PRICE
, “<price>”);

payOneIntent
.putExtra(
Constants
.
AI_CLIENT_TRAN,


<ai_client_tran
>
”);

this
.startActivity(
payOneIntent
);




4.1.1

Adding the
P
1
Library

l
ibrary
project
in to the Android project


To add the PayOne Mobile Payments Library to the project, the following steps have to
be followed:


1.

Create an Android Project by
selecting File Menu
-
> New
-
> Project and
choose the Android Project

option
.

2.

Select

Create the project from the existing source


option and point to the
P
1
Library Project.

3.

Right Click on the project to which P
1
Library is to be integrated.

4.

Select ”
Android”
.

5.

In the “Library” section, Click on Add.

6.

Browse and select the library project that was just created in Step 2.

7.

Click on “Ok” to add the library project to the Merchant App.


The following class should be imported into the application classes:



import

co
m.payone.
ui
.Pay
O
ne
Home
Activity;



Last Updated:
June 6, 2012

Page
9

of
29


PayOne Android Library V1.
0

4.1.2

Declaring the Library and Permissions in AndroidManifest.xml

Since the Mobile Payments Library
has

A
ctivit
ies
,
they

must be declared in the
AndroidManifest.xml file of the application.





<activity


androi
d:name
=
"com.payone.ui.PayOneHomeActivity"


android:launchMode=
"
singleTop
"


android:windowSoftInputMode=
"
stateHidden|adjustResize
"


android:theme
=
"
@android:style/Theme.NoTitleBar.Fullscreen
"


android:configChanges
=
"orientation"
/>




<activity


android:name
=
"com.payone.ui.TransactionSuccessActivity"


android:windowSoftInputMode=
"
stateHidden|adjust
Pan"


android:theme
=
"
@android:style/Theme.NoTitleBar.Fullscreen
"


android:configChanges
=
"orientation"
/>



<activity



android:name
=
"com.payone.ui.TransactionFailureActivity"


android:windowSoftInputMode=
"
stateHidden|adjust
Pan"


android:theme
=
"
@android:style/Theme.NoTitleBar.Fullscreen
"


android:configChanges
=
"orientation"
/>



Since the SDK uses some of the

system resources for processing, additional <uses
-
permission> tags must be declared in the AndroidManifest.xml file of the application.
Internet and Phone State permissions required by the Library must also be declared.



Below is an example AndroidMani
fest.xml. Add these after the <application> tag.




<
uses
-
sdk

android:minSdkVersion
="
7
"

/>


<
uses
-
permission

android:name
=
"android.permission.INTERNET"

/>


<
uses
-
permission

android:name
=
"android.permission.READ_PHONE_STATE"
/>


<
uses
-
permission

android:name
=
"android.permission.ACCESS_NETWORK_STATE"
/>


<
uses
-
permission

android:name
=
"android.permission.SEND_SMS"
/>


<
uses
-
permission

android:name
=
"android.permission.RECEIVE_SMS
"
/>


<
uses
-
permission

android:name
=
"android.permission.ACCESS_NET
WORK_STATE"
/>


<
uses
-
permission

android:name
=
"android.permission.ACCESS_WIFI_STATE
"
/>





Last Updated:
June 6, 2012

Page
10

of
29


PayOne Android Library V1.
0

4.2

Invoking the
PayOne
Home
Activity from your App

4.2.1

Initialize & create
PayOneHomeActivity



// start the intent

Intent payOneIntent = new
Intent (
this
, PayOneHomeActivi
ty.
class
);

payOneIntent.putExtra
(Constants.
BUTTON_ID
, “<button_id>”);

payOneIntent.putExtra(Constants.
SKU_ID
, “<sku>”);

payOneIntent.putExtra(Constants.
PRICE
, “<price>”);

payOneIntent.putExtra(Constants.
AI_CLIENT_TRAN,
“<ai_client_tran
>
”);

this.startActi
vity(payOneIntent);



5

Sample Application


5.1

Description

The sample application describes how to set the users permissions and add an activity
to call
PayOne
Home
Activity.


5.2

Code

Snippets


AndroidManifest.xml


Update the AndroidManifest.xml file as shown below:




<?xml
version
=
"1.0"

encoding
=
"utf
-
8"
?>

<manifest
xmlns:android
="
http://schemas.android.com/apk/res/android
"

package
=
"com.
sample.activity
"

android:versionCode
=
"1"

android:ve
rsionName
=
"1.0"
>




<uses
-
sdk

android:minSdkVersion
="
7
"
/>

<uses
-
permission

android:
name

="
android.permission.INTERNET
"
/>

<uses
-
permission

android:
name

="
android.permission.READ_PHONE_STATE
"
/>

<uses
-
permission

android:
name

="
android.permission.ACCES
S_NETWORK_STATE
"
/>

<uses
-
permission

android:
name

="
android.permission.SEND_SMS
"
/>

<uses
-
permission

android:
name

="
android.permission.RECEIVE_SMS
"
/>

<uses
-
permission

android:
name

="
android.permission.ACCESS_NETWORK_STATE
"
/>

<uses
-
permission

android:
name

="
a
ndroid.permission.ACCESS_WIFI_STATE
"
/>

<application

android:icon
=
"@drawable/ic
_launcher
"



android:label
=
"@string/app_name"
>



<activity

android:
name
="
com.sample.test.SampleAppActivity
"




Last Updated:
June 6, 2012

Page
11

of
29


PayOne Android Library V1.
0


android:
l
abel
="@string/app_name" >


<intent
-
filter>



<action

android:
name

="
android.intent.action.MAIN
"
/>


<category

android:
name

="
android.intent.category.LAUNCHER
"
/>


</intent
-
filter>

</activity>

<activity

android:
name

="
com.payone.ui.PayOneHomeActivity
"


android:
configChanges
="
orientation
"


android:
launchMode
="
singleTop
"


android:
theme
="
@android:style/Theme.NoTitleBar.Fullscreen
"


android:
windowSoftInputMode
="
stateHidden|adjustResize
" >

</activity>

<activity

android:
name

="
com.payone.ui.TransactionSucc
essActivity
"


android:
configChanges
="
orientation
"


android:
theme
="
@android:style/Theme.NoTitleBar.Fullscreen
"


android:
windowSoftInputMode
="
stateHidden|adjustResize
"

>

</activity>

<activity

android:
name

="
com.payone.ui.Transactio
nFailureActivity
"


android:
configChanges
="
orientation
"


android:
theme
="
@android:style/Theme.NoTitleBar.Fullscreen
"


android:
windowSoftInputMode
="
stateHidden|adjustResize
"

>

</activity>

</application>

</manifest>




SampleActivity
.java



package

com.
sample.activity
;


import

android.app.Activity;


import

android.content.Intent;


import

android.os.Bundle;


import

android.view.View;


import

android.view.View.OnClickListener;


import

android.widget.Button;


import

android.widget.TextVi
ew;


import

com.payone.payment_process.global_data.Constants;


import

com.payone.
ui
.PayOne
Home
Activity;



public

class

SampleActivity
extends

Activity {



private

Button
button
;



private String
buttonId

=
"
MTMyODY2NjcyNC5qcGdQQHk1MDAxMjI=
"
;



private

Stri
ng
ai
_
client
_
trans

=
"
A
NDROID
001
"
;



private

String
sku

=
"
MOProduct1
"
;




private

String
price =
"
1.99
"
;



Last Updated:
June 6, 2012

Page
12

of
29


PayOne Android Library V1.
0




/** Called when the activity is first created. */



@Override



public

void

onCreate(Bundle savedInstanceState) {




super
.onCreate(savedInsta
nceState);




setContentView(R.layout.
main
);




button

= (Button) findViewById(R.id.
btnBuyNow
);






button
.setOnClickListener(
new

OnClickListener() {





public

void

onClick(View v) {




Intent payIntent =
new

Intent(
v.getContext()
,


PayOne
Ho
me
Activity.
class
);




payIntent.putExtra(
Constants
.
BUTTON
_
ID
,
buttonId
);




payIntent.putExtra(
Constants
.
SKU
_
ID
,
sk
u
);




payIntent.putExtra(
Constants
.
AI
_
CLIENT
_
TRAN
,
ai
_
client
_
trans
);



payIntent.putExtra(Constants.
PRICE
,

price);




startActivity
(
payInten
t
);



}




});


}



@Override




public

void

onStop() {




super
.onStop();




}



@Override



public

void

onResume() {




super
.onResume();


}



@Override


public

void

onDestroy() {




super
.onDestroy();


}


}


Main.xml

<?xml

version="1.0" encodin
g="utf
-
8"
?>

<LinearLayout

xmlns:android
="http://schemas.android.com/apk/res/android"


android:layout_width
="fill_parent"


android:layout_height
="fill_parent"


android:orientation
="vertical"

>



<Button



android:id
="@+id/btnBuyNow"



android:layou
t_width
="fill_parent"



android:layout_height
="wrap_content"



android:layout_margin
="10dp"



android:text
="Buy With PayOne Mobile"

/>

</LinearLayout>





Last Updated:
June 6, 2012

Page
13

of
29


PayOne Android Library V1.
0

5.3

Sample Application Screen Shots


Screenshot 1
: The developer’s application screen.




Last Updated:
June 6, 2012

Page
14

of
29


PayOne Android Library V1.
0

Screenshot 2:
Fe
tching Data
:






Last Updated:
June 6, 2012

Page
15

of
29


PayOne Android Library V1.
0

Screenshot 3
: Product
Selected P
age:





Last Updated:
June 6, 2012

Page
16

of
29


PayOne Android Library V1.
0

Screenshot 4
: Authenticating your mobile number:





Last Updated:
June 6, 2012

Page
17

of
29


PayOne Android Library V1.
0

Screenshot 5:

Opt In Request





Last Updated:
June 6, 2012

Page
18

of
29


PayOne Android Library V1.
0

Screenshot 6:

After completion of the payment process
.


Case 1: If the purchase is a SUCCESSFUL purchase.








Last Updated:
June 6, 2012

Page
19

of
29


PayOne Android Library V1.
0

Case 2: If the purchase is NOT SUCCESSFUL.





Last Updated:
June 6, 2012

Page
20

of
29


PayOne Android Library V1.
0

6

Backend Integration

When the consumer completes their purchase, a payment notification is sent from the
PayOne

servers to your notification URL.
You must always accept this notification
and credit t
he user. This callback occurs after the user is charged
. If your server
does not respond, the callback will be retried every 10 minutes for 24 hours.


To minimize fraud you should:



Ensure that your callback server only accepts callbacks over SSL from a
P
ayOne

IP address. Please contact your Merchant Onboarding Team for network
connectivity details.



Verify that the timestamp in the message is within 5 minutes of the current time.



To prevent parameter spoofing and fraudulent activity you should verify the

digital signature of the parameters. See section
6.2

for details.


The following table gives data that is sent to the merchant’s server via an HTTP GET.
For positive payment confirmations the
ai_resp_appl
parameter has a value of
0000
.


Request Parameter

Data Types


Abbreviation

Data Type

Description

N

Numeric

0
-
9

ANS

AlphaNumeric
Strict

A
-
Z a
-
z 0
-
9
PLUS:

-

space ’ # . _ ,

(
PLUS:

hyphen, space, apostrophe, pound, period, underscore, comma)

AN

AlphaNumeric

A
-
Z a
-
z 0
-
9
PLUS:

-

space ' # .
_ ! @ # $ % ^ ( ) /

(
PLUS:

hyphen, space, single quote, pound, period, underscore, exclamation,
at sign, pound, dollar, percent, carrot, left paren, right paren, forward slash)

Any

Any

Allow any character. Used only for passwords. Passwords are a
ssigned by
PayOne
.

DT

Datetime

mm
-
dd
-
yyyy HH:MM:SS,sss, strictly 23 characters.





Last Updated:
June 6, 2012

Page
21

of
29


PayOne Android Library V1.
0

6.1

Notification Parameters


Parameter

Description

O


Optional

Y


Required

Parameter
Type

Parameter
Max Len

Example

ai_name

Name of the application interface

Y

AN

20

ai_nam
e=
PAY_CONNE
CT_NOTIFY

ai_version

Version of the application interface
assigned by
PayOne

Y

AN

4

ai_version=4.1

ai_user_id

End user identifier

Y

AN

64

ai_user_id=
joe

ai_password

The password associated with the
end user

Y

Any

128

ai_password=
password12
3

ai_resp_code

Response code

Y

AN

4

ai_resp_code=
0000

ai_resp_msg

Description of the response code

Y

AN

100

ai_resp_msg=
Success

ai_resp_appl

P1 Premium service response code

Y

AN

20

ai_resp_appl=
0000

ai_resp_appl_msg

P1 Premium service response
messag
e

Y

AN

100

ai_resp_appl_
msg=
Approved

ai_resp_timestamp

Timestamp when the API call
completed

Y

DT

23

ai_resp_timest
amp= 03
-
11
-
2010
12:00:00,000

ai_client_tran

Unique transaction ID assigned by
client. Returned on successful
transactions.

Y

AN

25

ai_cli
ent_tran=
2M443215z

transid

PayOne

created transaction id to
uniquely identify the transaction

Y

AN

32

transid=
12Akjdkr45Ajkf
jem0

btn

Billing telephone number

Y

N

10

btn=20255512
12

acctid

Account Identifier

O

AN

100

acctid=jsmith9
552

clientid

Assigned

client ID

Y

N

10

clientid=7001

amt

Amount of purchase

Y

N

$$$$.cc

7

amt=9.99

currency

Currency of amt using ISO 4217
standard

Y

A

3

currency
=
EUR

billcountry

Country of purchaser using
ISO3166
-
1 alpha
-
2 standard

Y

A

25

billcountry=DE

op

The
operator ID

of the BTN

Y

AN

5

op
=
49004


op_name

The name of the operator

Y

AN

100

Op_name=O2
+Germany

prodid

P1 unique product ID representing
carrier and price point

Y

N

64

prodid=863726

sku

Merchant provided SKU
representing a specific product

Y

AN

25

sku=WD1001B
LK

dig_sig

The digital signature

O

AN

128

dig_sig=
AB125FCE784


Last Updated:
June 6, 2012

Page
22

of
29


PayOne Android Library V1.
0

Parameter

Description

O


Optional

Y


Required

Parameter
Type

Parameter
Max Len

Example

93


Notification Callback Request Example Using
curl
:

curl
https://yourserver.com/notify/?acctid=&ai_client_tran=237969198&ai_name=PAY_CONNEC
T_NOTIFY&ai_password=&ai_resp_appl=0000&ai_resp_ap
pl_msg=Approved&ai_resp_code=000
0&ai_resp_msg=Success&ai_resp_timestamp=2012
-
01
-
31T10:48:36.728Z&ai_user_id=&ai_version=4.2&amt=9.99&currency=EUR&billcountry=DE&o
p=49004&op_name=O2+Germany&btn=4989322952&clientid=874&prodid=655&sku=600COINS&tra
nsid=877236J
07DMQ4G3K0PTXLORM6&dig_sig=dbe42b83570f601bb5b1178a55141fb11ef8487a





Last Updated:
June 6, 2012

Page
23

of
29


PayOne Android Library V1.
0

6.2

Notification Callback Response Parameters


The merchant should respond to the callback with a simple plain text string of pipe
-
delimited values as described in the following table. If
the callback should be resent,
please set “9999” as the
ai_resp_code
.


Parameter

Description

O


Optional

Y


Required

Parameter
Type

Parameter
Max Len

Example

ai_resp_code

Response code
generated from the
service. Values include:

“0000”


Success


“999
9”


Resend

Y

AN

4

ai_resp_code=000
0

ai_resp_msg


“Success” , “Resend”, or
brief description of the
error (if any)

Y

AN

100

ai_resp_msg=

Success

ai_resp_timestamp

Timestamp when the API
call completed

Y

DT

23

ai_resp_timestamp
=03
-
11
-
2010
12:00:00,000


Notification Callback Response Pipe
-
delimited Example:

ai_resp_code=0000|ai_resp_msg=Success|ai_resp_timestamp=03
-
22
-
2010 12:23:33,222




Last Updated:
June 6, 2012

Page
24

of
29


PayOne Android Library V1.
0

6.3

Example Notification Callbacks


There are 5 possible callbacks sent from the
PayOne

servers. For one
-
time transactions

the only possible callbacks are Success and User Refund. Subscriptions also have User
Opt
-
Out, Billing Not Delivered, and Exceeded Billing Limit. These three negative events
are terminal; merchants should cancel the subscription.


Success Callback

The mos
t common notification callback will be a Success with
ai_resp_appl=0000
.
This indicates that the payment was a success and that the user’s account should be
credited.

You should be prepared to accept this callback at any time.


Success Callback Example:

https://yourserver.com/notify/?acctid=&ai_client_tran=237969198&ai_name=PAY_CONNECT_
NOTIFY&ai_password=&ai_resp_appl=0000&ai_resp_appl_msg=Approved&ai_resp_code=0000&ai
_resp_msg=Success&ai_resp_timestamp=2012
-
01
-
31T10:48:36.728Z&ai_user_id=&ai_version=4.2&
amt=9.99&currency=EUR&billcountry=DE&op=
49004&op_name=O2+Germany&btn=4989322952&clientid=874&prodid=655&sku=600COINS&transid
=877236J07DMQ4G3K0PTXLORM6&dig_sig=dbe42b83570f601bb5b1178a55141fb11ef8229e



User Refund


When a carrier issues a refund, a User
Refund with
ai_resp_appl=7906
is sent to the
merchant. The original transaction amount is included in the amt parameter.

User Refund

Callback Example:

https://yourserver.com/notify/?acctid=&ai_client_tran=237969198&ai_name=PAY_CONNECT_
NOTIFY&ai_password=&
ai_resp_appl=7906&ai_resp_appl_msg=User+Refund&ai_resp_code=0210
&ai_resp_msg=Business+Warning&ai_resp_timestamp=2012
-
01
-
31T11:52:28.412Z&ai_user_id=&ai_version=4.2&amt=9.99&
currency=EUR&billcountry=DE&op=49004&op_name=O2+Germany&btn=4989322952&clientid=87
4&
prodid=655&sku=600COINS&transid=877236J07DMQ4G3K0PTXLORM6&dig_sig=dbe42b83570f601bb5
b1178a55141fb11ef857ea
s



User Opt
-
Out (Subscription Only)

When a user signs up for a mobile subscription they will receive a reminder message 5
days before the next bil
ling cycle. If they choose to opt
-
out of mobile billing, we will send
a User Opt
-
Out with
ai_resp_appl=7901
. Any block or cancel also sends a User Opt
-
Out with ai_resp_appl=7901. When this happens no billing will take place for this phone
number, so the me
rchant should change the payment instrument or cancel the
subscriber’s service.



Last Updated:
June 6, 2012

Page
25

of
29


PayOne Android Library V1.
0


User Opt
-
Out Callback Example:

https://yourserver.com/notify/?acctid=&ai_client_tran=237969198&ai_name=PAY_CONNEC
T_NOTIFY&ai_password=&ai_resp_appl=7901&ai_resp_appl_msg=user
+out
-
out&ai_resp_code=0210&ai_resp_msg=Business+Warning&ai_resp_timestamp=2012
-
01
-
31T11:53:39.782Z&ai_user_id=&ai_version=4.2&amt=9.99&
currency=EUR&billcountry=DE&op=49004&op_name=O2+Germany&btn=4989322952&clientid=87
4&prodid=655&sku=600COINS&transid=8772
36J07DMQ4G3K0PTXLORM6&dig_sig=dbe42b83570f60
1bb5b1178a55141fb11ef89e73





Billing Not Delivered (Subscription Only)

In some cases the carrier networks will have problems delivering the billing event to the
end user. When this happens the billing attempt

will be retried using carrier
-
specific
retry logic. Receipt of this Billing Not Delivered callback with
ai_resp_appl=7501

indicates a permanent billing failure. The most common cases are disconnected
phones, permanent blocks, porting of the number to a no
n
-
billable phone company, or
exceeding the maximum number of billing retries.


Billing Not Delivered Callback Example:

https://yourserver.com/notify/?acctid=&ai_client_tran=237969198&ai_name=PAY_CONNECT_
NOTIFY&ai_password=&ai_resp_appl=7501&ai_resp_appl_m
sg=Notification+service+
-
+Billing+not+delivered&ai_resp_code=0210&ai_resp_msg=Business+Warning&ai_resp_timest
amp=2012
-
01
-
31T11:57:42.183Z&ai_user_id=&ai_version=4.2&amt=9.99&
currency=EUR&billcountry=DE&op=49004&op_name=O2+Germany&btn=4989322952&clientid=8
74&
prodid=655&sku=600COINS&transid=877236J07DMQ4G3K0PTXLORM6&dig_sig=dbe42b83570f601bb5
b1178a55141fb11ef868ba



Exceeded Billing Limit

(Subscription Only)

Each phone can have thresholds that limit the dollar amount or number of billing
attempts. When a bi
lling attempt fails because of a billing limit we will send an
Exceeded Billing Amount callback with
ai_resp_appl=0060
. Receipt of this callback
indicates that the subscriber was not charged and the subscription was canceled.


Exceeded Billing Limit Exampl
e:

https://yourserver.com/notify/?acctid=&ai_client_tran=237969198&ai_name=PAY_CONNECT_
NOTIFY&ai_password=&ai_resp_appl=0060&ai_resp_appl_msg=Exceeded+Billing+Amount&ai_re
sp_code=0200&ai_resp_msg=Business+Error&ai_resp_timestamp=2012
-
01
-
31T11:58:55.831Z&a
i_user_id=&ai_version=4.2&amt=9.99&
currency=EUR&billcountry=DE&op=49004&op_name=O2+Germany&btn=4989322952&clientid=874&
prodid=655&sku=600COINS&transid=877236J07DMQ4G3K0PTXLORM6&dig_sig=dbe42b83570f601bb5
b1178a55141fb11ef81fbe



Last Updated:
June 6, 2012

Page
26

of
29


PayOne Android Library V1.
0

6.4

Daily Transaction File


A d
aily CSV file detailing all billing and refund events is available on the
PayOne

SFTP
server at sftp.paymentone.com. Merchants can use these files to correct any
discrepancies in their backend systems. There are 17 fields per line: Mobile Number,
Event Typ
e, Event DateTime, Carrier, Carrier Id, Merchant Id, Merchant Name, SKU,
Product Desc, Transaction Type, Billing Type, Amount, Currency,
PayOne

Transaction
Id, Merchant Transaction Id, Payment Type, and Bill Country.


Field Name

Description

Field Length


Field Attribute

Example

Mobile Number

The mobile billing number (MDN)

25

AN

4989322952

Event Type

Billing Event Type



refunded



billed

30

AN

billed

Event DateTime

The date/time of the event. Time is in
UTC.

24

DT

2012
-
01
-
30T10:03:39.000Z

Carrier

The ca
rrier name

100

AN

O2 Germany

Carrier Id

The code of the carrier

5

N

49004

Merchant Id

The
PayOne

merchant id number


N

123

Merchant Name

The merchant name

50

AN

SomeCo

SKU

The stock keeping unit

25

AN

GC999

Product Desc

The description of the product

200

AN

Game Credits

Transaction Type


The type of transaction



onetime



subscription

30

AN

Onetime

Billing Type


The billing type



PSMS



DMB

30

AN

PSMS

Amount

The amount in local currency.


N

9.99

Currency

The currency of the transaction (3
character ISO c
ode)

3

AN

EUR

PayOne

Transaction Id

PayOne

created id to uniquely
identify the transaction

32

AN

877236IZF3GWGDXW8
XOAKPXWL

Merchant
Transaction Id

The id assigned by the client to the to
track the transaction


AN

12345678

Payment Type

The Payment Type



m
ob = mobile



lec = Landline

30

AN

mob

Bill Country

Country of purchaser using ISO3166
-
1 alpha
-
2 standard

2

A

DE



Daily files are available in the Mobile directory using the naming convention,
nnnnnn_Mobile_Daily_Txns_yyyyMMdd.zip, where nnnnnn is the cli
ent ID.



Last Updated:
June 6, 2012

Page
27

of
29


PayOne Android Library V1.
0

6.5

Verifying the Digital Signature

A digital signature will be included with all notifications to prevent parameter spoofing
and fraudulent activity. Steps to verify the digital signature:


1.

Obtain the digital signature secret phrase from your
PayOne

representative

a.

Note that this secret phrase may be modified from time to time

Secret Phrase

=
Abc123def456


2.

Generate the digital signature using the URL
-
unencoded notification parameters


3.

Determine all of the parameter name
-
value pairs, except for the dig_
sig
parameter. This list of 17 parameters is L1

L1

=

ai_name=PAY_CONNECT_NOTIFY

ai_version=4.2

ai_user_id=merchantnotify

ai_password=u9Fjd02#x+M

ai_resp_code=0000

ai_resp_msg=Success

ai_resp_appl=0000

ai_resp_appl_msg=Approved

ai_resp_timestamp=201
0
-
03
-
22T12:23:33.222Z

ai_client_tran=2dewssw32swew

transid=32jihh232iji2

btn=4989322952

acctid=54321

clientid=874

amt=9.99

currency=EUR

billcountry=DE

op=49004

op_name=O2 Germany

prodid=863726

sku=WD1001BLK



4.

Sort the request parameters L1 int
o ascending alphabetical order based on the
request parameter name, this list is L2

L2

=

acctid=54321

ai_client_tran=2dewssw32swew

ai_name=PAY_CONNECT_NOTIFY

ai_password=u9Fjd02#x+M

ai_resp_appl=0000

ai_resp_appl_msg=Approved

ai_resp_code=0000

ai_res
p_msg=Success

ai_resp_timestamp=2010
-
03
-
22T12:23:33.222Z



Last Updated:
June 6, 2012

Page
28

of
29


PayOne Android Library V1.
0

ai_user_id=merchantnotify

ai_version=4.2

amt=9.99

billcountry=DE

btn=4989322952

clientid=874

currency=EUR

op=49004

op_name=O2 Germany

prodid=863726

sku=WD1001BLK

transid=32jihh232iji2



5.

Convert the list L2 into an
ordered

query string with name
-
value pairs separated
by ampersand characters, “&”. This is the string S1. Be sure to maintain the
ordering from step 4. Do not add carriage returns or line feeds.


S1=
acctid=54321&ai_client_tran
=2dewssw32swew&ai_name=PA
Y_CONNECT_NOTIFY&ai_password=u9Fjd02#x+M&ai_resp_appl=0000&
ai_resp_appl_msg=Approved&ai_resp_code=0000&ai_resp_msg=Suc
cess&ai_resp_timestamp=2010
-
03
-
22T
12:23:33.222Z&ai_user_id=merchantnotify&ai_version=4.2&amt=
9.99&billcountry=DE
&btn=4989322952&clientid=874&currency=EU
R&op=49004&op_name=O2
Germany&prodid=863726&sku=WD1001BLK&transid=32jihh232iji2




6.

Append the
secret phrase

to the end of the ordered query string S1, to create S2.
Note that there is no ampersand before the secret
phrase.


S2=
acctid=54321&ai_client_tran=2dewssw32swew&ai_name=PA
Y_CONNECT_NOTIFY&ai_password=u9Fjd02#x+M&ai_resp_appl=0000&
ai_resp_appl_msg=Approved&ai_resp_code=0000&ai_resp_msg=Suc
cess&ai_resp_timestamp=2010
-
03
-
22T
12:23:33.222Z&ai_user_id=merchantnotify
&ai_version=4.2&amt=
9.99&billcountry=DE&btn=4989322952&clientid=874&currency=EU
R&op=49004&op_name=O2Germany&prodid=863726&sku=WD1001BLK&tr
ansid=32jihh232iji2
Abc123def456


7.

Compute an SHA
-
1 hash on the S2 string, to get the resulting signature of DS1

DS1

=
e
2ea51c912a3918c26c62395b57897b5853217b4


8.

Compare DS1 to the value of dig_sig. They should match. If DS1 and dig_sig
do not match, the parameters were spoofed or manipulated in transit. For
example, a third
-
party attempted to change the amt value and sub
mit a POST to
the merchant’s URL.



Last Updated:
June 6, 2012

Page
29

of
29


PayOne Android Library V1.
0


In Linux, you can test computing the digital signature using the sha1sum command:


echo
-
n
"acctid=54321&ai_client_tran=2dewssw32swew&ai_name=PAY_CONNECT_NOTIFY&ai_pass
word=u9Fjd02#x+M&ai_resp_appl=0000&ai_resp_appl_msg=A
pproved&ai_resp_code=000
0&ai_resp_msg=Success&ai_resp_timestamp=2010
-
03
-
22T12:23:33.222Z&ai_user_id=merchantnotify&ai_version=4.2&amt=9.99&billcountr
y=DE&btn=4989322952&clientid=874&currency=EUR&op=49004&op_name=O2
Germany&prodid=863726&sku=WD1001BLK&trans
id=32jihh232iji2Abc123def456" |
sha1sum


Result:
e2ea51c912a3918c26c62395b57897b5853217b4