NganLuong.vn-Prepaid-Card-Integration-Guide

version 2.0

Author: Nguyễn Cẩm Huế

Hanoi, Feb 2017

BẢNG GHI NHẬN THAY ĐỔI TÀI LIỆU

*A – Creat, M – edit, D – Delete

Date / Position / A*
M, D / Old version / Description / New version / author
2/2017 / total / M / Version 2.0 / Standardizing information connection / Version 2.0 / Nguyễn Cẩm Huế

CONCEPTS, TERMINOLOGIES

Terms / define / Note /


MỤC LỤC

I. Introduction 4

II. Process 4

1. Provided service Diagrams 4

2. Visual depictions 4

III. Function API 5

1. POST method 5

a. Live environment 5

b. Test sandbox 6

c. Function 6

d. Error_code 8

2. Webservice method 10

a. Live enviroment 10

b. Test sandbox 10

c. Function API 10

d. Error_code 13

I.  Introduction

Nganluong provide to Merchant one Prepaid Card Integration. With this api integration, user input the card information on merchant website and then merchant sent them to Nganluong api.

Prepaid Card Integration usually use when user deposit amount on the merchant website. And the use that amount to buyer products.

II.  Process

1.  Provided service Diagrams

2.  Visual depictions

-  User fill the card info

-  Merchant sent card info to CardCharge func of Nganluong AP.

+ if it’s correct, Nganluong respone successfully with error_code = 00

+ if it’s wrong: Nganluong respone unsuccessfully with error_code != 00

-  Merchant show message to user

III. Function API

NganLuong.vn-Prepaid-Card-Integration use method: POST or Webservice

1.  POST method

a.  Live environment

-  Registry Nganluong Account link: https://www.nganluong.vn/nganluong.html

-  Nganluong api link: https://www.nganluong.vn/mobile_card.api.post.v2.php

-  Registry Merchant site code link: when you registry successfully, you have merchant_id and MerchantPass

https://www.nganluong.vn/nganluong/merchant.html

b.  Test sandbox

-  Registry Nganluong Account link: https://sandbox.nganluong.vn:8088/nl30/nganluong/home.html

-  Test Nganluong api link: https://sandbox.nganluong.vn:8088/nl30/mobile_card.api.post.v2.php

-  Registry Merchant site code link: when you registry successfully, you have merchant_id and MerchantPass https://sandbox.nganluong.vn:8088/nl30/nganluong/merchant.html

-  Note:

+ Registry Nganluong Account: choose Type of transaction authentication is Payment Password

+ Payment with informations:

·  Type_card: VIETTEL

·  pin_card: 13 digits

·  card_serial: 11 digits

c.  Function

-  funtion: CardCharge

Input parameter
No / name / data type / enforcement / Explanation
1 / Func / String(50) / / Processing function name, function to scratch the cards is: CardCharge
2 / version / String(5) / / Version API = 2.0
3 / merchant_id / String(50) / / website/merchant code registered on nganluong(ID connection)
4 / merchant_account / String(255) / / Email address of NganLuong.vn account that uses to receive money from the payment of prepaid card
5 / merchant_password / String(50) / / Password to connect API = MD5(merchant_id + “|” + MerchantPass).
With MerchantPass: password connection of merchnat_id
6 / pin_card / String(12 - 14) / / code of prepaid card
7 / card_serial / String(20) / / serial number of prepaid card
8 / type_card / String(10) / / Card type, accept one of these values:
-  VMS: MobiFone card
-  VNP: VinaPhone card
-  VIETTEL: Viettel card
-  GATE: Gate card
9 / ref_code / String(50) / / Only code is corresponding with a buyer at merchant (for ex: bill number, account name, account id..)
This case needs to be checked between Nganluong.vn and merchant
.
10 / client_fullname / String(255) / Full name of buyer at merchant
11 / client_email / String(255) / Email of buyer at merchant
12 / client_mobile / String(20) / Phone number of buyer at merchant
Output parameter
No / Parameter name / Data type / enforcement / Explanation
1 / String of characters separated by "|" / String / Is a chain of values separated by ‘|’, corresponding with the following parameter:
error_code|merchant_id|merchant_account|pin_card|card_serial|type_card|ref_code|client_fullname|client_email|client_mobile|card_amount|transaction _amount|transaction_id
error_code / String(5) / Result code of function
merchant_id / String(50) / website/merchant code registered on nganluong(ID connection)
merchant_account / String(255) / Email address of NganLuong.vn account that merchant used to receive money by prepaid cards.
pin_card / String(12-14) / Prepaid card code
card_serial / String(20) / Serial number of card
type_card / String(10) / Card type, accept one of these values:
-  VMS: MobiFone card
-  VNP: VinaPhone card
-  VIETTEL: Viettel card
-  GATE: Gate card
ref_code / String(50) / Only code is corresponding with a buyer at merchant (for ex: account name, account id)
client_fullname / String(255) / Full name of buyer at merchant
client_email / String(255) / Email of buyer at merchant
client_mobile / String(20) / Phone number of buyer at merchant
card_amount / Int / Value of prepaid card (VND)
transaction_amount / Int / Amount (VND) = Value of prepaid card – transaction fee
transaction_id / String(20) / Arising transaction id at NganLuong.vn

d.  Error_code

Error Code / Description
00 / Successful transaction
99 / Error, but undefined or without reason
01 / Error, IP address to access API of NganLuong.vn is refused
02 / Error, parameter sent from the merchant to NganLuong.vn is not correct ( wrong parameter name or missing parameter)
03 / Error, merchant id does not exist or merchant is blocked connection to NganLuong.vn
04 / Error, checksum code is not correct (this error arises when communication code between merchant and NganLuong.vn is not correct or the order of params is not correct)
05 / Account that used to receive money does not exist.
06 / Account that used to receive money is blocked or limited, impossible to accept transactions
07 / prepaid card has used already
08 / prepaid card is blocked
09 / out of date card
10 / unverified card
11 / Wrong format of prepaid card code
12 / Wrong serial number
13 / Wrong card code or serial number is not correct
14 / Prepaid card does not exist
15 / Prepaid card can not use
16 / Number of entering card code (enter wrong card code) is beyond the limits
17 / Telco system is error, card is not deducted
18 / Telco system is error or overloaded, maybe card is not deducted, should be work with NganLuong.vn to resolve.
19 / Connection from NganLuong.vn to Telco system is error, card is not deducted ( for ex: wrong connection para, this error is not related to merchant)
20 / Successful connection to Telco, card is deducted but not yet adding money on NganLuong.vn

2.  Webservice method

using SOAP service.

a.  Live enviroment

-  Registry Nganluong Account link: https://www.nganluong.vn/nganluong.html

-  Nganluong API: https://www.nganluong.vn/mobile_card_api.php?wsdl

-  Registry Merchant site code link: when you registry successfully, you have merchant_id and MerchantPass

https://www.nganluong.vn/nganluong/merchant.html

b.  Test sandbox

-  Registry Nganluong Account link: https://sandbox.nganluong.vn:8088/nl30/nganluong/home.html

-  Test Nganluong api link: https://sandbox.nganluong.vn:8088/nl30/mobile_card_api.php?wsdl

-  Registry Merchant site code link: when you registry successfully, you have merchant_id and MerchantPass https://sandbox.nganluong.vn:8088/nl30/nganluong/merchant.html

-  Note:

+ Registry Nganluong Account: choose Type of transaction authentication is Payment Password

+ Payment with informations:

·  Type_card: VIETTEL

·  pin_card: 13 digits

·  card_serial: 11 digits

c.  Function API

-  Func: CardCharge_v2

Input /
3 params /
No / Param / Type / enforcement / Description /
1 / merchant_id / String(50) / x / website/merchant code registered on nganluong(ID connection)
2 / checksum / String(50) / x / = MD5(params + “|” + MerchantPass).
With MerchantPass: password connection of merchnat_id
3 / params / String() / x / Is a chain of values separated by ‘|’, corresponding with the following parameter:
pin_card / String(20) / x / code of prepaid card
type_card / String(10) / x / Card type, accept one of these values:
-  VMS: MobiFone card
-  VNP: VinaPhone card
-  VIETTEL: Viettel card
-  GATE: Gate card
ref_code / String(50) / x / Only code is corresponding with a buyer at merchant (for ex: account name, account id)
merchant_account / String(255) / x / Email address of NganLuong.vn account that merchant used to receive money by prepaid cards.
client_fullname / String(255) / Full name of buyer at merchant
client_email / String(255) / Email of buyer at merchant
client_mobile / String(20) / Phone of buyer at merchant
card_serial / String(20) / x / serial number of prepaid card
params = pin_card|type_card|ref_code|merchant_account|client_fullname|client_email|client_mobile|card_serial
Tham số ra (trả về) /
Param / type / enforcement / Description /
result / String() / x / Is a chain of values separated by ‘|’, corresponding with the following parameter:
error_code|merchant_id|transaction_id|amount|pin_card|type_card|ref_code| merchant_account|client_fullname|client_email|client_mobile|card_amount
error_code / String(5) / Result code of function.
Check index III.2.c
merchant_id / String(50) / website/merchant code registered on nganluong(ID connection)
transaction_id / String(20) / Arising transaction id at NganLuong.vn
amount / Int / Amount (VND) = Value of prepaid card – transaction fee
pin_card / String(20) / Mã thẻ cào
type_card / String(10) / Card type, accept one of these values:
-  VMS: MobiFone card
-  VNP: VinaPhone card
-  VIETTEL: Viettel card
-  GATE: Gate card
ref_code / String(50) / Only code is corresponding with a buyer at merchant (for ex: account name, account id)
merchant_account / String(255) / NganLuong.vn email of merchant that merchant used to receive money by prepaid cards.
client_fullname / String(255) / Full name of buyer at merchant
client_email / String(255) / Email of buyer at merchant
client_mobile / String(20) / Phone of buyer at merchant
card_amount / Int / Value of prepaid card (VND)

d.  Error_code

Mã lỗi / Mô tả /
00 / Successful
01 / Error, but undefined or without reason
05 / Pin_card wrong or prepaid card has used already
06 / Telco is error
07 / NganLuong.vn email of merchant not exsit
08 / NganLuong.vn email of merchant have been blocked
09 / The prepaid card have been blocked (fill card info wrong alot of times)
10 / Don’t deposit amount to NganLuong.vn account of merchant
11 / Receipts have not been created by Nganluong System
12 / Receipts of Ngân Lương is not successful
13 / NganLuong.vn account of merchant haven’t received amount

Sk: nganluong_sup_tech

Mail: 11