Payment gateway technical specification v1 01

VIETTEL GROUP





TECHNICAL SPECIFICATION DOCUMENT
PAYMENT GATEWAY

Release: 1.0












HaNoi, Jun -2013
Payment Gateway – Technical Specification v1.0
Payment Gateway – Technical Specification 2/18
CONTENT
1 INTRODUCTION 3
1.1 General Purpose 3
1.2 Reference Document 3

1.3 Terms 3
2 BASIC FLOW 4
3 PROTOCOL DETAIL 5
3.1 Datafield in ISO 8583 Message 5
3.1.1 Datafields Detail 6
3.1.2 Format 7
3.1.3 Type 7
3.2 Message Type Indicator 8
3.3 Signature 8
3.3.1 Signature Composition 8
3.3.2 Sample Code 9
3.4 Response Code Detail 10
4 ISO MESSAGE DETAIL 12
4.1 List of messages 12
4.2 ISO 8583 Message Detail 12
4.2.1 Network Checking (Ping) 12
4.2.2 Topup for prepaid subscriber 12
5 Webservice API 14
5.1 Topup to prepaid mobile 14
6 RECONCILIATION 16
6.1 Reconciliation regulations 16
6.1.1 General regulation 16
6.1.2 Reconciliation Process 16
6.2 Reconciliation File Format 17
6.3 Sample Code 18

Payment Gateway – Technical Specification v1.0
Payment Gateway – Technical Specification 3/18
1 INTRODUCTION
1.1 General Purpose

This document describes communication flows and message specification provided by
Payment Gateway.
1.2 Reference Document
- PKCS #1 version 1.5: RSA Laboratories.
- PKCS #7: RSA Laboratories.
- ISO 8583: International Standard Organization.
- SunJCE Document: Java Cryptography Architecture Sun Providers Documentation.
1.3 Terms
- ISO 8583: Standard for Financial Transaction Card Originated Messages - Interchange
message specifications.
- SHA-1: Stands for “Secure Hash Algorithm”, an algorithm using in hashing message‟s
fields before apply RSA algorithm to create message signature. Output stream after
applying SHA-1 is a 160 bits-length stream.
- AES: Stands for “Advanced Encryption Standard”, a symmetric algorithm for block
encryption. AES is used in encrypting sensitive fields of message.
- RSA: Stands for Ron Rivest, Adi Shamir and Len Adleman, an asynchronous
algorithm RSA is used in creating message‟s signature.
- Partner: Partner system that connect to Payment Gateway.
- Payment Gateway System (Topup System): Gateway system that provides payment
services (payment, topup, charging ) to Partner.
- Telco: Telelecommunication Service Provider.

Payment Gateway – Technical Specification v1.0
Payment Gateway – Technical Specification 4/18
2 BASIC FLOW
Partner Payment Gateway
Request
Telco ‘s Account
Management System
Request process

Response
Response

Partners connect to Payment Gateway System as Client in Client/Server model.
If Partner System can‟t get the Response Message (due to several reasons such as Connection
timeout, Connection Fail, Connection Closed…), the Query message can be used for querying
result of recent transactions.
Another option is using reconciliation file that being transferred periodically.
Payment Gateway – Technical Specification v1.0
Payment Gateway – Technical Specification 5/18
3 PROTOCOL DETAIL
3.1 Datafield in ISO 8583 Message
- Payment Gateway uses customized ISO 8583 Standard for exchanging messages.
Reference version is ISO 8583 1987. All datafield is in plain text format.
- Message length is indicated in Message Header, with a 4 bytes BCD field. Example:
message length “0276” indicates that there are 276 bytes of data after Message
Header.

3.1.1 Datafields Detail
No
Field Name
Order
Format
Type
Signat
ure
Length
Description
1
MTI

0
FIXED
n

4
Message Type Id
2
Bit Map
1
FIXED
An

16
Bit Map
3
MSISDN
2
LLVAR
N
Yes
19
Subscriber ID in GSM or UMTS.
MSISDN = CC + NDC + SN
- CC = Country Code
- NDC = National Destination Code
- SN = Subscriber Number
An valid sample MSISDN:
258987654321
4
Process Code

3
FIXED
N
Yes
6
Service code (Topup, Charging,
Payment…)
5
Transaction
Amount
4
FIXED
N
Yes
12
Amount of Transaction
6
Transmission
Date/Time
7
FIXED
N
Yes
14
Transaction Time
Format: yyyyMMddHHmmss
Example: 20080519204503 –
19/05/2008 at 20h45m03s
7
System Trace

Audit Number
11
FIXED
N
Yes
15
Message ID
8
Sub Balance
14
FIXED
N

12
Balance of subscriber account (using
in Response Message for Prepaid
Subscriber Query message)
9
Customer
Code
23
LLVAR
An
Yes
30
Subscriber ID in Billing System
10
Expire Date
28
FIXED

N

8
Expire Date of subscriber account
(using in Response Message for
Prepaid Subscriber Query message)
Format yyyyMMdd
11
Response
Code
39
FIXED
N
Yes
2
Response Code in Response message
12
Additional
Data
48
LLLVAR
Ans

999
Additional Information (depends on
each service), (composed from
multiple datafields)
- Each datafield is separated by „|‟
- If a data filed is empty, separated
token „|‟ is still required.

- In Resend message (MTI = 0201),
48
th
Datafield is used to define a
message is Query message of Resend
message. In Query message 48
th

datafield is set to "query".
- If Query message if System Trace
Audit Number doesn‟t exist, a
Response message with Response
Code 88 is returned.
13
Client ID
63
LLVAR
An
Yes
99
Client ID (registered in Payment
Gateway)
Payment Gateway – Technical Specification v1.0
Payment Gateway – Technical Specification 7/18
14
Message
Signature
64
LLLVAR
An

999
Signature of message:
- Datafields with
Signature=Yes are
concatenated in sequence of
order. The concatenated string
is hashed by a SHA1 hashing
function. The result string
after that is encrypted using
RSA algorithm. Encrypted
value is encoded in Base64
before set to 64th field of
message.
- RSA Encryption Algorithm:
comply with PKCS#1 version
1.5 (PKCS#1 section 8,9,10 -
RSA Laboratories). Length of
key is 1024 bits.
- A datafield is marked
Signature=Yes but does not
exist in message will be
ignored in signature
composing / verifying.
- Value of each datafield is
standardized before
composing signature.
- Example: 11
th
datafield has

value of „25‟will be
transformed into
„000000000000025‟ (13 digits
„0‟ are left-padded to full
length).

3.1.2 Format
- FIXED – Predefined length; no need of length-specifying indicator;
- LVAR – Variable-length datafield, with length is smaller than or equal 9, with 1 prefix
BCD character as length-specifying indicator. The BCD prefix character if right-
alignment and left-padded with „0‟ to full length;
- LLVAR – Variable-length datafield, with length is smaller than or equal 99, with 2
prefix BCD character as length-specifying indicator;
- LLLVAR – Variable-length datafield, with length is smaller than or equal 999, with 3
prefix BCD character as length-specifying indicator.
3.1.3 Type
- n – Numeric, in BCD format, right alignment and left-padded with „0‟ to full length;
- an – Alpha-numeric datafield (not include Blank characters – ASCII code 0x20);
- anp – Alpha-numeric datafield (may be include Blank characters – ASCII code 0x20);
- ans – Alphabetic, numeric and special characters datafield;
- b – Binary datafield.
Payment Gateway – Technical Specification v1.0
Payment Gateway – Technical Specification 8/18
3.2 Message Type Indicator
MTI (Message Type Indicator): a 4 digit numeric field which classifies high level
function of the messages.
- The first digit indicates version of protocol: Payment Gateway set default 0 ;
- The second digit indicates class of messages:
Value
Class of message

Description
-1
Authenticate message

-2
Transaction message

-3
Transaction confirmation
message

-8
Network, Key exchange
message

-9
Internally used message
Using in internally interchanging message
within Payment Gateway System.
- The third digit indicates function of messages:
Value
Function of message
Description
0-
Request message

1-
Response message

- The fourth digit specifies message origin (Acquirer or Issuer):

Value
Message Origin
Description
0
Acquirer
Client init transaction
1
Acquirer Repeat
Client resend
2
Issuer
Server init transaction
3
Issuer Repeat
Server resend
3.3 Signature
3.3.1 Signature Composition
- Signature is composed from several specific datafields in message to security purpose
(authenticity and integrity of data flow).
- Payment Gateway System and Partner System have own pair of key (private
key/public key). Payment Gateway System will exchange public key with partner
when registering Partner and provide Client ID to partner.
- Message is signed with private key of sender. Receiver will use public key of sender
to verify signature.
- In detail description (Section 3.1), datafields with Signature=Yes will be concatenated
in the order of datafield to make a string. The concatenated string is hashed with a
Hash function (SHA1), the result after that is encrypted using RSA algorithm.
Encrypted value is encoded by Base64 function and final value is put into Message
Signature datafield (64
th

field).
Payment Gateway – Technical Specification v1.0
Payment Gateway – Technical Specification 9/18
- RSA Algorithm: comply with PKCS#1 version 1.5 (PKCS#1 section 8,9,10 - RSA
Laboratories). Key length is 1024 bits.
- Datafields with Signature=True but do not exist in message will be bypassed in
composing or verifying signature.
- Value of datafields are standardized before composing signature.
Example:
The 11
th
field has value of „25‟, will be transformed to 000000000000025 (13 digit „0‟
are left-padded).
3.3.2 Sample Code
import java.security.KeyFactory;
import java.security.PrivateKey;
import java.security.PublicKey;
import java.security.spec.EncodedKeySpec;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;
import org.bouncycastle.util.encoders.Base64;

Generate signature from private key

//private key
private PrivateKey getPrivateKeyFromString(String key) {
try {
KeyFactory keyFactory = KeyFactory.getInstance("RSA");
EncodedKeySpec privateKeySpec = new PKCS8EncodedKeySpec(Base64.decode(
key));

privateKeyVpg = keyFactory.generatePrivate(privateKeySpec);
} catch (Exception e) {
//TODO here
}
return privateKeyVpg;
}
//public key
public PublicKey getPublicKeyFromString(String key) {

try {
KeyFactory keyFactory = KeyFactory.getInstance("RSA");
EncodedKeySpec publicKeySpec = new X509EncodedKeySpec(Base64.decode(
key));
return keyFactory.generatePublic(publicKeySpec);
} catch (Exception e) {
e.printStackTrace();
return null;
}
}


Generate signature

public String generateVpgMacBase64(String data) {
String encryptData = "";
try {
java.security.Signature sig = java.security.Signature.getInstance(
"SHA1withRSA");
sig.initSign(privateKeyVpg);
sig.update(data.getBytes());

Payment Gateway – Technical Specification v1.0
Payment Gateway – Technical Specification 10/18
byte[] signature = sig.sign();
// Encrypt data
encryptData = new String(Base64.encode(signature));
} catch (Exception e) {
e.printStackTrace();
}
return encryptData;
}

Verify signature

public boolean verifyMacVpg(String data, String signature, PublicKey publicKey) throws
ISOException {
byte[] base64Bytes = Base64.decode(signature);
try {
// decode base64
java.security.Signature sig = java.security.Signature.getInstance(
"SHA1WithRSA");
sig.initVerify(publicKey);
sig.update(data.getBytes());

return sig.verify(base64Bytes);
} catch (Exception e) {
//Exception…
}
return false;
}

3.4 Response Code Detail
No
Response
Code
Description
1
00
Transaction Successfully
2
11
Invalid parameter (mandatory fields are missing such as MSISDN, Transaction
Amount
3
12
Partner Balance is not enough for transaction
4
13
MSISDN does not exist or is not in required format
5
14
Transaction Amount or Transaction Currency is invalid
6
15
Partner Balance Deduction Error
7
44
MSISDN is a postpaid subscriber (cannot topup)
8
48
Subscriber does not exist or cannot query subscriber information

9
67
Error in querying transaction information
10
70
Message is in invalid form or mandatory fields are missing ((Message Type,
Client ID, Process Code,SystemTrace Audit Number)
11
71
System Trace Audit Number is invalid
12
72
Duplicated message (non-Resend message with similar SystemTrace)
13
75
Exceed maximum allowed concurrent transaction
14
80
PartnerID is not registered
15
81
Service (Process Code) is not registered
Payment Gateway – Technical Specification v1.0
Payment Gateway – Technical Specification 11/18
16
82
Exceed maximum allowed concurrent connection
17
83
Fail to verify signature

18
84
Transaction Timeout
19
85
Cannot query subscriber information to transfer to Core Network Switch
20
86
Core Network Switch are busy
21
87
Configuration information is not enough to perform transaction
22
88
Transaction does not exist (in case of using Query Message)
23
90
Cannot perform transaction at Billing System
24
91
Service (Process Code) does not exist
25
92
Error in Payment Gateway Database
26
93
Transaction is processing
27
95
Error in connection with Core Network Switch

28
96
Error in connection with Billing System
29
99
Payment Gateway System is being upgraded

4 ISO 8583 API
4.1 List of messages
No
Message
Source
MTI
Query
Resend
Process Code
1
Network Checking (Ping)
Client
0800


000000
2
Topup for prepaid subscriber
Client
0200
x
0201
000000

4.2 ISO 8583 Message Detail
M – Mandatory
O – Optional
4.2.1 Network Checking (Ping)
No
Field Name
Order
Request
Response
Description
1
MTI
0
0800
0810
MTI
2
BitMap
1
M
M
Bitmap
3
Process code
3
000000
000000
Service code
4
Transmission

Date/Time
7
M
M
Transaction time
Format: yyyyMMddHHmmss
Example: 20080519204503 –
19/05/2008 at 20h45h03s
5
System Trace Audit
Number
11
O
O
Message ID of each partner
6
Response Code
39

M
Response Code
7
Client ID
63
M
M
Partner ID
8
Message Signature
64

O
O
Message Signature

4.2.2 Topup for prepaid subscriber
No
Field Name
Order
Request
Response
Description
1
MTI
0
0200
0210
MTI
2
BitMap
1
M
M
Bitmap
3
MSISDN
2
M
M
MSISDN of subscriber that being
topup

Example: 258987654321
4
Process code
3
000000
000000
Service code
5
Transaction Amount
4
M
M
Transaction Amount
Left-padding with „0‟ to full
length
6
Transmission
Date/Time
7
M
M
Transaction time.
Format: yyyyMMddHHmmss
Example: 20080519204503 –
19/05/2008 at 20h45m03s
7
System Trace Audit
Number
11
M

M
Message ID of each partner
Left-padding with „0‟ to full
length
8
Response Code
39

M
Response code
Payment Gateway – Technical Specification v1.0
Payment Gateway – Technical Specification 13/18
9
Additional Data
48
O
O
If Partner system want to query
transaction result:
- Set 48
th
field to „query‟
- Set fourth digit of MTI to
1 ( 1: Acquirer Resend)
10
Client ID
63
M
M
Partner ID

11
Message Signature
64
M
M
Message Signature

Payment Gateway – Technical Specification v1.0
Payment Gateway – Technical Specification 14/18
5 Webservice API
APIs of service described as below, which:
M – Mandatory, O – Option
5.1 Topup to prepaid mobile
Method: public String topup(String msg)
Field Name
Inpu
t
Output
Description
<TOPUP>



<MTI/>
0200
0210
MTI
<MSISDN/>
M
M

MSISDN of subscriber that being topup
example: 258987654321
<PROCESS_COD
E/>
0000
00
000000
Process code
<TRANS_AMOU
NT/>
M
M
Transaction Amount.add '0' to the left for full length
<TRANS_TIME/>
M
M
Transmission date time. Format yyyyMMddHHmmss
Example: 20080519204503 is 19/05/2008 20:45:03
<SYSTEM_TRAC
E/>
M

M
Transaction Identify.add '0' to the left for full length
<CLIENT_ID/>
M
M
Partner id
<RESPONSE_CO
DE>

M
Response code
</SIGNATURE>
M
M
Message Signature
</ADD_DATA>
O
M
If partner only query transaction result, partner use this field
with value “query”, MTI formatted by “ 1” (MTI of resend
message)
</TOPUP>




Example:
Input:
<TOPUP><MTI>0200</MTI><MSISDN>855977545444</MSISDN><PROCESS_CODE>0
00000</PROCESS_CODE><TRANS_AMOUNT>10</TRANS_AMOUNT><TRANS_TIM
E>20122911070000</TRANS_TIME><SYSTEM_TRACE>020121220051042</SYSTEM_
TRACE><CLIENT_ID>hanv</CLIENT_ID><SIGNATURE>PHryvUjVwR+vB8eupN+OV
9CMGS24ktH6I1w8FVd/U0hvsGnCEeUoa74NOVtpzy0gRSRImu/nQjthwrS1omKHruMbb
Q1P2EA81lue3imQc+krHa1FjqG5fHBbKm/A5Jx/zJDUJlMBWGmMEL/KWB8/4QRtFVpP
Gzy5+0P48W16+DY=</SIGNATURE><ADD_DATA></ADD_DATA></TOPUP>

Output:
<TOPUP><MTI>0210</MTI><MSISDN>855977545444</MSISDN><PROCESS_CODE>0

00000</PROCESS_CODE>
Payment Gateway – Technical Specification v1.0
Payment Gateway – Technical Specification 15/18
<TRANS_AMOUNT>000000000010</TRANS_AMOUNT><TRANS_TIME>20122911070
000</TRANS_TIME>
<SYSTEM_TRACE>020121220051042</SYSTEM_TRACE><CLIENT_ID>hanv</CLIEN
T_ID><SIGNATURE>
fOqwcHs+beJCPayiGR4BV38cJWCSD2l3swxXkUnFrbLs1+JOr7Z6wFs9uIp5U7Wq6TQJT
ahYBoH09DYl4NYb2
+xvbbDjUoY+fTnFI1udmaXTaLKNI94N/1osbrx/21+ATlYubCcfQuOWv6h//9b8ATRpXGf
n/m3FMrYIsiZ4kL4=</SIGNATURE>
<ADD_DATA>null</ADD_DATA><RESPONSE_CODE>00</RESPONSE_CODE></TOP
UP>

6 RECONCILIATION
6.1 Reconciliation regulations
6.1.1 General regulation
- Using FTP server of Telco to keep reconcile files
o Each partner will see 2 subfolders:
 <Telco>: is folder that store file exported by Payment Gateway System, partner
is just allowed to read.
 partner: this folder is used by Partner System to upload file to server with
writeable permission.
o Processing reconcile files and back up periodically:
 After being processed, partner‟s reconcile files will be moved to backup folder.
 If there is not any error with the file, it will be moved to subfolder
PROCESSED of the correlative file folder.
 If there is any error with the file it will be moved to subfolder ERROR of the
correlative file folder
 Everyday, Payment Gateway System will move files dated for more than 30

days to back up folder. The link to backup folder is
Telco/backup/transaction/hour
o Partner downloads reconcile files from Payment Gateway System to get data for
reconciliation.
- Regulation on uploading data to FTP server:
o Partner uploads reconcile files to FTP server. Both parties upload files to
temporary folder firstly to avoid the case that while file is being uploaded, Telco
(partner) downloads data to process. This temporary folder is created by Telco
(Partner) on FTP server. After file is uploaded in contemporary folder, it will be
moved to main folder in FTP folder.
6.1.2 Reconciliation Process
- Both parties export and process reconcile files hourly. There is one type of
reconciliation file for all services
- Frequency: 15minutes/file. If there is not transaction, it is no need to create file.
- FTP server: Telco‟s FTP server
o IP: 10.58.4.22
o Port: 21
- Folder :
o Telco exports reconcile file to folder: /Telco/transaction/hour
o Partner exports reconcile file to folder: /partner/transaction/hour
Payment Gateway – Technical Specification v1.0
Payment Gateway – Technical Specification 17/18
- Regulation on naming the file: yyyymmddhh24miss_[telco]_[sequence].cdr
o In which [telco] is (client_id) or “STL”, time (24 hours).
o Example:
 Telco‟s file: 20111019140930_STL_000012.cdr: is the file with ordinal number
12 which is uploaded at 14:09:30 19/10/2011.
 20111019140930_client_000012.cdr: is the file with ordinal number 12 which
is uploaded at 14:09:30 19/10/2011 of partner whose client_id = “client”
6.2 Reconciliation File Format

- Each transaction‟s datafield are separated by “:”
- Each transaction is exported in one row with enough quantity of “:” even though the
field‟s value is null
- Each row has the last field as checksum ( to check entireness of the line)

No
Field Name
Null able
Data Format
Description
1
Client ID
Not null

Client id
2
Processing Code
Not null

Service id
3
Message Type
Not null

Message Type
4
System Trace Audit
Number
Not null

System Trace Audit Number
of the transaction
5
MSISDN/Customer Code
Not null
856*********/ **
MSISDN/Customer Code
6
Transaction Amount
Not null

Transaction amount
7
Response Code
Not null

Response Code
8
Request Transmission
Time
Not null
Yyyymmddhh24mi
ss
Request Transmission Time
9
Response Transmission
Time

Yyyymmddhh24mi
ss

Response Transmission Time
1
0
Telecom type








Telecom type
1: Prepaid
0: Postpaid
1
1
Checksum row
Not null

to check row‟s entireness
Checksum row =
HEXA(MD5([row data]+
mac_key))

Payment Gateway – Technical Specification v1.0
Payment Gateway – Technical Specification 18/18
- Each file has one row as checksum file (to check file‟s entireness), this row is at the
end of the file. Checksum file‟s format is: EOF:[checksum file]
o Checksum file = HEXA(MD5(count + mac_key))

In which:
 HEXA is a function to convert byte array to hexa.(upper case)
 MD5: is function create hash by md5 algorithm
 count: is total number of data rows ( row with 9 data fields) in file
 mac_key: the key provided partner by Payment Gateway System
6.3 Sample Code
- MD5 function in java:
MessageDigest msgDigest = java.security.MessageDigest.getInstance("MD5");
msgDigest.update(data.getBytes());
return msgDigest.digest();
- HEXA function in java:
private static String byteToHex(byte[] data) {
StringBuilder buf = new StringBuilder();
for (int i = 0; i < data.length; i++) {
int halfbyte = (data[i] >>> 4) & 0x0F;
int two_halfs = 0;
do {
if ((0 <= halfbyte) && (halfbyte <= 9)) {
buf.append((char) ('0' + halfbyte));
} else {
buf.append((char) ('a' + (halfbyte - 10)));
}
halfbyte = data[i] & 0x0F;
} while (two_halfs++ < 1);
}
return buf.toString();
}