Data Loading...
iPay88 Technical Spec (MT) V1.0.6 copy Flipbook PDF
iPay88 Technical Spec (MT) V1.0.6 copy
138 Views
90 Downloads
FLIP PDF 971.47KB
Online Payment Switching Gateway Technical Specification (Merchant Tokenization) v1.0.6 (For Malaysia Only)
Contents Contents .........................................................................................................................................................1 1
Introduction ............................................................................................................................................3 ePayment .......................................................................................................................................3 Objective.........................................................................................................................................3 Pre-requisite of Merchant Integration .........................................................................................3 Transaction Flow Diagram ............................................................................................................4 Transaction Processing Steps ......................................................................................................5 Rule, Limitation and Constraint ....................................................................................................5
2
Merchant Integration..............................................................................................................................6 URL ................................................................................................................................................6 Logo ...............................................................................................................................................6 Payment Request Parameter .......................................................................................................7 Sample HTML Source (Payment Request) ...................................................................................8 Payment Response Parameters ...................................................................................................9 Sample HTML Source (Payment response) ............................................................................... 10 2.6.1
ASP Sample Code ................................................................................................................... 10
2.6.2
PHP Sample Code ................................................................................................................... 10 Merchant Tokenization ................................................................................................................ 11
2.7.1
Bind Card (BC) ......................................................................................................................... 12
2.7.2
Bind Card & Charge (BCC) ..................................................................................................... 13
2.7.3
Subsequent Charge (SC) ......................................................................................................... 14
2.7.4
Manage Card ........................................................................................................................... 15
2.7.5
Merchant Tokenization’s Token Sharing (MTTS) ................................................................... 21 Backend Post Feature................................................................................................................. 25
2.8.1
Payment Backend Post ........................................................................................................... 25
2.8.2
Unbind Credit Card Backend Post ......................................................................................... 26 Re-query Payment Status Parameters (Response URL to enquiry.asp) .................................. 27
2.9.1
Sample source code for re-query function in ASP ................................................................ 28
2.9.2
Sample source code for re-query function in PHP ................................................................ 29 Re-query Credit Card Information .............................................................................................. 30
2.10.1
Encryption for re-query input parameter .......................................................................... 31
2.10.2
Encryption for re-query output parameter ........................................................................ 32
Re-query Merchant Tokenization Transaction (MTT) ................................................................ 34 2.11.1 3
Encryption for re-query MTT output parameter ................................................................ 35
Security Control .................................................................................................................................... 38
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 1 of 52
Request page signature .............................................................................................................. 39 Response page signature ........................................................................................................... 40 Sample function code to generate iPay88 OPSG Signature ...................................................... 42 4
Reports and Notification ...................................................................................................................... 43 Objective....................................................................................................................................... 43 Transaction Report ...................................................................................................................... 43 Email Notification Disclaimer ..................................................................................................... 43
5
4.3.1
Customer Payment Receipt Email ......................................................................................... 44
4.3.2
Merchant Payment Notification Email ................................................................................... 45
iPay88 OPSG Integration FAQs ............................................................................................................ 46
APPENDIX A. MERCHANT CHECKLIST ....................................................................................................... 49
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 2 of 52
1 Introduction ePayment This document describes the following functionalities of iPay88’s Online Payment Switching Gateway (OPSG) system: ePayment: Multiple payment methods for merchant e-commerce website Reports: Online view transaction report
Objective Enable iPay88’s OPSG merchant to perform multiple payment types for their customers to make online purchase(s).
Pre-requisite of Merchant Integration Follow the guidelines below before integration.
Merchant Code and Merchant Key from iPay88 are required. Merchant to provide Request URL to iPay88 Support team. Registered Request URL must be either IP or domain based.
Note: LocalHost is not allowed.
Important Notice Test transaction must from registered Request URL. Test transaction with amount MYR 1.00. Response URL can be set in request page with ResponseURL field. Backend post URL can be set in request page with BackendURL field. Email notification is NOT guarantee by iPay88 OPSG as it is ISP dependant. (Refer section 4.3 Email Notification Disclaimer) Email notification should not use as action identifier by merchant instead use iPay88 Merchant Online Report to check for payment status. Ensure a technical person is assigned by merchant before integration. Return a copy of completed Merchant Checklist to [email protected] before start integration(Refer to APPENDIX A). Merchant must notify iPay88 Support team the intended live date of merchant account minimum 3 working days in advance.
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 3 of 52
Transaction Flow Diagram iPay88 Direct Link Integration Flow
START
Merchant website Customer choose products and proceed to check out
Customer select one payment method
MerchantCode PaymentId RefNo Amount Currency ProdDesc UserName UserEmail UserContact Remark Lang SignatureType Signature ResponseURL BackendURL ActionType TokenId
iPay88 website
iPay88 show the payment detail and wait for customer click confirm
Bank website
Navigate to bank s payment page for customer to login and authorize the transaction No Customer Confirm the payment
iPay88 website iPay88 get the payment status from bank and pass it to merchant
Merchant website
Payment success?
Yes Merchant requery payment status from iPay88 for security purpose
Merchant deliver the product to customer
MerchantCode PaymentId RefNo Amount Currency Remark TransId AuthCode Status ErrDesc Signature TokenId CCName CCNo S_bankname S_country BindCardErrDesc
END
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 4 of 52
Transaction Processing Steps Step 1. Merchant sends HTTPs Post Request containing payment details to iPay88 OPSG payment page. Payment Details contain the following fields:
MerchantCode PaymentId RefNo Amount Currency ProdDesc UserName UserEmail UserContact Remark Lang SignatureType Signature (refer to 3.1) Response URL Backend URL ActionType TokenId
Step 2. User views and confirms payment details entered in Step 1. For credit card payment, the user will need to key-in credit card information. Step 3. User continues to fill in Username and Password at bank website (for non-credit card payment) Step 4. User selects the account to debit the payment. (for non-credit card payment) Step 5. User confirms the payment. If yes, go to next step. (for non-credit card payment) Step 6. User views and prints the payment detail. (for non-credit card payment) Step 7. Response is returned to the iPay88 OPSG website indicating a successful or failed transaction. Step 8. iPay88 OPSG response back the payment status to merchant with a signature Step 9. For successful payment transaction, the merchant needs to compare the signature from iPay88 OPSG. Refer to (3.2)
Rule, Limitation and Constraint
Service Hours: 7x24 exclude host down time
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 5 of 52
2 Merchant Integration URL iPay88 OPSG payment posting URL (payment page) URL: https://www.mobile88.com/ePayment/entry.asp iPay88 OPSG payment re-query URL: https://www.mobile88.com/ePayment/enquiry.asp iPay88 OPSG merchant tokenization credit card re-query URL URL: https://www.mobile88.com/ePayment/WebService/MerchantTokenization/Requery.asmx iPay88 OPSG merchant tokenization manage card URL URL: https://www.mobile88.com/ePayment/MerchantTokenization/manageCard.asp iPay88 OPSG merchant tokenization transaction (MTT) re-query URL URL: https://www.mobile88.com/ePayment/WebService/MerchantTokenization/RequeryTrx.asmx Merchant Request URL: [provided by merchant before the integration] Definition: Merchant Request URL is a checkout page at merchant website that submits the required parameter/value to iPay88 OPSG. Merchant Response URL: [can be specify with ResponseURL in request page] Definition: Response page URL is the page at merchant website that will receive payment status from iPay88 OPSG.
Logo iPay88’s OPSG allow merchant logo/banner to appear in payment page and email notification. Merchant can provide the logo to iPay88 Support team and upload to merchant account. The maximum allow size for the logo is 600 pixel (width) by 100 pixel (height) and the allow format are JPG, BMP, and GIF.
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 6 of 52
Payment Request Parameter Merchant HTTPS POST payment request parameters to iPay88 OPSG Size
M/O
20
M
The Merchant Code provided by iPay88 and use to uniquely identify the Merchant.
M
Refer to Appendix I.pdf file for MYR gateway.
M
Unique merchant transaction number / Order ID across the system
M
Payment amount with two decimals and thousand symbols. Example: 1,278.99
5
M
Refer to Appendix I.pdf file for MYR gateway.
String
100
M
Product description
UserName
String
100
M
Customer name
UserEmail
String
100
M
Customer email for receiving receipt
UserContact
String
20
M
Customer contact number
Remark
String
100
O
Merchant remarks
Field Name
name="ePayment" action="https://www.mobile88.com/ePayment/entry.asp">
Note: Do not copy and paste the code above as it just a reference only
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 8 of 52
Payment Response Parameters HTTPS POST response from iPay88 OPSG after performing payment M/O
Description
M
The Merchant Code provided by iPay88 and use to uniquely identify the Merchant.
M
Refer to Appendix I.pdf file for MYR gateway.
M
Unique merchant transaction number / Order ID across the system
M
Payment amount with two decimals and thousand symbols. Example: 1,278.99
5
M
Refer to Appendix I.pdf file for MYR gateway.
String
100
O
Merchant remarks
TransId
String
30
O
iPay88 OPSG Transaction ID
AuthCode
String
20
O
Bank’s approval code
1
M
Payment status “1” – Success “0” – Fail
100
O
Payment status description (Refer to Appendix I.pdf)
100
M
SHA-256 signature (refer to 3.2)
16
O
Unique id assigned by iPay88 for the bind card. If error occurred, no value will be returned. Refer to BindCardErrDesc parameter for error description.
200
O
Applicable for credit card payment only. Credit card holder name
16
O
Applicable for credit card payment only. Masked credit card number. First six and last four of credit card number. Eg: 492159xxxxxx4941
100
O
Applicable for credit card payment only. Credit card issuing bank name
100
O
Applicable for credit card payment only. Credit card issuing country
100
O
Bind card error description
Field Name
value="http://www.abc.com/backend_response.asp"> On the ‘backend_response.asp’ page you need to write out the word ‘RECEIVEOK’ only (without quote) as an acknowledgement once the backend page success get the payment status from iPay88 OPSG and update status to success on merchant system. iPay88 OPSG will re-try send the payment status to the ‘backend_response.asp’ page up to 3 times on different interval if no ‘RECEIVEOK’ acknowledgement detected. Example: In ASP >> response.write "RECEIVEOK" In PHP >> echo "RECEIVEOK"; Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 25 of 52
Note: 1. 2.
Make sure just the word ‘RECEIVEOK’ only on the backend page and without any HTML tag on the page. The ‘OK’ reply is still accepted which based on previous API revision but it’s recommended to change it to ‘REVEICEOK’
2.8.2 Unbind Credit Card Backend Post 1. 2. 3. 4.
This backend post feature will return success or fail status for unbind credit card. The backend page is not a replacement for the response page. You will still need to continue to use the normal response page as usual. iPay88 OPSG will send the status to the ‘BackendURL’ page for once only. Output parameters for backend post is the same as manage card output (Refer 2.7.4, 2.7.4.1 & 2.7.4.2).
Implementation 1. At manage card page, specify the backend post URL by using "BackendURL" parameter. (Refer to 2.7.4.1) 2. On the “BackendURL” page merchant need to write out the word ‘RECEIVEOK’ only (without quote) as an acknowledgement once the backend page successfully obtain status from iPay88 OPSG Example: In ASP >> response.write "RECEIVEOK" In PHP >> echo "RECEIVEOK"; Note: Make sure just the word ‘RECEIVEOK’ only on the backend page and without any HTML tag on the page.
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 26 of 52
Re-query Payment Status Parameters (Response URL to enquiry.asp) Merchant HTTPS POST re-query payment status parameters to iPay88 OPSG Size
M/O
String
20
M
Merchant Code assigned by iPay88
RefNo
String
30
M
Unique merchant transaction number / Order ID across the system
Amount
Currency
M
Payment amount with two decimals
Field Name
&RefNo=" & RefNo & _ "&Amount=" & Amount URL = "https://www.mobile88.com/ePayment/enquiry.asp" On Error Resume Next Do Set xobj = Server.CreateObject ("Msxml2.ServerXMLHTTP.3.0") xobj.setTimeouts 30000, 60000, 60000, 60000 xobj.open "POST", URL, false xobj.setRequestHeader "Content-Type", "application/x-www-form-urlencoded" xobj.send QString TryNo = TryNo + 1 Loop While xobj.status 200 and TryNo < 3 If xobj.status 200 Then SendToiPayInq = Err.Description & "(" & Err.Number & ")" Else SendToiPayInq = xobj.responseText End If set xobj = nothing End Function %>
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 28 of 52
2.9.2 Sample source code for re-query function in PHP
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 29 of 52
Re-query Credit Card Information A re-query web service API will be provided to merchant to obtain credit card information that are bind into iPay88 OPSG. Refer to 2.1 for the URL. Below are the input parameters to the re-query API: Field Name
Data Type
Size
M/O
Description
param1
String
100
M
Encrypted list of parameters. Refer to 2.10.1
param2
String
24
M
Initialize Vector (IV) for encrypted param1. Refer to 2.10.1
param3
String
20
M
The Merchant Code provided by iPay88 and use to uniquely identify the Merchant.
Field Name
Data Type
Size
M/O
Description
param1
String
100
M
Encrypted list of parameters. Refer to 2.10.2
param2
String
24
M
Initialize Vector (IV) for encrypted param1. Refer to 2.10.2
param3
String
200
O
Error description. If error occur, param1 & param2 will be empty string and param3 will have error description.
Output parameters:
Note: M: Mandatory field O: Optional field, value can be empty but parameter must exist
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 30 of 52
2.10.1 Encryption for re-query input parameter For security purposes, all the parameters to be send over to iPay88 OPSG need to be encrypted. Below is the encryption method used: Algorithm: AES Key length: 128 bits (will be given by iPay88) Block size: 128 bits Operation modus: CBC (Cipher Block Chaining) Padding: PKCS#7
* Sample code can be found in the sample code folder include
VB.Net C# Java PHP
The following are the parameters to be encrypted: Field Name
Data Type
Size
M/O
Description
MerchantCode
String
20
M
The Merchant Code provided by iPay88 and use to uniquely identify the Merchant.
TokenId
String
16
M
Unique id assigned by iPay88 for the bind card
Parameters to be encrypted need to be in accordance of the following with “|” separator and no space in between: [MerchantCode]|[TokenId] Sample: Plain text: M00003|M63YyHHNVbFUMe71 Encrypted text: VOzMTDCS/bm8DduzwfnYc9+coEFUxqMukCQGuozphVY= IV: SVd0t/esbyBR73wnA8cbDA== With the encrypted parameters and IV generated, the value will be pass over to iPay88 as: param1 = VOzMTDCS/bm8DduzwfnYc9+coEFUxqMukCQGuozphVY= param2 = SVd0t/esbyBR73wnA8cbDA== param3 = M00003
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 31 of 52
2.10.2 Encryption for re-query output parameter Since the output parameters contain sensitive information, it need to be encrypted. Below is the encryption method used: Algorithm: AES Key length: 128 bits (will be given by iPay88) Block size: 128 bits Operation modus: CBC (Cipher Block Chaining) Padding: PKCS#7 * Sample code can be found in the sample code folder include VB.Net C# Java PHP The following are the parameters to be encrypted: Field Name
Data Type
Size
M/O
Description
MerchantCode
String
20
M
The Merchant Code provided by iPay88 and use to uniquely identify the Merchant.
TokenId
String
16
M
Unique id assigned by iPay88 for the bind card
CCNo
String
30
M
Masked credit card number. Only first 6 and last 4 credit card number will be shown. Eg: 411111xxxxxx1111
CardType
String
50
M
Type of credit card. Eg: Visa, Mastercard
CardHolderName
String
200
M
Credit card holder name
IssuerBank
String
100
O
Credit card issuer bank
IssuerCountry
String
100
O
Credit card issuer country
Status
Integer
M
Re-query status. 0 = fail 1 = success
ErrDesc
String
200
O
Error description, if status = 0.
CCCOldTokenId
String
16
O
Old token id for customer who changed credit card (ActionType = CCC) before in manage card
Parameters to be encrypted need to be in accordance of the following with “|” separator and no space in between: [MerchantCode]|[TokenId]|[CCNo]|[CardType]|[CardHolderName]|[IssuerBank]|[IssuerCountry]|[Stat us]|[ErrDesc]|[CCCOldTokenId] Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 32 of 52
Sample: Plain text: M00003|M63YyHHNVbFUMe71|411111xxxxxx1111|Visa|Ahmad|Maybank|MY|1||yaIixJGFSEgbQuLH Encrypted text: 1Rvp+VffSEIlO1jjLlZzNLIvyhyAvgbtLLExzCXiBjEDXVppf8G+jhvI+RFlzUYw8YSftUP/rYWhH3E+eKfHg9kQht 2QaY5NnENTp2Kzi4eSkWGN5eU+mtCypQT+NmYu IV: KEHTbW7IpGiuqsjdPBL+Q== With the encrypted parameters and IV generated, the output value will be as below: param1 = 1Rvp+VffSEIlO1jjLlZzNLIvyhyAvgbtLLExzCXiBjEDXVppf8G+jhvI+RFlzUYw8YSftUP/rYWhH3E+eKfHg9kQht 2QaY5NnENTp2Kzi4eSkWGN5eU+mtCypQT+NmYu param2 = KEHTbW7IpGiuqsjdPBL+Q== param3 =
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 33 of 52
Re-query Merchant Tokenization Transaction (MTT) Merchant are able to re-query on merchant tokenization transaction using the web service API. Refer to 2.1 for the URL. Below are the action types that are available in this API: 1. 2. 3. 4. 5. 6.
Bind Card (BC) Bind Card & Charge (BCC) Subsequent Charge (SC) Update Card (UC) Unbind Card (UBC) Change Credit Card (CCC)
Note: All the above action types involved credit card transaction (Pre-Authorization/Capture) only. For non-credit card transaction (eg: online banking) please refer to 2.9 for details on how to perform requery. Below are the input parameters to the re-query API: Field Name
Data Type
Size
M/O
Description
MerchantCode
String
20
M
The Merchant Code provided by iPay88 and use to uniquely identify the Merchant.
RefNo
String
30
M
Unique merchant transaction number / Order ID across the system
Field Name
Data Type
Size
M/O
Description
param1
String
500
M
Encrypted list of output parameters. Refer to 2.11.1
param2
String
24
M
Initialize Vector (IV) for encrypted param1. Refer to Refer to 2.11.1
param3
String
500
O
Error description. If error occur, param1 & param2 will be empty string and param3 will have error description.
Output parameters:
Note: M: Mandatory field O: Optional field, value can be empty but parameter must exist
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 34 of 52
2.11.1 Encryption for re-query MTT output parameter Since the output parameters contain sensitive information, it need to be encrypted. Below is the encryption method used: Algorithm: AES Key length: 128 bits (will be given by iPay88) Block size: 128 bits Operation modus: CBC (Cipher Block Chaining) Padding: PKCS#7 * Sample code can be found in the sample code folder include VB.Net C# Java PHP The following are the parameters to be encrypted: Field Name
Data Type
Size
M/O
Description
MerchantCode
String
20
M
The Merchant Code provided by iPay88 and use to uniquely identify the Merchant.
RefNo
String
30
M
Unique merchant transaction number / Order ID across the system
PaymentId
Integer
O
Refer to Appendix I.pdf file for MYR gateway.
Amount
Currency
O
Payment amount with two decimals and thousand symbols. Example: 1,278.99
Currency
String
5
O
Refer to Appendix I.pdf file for MYR gateway.
Remark
String
100
O
Merchant’s remarks. Eg: Account Number
TransId
String
30
O
iPay88 OPSG Transaction ID
AuthCode
String
20
O
Bank’s approval code
Iplocation
String
50
O
User IPAddress
CardHolderName
String
200
O
Credit card holder name
Creditcardno
String
16
O
Masked credit card number. First six and last four of credit card number. Eg: 492159xxxxxx4941
U_bankname
String
100
O
User input credit card issuer bank
U_country
String
100
O
User input credit card issuer country
S_bankname
String
100
O
System credit card issuer bank
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 35 of 52
S_country
String
ThreeDStatus
Integer
CardType
String
TokenId CCCOldTokenId
ActionType
Status
O
System credit card issuer country
O
Credit card 3D status
50
O
Type of credit card. Eg: Amex, Mastercard
String
16
O
Unique id assigned by iPay88 for the bind card
String
16
O
Old token id for user who changed credit card (ActionType = CCC) before in manage card
O
BC = Bind Card BCC = Bind Card & Charge SC = Subsequent Charge UC = Update Card UBC = Unbind Card CCC = Change Card CMC = Cancel Manage Card
M
100 = Success 200 = Fail 201 = Pending 203 = No record found 204 = Reach maximum daily re-query limit 205 = No action chosen 206 = Failed verification/validation 207 = Invalid TokenId 208 = Cancel manage card
String
Integer
100
50
Parameters to be encrypted need to be in accordance of the following with “|” separator and no space in between: [MerchantCode]|[RefNo]|[PaymentId]|[Amount]|[Currency]|[Remark]|[TransId]|[AuthCode]|[Iplocatio n]|[CardHolderName]|[Creditcardno]|[U_bankname]|[U_country]|[S_bankname]|[S_country]|[ThreeD Status]|[CardType]|[TokenId]|[CCCOldTokenId]|[ActionType]|[Status] Sample: Plain text: M00003_S0009|714201621000PM|2|1,000.00|MYR||T005310450400|657300|188.188.188.172|Leong Chui Li|542634xxxxxx4101|Maybank|MY|PUBLIC BANK BERHAD|MY||Mastercard|Fi4EMnATWBUo4101||BCC|100 Encrypted text: htnNLa4v56HeKf3Uezdbher6HRPavmiw3R9LeItBNJwup6np8wJjjVeeA/3fR647SmVgoEsQ8hIhinpP+X+b E8akZ4xsA8OY29v4+S+0T62OGHz4HEyORaYF8V3j1ytFoi/cs5tMQk1K3IU39RBynJyONHkQN0qBOvgVaHz G01HT6HykvaV6rDYY5jlmX9bHBxjQbiEThx4hjx1nmlLexjG+3sWZ8Qq/BXCNfRFcRxYZHU0/VXAUaKPokqk lXl8K IV: WZyvaiNeZdgWGnatvlwW5g==
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 36 of 52
With the encrypted parameters and IV generated, the output value will be as below: param1 = htnNLa4v56HeKf3Uezdbher6HRPavmiw3R9LeItBNJwup6np8wJjjVeeA/3fR647SmVgoEsQ8hIhinpP+X+b E8akZ4xsA8OY29v4+S+0T62OGHz4HEyORaYF8V3j1ytFoi/cs5tMQk1K3IU39RBynJyONHkQN0qBOvgVaHz G01HT6HykvaV6rDYY5jlmX9bHBxjQbiEThx4hjx1nmlLexjG+3sWZ8Qq/BXCNfRFcRxYZHU0/VXAUaKPokqk lXl8K param2 = WZyvaiNeZdgWGnatvlwW5g== param3 =
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 37 of 52
3 Security Control To enhance security, please go through the following steps at the merchant’s payment status receiving page (Response URL):
Check the HTTP_REFERER value is from https://www.mobile88.com (only applicable if the merchant web site is working with SSL Certificate). Check the payment amount from iPay88 OPSG is match with yours. Compare the Signature from iPay88 OPSG with your own generated Signature.
Data Integrity and Security using Hash Signature SHA-256 hash is a security feature that enables your script to identify the results of a transaction are actually from the appropriate authorization source and also for iPay88 OPSG to make sure the integrity of data received on a transaction request. Using the SHA-256 algorithm, a unique signature or fingerprint of the transaction can be created. This mathematical algorithm used to construct this signature is designed in such a way that any change to the information used in the calculation of the signature will cause a completely different signature to be created. Also, the information used in the calculation of the signature cannot be discovered through any analysis of the signature itself. This is done by using information from your account. Every transaction that is processed through the system has a corresponding hash signature of the transaction created during the transaction process.
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 38 of 52
Request page signature This signature must be included in the request of every transaction. This hash signature for a request is a hash of the following five fields: 1. 2. 3. 4. 5.
MerchantKey (Provided by iPay88 OPSG and share between iPay88 and merchant only) MerchantCode RefNo Amount Currency
The fields must set in the following order, (MerchantKey & MerchantCode & RefNo & Amount & Currency) Example: MerchantKey = “apple” MerchantCode = “M00003” RefNo = “A00000001” Amount = “1.00” (Note: Remove the “.” and “,” in the string before hash) Currency = “MYR” The hash would be calculated on the following string: appleM00003A00000001100MYR The resulting has signature value equals to (using SHA-256 algorithm) 110f0be755ccfa9373aa38104bafbc5c6e5462344e44bcfbb70439c82b4b07fa To ensure the signature generated was correct, visit the link below for signature comparison. http://www.mobile88.com/epayment/testing/testsignature_256.asp
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 39 of 52
Response page signature If the Merchant request is successful, the response message will contain as SHA-256 hashed signature. The hash signature for the response is a hash of the following fields: 1. 2. 3. 4. 5. 6. 7.
MerchantKey (Provided by iPay88 OPSG and share between iPay88 and merchant only) MerchantCode PaymentId RefNo Amount Currency Status
The fields must be set in the following order, (MerchantKey & MerchantCode & PaymentId & RefNo & Amount & Currency & Status) For Example: MerchantKey = “apple” MerchantCode = “M00003” PaymentId = “2” RefNo = “A00000001” Amount = “1.00” (Note: Remove the “.” and “,” in the string before hash) Currency = “MYR” Status = “1” The hash would be calculated on the following string: appleM000032A00000001100MYR1 The resulting has signature value equals to (using SHA-256 algorithm) f173a2521d178574caab19ab7ddd04b299dbc0d656a26c1d1aabf9187dfbf352 To ensure the signature generated was correct, visit the link below for signature comparison. http://www.mobile88.com/epayment/testing/testsignature_response_256.asp
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 40 of 52
When iPay88 OPSG receives the request or transaction order from the merchant, it will check the hash value it generates to match with the value you as a merchant have included. When your script receives the results of the transaction, you can create the hash on your side and be sure that matches ours. As you will already know your Merchant Key and the Merchant Code, and will receive the Ref No which will then be presented to us. Do take note that the signature in the response will only be present if the transaction is not in error, that is, for approved and declined transactions. A developer would then take the results of the transaction AFTER it has been returned to your site, and run the hash algorithm on the fields mentioned above. The only way that the results of a developer’s procession can match the signature included with the transaction results is if the password used in the hash on the developer’s end MATCHES the one used in the transaction. The iPay88 OPSG Merchant Key is a shared secret (between merchant and iPay88 OPSG), and is one of the key pieces of information in the hash. One can be assured that if the signature generated on your end matched the one sent with the transaction, then the transaction has in fact been processed by our system, and has not been posted back to the merchant’s server from any other location. The iPay88 OPSG Merchant Key is generated by us that it’s send to you. The key will only recreate if iPay88 OPSG suspects that the key is not secure or any fraud cases happen.
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 41 of 52
Sample function code to generate iPay88 OPSG Signature Using .NET, you can use the available libraries to perform this: Public Shared Function GenerateSHA256String(ByVal inputString) As String Dim sha256 As SHA256 = SHA256Managed.Create() Dim bytes As Byte() = Encoding.UTF8.GetBytes(inputString) Dim hash As Byte() = sha256.ComputeHash(bytes) Dim stringBuilder As New StringBuilder() For i As Integer = 0 To hash.Length - 1 stringBuilder.Append(hash(i).ToString("X2")) Next Return stringBuilder.ToString().ToLower End Function
Using PHP, you can use the following code to perform this:
* Sample code can be found in the sample code folder include
ASP C# VB.Net PHP Javascript Java
You may utilize the web service at http://www.mobile88.com/ePayment/Security/SHA_256.asmx to fit into your system
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 42 of 52
4 Reports and Notification Objective Allow merchants to login and view the reports online
Transaction Report Step 1.
Merchant can visit iPay88 OPSG report page by keying-in:
Report URL: http://www.mobile88.com/ePayment/report Login: [provided by iPay88 OPSG] Password: [provided by iPay88 OPSG] Step 2. Step 3.
After login, select transaction date The payment transaction report will display on the screen.
Email Notification Disclaimer Note: Email notifications are NOT guaranteed by iPay88 OPSG as it is ISP dependent. Online Report is the primary channel to obtain transaction status. Email notification should not be taken as a replacement of the primary channel. E-mail transmissions cannot be guaranteed to be secure or error-free as information could be intercepted, corrupted, lost, destroyed, arrive late or incomplete, or contain viruses. The sender therefore does not accept liability for any errors or omissions in the contents of the email, which arise as a result of e-mail transmission. iPay88 accepts no liability for the content of the email, or for the consequences of any actions taken on the basis of the information provided, unless that information is subsequently confirmed in writing.
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 43 of 52
4.3.1 Customer Payment Receipt Email Customers will receive a payment detail’s email after successful payment. Below is the email sample: Subject: iPay88 - Payment details (Ref# T0009378700) From: iPay88 Sales ([email protected]) To: John Tan ([email protected])
Date: Thu, 26 Jan 2009 09:59:30 GMT
Dear John Tan, We are pleased to inform you that your online payment via iPay88 is successful. Your credit card/bank account has been debited with RM 1.00. Please note that iPay88 / Mobile88.com will be listed in your credit card/bank statement for this transaction. Transaction Detail Order No: Transaction ID: Transaction Date: Transaction Amount: Payment Type: Product Description:
A00000001 T0009378700 26-1-2006 09:59:30 AM RM 1.00 Credit Card Photo Print
*************************************************************************** Customer Support If you have any questions about our product and services, please contact I & J Sdn Bhd directly at: Tel No: 603-9999 0000 Fax No: 603-9999 0001 Email: support@i&j.com *************************************************************************** Please do not reply to this email as it was automatically generated. If you found any fraudulent cases, please contact iPay88.com Sdn Bhd immediately at Tel: 603-9200 5555 Fax: 603-9200 3333 Email: [email protected]
*iPay88 OPSG is an Online Payment Switching Gateway provided by Mobile88.com Sdn Bhd. For more information, please visit www.ipay88.com
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 44 of 52
4.3.2 Merchant Payment Notification Email The Merchant will also receive a payment notification email after successful payment. In order to ensure you are able received all our mail; do make sure you proceed with the following steps:
From your mailbox, please white-list iPay88 OPSG mail address by adding [email protected] into your friend list. Also, please make sure your mailbox has not blacklisted our address which is the following [email protected] Allow us to serve you better by white listing our email address and domain iPay88.com. Please verify or allow your technical personnel (at the webhosting or email server) to verify the status of your email.
Below is the email sample: Subject: iPay88 - Payment details (Ref# A00000001) From: iPay88 Support ([email protected]) To: ABC Admin ([email protected])
Date: Thu, 26 Jan 2006 09:59:30 GMT
Dear I & J Admin, RefNo: A00000001 One new payment has been collected for ABC Sdn Bhd. Please check the payment report at iPay88 Online Report Customer Detail Name Email Contact
: Ali : [email protected] : 0392005555
Transaction Detail Payment ID: T0009378700 Payment Date Time: 26-1-2006 09:59:30 AM Payment Amount: RM 1.00 Payment Type: Credit Card Product Description: Photo Print Remark: Sincerely, Your iPay88 Team Tel: 603-92005555 Fax: 603-92003333 Email: [email protected]
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 45 of 52
5 iPay88 OPSG Integration FAQs 1.
What method use to pass payment parameters value to iPay88 OPSG? By using the HTTP POST method.
2.
What do I provide to iPay88 OPSG before the integration of a merchant account? Return a copy of completed Merchant Checklist to [email protected] and provide both the Request URL and Response URLs’ of merchant website.
3.
What are the merchant Request URL and Response URL? Request URL is a checkout page at merchant website that passes in iPay88 OPSG parameters to request payment page. Response URL is a page at merchant website that accepts payment status from iPay88 OPSG after transaction.
4.
How do I perform a payment testing during the integration stage? You can use any valid credit card for testing purpose. Details required are the credit card number, expiry date, CVV number and the card holder’s name.
5.
What transaction amount do I use for test payment? Use the following amount for the respective currency code.
Currency Code
Amount
MYR
1.00
USD
1.00
AUD
1.00
CAD
1.00
EUR
1.00
GBP
1.00
SGD
1.00
HKD
2.50
IDR
3000.00
INR
15.00
PHP
15.00
THB
15.00
TWD
15.00
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 46 of 52
6.
What if I get an error message and is unable to reach iPay88 OPSG payment page? Below are the common error messages returned and its respective description: Error Message
Description
Duplicate reference number
Do not re-use Reference Number that previously payment success for transaction.
Invalid merchant code
The merchant code does not exist or incorrect.
Invalid parameters
Some parameter posted to iPay88 OPSG is invalid or empty.
Overlimit per transaction
Payment amount exceeded the value per transaction that assigned to merchant account.
Payment not allowed
Payment method requested is not allowed for the merchant account.
Permission not allow
Referrer URL of transaction request is not same as registered with iPay88 OPSG.
Signature not match
Signature on request page which pass to iPay88 OPSG is incorrectly generated. Refer section 3.1 in iPay88 OPSG Technical Specification for more information about Signature for request page.
Status not approved
Merchant account was suspended or not active.
Bind credit card not found.
Credit card information doesn’t exist.
Invalid amount for bind card
Only RM1.00 is allowed for merchant tokenization (Bind Card)
Bind card & charge not allowed.
Credit card is bounded. One credit card can be bind with one user only.
7.
Why do I get ‘The return page URL not exist’ message display on web browser and is unable to see the iPay88 OPSG payment page? a) Make sure the correct merchant code is used. b) Provide the Request URL to [email protected] before the integration. c) Make sure response URL is specified through ResponseURL field in request page or had updated in iPay88.
8.
How do I ensure the integration is completed? a) Make sure parameters are properly passed to iPay88 OPSG and success reach iPay88 OPSG payment page. b) Success receives payment status from iPay88 OPSG after perform test transaction. c) Make sure implemented security control on the merchant response page. Example: Compare the Signature from iPay88 OPSG with the generated merchant response page.
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 47 of 52
9.
How can I change the merchant information such as Request URL, contact number, company name and bank account number? Send an email to [email protected] to request for these changes.
10. What not to do after press “Proceed Payment” button at iPay88 OPSG payment page? a) Do not disconnect your Internet connection. b) Do not close the web browser while transaction being process. c) Do not click “Back” button on web browser to avoid duplicate payment. 11. I am getting error description “Fail (Card issuing bank do not honor the transaction)” returned by iPay88 OPSG, what does it mean? Please contact credit card issuer bank to check whether the card can be used for online purchases. 12. Is there any function from iPay88 OPSG where I can query payment status if my system did not get payment status return from iPay88 OPSG? You can use the iPay88 OPSG Server Requery function to query the transaction status. Please refer section 2.9 in iPay88 OPSG Technical Specification for more information about iPay88 server re-query.
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 48 of 52
APPENDIX A. MERCHANT CHECKLIST
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 49 of 52
Merchant Checklist Merchant Name:
Name of iPay88 Account Manager: Contact Info:
Date:
Intended Live Date:
1.
Status:
Name: Contact No: Email address: Successful Fail
Description
Remarks
Test Account Request
Please fill up this section if test account is requested.
Status Yes
Purpose: Start Date: End Date: Assigned by: 2.
Pre-requisite and Merchant Expectation on Integration
Before integration commencement please ensures the guidelines below are adhered. 1. Please register request URL on iPay88 before do integration/testing. Request URL: ------------------------------------------------------------2. Registered request URL must be either IP or domain based. Note: LocalHost is not allowed. 3. Testing transaction must from registered URL. 4. Test transaction with amount MYR 1.00. 5. Test transaction with credit card ONLY. 6. Response URL can be set in request page with ResponseURL field or provided on below. Response URL: ------------------------------------------------------------7. Backend post URL can be set in request page with BackendURL field. 8. Email notification is NOT guarantee as it ISP dependant.
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 50 of 52
No
3.
Technical Competencies
Integration Competencies Required (at least one) Programming Language ASP.Net PHP ASP Java Database MySQL MS SQL
4.
Integration Info
Others skill set XML or Web service Please fill up this section Integration Start Date: ............................... Integration End Date: ............................... Target Live Date: ............................... Staging/Test URL: .............................................................. Production URL: .............................................................. Merchant Technical contact no: ............................... Merchant Technical email: ............................... iPay88 Integration contact : ...............................
5.
Implemented iPay88 feature
Please specific implemented feature in merchant system Standard re-query Web service re-query Backend post Signature (via web services)
6.
Merchant ID Requirement
iPay88
Own
If Own, list the intended Financial Provider, MID, Admin and UserID 1. 2. 3.
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 51 of 52
7.
Customisation Requirement
If yes, please specify Landing Pages showing Merchant’s Name Statement showing Merchant’s Name Transaction Verification Report Requirement Data Requirement Others, please specify
Please tick on the section that completed. Test Account Request Prereq uisit es a nd M erc h an t Technical Competency Integration Info Implemented iPay88 feature Merchant ID Requirement Customization Requirement
Expec t at ion
o n
Int egrat ion
Integration Completed Live Merchant Activation Live Merchant Test Run Payment Collected Signoff and Submitted by:
Remarks:
____________________ Signature: Name: Designation: Date:
Copyright ©iPay88 Sdn Bhd 2016. All rights reserved. No part of this publication may be reproduced in any form except as permitted by the copyright owners.
Page 52 of 52