Merchant Integration Guide

7-Pay Merchant Integration Guide

v0.7

-1-

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 errorfree. If you find any errors, please report them to us in writing.

7-Pay Merchant Integration Guide

v0.7

-2-

Revision History
Version 0.1 0.2 0.3 0.4 Date 2011-03-02 2011-03-16 2011-03-18 2011-03-24 Revisions Initial document draft Added test plan section Added screenshots. Renamed 7-Pay ID to 7-Pay Reference. Added documentation on generating the token. Also added sample php code for getting the 7-Pay Reference. 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 0.7 2011-04-26 2011-07-26 Modified branding to 7-CONNECT. 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.

0.5

2011-04-06

7-Pay Merchant Integration Guide

v0.7

-3-

Table of Contents 7-CONNECT Merchant Integration Guide................................................................................................. 2 Revision History....................................................................................................................................... 3 1. 2. Introduction .................................................................................................................................... 5 7-CONNECT Web Services................................................................................................................ 6 2.1. 2.1.1. 2.1.2. 2.1.3. 2.1.4. 2.1.5. 2.2. 2.2.1. 2.2.2. 2.2.3. 3. 7-CONNECT Reference............................................................................................................ 6 Process Flow....................................................................................................................... 6 Request Parameters ........................................................................................................... 8 Response Parameters ......................................................................................................... 9 URLs ................................................................................................................................. 10 Sample Code .................................................................................................................... 10 Transaction Inquiry ............................................................................................................... 12 Request Parameters ......................................................................................................... 12 Response Parameters ....................................................................................................... 12 URLs ................................................................................................................................. 13

Merchant Web Services ................................................................................................................. 13 3.1. 3.2. 3.3. Requirements ....................................................................................................................... 13 Request Parameters ............................................................................................................. 13 Response Parameters ........................................................................................................... 14

Sample Code ..................................................................................................................................... 14 Merchant Test Plan............................................................................................................................ 16

7-Pay Merchant Integration Guide

v0.7

-4-

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 will be used by customers to pay at the store. Merchant Payment API: This URL will enable the 7-Eleven store to notify your system in realtime whenever the customer pays at the store.

To get the latest information and graphic logos, pleas e visit the site: http://7-connect.philseven.com

7-Pay Merchant Integration Guide

v0.7

-5-

2. 7-CONNECT Web Services

2.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-Pay Merchant Integration Guide

v0.7

-6-

a. Write down the 7-CONNECT Reference or Print the page b. 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.

7-Pay Merchant Integration Guide

v0.7

-7-

2.1.2. Request Parameters

Using 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 and TransactionKey after completing the merchant agreement. Name merchantID merchantRef amount Data Type Text (15) Text (40) Number (12, 2) Number (14) Required? Yes Yes Yes Description Merchants ID as provided by 7-CONNECT Merchants Reference Number Transaction amount. Format: XXXXXXXXXX.XX expDate 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. The page to which 7-CONNECT redirects to after a failed transaction. Transaction Security Token To create this, get the SHA-1 digest of: merchantID + merchantRef + {transactionKey} PHP code:
$token = sha1($merchantID . $merchantRef . '{' . $transactionKey . '}');

failURL

Text (300)

Yes

token

Text

Yes

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) Will be printed in the receipt (if none, defaults to {merchantID}|{merchantRef}) (max of 660 characters). Use the |^ characters to instruct a new v0.7 -8-

receiptRemarks

Text(660)

No

7-Pay Merchant Integration Guide

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 the customer. 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 Parameters

From the confirmation page, 7-CONNECT redirects to the merchant site, depending on whether the 7CONNECT Request was a success of not. The parameters are: Name merchantID Data Type Text (15) Required? Yes Yes Yes Description Merchants ID as provided by 7-CONNECT Merchants Reference Number Transaction amount. Format: XXXXXXXXXX.XX payID token Text (20) Text Yes Yes 7-CONNECT Reference generated by the gateway Transaction Security Token To create this, get the SHA-1 digest of: merchantID + merchantRef + payID + {transactionKey} PHP code:
$token = sha1($merchantID . $merchantRef . $payID . '{' . $transactionKey . '}');

merchantRef Text (40) amount Number (12, 2)

7-Pay Merchant Integration Guide

v0.7

-9-

transactionKey as provided by 7-CONNECT message Text No Error message.

2.1.4. URLs
PRODUCTION URL: TEST URL: https://pay.7-eleven.com.ph/transact http://testpay.7-eleven.com.ph:8888/transact

2.1.5. Sample Code

This 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
<?php if (isset($_REQUEST['submit'])) { $merchantRef = $_REQUEST['merchantRef']; $amount = $_REQUEST['amount']; if (!is_numeric($amount)) { $errormsg = "Invalid amount."; } $transactURL = 'http://testpay.7-eleven.com.ph:8888/transact'; $inquireURL = 'http:// testpay.7-eleven.com.ph:8888/inquire'; $transactionKey = '628e936f45884030ac1f34bcde9c28efa6ae9c839623b45b8942bd4490e1f05d'; $merchantID = '7-Eleven'; $successURL = $_SERVER['SERVER_NAME']; $failURL = $_SERVER['SERVER_NAME']; $token = sha1($merchantID . $merchantRef . '{' . $transactionKey . '}'); //set variables $fields = array( 'merchantID'=>$merchantID, 'merchantRef'=>$merchantRef, 'amount'=>$amount, 'successURL'=>$successURL, 'failURL'=>$failURL, 'token'=>$token ); $params = http_build_query($fields); header("Location: $transactURL?$params"); } if (isset($error)) { echo "Invalid Amount. Please enter again."; } ?> <h1>7-CONNECT Test Request</h1> <form method="post"> <table> <tr> <td>Merchant Reference:</td> <td><input type="text" name="merchantRef"></td> </tr> <tr>

7-Pay Merchant Integration Guide

v0.7

- 10 -

<td>Amount:</td> <td><input type="text" name="amount"></td></tr> <tr> <td><input type="submit" name="submit" value="Submit to 7-CONNECT"></td> </tr> </table> </form>

7-Pay Merchant Integration Guide

v0.7

- 11 -

2.2.

Transaction Inquiry

2.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 merchantID merchantRef token Data Type Text (15) Text (40) Text Required? Yes Yes Yes Description Merchants ID as provided by 7-CONNECT Merchants Reference Number Transaction Security Token To create this, get the SHA-1 digest of: merchantRef + {transactionKey} transactionKey as provided by 7-CONNECT

2.2.2. Response Parameters

7-CONNECT returns a JSON-formatted string. Example response: { "merchantID": "123", "merchantRef": "123", "payID": "123", "status": "UNPAID", "token": "123" } Name merchantID Data Type Text (15) Required? Yes Yes Description Merchants ID as provided by 7-CONNECT Merchants Reference Number. If the merchant reference number is not unique, the gateway will return the first match. 7-CONNECT Reference generated by the gateway Valid values: UNPAID, PAID, POSTED, EXPIRED, ERROR 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

merchantRef Text (40)

payID status token

Text (20) Text Text

Yes Yes Yes

7-Pay Merchant Integration Guide

v0.7

- 12 -

2.2.3. URLs
PRODUCTION URL: TEST URL: https://pay.7-eleven.com.ph/inquire http://testpay.7-eleven.com.ph:8888/inquire

3. Merchant Web Services

3.1. Requirements
7-CONNECT requires its merchants to have the following web services: 1. Validate This is used to verify the validity of a given Merchant Reference Number. 2. Confirm This is used to confirm the payment for a given Merchant Reference Number. 3. Void This is used to void the payment made to a given Merchant Reference Number. Communication will be done using HTTP Post.

3.2.
Name type merchantRef amount

Request Parameters
Data Type Text Text (40) Number (12, 2) Text Required? Yes Yes Yes Description Valid values: VALIDATE, CONFIRM, VOID Merchants Reference Number Transaction Amount Format: XXXXXXXXXX.XX

token

Yes

Transaction Security Token To create this, get the SHA-1 digest of: type +merchantID + merchantRef + {transactionKey} transactionKey as provided by 7-CONNECT

7-Pay Merchant Integration Guide

v0.7

- 13 -

3.3.
Name type merchantRef amount

Response Parameters
Data Type Text Text (40) Number (12, 2) Text (20) Required? Yes Yes Yes Description Valid values: VALIDATE, CONFIRM, VOID Merchants Reference Number Transaction Amount Format: XXXXXXXXXX.XX

authCode

Yes, except for Validate Yes No No

Merchant-system-generated Authorization Code

responseCode responseDesc remarks

Text (12) Text (40) Text (160)

Valid values: SUCCESS, DECLINED Details for the declined transaction. Any remarks from the Merchant. This will be printed on the receipt. Transaction Security Token To create this, get the SHA-1 digest of: type + merchantID + merchantRef + authCode + responseCode + {transactionKey} transactionKey as provided by 7-CONNECT

token

Text

Yes

Sample Code
The following php code implements the merchant service that will handle VALIDATE, CONFIRM and VOID instructions coming from the 7-CONNECT gateway.
<?php /* This is the verification service that listens to payment transactions from the gateway. */ if (isset($_REQUEST['type'])) { $transactiontype = $_REQUEST['type']; $merchantRef = $_REQUEST['merchantRef']; $amount = $_REQUEST['amount']; $token = $_REQUEST['token']; // Check if token is valid // Replace merchantID with your merchant ID $transactionKey = '7ede208b7f8a58573057e7dde57fe8f3969fe0b2c32149c36b8c29ae9f744274'; $merchantID = 'TestMerchant01'; $validtoken = sha1($transactiontype . $merchantID . $merchantRef . '{' . $transactionKey . '}');

7-Pay Merchant Integration Guide

v0.7

- 14 -

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

7-Pay Merchant Integration Guide

v0.7

- 15 -

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 Merchant Activity Make 10 purchases and choose 7CONNECT as the payment system. Expected Output 7-CONNECT generates a 7-CONNECT Reference per purchase. (Total of 10 7CONNECT References) 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 calendar date). All transactions with PAID (and/or POSTED?) status are included in the report. Details of which are: Transaction Date 7-CONNECT Reference Amount 7-CONNECT Reference No. Merchant Reference No.

PSC

Transact five of the generated 7CONNECT References in POS.

7-Pay Merchant Integration Guide

v0.7

- 16 -