Upload
jason-jan-ngo
View
221
Download
0
Embed Size (px)
Citation preview
8/3/2019 7-CONNECT Merchant Integration Guide 0.7
1/16
7-Pay Merchant Integration Guide v0.7 - 1 -
Merchant Integration Guide
8/3/2019 7-CONNECT Merchant Integration Guide 0.7
2/16
7-Pay Merchant Integration Guide v0.7 - 2 -
7-CONNECT Merchant Integration Guide
Copyright 2011, Philippine Seven Corporation and affiliates. All rights reserved.
The information contained in this document is confidential and intended for merchants who will be
integrating to the 7-CONNECT gateway. Copying and distribution of this document to unauthorized
parties is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-
free. If you find any errors, please report them to us in writing.
8/3/2019 7-CONNECT Merchant Integration Guide 0.7
3/16
7-Pay Merchant Integration Guide v0.7 - 3 -
Revision History
Version Date Revisions
0.1 2011-03-02 Initial document draft
0.2 2011-03-16 Added test plan section
0.3 2011-03-18 Added screenshots. Renamed 7-Pay ID to 7-Pay Reference.
0.4 2011-03-24 Added documentation on generating the token. Also added sample
php code for getting the 7-Pay Reference.
0.5 2011-04-06 Added 3 new optional fields (transactionDescription - will be shown
in the customer LCD screen and payment instruction page,receiptRemarks that is printed in the receipt, and email for notifying
customers of 7-Pay transactions.
Also added sample code for merchant web service implementation.
0.6 2011-04-26 Modified branding to 7-CONNECT.
0.7 2011-07-26 Updated the instruction page screenshot to include the Email
instructions to button. (2.1)
Changed receipt remarks maximum limit to 660 characters and
added an example. (2.1.2)
Corrected URL of test environment. (2.1.4)
Added a merchant ID parameter to the transaction inquiry (2.2 and
2.2.3) and modified the return values directly in JSON format. The
previous API has been deprecated.
8/3/2019 7-CONNECT Merchant Integration Guide 0.7
4/16
7-Pay Merchant Integration Guide v0.7 - 4 -
Table of Contents
7-CONNECT Merchant Integration Guide.................................................................................................2Revision History.......................................................................................................................................31. Introduction ........................ ................... ............................... ................... ............................ ........... 52. 7-CONNECT Web Services................................................................................................................6
2.1. 7-CONNECT Reference............................................................................................................62.1.1. Process Flow.......................................................................................................................62.1.2. Request Parameters ........................... ...................... ............................ ................... ........... 82.1.3. Response Parameters ........................... ......................... ............................ .................... .....92.1.4. URLs.................................................................................................................................10 2.1.5. Sample Code .......................... .................... .............................. .................... .................... 10
2.2. Transaction Inquiry...............................................................................................................122.2.1. Request Parameters ........................... ...................... ............................ ................... ......... 122.2.2. Response Parameters ........................... ......................... ............................ .................... ... 122.2.3. URLs.................................................................................................................................13
3. Merchant Web Services .......................... ...................... ............................... ................... ............... 133.1. Requirements.......................................................................................................................13 3.2. Request Parameters ......................... ......................... ............................ ................... ............ 133.3. Response Parameters ....................... ......................... ............................ ................... ............ 14Sample Code ........................... ...................... ............................ ................... ............................ ......... 14Merchant Test Plan................................. ........................ ........................... ....................... ................. 16
8/3/2019 7-CONNECT Merchant Integration Guide 0.7
5/16
7-Pay Merchant Integration Guide v0.7 - 5 -
1.Introduction
Welcome to the 7-CONNECT Merchant Integration Guide.
7-CONNECT is 7-Elevens newest platform for e-commerce businesses that enables cash payment
convenience for your customers. As a customer, you can now pay for online purchases at any 7-Eleven
store.
This guide assumes you have a working knowledge of the following:
HTTP and webservice concepts SHA-1 hashing
7-CONNECT features the following:
24/7 cash payment at all 7-Eleven stores Increases your market beyond credit card holders Easier and faster than bank deposits Zero risk of fraud and chargebacks Real time notification of payment to your transaction systems
As a merchant, you will have access to new customers who do not have credit cards or who refuse to
use them online. This opens up opportunities for you. There are no chargebacks or fraud to worry about.
All completed transactions are guaranteed to be remitted to you.
Integrating your website to 7-CONNECT will require development of two points:
7-CONNECT Reference Request: You will need to request for a 7-CONNECT Reference which willbe used by customers to pay at the store.
Merchant Payment API: This URL will enable the 7-Eleven store to notify your system in realtimewhenever the customer pays at the store.
To get the latest information and graphic logos, pleas e visit the site: http://7-connect.philseven.com
8/3/2019 7-CONNECT Merchant Integration Guide 0.7
6/16
7-Pay Merchant Integration Guide v0.7 - 6 -
2.7-CONNECT Web Services2.1. 7-CONNECT Reference
2.1.1.Process Flow
1. Customer selects 7-CONNECT as Payment Mode in Checkout.2. Merchant Site sends a 7-CONNECT Reference Request to the 7-CONNECT Gateway.3. 7-CONNECT Gateway displays the following instruction page displaying the Merchant details and
the 7-CONNECT Reference. At this point, the Customer can:
8/3/2019 7-CONNECT Merchant Integration Guide 0.7
7/16
7-Pay Merchant Integration Guide v0.7 - 7 -
a. Write down the 7-CONNECT Reference or Print the pageb. Proceed with the transaction
4. Customer selects Proceed.5. 7-CONNECT Gateway redirects to the Merchants Success URL.6. Merchant Site displays the Order Confirmation page.
8/3/2019 7-CONNECT Merchant Integration Guide 0.7
8/16
7-Pay Merchant Integration Guide v0.7 - 8 -
2.1.2.Request ParametersUsing HTTP Post or Get, the merchant site has to provide the 7-CONNECT Gateway with the parameters
it requires to generate a 7-CONNECT Reference. You will be provided with your own Merchant ID andTransactionKey after completing the merchant agreement.
Name Data Type Required? Description
merchantID Text (15) Yes Merchants ID as provided by 7-CONNECT
merchantRef Text (40) Yes Merchants Reference Number
amount Number
(12, 2)
Yes Transaction amount.
Format: XXXXXXXXXX.XX
expDate Number
(14)
No Transactions expiration date/time.
Format: yyyyMMddHHmmss
If not specified, blank or malformed, the expiry date
is set to the value defined in the merchant settings
(typically +48 hours).
successURL Text (300) Yes The page to which 7-CONNECT redirects to after the
user clicks on the Proceed button.
failURL Text (300) Yes The page to which 7-CONNECT redirects to after a
failed transaction.
token Text Yes Transaction Security Token
To create this, get the SHA-1 digest of:
merchantID + merchantRef + {transactionKey}
PHP code:
$token = sha1($merchantID . $merchantRef . '{' .
$transactionKey . '}');
transactionKey as provided by 7-CONNECT
transactionDescription Text(128) No Will be shown in the customer LCD screen and
payment instruction page (max of 128 characters)
receiptRemarks Text(660) No Will be printed in the receipt (if none, defaults to
{merchantID}|{merchantRef}) (max of 660
characters). Use the |^ characters to instruct a new
8/3/2019 7-CONNECT Merchant Integration Guide 0.7
9/16
7-Pay Merchant Integration Guide v0.7 - 9 -
line. The width of the receipt is 32 characters.
Excess characters in a line will be truncated in the
receipt.
Example: "John Santos|^789 E. Rodriguez St.|^Call
777-7890 for questions|^Expected delivery date:
7/4/11"
This will be rendered on the receipt as:
John Santos
789 E. Rodriguez St.
Call 777-7890 for questions
Expected delivery date: 7/4/11
email Text No Used for notifications from 7-CONNECT to thecustomer. If not provided by the merchant, a button
will appear in the instruction page to allow the
customer to enter their email address.
2.1.3.Response ParametersFrom the confirmation page, 7-CONNECT redirects to the merchant site, depending on whether the 7-
CONNECT Request was a success of not. The parameters are:
Name Data Type Required? Description
merchantID Text (15) Yes Merchants ID as provided by 7-CONNECT
merchantRef Text (40) Yes Merchants Reference Number
amount Number
(12, 2)
Yes Transaction amount.
Format: XXXXXXXXXX.XX
payID Text (20) Yes 7-CONNECT Reference generated by the gateway
token Text Yes Transaction Security Token
To create this, get the SHA-1 digest of:
merchantID + merchantRef + payID + {transactionKey}
PHP code:
$token = sha1($merchantID . $merchantRef . $payID . '{' .
$transactionKey . '}');
8/3/2019 7-CONNECT Merchant Integration Guide 0.7
10/16
7-Pay Merchant Integration Guide v0.7 - 10 -
transactionKey as provided by 7-CONNECT
message Text No Error message.
2.1.4. URLsPRODUCTION URL: https://pay.7-eleven.com.ph/transact
TEST URL: http://testpay.7-eleven.com.ph:8888/transact
2.1.5.Sample CodeThis php code will display a form asking for a merchant reference and amount. Submitting this will
display the payment instruction page containing the 7-CONNECT Reference.
transact.php
7-CONNECT Test Request
Merchant Reference:
8/3/2019 7-CONNECT Merchant Integration Guide 0.7
11/16
7-Pay Merchant Integration Guide v0.7 - 11 -
Amount:
8/3/2019 7-CONNECT Merchant Integration Guide 0.7
12/16
7-Pay Merchant Integration Guide v0.7 - 12 -
2.2. Transaction Inquiry2.2.1.Request Parameters
Using HTTP Post or Get, the merchant site has to provide the 7-CONNECT Gateway with the parameters
it requires for transaction inquiry. These are:
Name Data Type Required? Description
merchantID Text (15) Yes Merchants ID as provided by 7-CONNECT
merchantRef Text (40) Yes Merchants Reference Number
token Text Yes Transaction Security Token
To create this, get the SHA-1 digest of:
merchantRef + {transactionKey}
transactionKey as provided by 7-CONNECT
2.2.2.Response Parameters7-CONNECT returns a JSON-formatted string. Example response: { "merchantID": "123", "merchantRef":
"123", "payID": "123", "status": "UNPAID", "token": "123" }
Name Data Type Required? Description
merchantID Text (15) Yes Merchants ID as provided by 7-CONNECT
merchantRef Text (40) Yes Merchants Reference Number. If the merchant reference
number is not unique, the gateway will return the first
match.
payID Text (20) Yes 7-CONNECT Reference generated by the gateway
status Text Yes Valid values: UNPAID, PAID, POSTED, EXPIRED, ERROR
token Text Yes Transaction Security Token
To create this, get the SHA-1 digest of:
merchantRef + payID + status + {transactionKey}
transactionKey as provided by 7-CONNECT
message Text No A description of the response
8/3/2019 7-CONNECT Merchant Integration Guide 0.7
13/16
7-Pay Merchant Integration Guide v0.7 - 13 -
2.2.3.URLsPRODUCTION URL: https://pay.7-eleven.com.ph/inquire
TEST URL: http://testpay.7-eleven.com.ph:8888/inquire
3.Merchant Web Services3.1. Requirements
7-CONNECT requires its merchants to have the following web services:
1. ValidateThis is used to verify the validity of a given Merchant Reference Number.
2. ConfirmThis is used to confirm the payment for a given Merchant Reference Number.
3. VoidThis is used to void the payment made to a given Merchant Reference Number.
Communication will be done using HTTP Post.
3.2. Request ParametersName Data Type Required? Description
type Text Yes Valid values: VALIDATE, CONFIRM, VOID
merchantRef Text (40) Yes Merchants Reference Number
amount Number (12,
2)
Yes Transaction Amount
Format: XXXXXXXXXX.XX
token Text Yes Transaction Security Token
To create this, get the SHA-1 digest of:
type +merchantID + merchantRef + {transactionKey}
transactionKey as provided by 7-CONNECT
8/3/2019 7-CONNECT Merchant Integration Guide 0.7
14/16
7-Pay Merchant Integration Guide v0.7 - 14 -
3.3. Response ParametersName Data Type Required? Description
type Text Yes Valid values: VALIDATE, CONFIRM, VOID
merchantRef Text (40) Yes Merchants Reference Number
amount Number
(12, 2)
Yes Transaction Amount
Format: XXXXXXXXXX.XX
authCode Text (20) Yes, except
for Validate
Merchant-system-generated Authorization Code
responseCode Text (12) Yes Valid values: SUCCESS, DECLINED
responseDesc Text (40) No Details for the declined transaction.
remarks Text (160) No Any remarks from the Merchant. This will be printed on
the receipt.
token Text Yes Transaction Security Token
To create this, get the SHA-1 digest of:
type + merchantID + merchantRef + authCode +responseCode + {transactionKey}
transactionKey as provided by 7-CONNECT
Sample Code
The following php code implements the merchant service that will handle VALIDATE, CONFIRM and
VOID instructions coming from the 7-CONNECT gateway.
8/3/2019 7-CONNECT Merchant Integration Guide 0.7
15/16
7-Pay Merchant Integration Guide v0.7 - 15 -
if ($token != $validtoken) {
$authCode = "";
$responseCode = "DECLINED";
$responseDesc = "Invalid token";
} else {$authCode = '1111';
$responseCode = "SUCCESS";
$responseDesc = "";
switch($transactiontype) {
case "VALIDATE":
// Check if merchantRef is still valid
break;
case "CONFIRM":
// Update the paid status of the table
break;
case "VOID":
// Update the paid status of the table
break;
default:
$responseCode = "DECLINED";
$responseDesc = "Unknown transaction type";
}}
$token = sha1($transactiontype . $merchantID . $merchantRef . $authCode . $responseCode .
'{' . $transactionKey . '}');
//set GET variables
$fields = array(
'merchantID'=>$merchantID,
'merchantRef'=>$merchantRef,
'amount'=>$amount,
'authCode'=>$authCode,
'responseCode'=>$responseCode,
'responseDesc'=>$responseDesc,
'token'=>$token
);
$params = http_build_query($fields);//output response
echo "?$params";
//write logfile
$myFile = "/tmp/7-CONNECT.log";
$fh = fopen($myFile, 'a') or exit();
fwrite($fh, date('Y-m-d H:i ') . $params . "\n");
fclose($fh);
}
8/3/2019 7-CONNECT Merchant Integration Guide 0.7
16/16
7-Pay Merchant Integration Guide v0.7 - 16 -
Merchant Test Plan
Objective:
To test the ability of the 7-CONNECT Gateway to generate a 7-CONNECT Reference and then post the
transaction to the Merchant Server.
Activities:
In-charge Activity Expected Output
Merchant Make 10 purchases and choose 7-
CONNECT as the payment system.
7-CONNECT generates a 7-CONNECT
Reference per purchase. (Total of 10 7-
CONNECT References)
PSC Transact five of the generated 7-
CONNECT References in POS.
Status of five transacted 7-CONNECT
References in 7-CONNECT is POSTED.
Status of the other 7-CONNECT
References is UNPAID.
Merchant Name and Merchant Reference
No. is printed on the POS receipt.
7-CONNECT
Gateway
Generate a weekly settlement report
for the Merchant (based on calendardate).
All transactions with PAID (and/or
POSTED?) status are included in thereport. Details of which are:
Transaction Date 7-CONNECT Reference Amount 7-CONNECT Reference No. Merchant Reference No.