Đang tải... (xem toàn văn)
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.
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 [...]... Response code Payment Gateway – Technical Specification v1. 0 9 Additional Data 48 O O 10 Client ID 63 M M If Partner system want to query transaction result: - Set 48th field to „query‟ - Set fourth digit of MTI to 1 ( -1: Acquirer Resend) Partner ID 11 Message Signature 64 M M Message Signature Payment Gateway – Technical Specification 13/18 Payment Gateway – Technical Specification 5 v1. 0 Webservice... Gzy5+0P48W16+DY= Output: 02108559775454440 00000 Payment Gateway – Technical Specification 14/18 Payment Gateway – Technical Specification v1. 0 00000000 0010 2012 2911070 000 0 2012 1220051042hanv fOqwcHs+beJCPayiGR4BV38cJWCSD2l3swxXkUnFrbLs1+JOr7Z6wFs9uIp5U7Wq6TQJT... folder: /partner/transaction/hour Payment Gateway – Technical Specification - v1. 0 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: 2011 1019 140930_STL_00 0012 .cdr: is the file with ordinal number 12 which is uploaded at 14:09:30 19/10/ 2011 2011 1019 140930_client_00 0012 .cdr: is the file with ordinal... ss Yyyymmddhh24mi ss MSISDN/Customer Code Response Transmission Time Telecom type 1: Prepaid 0: Postpaid 0 Not null 1 Payment Gateway – Technical Specification 17/18 to check row‟s entireness Checksum row = HEXA(MD5([row data]+ mac_key)) Payment Gateway – Technical Specification - v1. 0 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... 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 Payment Gateway – Technical Specification 11/18 4 ISO 8583 API 4.1 List of messages No 1 2 Message Network Checking... null00 Payment Gateway – Technical Specification 15/18 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: : is folder that store file exported by Payment Gateway System, partner is just allowed to read partner: this folder.. .Payment Gateway – Technical Specification v1. 0 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... 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... (halfbyte . TECHNICAL SPECIFICATION DOCUMENT PAYMENT GATEWAY Release: 1.0 HaNoi, Jun -2 013 Payment Gateway – Technical Specification v1. 0 Payment Gateway – Technical Specification. - Partner: Partner system that connect to Payment Gateway. - Payment Gateway System (Topup System): Gateway system that provides payment services (payment, topup, charging ) to Partner. -. 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