Home

NetPayClient Merchant Operation Manual ( for Cross

1. Sample Codes of Signature NetPayClient for Java NetPayClient for Win32 NetPayClient for C NetPayClient for C NetPayClient for PHP Sign refer to chapter3 1 1 signData refer to chapter 3 1 2 signData refer to chapter 3 1 3 Sign refer to chapter 3 1 4 sign refer to chapter 3 1 5 Note For Version 20080515 digital signature should use Function Sign to generate digital signature for a string and the strings should be linked by the following order Mer Ordl TransA mt Curyl d TransDa te TransTim e TransTyp e Countr yld TimeZo ne DSTFlag ExtFla g Priv 32 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FRER HAT Soft 3 2 4 ChinaPay online payment gt gt gt Merchant Page Return Sample Code netpay order callback jsp netpay_order_callback php Useage After the payment has been finished ChinaPay will send transaction response to merchant via client s page link This step of procedure mainly include two parts Page receiving URL and background receiving URL will both receive transaction data including the following fields Take page FORM data for example Information Format ChinaPay will send transaction response to merchant when the payment has been finished Page receiving URL and background receiving URL will both receive transaction data including the following fields T
2. Scuryid Stransdate Stranstype Spriv1 sign for the order Schkvalue sign Smerid Sordid Stransamt Scuryid Stransdate Stranstype sign for a string Schkvalue sign Splain if 1ISchkvalue echo 4 KI exit gt amp Verify Signature Sample Code lt php include_once netpayclient php 29 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay REKET Sflag buildKey PgPubk key if Sflag echo FA SHR exit Smerid _REQUEST merid Sorderno _REQUEST orderno Stransdate _REQUEST transdate Samount _REQUEST amount Scurrencycode _REQUEST currencycode Stranstype REQUEST transtype Sstatus S_REQUEST status Scheckvalue S_REQUEST checkvalue Sgateld S_REQUEST Gateld priv1 REQUEST Priv1 Splain Smerid Sorderno Samount Scurrencycode Stransdate Stranstype Sstatus Scheckvalue verify signature of order Sflag verifyTransResponse Smerid Sorderno Samount Scurrencycode Stransdate Stranstype Sstatus Scheckvalue Sflag verify Splain Scheckvalue if Iflag echo lt h gt WUE 4 AMC lt h2 gt exit gt 3 2 Payment Version 20080515 3 2 1 Payment Connecting URL Merchant can connect with ChinaPay s online payment system by the means of WEB service URL of receiving transaction data is Test Environment http payment test chinapay
3. char OrderStatus 5 20 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay REKET int flag setPubKeyFile app netpay key PubPrk key if it is not set files will be acquired according to NPCDIR environment variables receive digits that ChinaPay returns Merld Ordid TransAmt Curyld TransDate TransType OrderStatus ChkValue sign the verified order flag verifyTransResponse Merld Ordld TransAmt Curyld TransDate TransType OrderStatus ChkValue if flag 0 signature failiure sign a string plainData test sign data flag verifySignData plainData ChkValue ChkValue is return value which ChinaPay sends to merchant if flag 0 signature failure 3 1 4 NetPayClient for C Function Description 3 1 4 1 Key file netpay dll Installed in the corresponding To provide the pathaccording to the need of method of project deploying digital signature MerPrk key Unspecified but needed to deploy Merchant s private function appointed file path and key file name PgPubk key Unspecified but needed to deploy ChinaPay s public function appointed file path and key file name 3 1 4 2 Instruction Installed netpay dll in the corresponding path according to the need of project In the development environment using add citing add netpay dll into project then call it directly 5 http www ChinaPay com Merchant
4. com pay TransGet Production Environment https payment chinapay com pay TransGet 3 2 2 Transaction Flow Gather payment Submit payment Handle payment gt gt e gt Feedback payment information information information information 30 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FRAKT Soft 3 2 3 Merchant gt gt gt ChinaPay online payment Sample Code netpay order submit jsp order submit asp netpay order submit php Usage receiving and encrypting the data sent by netpay order jsp then send it to the gateway interface of ChinaPay s online electric payment platform In this procedure it mainly includes two parts one is the content generated from submitted data the other is the signature of generated content amp Content of Submitting Transaction Data lt form action https payment ChinaPay com pay TransGet METHOD POST gt action here is the URL of submitting transaction data lt input type hidden name Merld value 808080290000001 gt Merld is the Merchant ID assigned by ChinaPay length of 15 bytes necessary lt input type hidden name Ordld value 0000000000000006 gt Order ID merchants submits to ChinaPay length of 16 bytes necessary lt input type hidden name TransAmt value 000000001234 gt Order transaction amount with 2 decimal length of 12 bytes add 0 from the left if inadequate necessary lt input type hidden name Curyld valu
5. if NetPay NETPAY buildKey 999999999999999 0 c key PgPubk key showlnfo gt gt set public key succeed r n r n verify signature for a order if NetPay NETPAY PublicKeyFlag bool flag NetPay NETPAY verifyTransResponse Merld Ordld TransAmt Curyld TransDate TransType OrderStatus ChkValue ChkValue is return value which ChinaPay reponse sends showlnfo gt gt plaintext ostr r n r n showlnfo gt gt ciphertext check r n r n showlnfo gt gt verify signature result r n r n 25 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FRAKT Soft if flag error of signature verification verify signature for a string plainData test sign data if NetPay NETPAY PublicKeyFlag bool result NetPay NETPAY verifyAuthToken plainData ChkValue2 ChkValue2 is return value which ChinaPay reponse sends showlnfo gt gt plaintext ostr r n r n showlnfo gt gt ciphertext check r n r n showlnfo gt gt verify signature result r n r n if flag error of signature verification 3 1 5 NetpayClient for PHP Function Description 3 1 5 1 File List netpayclinet php Installed in the corresponding To provide the pathaccording to the need of user method of deploying digital signature MerPrk key Unspecified but needed to deploy Merchant s private function appointed fi
6. last two numbers of amount s value should be 00 Scuryid the type of the currency used It is a string containing 3 bytes For example 156 represents RMB JPY represents Japanese yen USD represents U S dollar Stransdate the date of the transaction This numeric string is defined with the length of 8 to represent the transaction date with the format of YYYYMMDD Stranstype the transaction type It is a string sized 4 and values between 0001 and 0002 Hereinto 0001 represents payment transaction and 0002 refers to refund transaction Return Value NetPayClient generates a digital signature string with the length of 256 bytes using the input parameter values listed above If the length of input parameter is invalid the function return false Function verifyTransResponse to verify transaction response Function Description function verifyTransResponse Smerid Sordid Samount Scuryid Stransdate Stranstype Sstatus Scheckvaluue Function To verify digital signature is right or not 27 ChinaPay http www ChinaPay com Merchant Manual for Cross Border Settlement REKET TI Parameters Description Smerid merchant ID It is defined as a string with the length of 15 bytes that is assigned by ChinaPay Sordid order number It is specified as a 16 byte long numeric string that is generated by the merchant s system and previously failed transactions co
7. loadlib CHINAPAY DLL QA Netpay dll must be put in the system32 folder Appendix B The Instructions for Payment Interfaces 1 Response for payment results from ChinaPay BgRetUrl URL of receiving background transactions necessary It is used to receive the payment results sent by ChinaPay when cardholders didn t return to merchant s website after paying successfully on the online banking page The address is suggested to use the ip address instead of domain name and external network must be able to access while can t fill any parameters Otherwise it ll affect merchants receiving ChinaPay s background response If merchants need to transfer parameters they could make full use of Priv1 whose length is limited to 60 bytes Before putting the payment interface into operation formally merchants must test whether the BgRetUrl can normally receive ChinaPay s response After receiving ChinaPay s payment results merchant should firstly verify its signature If it s ok then judge whether the value of status equals 1001 Only 1001 means success while other codes mean has not been success yet ChinaPay has two payment results notifications and the background response has retransmission mechanism so merchants system must judge whether the order is repeatable before modifying the order s status in merchants database 2 Priv1 Merchant private field ChinaPay fulfills the same content that merchants send to Ch
8. necessary lt input type hidden name Version value 20080515 gt Version of single enquiry necessary lt input type hidden name Resv value gt Merchant s reserve field lt input type hidden name ChkValue value X X gt ASCII code of 256 bytes necessary lt form gt Digital Signature of Transaction Data Digital signature is required when Merchant sends transaction data to ChinaPay For Version 20060831 signature data should use Function Sign to generate digital signature for a string Names of functions are NetPayClient for Java Sign refer to Chapter 3 1 1 NetPayClient for Win32 signData refer to Chapter 3 1 2 NetPayClient for C signData refer to Chapter 3 1 3 NetPayClient for C Sign refer to Chapter 3 1 4 NetPayClient for PHP sign refer to Chapter 3 1 5 For Version 20080515 digital signature of query transaction should use Function Sign to generate digital signature for a string and the strings should be linked by the following sequence MerlD TransDate Orderld TransType 3 4 4 ChinaPay online query gt gt gt Merchant Server Return Sample Code netpay query result jsp netpay_query_result php Useage ChinaPay s server program will return response to merchant after processing query request In this procedure it mainly includes two parts one is the format of returned information the other is the signature of generated content Specia
9. 0 char Curyld 3 the type of the currency used It is an array of numbers and has a size of 3 For example 156 represents RMB JPY represents Japanese yen USD represents U S dollar char TransDate 8 the date of the transaction This variable is defined as an array of numbers sized 8 and the format defined is YYYYMMDD char TransType 4 the type of the transaction It is a four bytes long array and values between 0001 and 0002 0001 represents payment transaction and 0002 refers to refund transaction char CheckValue 256 check value It is the digital signature value generated by 17 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FRAKT Soft ChinaPay based on the transaction results Return value The value 0 means that the method has been executed successfully Otherwise means failure Verify transaction response verifyTransResponse Function Description int verifyTransResponse char Merld 15 char Ordld 16 char TransAmt 12 char Curyld 3 char TransDate 8 char TransType 4 char OrderStatus 4 char CheckValue 256 Function To verify digital signature of target string Parameters Description String Merld 15 merchant ID It is defined as a string with the length of 15 bytes that is assigned by ChinaPay or the clearing bank when the merchant agrees to use the service provided by ChinaPay String Ordld 1
10. 3 NetPayClient for C erifyAuthToken refer to Chapter 3 1 4 NetPayClient for PHP verify refer to Chapter 3 1 5 Statement For Version 20070129 verifying digital signature of refund transaction should use Function check to verify transaction response and the strings should be linked by OTs http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FRAKT Soft the following order MerlD ProcessDate TransType Orderld RefundAmount Status Priv1 3 4 Query Single Query Version 20080515 3 4 1 Connecting URL Merchant can connect with ChinaPay s system by the means of WEB service URL of receiving transaction data is Test Environment http payment test chinapay com QueryWeb processQuery jsp Production Environment https control chinapay com QueryWeb processQuery jsp In addition as we add extra note that ChinaPay adopts the way of flow control to permit merchant accessing to following conditions should be satisfied Request will be responded only if it is submitted from IP address designated by merchant that has the right to inquire transaction and the interval between two successful enquiries should be longer than the system s set interval Otherwise system will report illegal merchant request Error code 111 Transactions of failure status which are inquired in a fix time should not exceed some volume otherwise system will re
11. 6 order number It is specified as a 16 byte long numeric string that is generated by the merchant s system and previously failed transactions could be paid again String TransAmt 12 transaction amount This variable is defined as a numeric string and has the length of 12 For example the string 000000001234 represents 12 34RMB or 12 34USD in this case NOTE If the value of Curyld is JPY the last two numbers of TransAmt s value should be 00 String Curyld 3 the type of the currency used It is a string containing 3 bytes For example 156 represents RMB JPY represents Japanese yen USD represents U S dollar String TransDate 8 the date of the transaction This numeric string is defined with the length of 8 to represent the transaction date with the format of YYYYMMDD String TransType 4 the transaction type It is a string sized 4 and values between 0001 and 0002 Hereinto 0001 represents payment transaction and 0002 refers to refund transaction String OrderStatus 4 the status of the transaction It is specified as an array of numbers sized4 See the transaction response code table for details String CheckValue 256 check value It is the digital signature value with 256 bytes generated by ChinaPay based on the transaction results Return Value The value 0 means that the method has been executed successfully That is to say it is ChinaPa
12. Chapter 3 1 4 NetPayClient for PHP verifyTransResponse refer to chapter 3 1 5 3 2 5 ChinaPay online payment gt gt gt Merchant Server Return Sample Code netpay_order_feedback jsp netpay order callback php Useage After the payment has been finished ChinaPay will send transaction response to merchant from ChinaPay online payment server 33 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FRAKT Soft Information Format ChinaPay will send transaction response to merchant when the payment has been finished Page receiving URL will receive transaction data Take page FORM data for example lt form name SendToMer method post action gt action here is the URL of submitting transaction data lt input type hidden name merid value 808080290000001 gt lt input type hidden name orderno value 0000000010096806 gt lt input type hidden name transdate value 20080601 gt lt input type hidden name amount value 000000001234 gt lt input type hidden name currencycode value USD gt lt input type hidden name transtype value 0001 gt lt input type hidden name status value 1001 gt lt input type hidden name checkvalue value X X gt lt input type hidden name Gateld value 0001 gt lt input type hidden name Priv1 value Memo gt lt form gt amp Verifying Signature of Response Data After pay
13. Data is applied in the string which generates digital signature String CheckValue Verification value to verify signature of a 256 byte string Return value True represents success otherwise is failure Note This method is in class netpay NETPAY 3 1 4 4 Sample Codes the following code is not verified and only for reference Sign Sample Code 24 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FRAKT Soft string Merld Ordld TransAmt Curyld TransDate TransType ChkValue string plainData ChkValue2 nitializing key file if NetPay NETPAY buildKey 808080290000001 0 c key MerPrk key showlnfo gt gt set privatekey succeed r n r n sign a order if NetPay NETPAY PrivateKeyFlag string ChkValue NetPay NETPAY signOrder Merld Ordld TransAmt Curyld TransDate TransType showlnfo gt gt plaintext ostr r n r n showlnfo gt gt ciphertext ChkValue r n r n sign a string 4 string plainData 8080802900000010000000010273765000000000001156201008060001 if NetPay NETPAY PrivateKeyFlag string ChkValue2 NetPay NETPAY Sign plainData showlnfo gt gt plaintext ostr r n r n showlnfo gt gt ciphertext ChkValue r n r n Verify Signature Sample Code String Merld Ordld TransAmt Curyld TransDate TransType ChkValue String plainData ChkValue2 nitializing key file
14. Function Description rrnnrrrronnovvrrnnnnvnrnrnnnvnrnnnnvnnrnnnnvnrsnnnvvnsennnnn 21 3 1 5 NetpayClient for PHP Function Description srrrrrnnnrvrronnnvnrnrnnrrrrrrnnvnrrnnnnvnrnnnnvvnsennnnn 26 3 2 Payment Version 20080515 sriid aaae e aE R EE EEE EA 30 3 2 1 Payment Connecting URL cccccccccccssssssnnecececesssssneeeececeeseeeeaueeeeceeeeeeeaaeeeeeeeseeesaaaeeees 30 3 2 2 Transaction FOW eraa aaa aa EE aa aAa A a Aaaa ak aAa NETRA 30 3 2 3 Merchant gt gt gt ChinaPay online payment cccssccssssecesssseecesssseeessssseeesssseeeesseeeesses 31 3 2 4 ChinaPay online payment gt gt gt Merchant Page Return rmrannrrnnnronnnvrrnnvrrnnvrrnnnrennnnennn 33 3 2 5 ChinaPay online payment gt gt gt Merchant Server Return rrrrrnnrnnnnvnnnnrrrnnvrrnnnrennnnennn 33 3 3 Refund Version 20070129 sssrinin narani namana iaaa diiy 34 3 3 1 Connecting URL oeiisoesiesans eaaa aa aa aia saaa eaa aa Ra aaaea 34 3 3 2 Transaction FOW irinenn etiske ker d a aagana eiaa rakke 34 3 3 3 Merchant gt gt gt ChinaPay online single refund rrrrrrnnrvrrnnnnvnrnrnnnvnrnnnnrnnrnnnnvnrnnnnvnernnnnnn 35 3 3 4 ChinaPay online single refund gt gt gt Merchant Server Return rrnrrrnnnrrnnvrrnnnrennnrrnnn 36 3 4 Query Single Query Version 20080515 ccccccssccsssccssscccssecessecessecesssecssesceseeceseecesseeesseeesaes 38 3 4 1 Connecting URL wisscccs secede sshecscccscccese neeaae cved ia aceved a eacved i aiaa
15. Manual for Cross Border Settlement ChinaPay REKET TI 3 1 4 3 Method Description Function buildKey to build public key private key Function Description public boolean buildKey String Merld int KeyUsage String KeyFile Function To build public key private key for generating signature or verifying digital signature Parameter Description String Merld merchant ID it is defined as an array of digits with the length of 15 and is assigned by ChinaPay int KeyUsage the way of using public private key fixed value is 0 String KeyFile file path of public private key including file name e g d MerPrk key Return Value true represents correct public private key is found and can use function of digital signature and digital signature verification false represents failure of building public private key can t use function of digital signature and digital signature verification Note The method is in class netpay NETPAY which also can judge the current status of public private key via NetPay NETPAY PrivateKeyFlag or NetPay NETPAY PublicKeyFlag Function signOrder to generate digital signature Function Description public String signOrder String Merld String Ordld String TransAmt String Curyld String TransDate String TransType Function To generate digital signature for inputted parameters Parameters Description String Merld merchant ID It is defined as a string with the length of 15 bytes
16. Merld merchant ID It is defined as a string with the length of 15 bytes that is assigned by ChinaPay String Ordld order number It is specified as a 16 byte long numeric string that is generated by the merchant s system and previously failed transactions could be paid again String TransAmt transaction amount This variable is defined as a numeric string and has the length of 12 For example the string 000000001234 represents 12 34RMB or 12 34USD in this case NOTE If the value of Curyld is JPY the last two numbers of TransAmt s value should be 00 String Curyld the type of the currency used It is a string containing 3 bytes For example 156 represents RMB JPY represents Japanese yen USD represents U S dollar String TransDate the date of the transaction This numeric string is defined with the length of 8 to represent the transaction date with the format of YYYYMMDD String TransType the transaction type It is a string sized 4 and values between 0001 and 0002 Hereinto 0001 represents payment transaction and 0002 refers to refund transaction String OrderStatus the status of the transaction It is specified as an array of numbers sized4 See the transaction response code table for details String CheckValue check value It is the digital signature value with 256 bytes generated by ChinaPay based on the transaction results Return Value true me
17. PI ChinaPay supplied It mainly include three parts Part 1 NetPayClient s functionality and use practice Part 2 The process of all versions of NetPayClient s installation and deployment Part 3 Appendix Show common error codes during the process of program and a few notes on integrating API 1 2 User The manual s target user is ChinaPay merchant member s on line application development personnel the attendants and the administrative personnel 1 3 Operation procedure For developers quick and precise application development ChinaPay recommends the procedures as follows Step 1 Choose the version of NetPayClient which is suitable to merchant s actual demand refer to Chapter2 2 Step 2 Install selected NetPayClient refer to Chapter 3 1 Step 3 Choose desired functions payment query refund refer to Chapter 3 2 3 3 3 4 Step 4 Query the response code appeared during the payment transaction refer to Appendix B Step 5 Finish the operation follow response codes 2 Introduction and use practice of NetpayClient 2 1 Functionality NetPayClient is an API Lib installed on the client side of ChinaPay s authorized merchants It integrates with merchants online system to realize secure online payment between customers merchants and banks It offers functions as follows amp Merchant carries on digital signature to the key information of an order 4 http www ChinaPay com Merchant Manual
18. String sign String Merld String Ordld String TransAmt String Curyld String TransDate String TransType Parameters Description String Merld merchant ID It is defined as a string with the length of 15 bytes that is assigned by ChinaPay or the clearing bank when the merchant agrees to use the service 11 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay REKET TI provided by ChinaPay String Ordld order number It is specified as a 16 byte long numeric string that is generated by the merchant s system and previously failed transactions could be paid again String TransAmt transaction amount This variable is defined as a numeric string and has the length of 12 For example the string 000000001234 represents 12 34RMB or 12 34USD in this case NOTE If the value of Curyld is JPY the last two numbers of TransAmt s value should be 00 String Curyld the type of the currency used It is a string containing 3 bytes For example 156 represents RMB JPY represents Japanese yen USD represents U S dollar String TransDate the date of the transaction This numeric string is defined with the length of 8 to represent the transaction date with the format of YYYYMMDD String TransType the type of the transaction It is a string sized 4 and values between 0001 and 0002 Hereinto 0001 represents payment transaction and 0002 refers to refu
19. aPay who sends the result to the merchant And the merchant will be responsible for the subsequent processing All the other return values indicate the failure of the function and the results can be ignored 3 1 3 3 Sample Code Sign Sample Code the following code is not verified and only for reference include lt stdio h gt include lt stdlib h gt Hinclude netpayclient h 19 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay REKET int main int argc char argv char Merld 16 char Ordld 17 char TransAmt 13 char Curyld 4 char TransDate 9 char TransType 5 char ChkValue 257 int flag setMerKeyFile app netpay key MerPrk key if it is not set files will be acquired according to NPCDIR environment variables Sign a order flag signOrder Merld Ordld TransAmt Curyld TransDate TransType ChkValue if flag 0 signature failure sign a string plainData test sign data flag signData Merld plainData ChkValue ChkValue is the signature of the string if flag 0 I signature failure Verify Signature Sample Code the following code is not verified and only for reference include lt stdio h gt include lt stdlib h gt include netpayclient h int main int argc char argv char Merld 16 char Ordld 17 char TransAmt 13 char Curyld 4 char TransDate 9 char TransType 5 char ChkValue 257
20. aani ieaiaia ances 38 3 4 2 Transaction FIOW iicr asa araa kapeaa Eaa a aadar araa E aada Eaa Ear dan EEAS 38 3 4 3 Merchant gt gt gt ChinaPay online Query rr rannnvnrnnnnvvnrnnnnvnrrnnnnvnrssnnnvnrennnrnssnnnnvnrsnnnvnessnnnnn 38 3 4 4 ChinaPay online query gt gt gt Merchant Server Return rrnnrrnnnrrnnnvnnnnrrrnnvrrnnnrennnrennn 39 Appendix A Common Connection Problems and Solutions c ccccssssccessseeesssseecesssseeesssseeessseeeees 40 1 Inthe development process reported 157 error code rrrnnrrrrnnnnvvrrnnnrvvrrnnnvnrrrnnnvnrnrnnnnnnn 41 2 After payment online how to do if click submit button the page presents Gateway ST RO OEA E T E E A E E 41 3 After payment online how to do if click submit button the page presents The standard data field cannot be blank snrnennrnnonrnnenvnnennnnennrnsnnrnnenrnnenvensnnenennrnsnnrnsensenennenennrnennrnsenresenresenen 41 4 After payment online how to do if click submit button the page presents The merchant s COE is ETAN 1A Pune 41 5 How to deal with the problem that the system report 500 error code during merchant s TESTING PROCESS E E A E AT 41 6 How to deal with the problem that merchant comes to illegal length rrrnrrrrrnnnvrnnnnnn 41 7 What s the problem that ERRORCODE 110 errnnvrvernnnnvnronnnvvrrnnnnvnrnnnnnvnrnnnnnvnrnnnnnnssnnnnnnsennn 42 8 How to deal with the problem that AXTIVEX control can t create object
21. action This numeric string is defined with the length of 8 to represent the transaction date with the format of YYYYMMDD String TransType the type transaction It is a string sized 4 and values between 0001 12 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FR ERAT Soft and 0002 Hereinto 0001 represents payment transaction and 0002 refers to refund transaction String OrderStatus the status of the transaction It is specified as an array of numbers sized 4 See the transaction response Code De for details String CheckValue check value It is the digital signature value with 256 bytes generated by ChinaPay based on the transaction results Return Value The value O means that the method has been executed successfully That is to say it is ChinaPay who sends the result to the merchant And the merchant will be responsible for the subsequent processing All the other return values indicate the failure of the function and the results can be ignored or simply put into the garbage bin Note If COM is called method return value is O in string means signature verification successful If COM is not called load netpay dll with LoadLibrary need to find corresponding name with Dependency Walker Function signData to generate digital signature for a string Function Description public String Sign String Merld String SignMsg Parame
22. ake page FORM data for example lt form name SendToMer method post action gt action here is the URL of submitting transaction data lt input type hidden name merid value 808080290000001 gt lt input type hidden name orderno value 0000000010096806 gt lt input type hidden name transdate value 20080601 gt lt input type hidden name amount value 000000001234 gt lt input type hidden name currencycode value USD gt lt input type hidden name transtype value 0001 gt lt input type hidden name status value 1001 gt lt input type hidden name checkvalue value X X gt lt input type hidden name Gateld value gt lt input type hidden name Priv1 value Memo gt lt form gt Verifying Signature of Response Data After payment transaction is finished ChinaPay will send result information to merchant which can be received by both page receiving URL and background receiving URL Merchant should verify its signature to confirm whether this response is sent by ChinaPay To different versions of NetPayClient the realize codes of verifying signature of response data are different They are showed as follows NetPayClient for Java verifyTransResponse refer to Chapter 3 1 1 NetPayClient for Win32 check refer to Chapter 3 1 2 NetPayClient for C verifyTransResponse refer to Chapter 3 1 3 NetPayClient for C verifyTransResponse refer to
23. al for Cross Border Settlement ChinaPay FRAKT Soft 205 Repeat submitting the transaction 301 Inquired transaction does not exist 302 Inquiry database error 303 Response data package error 304 Response data string transformation error 305 Exceed volume control range 307 Corresponding data is not found Original transaction doesn t exist The transaction date in 402 the refund request should be the date when the payment transaction happened 404 Other internal errors ChinaPay E Payment Service Co Ltd 2013 04 03 http www ChinaPay com 47
24. ans success That is to say it is ChinaPay who sends the result to the merchant And the merchant will be responsible for the subsequent processing All the other return values indicate the failure of the function and the results can be ignored or simply put into the garbage bin Note This method is in class chinapay SecureLink Function Sign to generate digital signature for a string Function Description public String Sign String SignMsg http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay RIKET TI Function To generate digital signature for inputted string of parameters Parameters Description String SignMsg is applied in the string for signature Return value String CheckValue 256 It is a digital signature string with the length of 256 bytes It is generated using the input parameter values listed above Note This method is in class chinapay SecureLink Function verifyAuthToken to verify signature for a string Function Description public boolean verifyAuthToken String PlainData String CheckValue Function To verify the digital signature of target string Parameters Description String PlainData is applied in the string which generates digital signature String CheckValue Verification value to verify signature of a 256 byte string Return value True represents success otherwise is failure Note This method is in class chinapay SecureLink 3 1 1 3 Sample code
25. arbage bin Function sign to generate digital signature for a string Function Description function sign Smsg Function To generate digital signature for inputted string of parameters Parameters Description Smsg is applied in the string for signature Return Value NetPayClient generates a digital signature string with the length of 256 bytes using the input parameter values listed above Function verify to verify signature for a string Function Description 28 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay RIKET TI function verify Splain Scheckvalue Function To verify the digital signature of target string Parameters Description Splain is applied in the string which generates digital signature Scheckvalue Verification value to verify signature of a 256 byte string Return Value True represents success otherwise is failure 3 1 5 3 Sample Codes the following code is not verified and only for reference Sign Code lt php include_once netpayclient php Smerid buildKey MerPrk key if Smerid echo A WHR exit Sordid 00 date YmdHis Stransamt padstr 1 12 Scuryid 156 Stransdate date Ymd Stranstype 0001 Sversion 20070129 Spagereturl Ssite url netpayclient order feedback php Sbgreturl site url netpayclient order feedback php Splain Smerid Sordid Stransamt
26. c string and has the length of 12 For example the string 000000001234 represents 12 34RMB or 12 34USD in this case NOTE If the value of Curyld is JPY the last two numbers of TransAmt s value should be 00 String Curyld the type of the currency used It is a string containing 3 bytes For example 156 represents RMB JPY represents Japanese yen USD represents U S dollar String TransDate the date of the transaction This numeric string is defined with the length of 8 to represent the transaction date with the format of YYYYMMDD String TransType the transaction type It is a string sized 4 and values between 0001 and 0002 Hereinto 0001 represents payment transaction and 0002 refers to refund transaction Return Value String CheckValue 256 It is a digital signature string with the length of 256 bytes It is generated using the input parameter values listed above Note The method is in class chinapay SecureLink 6 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FREAK HAT Sct Function verifyTransResponse to verify transaction response Function Description public boolean verifyTransResponse String Merld String Ordld String TransAmt String Curyld String TransDate String TransType String OrderStatus String CheckValue Function To verify digital signature for inputted parameters Parameters Description String
27. ction It is specified as an array of numbers sized4 See the transaction response code table for details String CheckValue check value It is the digital signature value with 256 bytes generated by ChinaPay based on the transaction results Return Value true means success That is to say it is ChinaPay who sends the result to the merchant 23 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FRAKT Soft And the merchant will be responsible for the subsequent processing All the other return values indicate the failure of the function and the results can be ignored or simply put into the garbage bin Note This method is in class netpay NETPAY Function Sign to generate digital signature for a string Function Description public String Sign String SignMsg Function To generate digital signature for inputted string of parameters Parameters Description String SignMsg is applied in the string for signature Return value String CheckValue 256 It is a digital signature string with the length of 256 bytes It is generated using the input parameter values listed above Note This method is in class netpay NETPAY amp Function verifyAuthToken to verify signature for a string Function Description public boolean verifyAuthToken String PlainData String CheckValue Function To verify the digital signature of target string Parameters Description String Plain
28. de is not verified and only for reference Sign Sample Codes using System using ChinaPay tsl namespace ConsoleApplication1 class Class1 STAThread public static void Main Sign NetPayClientClass a new NetPayClientClass Set private key path a setMerKeyFile D MerPrK key if this method is not called it will proceed according to the default path String ChkValue String Merld merchant id Sign order ChkValue a sign Merld 0000000000000001 000000001234 156 20070123 0001 Sign a string String ChkValue2 String plainData test sign data ChkValue2 a signData Merld plainData 14 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FRAKT Soft Verify Signature Sample Codes using System using ChinaPay tsl namespace ConsoleApplication1 class Class1 STAThread public static void Main verify signature NetPayClientClass a new NetPayClientClass set private key path a setPubKeyFile D PgPubk key if this method is not called it will proceed according to the default path String ChkValue String Merld merchant id sign order string flag a check Merld 070699060500011 000000010000 156 20070615 0001 1001 ChkValue ChkValue is return value which ChinaPay sends to merchant sign a string String ChkValue2 String plainData test sign data string flag a checkData plainData C
29. e 156 gt Order transaction currency length of 3 bytes for example 156 represents RMB JPY represents Japanese yen USD represents U S dollar necessary lt input type hidden name Countryld value 0086 gt Country code 4bytes telephone number code necessary lt input type hidden name TransDate value 20080601 gt Order transaction date length of 8 bytes necessary lt input type hidden name TransType value 0001 gt Transaction type length of 4 bytes necessary lt input type hidden name Version value 20080515 gt payment connection version necessary lt input type hidden name BgRetUrl value http www example com pay Bgreturn jsp gt CURL of receiving background transactions within 80 bytes necessary lt input type hidden name PageRetUrl value www example com pay Pgreturn jsp gt URL of receiving page transaction within 80 bytes necessary lt input type hidden name Gateld value gt Payment gateway number optional lt input type hidden name Priv1 value Memo gt Merchant private field within 60 bytes lt input type hidden name TimeZone value 06 gt Eastern time zone is western time zone is 3bytes necessary lt input type hidden name TransTime value 122340 gt transaction submit time 6 bytes necessary lt input type hidden name DSTFlag value 1 gt flag of summer time 1 represents summer time 0 represents no neces
30. e2 ChkValue2 is return value which ChinaPay reponse sends if flag1 error of signature verification 3 1 2 NetPayClient for Win32 Function Description 3 1 2 1 Key file Path Usage Name netpay dll The same path as ChinaPay dll To provide the or copy the file to function of order sign c winnt system32 c windows s_ and ChinaPay s ystem for win95 98 etc signature verification http www ChinaPay com netpay lib MerPrk key PgPubk key ChinaPay dll Installation procedure Merchant Manual for Cross Border Settlement Unspecified such as c netpay Copy to the same path windows c winnt for NT c windows for win95 98 Unspecified but needed deploy function appointed location and file name Copy to the same path windows c winnt for NT c windows for win95 98 Unspecified but needed as OR or to as OR or to deploy function appointed file path and file name Unspecified such as c netpay ChinaPay 3 REETZ TI This file is required when invoking netpay dll for compiling Merchant s key private ChinaPay s public key Method package with netpay dll in COM need to register with regsvr32 Decompress NetPayClinet for Win32 rar according to installation explanation Install manually If there is exception thrown out during installation probably due to the system abnormity you may need to follow the procedures below to install the software manual
31. en send it to ChinaPay s URL of receiving transaction data In this procedure it mainly include two parts one is the content of single refund generated from submitted data the other is the signature of generated content Special codes are as follows Content of Submitting Single Refund Data lt form action https console chinapay com refund SingleRefund jsp METHOD POST gt action here is the URL of submitting refund data lt input type hidden name MerlD value 808080290000001 gt Merld is the Merchant ID assigned by ChinaPay length of 15 bytes necessary lt input type hidden name TransType value 0002 gt Transaction Type 0002 represents refund request necessary lt input type hidden name Orderld value 0000000010096806 gt Original order ID length of 16 bytes necessary lt input type hidden name RefundAmount value 000000001234 gt Refund amount with 2 decimal length of 12 bytes add 0 from the left if inadequate necessary lt input type hidden name TransDate value 20070801 gt Original transaction date length of 8 bytes necessary lt input type hidden name Version value 20070129 gt Version of single refund necessary lt input type hidden name ReturnURL value http www example com back1 jsp gt URL of receiving refund status optional within 100 bytes lt input type hidden name Priv1 value gt Merchant private field necessary within 40 bytes
32. for Cross Border Settlement ChinaPay REKET Merchant verifies the response code sent by ChinaPay Merchant signs a string Merchant verifies the signature of a string 2 2 Types of version Merchant chooses appropriate development platform and operating platform according to his actual situation ChinaPay will offer relative version of NetPayClient Now ChinaPay s NetPayClients are as follows 3 3 1 NetPayClient for Java Cin JAR for Java development NetPayClient for Win32 in DLL for Windows system development NetPayClient for C in so or a for UNIX LINUX FreeBSD etc development NetPayClient for C in DLL for Windows system development NetPayClient for PHP in PHP for PHP development NetpayClient s Installation and invocation NetPayClient s installation 3 1 1 NetPayClient for JAVA Function Description 3 1 1 1 File list netpayclinet jar Installed in the corresponding To provide the pathaccording to the need of method of project deploying digital signature MerPrk key Unspecified but needed to deploy Merchant s private function appointed file path and key file name PgPubk key Unspecified but needed to deploy ChinaPay s public function appointed file path and key file name 3 1 1 2 Method Description Function buildKey to build public key private key Function Description public boolean buildKey String Merld int KeyUsage String KeyFile Function To build public key pri
33. g company 13 What we should do when the 118 mistake occurs QA Generally speaking this mistake does not occur frequently It is mainly because the merchant use the incorrect private key or transmit the wrong parameters to verifying signature method which lead to verify signature error For example the testing merchant use the producing merchant s private key or signature method lead to incorrectly parameter transmitting and verifying signature failure 43 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FRAKT Soft Typical Example One merchant use producing public key when test testing online system result to 118 mistake after modified to testing merchant public key the error removed 14 What about can t receive the background answer QA Checking that whether the response acceptance code have something wrong with the judgment which responsible for judging the qualification of accepting response and ensure the correct accepting response URL when sending transaction 15 How to inform ChinaPay when accept background response successfully QA WEBSEVER feedback automatically generally successfully acceptance will return number 200 automatically so merchant don t need any parameter Only when the value of OrderStatus is 1001 means successful transaction the rest values all mean failing transaction And merchant need to judge this then adds to own database 16 What about the failure of
34. hkValue2 3 1 3 NetPayClient for C Function Description 3 1 3 1 Key File Name Path Usage netpayclient h Unspecified Applied in import file of C language etc libnpc so libnpc a Unspecified Method lib of signature data and signature verification 15 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay REKET apply for so or a according to merchants condition MerPrk key Set NPCDIR environment variable Merchant signature private appointed file path can t change key file name or appoint NPCDIR environment variable but need to call method appointed file path and name PgPubk key Set NPCDIR environment variable ChinaPay signature public appointed file path can t change key file name or appoint NPCDIR environment variable but need to call method appointed file path and name 3 1 3 2 Method Description Set Private Key Path setMerKeyFile Function Description void setMerKeyFile char keyFile 256 Function Set private key path Parameters Description char KeyFile file path of private key including file name e g d MerPrk key Unset private key path unsetMerKeyFile Function Description void unsetMerKeyFile Function Unset previous private key path recover default private key path Parameters Description None amp Set ChinaPay Public Key Path setPubKeyFile Function Description
35. http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay REKET TI NetPayClient Merchant Operation Manual for Cross border Settlement Version 1 2 ChinaPay e Payment Service Co Ltd Tel 86 21 60872088 Fax 86 21 60872000 Website http www ChinaPay com Copyright 2013 4 Chinapay e Payment Service Co Ltd All rights reserved http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay REETZ Revision History Date Verson Deseription Author Adjust the display format and change 2013 04 03 1 2 TransAmt s description when Curyld s Ye qingqing value equals to JPY 2012 08 08 1 1 3 Change from transget to TransGet in the Xi nan fifth question of Appendix A Payment Interfaces 2012 06 28 1 1 2 ul G Appendix A Add Error Code description about 109 120 402 in Appendix C 2011 10 13 Correcting a number of factual details Qi shuangshuang Correcting the description of transtype 0002 Correcting formation of successful response message of Single 2011 09 08 1 1 0 Query Delete superfluous message in Ye qingqing Payment and Refund API Delete the illustration of Refund Response Page Return Correcting a number of factual details and the linked way of strings which are me pea ad used to verifying the refund response Me gIneaIne message 011 07 20 0 1 13 definition of PHP in Chapter dead 2 2 2 2 Change the value of return URL
36. inaPay in this field and returns to merchants In the version of 20070129 this field does not support Chinese and special characters which will affect the signature So the merchants must limit the input type of this field and prevent the cardholders inputting Chinese characters or other special characters 3 Merchant web page tips Suggest cardholders use IE browser amp Suggest cardholders following the page prompts jump back to the merchant site after paying successfully on the online banking page so as to ensure the merchant s 44 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FRAKT Soft system receiving payment results in time amp Suggest cardholders finish payment operation after ordering as soon as possible 4 Merchant change tips If there are changes in merchant s server here are a couple of things to be aware 1 If the domain name changes merchants need to consider updating the following information PageRetUrl and BgRetUrl in payment interface amp Notification addresses in settlement reconciliation and settlement account interfaces Merchants should contact the operation center phone NO 021 61871399 to bind new addresses which will take effect in the next day 2 If IP address changes merchants need to consider updating the following information PageRetUrl and BgRetUrl in payment interface p addresses bound in ChinaPay where merchants launch sing
37. ion public boolean verifyTransResponse String Merld String Ordld String TransAmt String Curyld String TransDate String TransType String OrderStatus String CheckValue Function To verify the digital signature of inputted parameters Parameters Description String Merld merchant ID It is defined as a string with the length of 15 bytes that is assigned by ChinaPay String Ordld order number It is specified as a 16 byte long numeric string that is generated by the merchant s system and previously failed transactions could be paid again String TransAmt transaction amount This variable is defined as a numeric string and has the length of 12 For example the string 000000001234 represents 12 34RMB or 12 34USD in this case NOTE If the value of Curyld is JPY the last two numbers of TransAmt s value should be 00 String Curyld the type of the currency used It is a string containing 3 bytes For example 156 represents RMB JPY represents Japanese yen USD represents U S dollar String TransDate the date of the transaction This numeric string is defined with the length of 8 to represent the transaction date with the format of YYYYMMDD String TransType the transaction type It is a string sized 4 and values between 0001 and 0002 Hereinto 0001 represents payment transaction and 0002 refers to refund transaction String OrderStatus the status of the transa
38. ion succeeded 1005 Refund order cancel succeeded All the other response codes refer to a failed transaction Please check others the detailed description from ChinaPay s Merchant Management System or error information files of banks 11 During the system testing successful payment but occur verifying signature mistake when return to merchant website page QA Firstly the program developing must keep accord to the content of lt lt NetPayClient User Manual gt gt Meanwhile you should care when accepting the response the signature method of version 20070129 and version 20040916 are identical Please pay especial attention to this Typical Example One company s programmer input following content when testing company Because the sending parameter s name is ChkValue when feedback fetch the ChkValue too In fact this parameter should be checkvalue so the transmit parameter value is null and results to failure of verifying signature That is to say Chkvalue request getparameter checkvalue This mistake as a result of the merchant didn t code the program according to lt lt NetPayClient User Manual gt gt 12 What should we do when the failure of initializing public key occurs QA If merchants develop their program in JAVA please check that whether merchants have input the public key number instead of merchant ID Typical Example One company s programmer input following content when testin
39. l codes are as follows Format of success response ResponeseCode value1 amp merid value2 amp orderno value3 amp amount value4 amp cu rrencycode value5 amp transdate value6 amp transtype value7 amp status value8 amp che ckvalue value9 amp Gateld value10 amp Priv1 value11 Format of failure response 39 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FREAK HT Soft ResponeseCode value0 amp Message message string Note Merchant can judge whether the refund is successful via ResponseCode ResponseCode value of 0 represents successful query while other Response codes mean failed query Refer to Appendix B the chapter of error code of single refund Definition of each field in success response ResponeseCode Response code value is 0 merid Merchant ID 15 bytes figure orderno Enquiry Order ID 16 bytes figure amount Transaction amount 12 bytes figure currencycode Transaction currency 3 bytes figure transdate Transaction date 8 bytes figure transtype Transaction type 4 bytes figure status Transaction status 4 bytes figure checkvalue Digital signature 256 bytes Gateld Transaction gateway ID 4 bytes Priv1 Merchant private field Definition of each field in failure response ResponeseCode Response code 3 bytes figure Message Explanation of response code Signature Verification of Response Data ChinaPay will
40. le path and key file name PgPubk key Unspecified but needed to deploy ChinaPay s public function appointed file path and key file name 3 1 5 2 Method Description amp Function buildKey to build public key private key Function Description function buildKey Skeyfile Function To build public key private key for generating signature or verifying digital signature Parameter Description 26 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay REKET Skeyfile file path of public private key including file name e g d MerPrk key support relative path Return Value If build successfully return 15 bytes merchant id else is false Function signOrder to generate digital signature Function Description function signOrder Smerid Sordno Samount Scuryid Stransdate Stranstype Function To generate digital signature for inputted parameters Parameters Description Smerid merchant ID It is defined as a string with the length of 15 bytes that is assigned by ChinaPay Sordno order number It is specified as a 16 byte long numeric string that is generated by the merchant s system and previously failed transactions could be paid again Samount transaction amount This variable is defined as a numeric string and has the length of 12 For example the string 000000001234 represents 12 34RMB or 12 34USD in this case NOTE If the value of curyid is JPY the
41. le query request in single query interface Merchants should contact the operation center phone NO 021 61871399 to bind new ip addresses which will take effect in the next day amp Notification addresses in settlement reconciliation and settlement account interfaces Merchants should contact the operation center phone NO 021 61871399 to bind new addresses which will take effect in the next day Appendix C Response Code Description 1 ChinaPay transaction status code Form 3 ChinaPay transaction status code status Transaction Description code 1001 Purchase transaction succeeded 1003 Refund transaction succeeded 1005 Refund order cancel succeeded All the other response codes refer to a failed transaction Please check others the detailed description from ChinaPay s Merchant Management System or error information files of banks 2 NetPayClient API Error Codes Form 4 NetPayClient API Error Codes status Status Information code All methods 111 Private key path is not set or NPCDIR environment variable is not set Signature methods 100 NPCDIR environment variable is not set 101 Merchant private key file does not exist or can t be opened 102 private key file format error 103 private key merchant id is not compatible with signature merchant id 109 Checking the merchant s signature failure 130 Length of string for signature is blank Signature verificatio
42. lt input type hidden name ChkValue value X X gt ASCII code of 256 bytes necessary lt form gt Statement TransType transaction type 0002 represents refund request which will be rejected if refund amount is greater than original order s amount ReturnURL is response of refund request whose content is optional If merchant needs to be informed when the refund status changes this filed should be filled in Priv1 is merchant private field necessary whose data is defined by merchant but should not be repeated In order to avoid submitting refund request for several times data in this field will be verified if it is repeated If the refund request has been submitted before it is considered that it has been received and will not be processed again 35 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FRAKT Soft Digital Signature of Transaction Data Digital signature is required when Merchant sends transaction data to ChinaPay For Version 20040916 signature data should use Function Sign to generate digital signature for a string Names of functions are NetPayClient for Java Sign refer to Chapter 3 1 1 NetPayClient for Win32 signData refer to Chapter 3 1 2 NetPayClient for C signData refer to Chapter 3 1 3 NetPayClient for C Sign refer to Chapter 3 1 4 NetPayClient for PHP sign refer to chapter 3 1 5 Statement For Version 20070129 digital signat
43. lue String CheckValue check value It is the digital signature value with 256 bytes generated by ChinaPay based on the transaction results 7 What s the problem that ERRORCODE 110 QA Background return URL or Page return URL is too long The length of Background return URL can t over 80 bytes If it is over 80 bytes the system will report 110 error code Advice merchant alter Background return URL and Page return URL limit the length within 80 bytes 8 How to deal with the problem that AXTIVEX control can t create object or DLL is not registered during the development process of ASP QA a Let merchant to check whether the SCRIPT of system XP has been updated to the latest version b Let merchant to check whether lode CHINAPAY DLL and CPNPC DLL correctly and put NETPAY DLL on the SYSTEM32 folder 9 What s the problem that system reports illegal page in the development process QA Submit page should use popup windows If merchant use frame interface that the submission page will not redirect properly that would report illegal page Advising merchant to alter the structure of website and to use popup windows instead of directing in the frame of page 42 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay K FRK Fet 10 When sending transaction some other error report information status Transaction Description code 1001 Purchase transaction succeeded 1003 Refund transact
44. ly Copy all the key files to the specified directory Register ChinaPay dll put in regsvr32 the path of gensign in the command line This control can only work in a VC environment it is suggested to use Dependency Walker to make sure that this DLL file has been set correctly 3 1 2 2 Method Description Set Private Key Path setMerKeyFile Function Description void setMerKeyFile String KeyFile Function 10 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay RIKE Fo Set private key path Parameters Description String KeyFile file path of private key including file name e g d MerPrk key Unset private key path unsetMerKeyFile Function Description void unsetMerKeyFile Function Unset previous private key path recover default private key path Parameters Description None Set ChinaPay Public Key Path setPubKeyFile Function Description void setPubKeyFile String KeyFile Function Set ChinaPay Public Key path Parameters Descripiton String KeyFile file path of private key including file name e g d PgPubk key Unset public key path unsetPubKeyFile Function Description void unsetPubKeyFile Function Unset previous ChinaPay public key path which setPubKeyFile sets recover default public key path Parameters Description None Function sign generate digital signature for order Function Description public
45. ment transaction is finished ChinaPay will send result information to merchant which can be received by both page receiving URL and background receiving URL Merchant should verify its signature to confirm whether this response is sent by ChinaPay To different versions of NetPayClient the realize codes of verifying signature of response data are different They are showed as follows NetPayClient for Java verifyTransResponse refer to Chapter 3 1 1 NetPayClient for Win32 check refer to Chapter 3 1 2 NetPayClient for C verifyTransResponse refer to Chapter 3 1 3 NetPayClient for C verifyTransResponse refer to Chapter 3 1 4 NetPayClient for PHP verifyTransResponse refer to chapter 3 1 5 3 3 Refund Version 20070129 3 3 1 Connecting URL Merchant can connect with ChinaPay s refund system by the means of WEB service URL of receiving transaction data is Test Environment http payment test chinapay com refund1 SingleRefund jsp Production Environment https console chinapay com refund SingleRefund jsp 3 3 2 Transaction Flow Gather refund Submit refund Handle refund Feedback refund information information information information http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay REKET TI 3 3 3 Merchant gt gt gt ChinaPay online single refund Sample Code netpay_refund_submit jsp netpay_refund_submit php Usage Receiving and encrypting the data sent by netpay_refund jsp th
46. n methods 45 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay a FRAT ett 112 ChinaPay public key file does not exist or can t be opened 113 Public key file format error 114 Public key file error 118 Signature verification failure 134 Public key file path set error 3 Query Single Refund Error Codes ERROR CODE ERROR MESSAGE 101 Merchant id error or is blank 102 Order number of transaction response inquiry is blank 103 Transaction date is blank 104 Request transaction type error 105 Merchant id length error 106 Order number length error 107 Transaction date length error 108 Transaction type is blank or length error 109 Version number is blank 110 Version number error 111 Merchant request forbidden 112 Transaction type error 116 Amount is blank 117 Merchant private field length error 118 Signature field error 120 Accumulated refund amount is over original payment amount 121 Refund amount does not equal to original order amount 122 Refund amount should be less than original order amount 123 Total refund amount is more than original order amount 201 Plaintext data is blank 201 Signature data does not exist 202 Signature error 203 Signature verification failure 204 Signature verification data error 46 http www ChinaPay com Merchant Manu
47. nd transaction Return value String CheckValue 256 It is a digital signature string with the length of 256 bytes It is generated using the input parameter values listed above Note If COM is not called load netpay dll with LoadLibrary need to find corresponding name with Dependency Walker amp Function check to verify transaction response Function Description public String check String Merld String Ordld String TransAmt String Curyld String TransDate String TransType String OrderStatus String CheckValue Parameters Description String Merld merchant ID It is defined as a string with the length of 15 bytes that is assigned by ChinaPay or the clearing bank when the merchant agrees to use the service provided by ChinaPay String Ordld order number It is specified as a 16 byte long numeric string that is generated by the merchant s system and previously failed transactions could be paid again String TransAmt transaction amount This variable is defined as a numeric string and has the length of 12 For example the string 000000001234 represents 12 34RMB or 12 34USD in this case NOTE If the value of Curyld is JPY the last two numbers of TransAmt s value should be 00 String Curyld the type of the currency used It is a string containing 3 bytes For example 156 represents RMB JPY represents Japanese yen USD represents U S dollar String TransDate the date of the trans
48. nnrnnonrnnenrnnenrnnnnnrnsnnrnnenrnnennnnenvnnsnnrnsnnrnsenensenvesenen 44 3 Merchant web page tips cccccccccssccccsssseccessssecesesseecesssseeessssseseseueecesssaeeessssseeeseeuseeeseseeees 44 4 Merchant chang tips nisemumenduantuasaneelenarns lesende duse aat 45 Appendix C Response Code DeSCription ccccccccssscccsssscecesssseecessssecesssssecsscseecessaeeeesesseeesseseessesaeeees 45 1 ChinaPay transaction status COdC cccccsscccessssecessseecesssseecesssseeescsseecesesseeesssseeeesssueeesssaaes 45 2 NetPayClient API Error Codes cccccccsssscccsssssecesesseecesssseeessssseceseueecessaueecssssaeseseeueeeeseeeeees 45 3 Query Single Refund Error Code S csscccesssscccssssseeesssscecessssecesssueeeessaeecesesseeeseesaeeeseseeeess 46 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FRAKT Soft 1 Backgrounds NetPayClient is an API Lib installed on the client side of ChinaPay s authorized merchants It integrates with merchants online system to provide secure online payment method between customers merchants and banks Its main functions can be described as follows Bankcard online payments of merchants transaction Merchants refund operation to successful transaction Merchants enquiry operation to existing payment transaction 1 1 Recommendations for use The main purpose of this manual is to help ChinaPay s merchant members to use the A
49. on of each field in success response 36 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay RAK F 3 ResponseCode Response code value is 0 MerID Merchant ID 15 bytes figure ProcessDate ChinaPay s process date 8 bytes figure SendTime Time of ChinaPay sending response 6 bytes figure hhmmss this field is not in digital signature TransType Transaction type 4 bytes figure Orderld Original order ID 16 bytes figure RefundAmount Refund amount 12 bytes figure Status Status of particular refund 1 byte figure 1 Refund request submitted successfully Refund succeed HKN Refund fail Priv1 Merchant s private field maximum 40 bytes Checkvalue Signature verification 256 bytes Definition of each field in failure response ResponseCode Response code 3 bytes figure Message Explanation of response code Signature Verification of Response Data Response data will be sent to merchant when the refund request is successfully submitted or the refund status changes into success or failure After receiving response data merchant should verify the signature to confirm whether this data is sent by ChinaPay using Function check to verify transaction response Names of functions are NetPayClient for Java verifyAuthToken refer to Chapter 3 1 1 NetPayClient for Win32 checkData refer to Chapter 3 1 2 NetPayClient for C verifySignData refer to Chapter 3 1
50. or DLL is not registered during the development process Of ASP ccsscccssssccessseeeesseeeesesseeeessseeeesssaeeesses 42 9 What s the problem that system reports illegal page in the development process 42 10 When sending transaction some other error report information rrnnrrrrrrnvvvrrrnnvvnrnrnn 43 11 During the system testing successful payment but occur verifying signature mistake when return to merchant website page rrrnrrrrrrnnrrrrarnnrvrrnnnnvnrrnnnnvnrnnnnnvnrsnnnvnssnnnnvnsssnnnvnsssnnnssre 43 12 What should we do when the failure of initializing public key OCCUIS rrrrnnnnnnrrnnnnvnrnnnn 43 13 What we should do when the 118 mistake OCCUIS eanrnnonvrnnnnrnnnnrnnenrnnnnnrnennrnnenrnsenvnnenen 43 14 What about can t receive the background ansWer rrnnrvrrnnnnvnnrnnnnvnrnnnnvvnrsrnnvnnrnnnnvnrsnnn 44 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay REETZ 15 How to inform ChinaPay when accept background response successfully 08 44 16 What about the failure of loadlib CHINAPAY DLL cccccccccssssesccssscesesssseeeesssseseesseeeees 44 Appendix B The Instructions for Payment Interfaces cccccccsssccesssseccesssseceessseecesssseeessssaeeessseeeees 44 1 Response for payment results from ChinaPay c cccccssscccessssecesssseeeeseseeecessseeeesssseeesssaees 44 2 Priv1 Merchant private field nrrronrroonnrno
51. port over flow control Error code 305 Therefore when merchant applies for single enquiry function its server s IP address and Merchant ID should be provided 3 4 2 Transaction Flow Gather query information Query Feedback query and submit information 3 4 3 Merchant gt gt gt ChinaPay online Query Sample Code netpay_query jsp netpay_query php Usage Receiving and encrypting the data sent by merchant then send it to ChinaPay s URL of receiving transaction data In this procedure it mainly includes two parts one is the content of query generated from submitted data the other is the signature of generated content Special codes are as follows Content Submitted on Single Enquiry Page lt form action http control chinapay com QueryWeb processQuery jsp METHOD POST gt action here is the URL of submitting enquiry data lt input type hidden name Merld value 808080290000001 gt Merld is the Merchant ID assigned by ChinaPay length of 15 bytes necessary lt input type hidden name TransType value 0001 gt Transaction Type 0001 38 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FREAK HLT Soft represents consumption transaction lt input type hidden name Ordld value 0000000010096806 gt Order ID length of 16 bytes necessary lt input type hidden name TransDate value 20070801 gt Transaction date of the particular order length of 8 bytes
52. ransAmt Curyld TransDate TransType and some relative programs Typical case One company s program s designer input The correct one is lt input type hidden name curyld value 156 gt A word s error contributes to the difficult of data reading That is function can t find the important information included by curyld which contributes to the report of Standard data field can not be blank 4 After payment online how to do if click submit button the page presents The merchant s code is empty QA This problem mainly happened in UPOP as the Merld has not been configured the Id used in UPOP Merchants need to contact the operation center phone NO 021 61871399 to configure this information 5 How to deal with the problem that the system report 500 error code during merchant s testing process QA This error is systematic error which belongs to the error of compiling program That is because merchant mixed test submit URL and official submit URL Typical case When compile programs designer input This is test merchant so the right content after action is http payment test chinapay com that is to say the right input is lt form action http payment test chinapay com pay TransGet method post gt 6 How to deal with the problem that merchant comes to illegal length A http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FRAKT Soft QA Illegal leng
53. s the following code is not verified and only for reference Sign code nitializing key files chinapay PrivateKey key new chinapay PrivateKey chinapay SecureLink t boolean flag String Merld Ordld TransAmt Curyld TransDate TransType ChkValue String plainData ChkValue2 flag key buildKey Merld 0 app usr chinapay keys MerPrk key if flag false System out printin build key error return http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay REKET t new chinapay SecureLink key sign a order ChkValue t signOrder Merld Ordid TransAmt Curyld TransDate TransType sign a string plainData test sign data ChkValue2 t Sign plainData Verify Signature Sample Codes chinapay PrivateKey key new chinapay PrivateKey chinapay SecureLink t boolean flag boolean flag1 String Merld Ordld TransAmt Curyld TransDate TransType ChkValue String plainData ChkValue2 flag key buildKey 999999999999999 0 c winnt PgPubk key if flag false msg build key error return t new chinapay SecureLink key flag1 t verifyTransResponse Merld Ordid TransAmt Curyld TransDate TransType OrderStatus ChkValue ChkValue is return value which ChinaPay reponse sends if flag1 0 I error of signature verification verify signature for a string plainData test sign data flag1 t verifyAuthToken plainData ChkValu
54. s in Sr 10 11 1 1 12 Ye i Payment and Refund Stiki NetPayCli Merch ional 010 09 02 0 1 11 etPayClient_Merc ant Operationa Veainegine Manual oversea version http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay REETZ Contents T B ckgro ndS soenen aa a a teaanelsieundhereaganeseustieee es 4 1 1 Recommendations for USC c cceesceeeseeeeseeceeceeeeaeeeeaeeceaeecesnecesaeeseaeeseaceceaeeceeaeeeeaeeseaeeseeneseeaeenes 4 1 2 ETT EN NE RE NE 4 1 3 Operation procedure isurian iaa a aa aE ee 4 2 Introduction and use practice of NetpayClient rrrnnrrrrnnnnvrrnnnnnvrrnnnnrvnrnnnnnrnrnnnnnnrrnnnnnnrnnnnvnnrnnnner 4 2 1 Functionality sssinsseusashesnesd masnharnsf eerglnnksahasenntamvrdnakesduednkennen 4 2 2 Types of VEPSION wisssccecccsecescccsscescacsecseanssckexcdseodevedancdeuedadecdbadededcaedeladeaeded E 5 3 NetpayClient s Installation and INVOCATION ccesccceeesseceessssecesesseeeeseseecesssseeesesseeeseseeesessaeeeesses 5 3 1 NetPayClient s installation scissa renata aaae aoaaa Ea area na aE REEE eRT A aR 5 3 1 1 NetPayClient for JAVA Function Description rrrrrnnrvrrnonnrvrrnnnnvvrrnnnnvnrnnnnrnrrnnnnvnrsrnnnsnre 5 3 1 2 NetPayClient for Win32 Function Description rrrrrrrnrnnrvrrnnnnvvrrnnnnvnrnnnnvnrrnnnnvnrnrnnnnenn 9 3 1 3 NetPayClient for C Function Description rrrrnnnvvrrnnnnvrrnnnnnvnrnrnnnvnrnnnnvnnrnnnnvnsnnnnvnnsnnnnnn 15 3 1 4 NetPayClient for C
55. sary lt input type hidden name ExtFlag value 00 gt flag of overseas merchant the default value is 00 necessary 31 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay 3 REKET lt input type hidden name Priv2 value priv2 gt Merchant private field 2 within 200 bytes optional lt input type hidden name ChkValue value X X gt ASCII Code with 256 bytes sign for the key data of this transaction necessary lt form gt Note TransAmt Order transaction amount the last two bytes represent decimal e g 000000000123 represents 1 23 monetary unit PageRetUrl URL of receiving page transactions guides users to return to merchant webpage after payment BgRetUrl URL of receiving background transactions for merchants to record transaction information and settlement not visible for users According to the return code of http ChinaPay decides whether to repeat sending Background responses reference number to assure receipt of background response Priv1 Merchant s private field join digital signature in payment of version 20080515 ChinaPay fulfills the same content that merchants send to ChinaPay in this field and returns to merchants Gateld Optional means payment gateway number if it is Gateld payment gateway number users directly enter payment webpage if not users enter gateway selection webpage Ordld means order id it can be defined by merchants
56. send the query information to merchant when completing query transaction using Function check to verify transaction response Names of functions are NetPayClient for Java verifyTransResponse refer to Chapter 3 1 1 NetPayClient for Win32 check refer to Chapter 3 1 2 NetPayClient for C verifyTransResponse refer to Chapter 3 1 3 NetPayClient for C verifyTransResponse refer to Chapter 3 1 4 NetPayClient for PHP verifyTransResponse refer to Chapter 3 1 4 Appendix A Common Connection Problems and Solutions 40 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay REKET 1 In the development process reported 157 error code QA Check to see if GATEID is 0001 if it is delete 0001 2 After payment online how to do if click submit button the page presents Gateway Routing doesn t exsit QA Set Gateld s value to empty and then to submit the order to ChinaPay 3 After payment online how to do if click submit button the page presents The standard data field cannot be blank QA Merchant checks whether every piece of program is written according to lt lt NetPayClient_MerchantOperationManual gt gt When come up with such report it expresses program designer doesn t meet with the manual there are some stupid mistakes such as spelling mistake forgetting to put in important data and so on Remind merchant to check the parameters as follows Merld Ordld T
57. ters Description String Merld Merchant ID It is defined as a string with the length of 15 bytes that is assigned by ChinaPay String SignMsg is applied in the string for signature Return value String CheckValue 256 It is a digital signature string with the length of 256 bytes It is generated using the input parameter values listed above Note If COM is not called load netpay dll with LoadLibrary need to find corresponding name with Dependency Walker Function checkData to verify signature for a string Function Description public String checkData String PlainData String CheckValue Parameters Description String PlainData is applied in the string which generates digital signature String CheckValue Verification value to verify signature of a 256 byte string 13 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FRK Fet Return value 0 represents success otherwise is failure Note If COM is called method return value is O in string means signature verification successful If COM is not called load netpay dll with LoadLibrary need to find corresponding name with Dependency Walker 3 1 2 3 Sample codes Take C for example First transform Com type information into NET digits tlbimp ChinaPay dll out ChinaPay_tsl dll tlbimp is the tool vs net provides in the project if project gt add reference selectcom input ChinaPay_tsl dll the following co
58. th is because of merchant s wrong configuration that the length of parameters is not follow actual demands For example Orderld is not 16 bytes TransDate is not 8 bytes TransAmt is not 12 bytes Checkvalue is not generated and so on all of which may cause illegal length The detail statement of sending parameters is as follows String Merld merchant ID It is defined as a string with the length of 15 bytes that is assigned by ChinaPay or the clearing bank when the merchant agrees to use the service provided by ChinaPay String Ordld order number It is specified as a 16 byte long numeric string that is generated by the merchant s system and previously failed transactions could be paid again String TransAmt transaction amount This variable is defined as a numeric string and has the length of 12 For example the string 000000001234 represents 12 34RMB 12 34JPD or 12 34USD in this case String Curyld the type of the currency used It is a string containing 3 bytes Currently only the value 156 is accepted to represent RMB in the system String TransDate the date of the transaction This numeric string is defined with the length of 8 to represent the transaction date with the format of YYYYMMDD String TransType the transaction type It is a string sized 4 and values between 0001 and 0002 Hereinto 0001 represents payment transaction and 0002 refers to refund transaction Return Va
59. that is assigned by ChinaPay String Ordld order number It is specified as a 16 byte long numeric string that is generated by the merchant s system and previously failed transactions could be paid again String TransAmt transaction amount This variable is defined as a numeric string and has the length of 12 For example the string 000000001234 represents 12 34RMB or 12 34USD in this case NOTE If the value of Curyld is JPY the last two numbers of TransAmt s value should be 00 String Curyld the type of the currency used It is a string containing 3 bytes For example 156 represents RMB JPY represents Japanese yen USD represents U S dollar String TransDate the date of the transaction This numeric string is defined with the 22 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FRAKT Soft length of 8 to represent the transaction date with the format of YYYYMMDD String TransType the type of transaction It is a string sized 4 and values between 0001 and 0002 Hereinto 0001 represents payment transaction and 0002 refers to refund transaction Return value String CheckValue It is a digital signature string with the length of 256 bytes It is generated using the input parameter values listed above Note The method is in class netpay NETPAY Function verifyTransResponse to verify transaction response Function Descript
60. uld be paid again Samount transaction amount This variable is defined as a numeric string and has the length of 12 For example the string 000000001234 represents 12 34RMB or 12 34USD in this case NOTE If the value of curyid is JPY the last two numbers of amount s value should be 00 Scuryid the type of the currency used It is a string containing 3 bytes For example 156 represents RMB JPY represents Japanese yen USD represents U S dollar Stransdate the date of the transaction This numeric string is defined with the length of 8 to represent the transaction date with the format of YYYYMMDD Stranstype the transaction type It is a string sized 4 and values between 0001 and 0002 Hereinto 0001 represents payment transaction and 0002 refers to refund transaction Sstatus the status of the transaction It is specified as an array of numbers sized4 See the transaction response code table for details Scheckvalue check value It is the digital signature value with 256 bytes generated by ChinaPay based on the transaction results Return Value true means that the method has been executed successfully That is to say it is ChinaPay who sends the result to the merchant And the merchant will be responsible for the subsequent processing All the other return values indicate the failure of the function and the results can be ignored or simply put into the g
61. ure of refund transaction should use Function Sign to generate digital signature for a string and the strings should be linked by the following order MerID TransDate TransType Orderld RefundAmount Priv1 3 3 4 ChinaPay online single refund gt gt gt Merchant Server Return Sample Code netpay refund callback jsp netpay refund callback php Useage ChinaPay s server program will return refund request received response to merchant after processing refund request When the status of particular refund changed into success or failure corresponding response will also be sent to merchant In this procedure it mainly includes two parts one is the content of single refund generated from submitted data the other is the verification of returned query information Special codes are as follows Format of success response ResponseCode value0 amp MerID value1 amp ProcessDate value2 amp SendTime value9 amp TransT ype value3 amp O0Orderld value4 amp RefundAmount value5 amp Status value6 amp Priv1 value7 amp Ch eckValue value8 Format of failure response ResponseCode value0 amp Message message string Statement Merchant can judge whether the refund is successful via ResponseCode ResponseCode value of 0 represents successful refund while other Response codes mean failed refund Refer to Appendix B the chapter of error code of single refund Definiti
62. vate key for generating signature or verifying digital signature http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay FRAKT Soft Parameter Description String Merld merchant ID it is defined as an array of digits with the length of 15 and is assigned by ChinaPay int KeyUsage the way of using public private key fixed value is 0 String KeyFile file path of public private key including file name e g d MerPrk key Return Value true represents correct public private key is found and can use function of digital signature and digital signature verification false represents failure of building public private key can t use function of digital signature and digital signature verification Note The method is in the class of chinapay PrivateKey Function signOrder to generate digital signature Function Description public String signOrder String Merld String Ordld String TransAmt String Curyld String TransDate String TransType Function To generate digital signature for inputted parameters Parameters Description String Merld merchant ID It is defined as a string with the length of 15 bytes that is assigned by ChinaPay String Ordld order number It is specified as a 16 byte long numeric string that is generated by the merchant s system and previously failed transactions could be paid again String TransAmt transaction amount This variable is defined as a numeri
63. void setPubKeyFile char keyFile 256 Function 16 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay REETZ Set ChinaPay Public Key path Parameters Description char keyFile file path of private key including file name e g d PgPubk key Unset public key path unsetPubKeyFile Function Description void unsetPubKeyFile Function Unset previous ChinaPay public key path which setPubKeyFile sets recover default public key path Parameters Description None Generate digital signature Function signOrder Function Description int signOrder char Merld 15 char Ordld 16 char TransAmt 12 char Curyld 3 char TransDate 8 char TransType 4 char CheckValue 256 Function To generate digital signature for inputted parameters Parameters Description char Merld 15 merchant ID It is defined as an array of digits with the length of 15 ChinaPay or the clearing bank assigns it to the authorized merchants char Ordld 16 order number It is an array of numbers and has the length of 16 generated by the merchant s system and only the previously failed orders are allowed to be performed again char TransAmt 12 transaction amount It is specified as an array of numbers sized 12 For example the string 000000001234 represents 12 34RMB or 12 34USD in this case NOTE If the value of Curyld is JPY the last two numbers of TransAmt s value should be 0
64. y who sends the result to the merchant And the merchant will be responsible for the subsequent processing All the other return values indicate the failure of the function and the results can be ignored or simply put into the garbage bin 18 http www ChinaPay com Merchant Manual for Cross Border Settlement ChinaPay REKET generate digital signature for a string signData Function Description int signData char Merld 15 char SignMsg char ChkValue 256 Function To generate digital signature for inputted string of parameters Parameters Description char Merld 15 merchant ID It is defined as a string with the length of 15 bytes that is assigned by ChinaPay char SignMsg is applied in the string for signature char CheckValue 256 It is a digital signature string with the length of 256 bytes It is generated using the input parameter values listed above Return value 0 means successful otherwise is error codes Verify signature for a string verifySignData Function Description int verifySignData char PlainData char CheckValue 256 Function To verify the digital signature of target string Parameters Description char PlainData is applied in the string which generates digital signature char CheckValue 256 Verification value to verify signature of a 256 byte string Return value The value 0 means that the method has been executed successfully That is to say it is Chin

NetPayClient Merchant Operation Manual ( for Cross

Contents

Download Pdf Manuals

Related Search

Related Contents