Payment gateway technical specification v1 01

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. SHA1: 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 SHA1 is a 160 bitslength 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.

Trang 1

VIETTEL GROUP

TECHNICAL SPECIFICATION DOCUMENT

PAYMENT GATEWAY

Release: 1.0

HaNoi, Jun -2013

Trang 2

Payment Gateway – Technical Specification v1.0

Payment Gateway – Technical Specification 2/18

CONTENT

Trang 3

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

Trang 4

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

Trang 5

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

Trang 6

3.1.1 Datafields Detail

ure

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),

48th Datafield is used to define a message is Query message of Resend message In Query message 48th 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)

Trang 7

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: 11th 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

Trang 8

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:

-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:

0- Request message

1- Response message

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

-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 (authenticityand 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 (64th field)

Trang 9

- 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 11th 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);

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());

Trang 10

byte[] signature = sig.sign();

// Encrypt data

encryptData = new String(Base64.encode(signature));

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);

//Exception…

}

return false;

}

3.4 Response Code Detail

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

Trang 11

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

Trang 12

4 ISO 8583 API

4.1 List of messages

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)

3 Process code 3 000000 000000 Service code

4 Transmission

Date/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

8 Message Signature 64 O O Message Signature

4.2.2 Topup for prepaid subscriber

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

Trang 13

9 Additional Data 48 O O If Partner system want to query

transaction result:

- Set 48th field to „query‟

- Set fourth digit of MTI to

1 ( -1: Acquirer Resend)

11 Message Signature 64 M M Message Signature

Trang 14

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)

t

<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

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:

Định dạng
Số trang	18
Dung lượng	629,32 KB