ViMob Payment Description

Ti liu c t API payment game, app

CNG TY C PHN VIN THNG TINH VNTr s chnh: Tng 3, Ks. Th Thao, Lng sinh vin HACINCO, Thanh Xun, H Niin thoi: (+(84-4) 35576148

VIMOBTi liu t t k thut API payment game, appBNG GHI NHN THAY I

*A To mi, M Sa i, D Xa b

NgyV tr thay iA*,

M, DNgun gcPhin bn cM t tay iPhin bn mi

Mc lc

5PHN 1.GII THIU

51.1Tng qut

51.2Mc ch ti liu

51.3nh ngha thut ng v cc t vit tt

51.4Ti liu tham kho

6PHN 2.YU CU CU HNH FILE GAME, APP

62.1M t chung

62.2ng dng file xas.conf

72.2.1Cch to HASH

72.3Hng dn cchbuild file

72.3.1File .jar

72.3.2File .apk

82.3.3File .ipa

9PHN 3.K THUT KT NI

93.1SMS

93.1.1Kt ni

93.1.2D liu gi sang i tc

113.1.3D liu tr v

123.2Np th

123.2.1Request np th t game, app

153.2.2Kt ni thng bo th co

PHN 1.GII THIU1.1 Tng qutVIMOB cung cp API kt ni payment s dng 2 phng thc SMS v np th cho cc game v app trong h thng.1.2 Mc ch ti liu

Ti liu nhm m t cc yu cu v cu hnh game v app a ln h thng VIMOB, cng nh cung cp cc t t k thut cho pha i tc kt ni vi cng tin nhn v h thng np th. Hai bn cn c vo ti liu ny xy dng kt ni h thng1.3 nh ngha thut ng v cc t vit tt

Thut ngnh nghaGhi ch

MOTin nhn gi i t in thoi ca khch hng Vit tt ca Mobile Originated

MTTin nhn tr v cho khch hng, tng ng vi MOVit tt ca Mobile Terminated

MSISDNnh danh khch hng. Thng l s in thoi

1.4 Ti liu tham kho

JSON: http://www.json.org/

PHN 2.YU CU CU HNH FILE GAME, APP1.5 M t chung

H thng VIMOB cho php a ln 3 nh dng game, app: 1. JavaME (.jad, .jar)

2. Android (.apk)

3. Iphone (.ipa)

File upload ln VIMOB (ch p dng cho file .jar, .apk, .ipa) cn phi cha file xas.conf cha cc config cho API payment vi ng dn nh sau:

1. File .jar: nm trong th mc root ca file (c th ./xas.conf)

2. File .apk: nm trong th mc assets (c th ./assets/xas.conf)

3. File .ipa: nm trong th mc ng dng (c th (./Payload/[app_name]/xas.conf)

File xas.conf s c h thng VIMOB sinh ra t ng v a vo file khi ngi dng ti game, app. Do ni dung trong file ny c th thay i.

1.6 ng dng file xas.conf

File xas.conf s c nh dng sau (lu : th t cc dng c th thay i):

Trong :

1. CARD_URL: l url game, app POST (HTTP/1.1 POST) d liu v th np ln h thng2. CARD_SECURE_KEY: key dng sinh ra chui xc thc vi d liu game, app POST ln h thng.

3. CARD_PROVIDERS: danh sch cc provider cho th co. Hin nay h thng VIMOB h tr cc provider vi gi tr sau: mobi|viettel|vina|vtc|fpt4. SMS_PREFIX: chui k t c h thng VIMOB t ng sinh ra, khi game, app nhn tin, phi nh km chui ny vo u tin nhn.

5. SMS_NUMBERS: chui u s nhn tin km theo gi tr tin nhn. VD: 500:8075|1000:8175|2000:8275|3000:8375|4000:8475|5000:8575|10000:8675|15000:87756. HASH: key dng validate file config ny. Game, app s dng chy nu key ny validate khng ng.

1.6.1 Cch to HASH

m ha secureKey, i tc cn mt apiKey c cung cp bi VIMOB. Key ny c cung cp trong trang qun l ca i tc. Phng thc m ha nh sau:HASH = UpperCase(MD5(CARD_URL + | + CARD_SECURE_KEY + | + CARD_PROVIDERS + | + SMS_PREFIX + | + SMS_NUMBERS + | + apiKey))1.7 Hng dn cchbuild file1.7.1 File .jar

Cc bc build li mt file .jar a xas.conf vo:

1. Gii nn file jar (vd: `game.jar`, gii nn thnh th mc `game`)

2. Thm file xas.conf vo th mc gii nn (vd: th mc `game`)

3. Nn ni dung trong th mc gii nn thnh file .zip (vd: game.zip)4. ui ui file .zip thnh .jar

1.7.2 File .apk

build li mt file .apk, cn phi c cc tool sau:

1. Openssl (http://www.openssl.org/): sinh ra key sign file apk

2. Tool signapk.jar (http://code.google.com/p/signapk/downloads/list)

Cch sinh ra cc key sign file apk:

openssl genrsa -out key.pem 1024

openssl req -new -key key.pem -out request.pem

openssl x509 -req -days 9999 -in request.pem -signkey key.pem -out certificate.pem

openssl pkcs8 -topk8 -outform DER -in key.pem -inform PEM -out key.pk8 -nocrypt

Cc bc build li file .apk a file xas.conf vo:

1. Gii nn file .apk (vd: `game.apk`, gii nn thnh th mc `game`)

2. Thm file xas.conf vo th mc `assets` trong th mc gii nn

3. Nn ni dung trong th mc gii nn thnh file .zip

4. i ui file .zip thnh .apk

5. Chy cu lnh sau: java -jar signapk.jar certificate.pem key.pk8 [source_file].apk [signed_file].apk1.7.3 File .ipaCc bc build li mt file .ipa a xas.conf vo:

1. Gii nn file jar (vd: `game. ipa`, gii nn thnh th mc `game`)

2. Thm file xas.conf vo th mc gii nn (vd: th mc `game`)

3. Nn ni dung trong th mc gii nn thnh file .zip (vd: game.zip)

4. ui ui file .zip thnh .ipaPHN 3.K THUT KT NILu : cc cu trc cng nh m lnh pha di ch l pseudo code, khng phi l cu trc ca mt ngn ng lp trnh.1.8 SMS1.8.1 Kt ni1.8.2 D liu gi sang i tcKhi nhn c tin nhn ca khch hng, VIMOB s gi d liu n n URL ca i tc dng phng thc POST ca HTTP vi cu trc d liu nh sau:

Trong :

Tn binKiuNullM t

idintNoID ca tin nhn

timestringNoThi gian tin nhn n, cu trc yyyyMMddhhmmss (v d: 20120801100000)

phoneNumberstringNoL s in thoi vi cu trc 84xxxxxxx

serviceintNou s tin nhn.

valueintNoMnh gi tin nhn, c gi tr: 500, 1000, 2000, 3000, 4000, 5000, 10000, 15000

messagestringNoNi dung tin nhn, l ni dung y , khng bao gm SMS_PREFIX

secureKeystringNoMD5 hash ca d liu. Chui ny l upper case

1.8.2.1 M ha secureKey m ha secureKey, i tc cn mt apiKey c cung cp bi VIMOB. Key ny c cung cp trong trang qun l ca i tc. Phng thc m ha nh sau:

secureKey = UpperCase(MD5(id + | + phoneNumber + | + service + | + value+ | + message + | + time + | + apiKey))1.8.3 D liu tr v

i tc tr v d liu l mt chui JSON. Chui ny l m ha ca mng d liu vi cu trc sau:

Trong :

Tn binKiuNullM t

statusintNoM thng bo trng thi x l tin nhn. 0 - thnh cng, 1 - li

messagestringNoThng bo li ca i tc, thng bo ny s c log li sau ny kim tra

subbooleanNoC tr tin ngi dng hay khng

responsesarrayNoTin nhn tr v cho ngi dng, ti a c tr v 2 tin nhn.

responses/typeintNoloi tin nhn. 0 - tin nhn text bnh thng, 1 - wap push

responses/messagestringNoni dung tin nhn. Vi wap push ni dung cn c nh dng: [text]:[url] (vd: "truy cap link:http://astore.vn")

1.9 Np th1.9.1 Request np th t game, app

Khi ngi dng c nhu cu np th thanh ton, h nhp cc thng tin v th v game, app s POST cc d liu ny vo CARD_URL. D liu ny bao gm:1. Provider: nh cung cp th

2. Serial: s th

3. Pin: m s np tin1.9.1.1 Request

C th, game hoc app s phi POST (HTTP/1.1 POST) vo CARD_URL

Trong :Tn binKiuNullM t

providerstringNoNh cung cp th. Ly trong bin config CARD_PROVIDERS (xas.conf)

serialstringNoS th

pinstringNoM s np tin

accountstringNoTi khon ca ngi dng.

timestringNoThi gian hin ti.

nh dng `yyyy-MM-dd hh:mm:ss`

cardSecureKeystringNoL gi tr CARD_SECURE_KEY trong file xas.conf

secureKeystringNoChui xc thc

1.9.1.1.1 M ha secureKey

m ha `secureKey`, i tc cn mt key c cung cp bi VIMOB (c gi l `apiKey`). Key ny c cung cp trong trang qun l ca i tc, kt hp vi CARD_SECURE_KEY (xas.conf) Phng thc m ha nh sau:

secureKey = UpperCase(MD5(provider + | + serial + | + pin + | + account + | + time + | + CARD_SECURE_KEY + | + apiKey))1.9.1.2 Response from VIMOBSau khi game, app POST d liu th co, h thng VIMOB s tr v mt chui nh dng JSON. Chui ny l m ha ca mng vi d liu nh sau:


idintNoID giao dch

statusintNoM x l ca h thng. Gi tr 0 l thnh cng, chi tit xem bng di.

messagestringNoThng bo ca h thng cho game, app (khng hin th thng bo ny cho ngi dng)

valueintNoGi tr th co

userMessagestringYesThng bo dnh cho ngi dng. Thng bo ny c ly khi VIMOB kt ni sang u nhn thng bo th co ca server i tc. Chi tit xem bn di

secureKeystringNoM ha

1.9.1.2.1 M ha sercureKey

`secureKey` c h thng VIMOB m ha vi cng thc sau:

secureKey = UpperCase(MD5(id + | + status + | + message + | + value + | + userMessage + | + cardSecureKey + | + apiKey))Vi `cardSecureKey` l key c game, app POST ln1.9.1.2.2 Bng m li

StatusMessageM t

0Thnh cngTh co np thnh cng

1Li h thngH thng gin on hoc kt ni sang pha nh mng li

2Th saiProvider, serial hoc pin khng ng

3Th dngTh ny c np

4Np th khng thnh cngKhng th np th do cc li khc

1.9.2 Kt ni thng bo th coSau khi game, app POST d liu th co ln VIMOB, nu th co c s dng thnh cng, h thng s gi thng bo sang URL nhn kt qu np th ca i tc. URL ny c config khi upload game, app ln h thng VIMOB.1.9.2.1 D liu gi sang pha i tc

Trong :

Tn binKiuNullM t

idintNoID giao dch

providerstringNoM nh cung cp

serialstringNoS th

pinstringNoM s np tin

valueintNoGi tr th

timestringNoThi gian hin ti.

nh dng `yyyy-MM-dd hh:mm:ss`

secureKeystringNoChui xc thc

1.9.2.1.1 M ha sercureKey

`secureKey` c h thng VIMOB m ha vi cng thc sau:

secureKey = UpperCase(MD5(id + | + provider + | + serial + | + pin + | + value + | + time + | + apiKey))1.9.2.2 Yu cu d liu tr v

i tc tr v d liu l mt chui JSON. Chui ny l m ha ca mng d liu vi cu trc sau:


statusintNoM x l ca i tc

messagestringNoThng bo x l ca i tc

userMessagestringNoThng bo tr v cho ngi dng

CARD_URL=$cardUrl

CARD_SECURE_KEY=$cardSecureKey

CARD_PROVIDERS=$cardProviders

SMS_PREFIX=$smsPrefix

SMS_NUMBERS=$smsNumbers

HASH=[hash_key]

sms: Array

[

id: .

phoneNumber: .

service: .

value: .

message: .

time: .

secureKey: .

]

Array

[

status:

message:

sub: true|false

responses: Array

[

Array

[

type:

message:

]

]

]

card: Array

[

provider:

serial:

pin:

account:

time:

cardSecureKey:

secureKey:

]

Array

[

id:

status:

message:

value:

userMessage:

secureKey:

]

Array [

id:

provider:

serial:

pin:

value:

time:

secureKey:

]

Array

[

status:

message:

userMessage:

]

8TINH VN TELECOM

Documents

ViMob Payment Description