7-CONNECT Merchant Integration Guide 0.7

8/3/2019 7-CONNECT Merchant Integration Guide 0.7

1/16

7-Pay Merchant Integration Guide v0.7 - 1 -

Merchant Integration Guide


2/16


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.


3/16


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.


4/16


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


5/16


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


6/16


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:


7/16


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


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


9/16


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:




amount Number

(12, 2)

Yes Transaction amount.


payID Text (20) Yes 7-CONNECT Reference generated by the gateway



merchantID + merchantRef + payID + {transactionKey}

PHP code:

$token = sha1($merchantID . $merchantRef . $payID . '{' .

$transactionKey . '}');


10/16



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:


11/16


Amount:


12/16


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:






merchantRef + {transactionKey}


2.2.2.Response Parameters7-CONNECT returns a JSON-formatted string. Example response: { "merchantID": "123", "merchantRef":

"123", "payID": "123", "status": "UNPAID", "token": "123" }



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



merchantRef + payID + status + {transactionKey}


message Text No A description of the response


13/16


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


amount Number (12,

2)

Yes Transaction Amount




type +merchantID + merchantRef + {transactionKey}



14/16


3.3. Response ParametersName Data Type Required? Description

type Text Yes Valid values: VALIDATE, CONFIRM, VOID


amount Number

(12, 2)

Yes Transaction Amount


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.



type + merchantID + merchantRef + authCode +responseCode + {transactionKey}


Sample Code

The following php code implements the merchant service that will handle VALIDATE, CONFIRM and

VOID instructions coming from the 7-CONNECT gateway.


15/16


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

}


16/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.

Documents

7-CONNECT Merchant Integration Guide 0.7