CyberSource Secure Acceptance Migration Tutorial

March 2014

2

CyberSource Contact Information

For general information about our company, products, and services, go to http://www.cybersource.com. For sales questions about any CyberSource Service, email sales@cybersource.com or call 650-432-7350 or 888-330-2300 (toll free in the United States). For support information about any CyberSource Service, visit the Support Center at http://www.cybersource.com/support.

Copyright © 2014 CyberSource Corporation. All rights reserved. CyberSource Corporation ("CyberSource") furnishes this document and the software described in this document under the applicable agreement between the reader of this document ("You") and CyberSource ("Agreement"). You may use this document and/or software only in accordance with the terms of the Agreement. Except as expressly set forth in the Agreement, the information contained in this document is subject to change without notice and therefore should not be interpreted in any way as a guarantee or warranty by CyberSource. CyberSource assumes no responsibility or liability for any errors that may appear in this document. The copyrighted software that accompanies this document is licensed to You for use only in strict accordance with the Agreement. You should read the Agreement carefully before using the software. Except as permitted by the Agreement, You may not reproduce any part of this document, store this document in a retrieval system, or transmit this document, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written consent of CyberSource.

Restricted Rights Legends For Government or defense agencies. Use, duplication, or disclosure by the Government or defense agencies is subject to restrictions as set forth the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and in similar clauses in the FAR and NASA FAR Supplement. For civilian agencies. Use, reproduction, or disclosure is subject to restrictions set forth in subparagraphs (a) through (d) of the Commercial Computer Software Restricted Rights clause at 52.227-19 and the limitations set forth in CyberSource Corporation's standard commercial agreement for this software. Unpublished rights reserved under the copyright laws of the United States.

Trademarks CyberSource, The Power of Payment, CyberSource Payment Manager, CyberSource Risk Manager, CyberSource Decision Manager, CyberSource Connect, Authorize.Net, and eCheck.net are trademarks and/or service marks of CyberSource Corporation. All other brands and product names are trademarks or registered trademarks of their respective owners.

3

Contents Recent Revisions to This Document ............................................................................................................. 5

About This Guide .......................................................................................................................................... 5

Purpose ..................................................................................................................................................... 5

Audience ................................................................................................................................................... 5

Process ..................................................................................................................................................... 5

Related Documentation and Resources ................................................................................................... 6

Part 1: Setup SA within the CyberSource Business Center ......................................................................... 7

Enable SA on your CyberSource Merchant ID (MID) ............................................................................... 7

1. Determine your ability to eliminate multiple CyberSource MIDs through introduction of SA profiles 7

2. Choose between SA Web/Mobile or SA Silent Order POST and create a profile ............................ 8

3. Configure SA profile settings which translate directly from HOP/SOP settings ................................ 8

4. Enable SA features and functionality which do not translate directly from HOP/SOP settings ...... 10

Part 2: Modify the request message integration ........................................................................................ 11

1. Locate your legacy HOP/SOP integration ....................................................................................... 11

2. Update the endpoint ........................................................................................................................ 13

3. Download, modify, and reference the new security file .................................................................. 13

4. Populate the profile_id and access_key within the form POST ...................................................... 15

5. Populate the signed_date_time....................................................................................................... 15

6. Populate the locale .......................................................................................................................... 15

7. Generate a unique transaction_uuid for each transaction request ................................................. 16

8. Populate the transaction_type......................................................................................................... 16

9. Populate the reference_number...................................................................................................... 16

10. Update field names for optional fields included in form POST ................................................... 16

11. Populate merchant_defined_data[0-100] fields .......................................................................... 17

12. Specifying the Signed and Unsigned Fields ............................................................................... 17

Part 3: Modify the response message integration ...................................................................................... 18

1. Accommodate new response field names ...................................................................................... 18

2. Implement the new signature verification function .......................................................................... 18

Part 4: Test your updated integration to SA ............................................................................................... 19

1. Updated Request Page: .................................................................................................................. 19

2. Updated Receipt Page: ................................................................................................................... 20

Part 5: How to Debug SA Transactions during the Migration ..................................................................... 21

Part 6: SA Migration Checklist ................................................................................................................... 23

Appendix A: IFrame (Inline Frame) Support on Secure Acceptance .......................................................... 25

4

5

Recent Revisions to This Document Release Date Version Changes

March 2014 1.0 Initial Release

About This Guide Purpose This document serves as a comprehensive tutorial for merchants migrating from CyberSource’s legacy

Hosted Order Page (HOP) or Silent Order POST (SOP) to Secure Acceptance Web/Mobile (SA

Web/Mobile) or Secure Acceptance Silent Order POST (SA SOP). Secure Acceptance expands on

existing HOP/SOP capabilities by allowing merchants to take advantage of enhanced security, multiple

language support, and optimized functionality for mobile devices. In response to the recent release of

Secure Acceptance, CyberSource has announced the discontinuation of the legacy HOP/SOP solutions

by September 2014. Consequently, existing HOP/SOP merchants are encouraged to immediately migrate

to Secure Acceptance to avoid service disruption.

Audience This document may be used by a developer or technical resource that is looking to implement the

migration from legacy HOP/SOP to Secure Acceptance. It may also be used by a business or

management resource that is looking for a general understanding of the steps that must be taken to

perform the migration successfully.

Process The sample scripts in this document are provided in PHP for illustrative purposes only. The same

concepts and changes apply to any supported scripting language such as Java/JSP, Perl, ColdFusion,

VB.NET, C#, etc.

6

Related Documentation and Resources CyberSource provides a variety of documents and resources to help merchants with the migration. Some

of the more frequently referenced documents are listed in the following table.

Secure Acceptance Migration Documents and Resources

Target

Audience Document/Resource Description

1. General Secure Acceptance General Product Information Provides a general overview of new

functionality with Secure Acceptance

2. Technical Secure Acceptance Technical Guides The location of the technical

implementation documents for both

Secure Acceptance Web/Mobile and

Secure Acceptance Silent Order POST.

3. Technical Secure Acceptance Web/Mobile Configuration

Guide

Current users of the HOP should refer

to the Secure Acceptance Web/Mobile

Configuration Guide. This guide

contains the technical details on

implementing Secure Acceptance

Web/Mobile. This guide replaces the

legacy Hosted Order Page User Guide

4. Technical Secure Acceptance Silent Order POST

Configuration Guide

Current users of the SOP should refer

to the Secure Acceptance Silent Order

POST Configuration Guide. This guide

contains the technical details on

implementing Secure Acceptance

Silent Order POST. This guide replaces

the legacy Silent Order POST User

Guide

5. Technical Secure Acceptance Web/Mobile Field Mapping

Guide

With Secure Acceptance, many of the

field names changed from the legacy

HOP and SOP implementations.

CyberSource has provided a mapping

guide to assist with the migration.

6. General and

Technical

Secure Acceptance Migration Resource Center Additional resources to help with the

migration can be found on the Secure

Acceptance Migration Resource

Center. This site will continually be

updated with material to help

merchants with the migration.

7

Part 1: Setup SA within the CyberSource

Business Center

Enable SA on your CyberSource Merchant ID (MID) If your CyberSource MID is not already enabled for Secure Acceptance as shown below, please contact

CyberSource Customer Support to have it enabled in test and production.

1. Determine your ability to eliminate multiple CyberSource MIDs through

introduction of SA profiles It is important to understand the concept of Secure Acceptance profiles prior to beginning the

migration. Profile functionality was unavailable on legacy HOP/SOP, and as a result, many

businesses have created multiple CyberSource MIDs to satisfy the business needs of multiple sites,

brands, configuration settings, etc. Each SA profile contains a unique set of configuration capabilities

such as payment methods, appearance and branding characteristics, and functional settings which

may be leveraged to support multiple brands, websites, or customers all within a single CyberSource

MID. Unless you have specifically set up multiple CyberSource MIDs for specific payment processing

or reporting needs, this may be a great opportunity to condense the number of CyberSource MIDs

you are required to manage. Learn more about SA profiles within the SA Documentation.

8

The screenshot below illustrates the unique configurations which can now be made per profile within

a single CyberSource MID:

2. Choose between SA Web/Mobile or SA Silent Order POST and create a

profile Secure Acceptance Web/Mobile replaces legacy Hosted Order Page while Secure Acceptance Silent

Order POST replaces legacy Silent Order POST. Determining whether to use SA Web/Mobile or SA

SOP is based on your development preferences. Merchants who prefer to customize a basic order

page framework provided by CyberSource should select SA Web/Mobile, while merchants who prefer

to code the order page from the ground up should select SA SOP. Both options remove your network

from transmission of sensitive payment data. If the level of customization available on SA Web/Mobile

does not meet your business requirements, you should use SA SOP, which allows for full

customization of content rendered to the browser. In most cases, merchants will migrate directly to

the replacement solution (HOP to SA Web/Mobile or SOP to SA SOP). Some merchants may decide

to switch based on the introduction or removal of customization options such as multiple languages or

custom header/footer. Support for inline frame (IFrame) implementations has also changed from

legacy HOP/SOP and will directly impact your decision of which type of Secure Acceptance

profile to setup. Please see Appendix A for a detailed breakdown of IFrame support.

3. Configure SA profile settings which translate directly from HOP/SOP

settings Now that you have enabled your MID for Secure Acceptance and have created at least one profile,

you must configure the profile with the required settings. HOP/SOP settings have either been

replicated or substituted with a new approach within SA. This section will cover HOP/SOP settings

which may be copied directly into an SA profile, while the next section covers settings which do not

translate directly.

A. SA Profile -> General Settings (applies to SA Web/Mobile and SA SOP)

All of the information within this section is new except the contact information, which we

recommend you copy from the section Account Management -> Merchant Information ->

Technical Contact.

9

NOTE: If you intend to use Payment Tokenization and/or Decision Manager with SA, you must

select these added value services in this section of the profile.

B. SA Profile -> Payment Settings (applies to SA Web/Mobile and SA SOP)

Populate the card type, CVN requirements, Payer Authentication, eCheck configuration, and

currency settings within the SA Payment Settings configuration page as per your legacy

HOP/SOP settings found on Tools & Settings -> Hosted Order Page -> Settings -> Payment

Types / Payment Currencies / Payer Authentication.

NOTE: At least one currency and card type must be enabled in order to promote an SA profile to

“Active”.

C. SA Profile -> Security (applies to SA Web/Mobile and SA SOP)

You must generate at least one new security key for each profile within SA. The existing set of

security keys for legacy HOP/SOP found in Tools & Settings -> Hosted Order Page -> Security do

not replicate.

D. SA Profile -> Payment Form (applies to SA Web/Mobile only)

Tax Purchase Information can be retrieved from Tools & Settings -> Hosted Order Page ->

Settings -> Payment Details section.

Billing and Shipping Address Information can be retrieved from Tools & Settings -> Hosted Order

Page -> Settings -> Billing Information / Shipping Information sections.

NOTE: SA Web/Mobile supports two payment flows: Multi-step and Single Page. The legacy

HOP only supported a single page flow.

E. SA Profile -> Notifications (applies to SA Web/Mobile and SA SOP)

Merchant notifications (POST URL and POST Email) and customer email notifications can be

copied from the Tools & Settings -> Hosted Order Page -> Settings -> Notifications -> Addresses

and Options area. The format of the masked version of the credit card that is returned from SA

can be copied from the Tools & Settings -> Hosted Order Page -> Settings -> Reply Management

-> Data section.

F. SA Profile -> Customer Response Pages (applies to SA Web/Mobile and SA SOP)

The standard or custom response page settings can be retrieved from Tools & Settings -> Hosted

Order Page -> Settings -> Appearance -> Receipt Page and Appearance -> Decline Page

sections.

G. SA Profile -> Appearance and Branding (applies to SA Web/Mobile only)

Color scheme and buy button text can be retrieved from Tools & Settings -> Hosted Order Page -

> Settings -> Appearance -> General section. With SA, the ability to run JavaScript has been

removed from the header and footer. Instead, the header and footer can accept an 840px wide by

60px high image that can be used to maintain a seamless transition from your site to SA. If you

require the same level of customization provided by a custom header and footer, we recommend

moving to SA SOP.

H. SA Profile -> Localization (applies to SA Web/Mobile only)

Localization does not require configuration and is new to SA, so there are no corresponding

settings in the HOP.

10

4. Enable SA features and functionality which do not translate directly from

HOP/SOP settings A. HOP Settings -> Level II/III Fields

At the time this document was published, the tentative release date for Level II/III fields on SA is

March 2014.

B. HOP Settings -> Order Page Header/Footer

Custom header/footer content will not be replicated within SA. If you require the same level of

customization provided by a custom header and footer, we recommend moving to SA-SOP.

C. HOP/SOP echo of undefined request fields

Unlike the legacy HOP/SOP solutions, SA does not support an unbound number of undefined

request fields in the incoming POST. Moving forward, you must submit custom fields within the

100 Merchant Defined Data fields available within the new SA spec. This functionality was

intentionally removed by CyberSource to remove a DDoS vulnerability and maximize uptime.

11

Part 2: Modify the request message

integration

NOTE:

1. Locate your legacy HOP/SOP integration You must locate the section of your code which integrates to legacy HOP/SOP. The main

components of the integration include:

A. The security file (HOP.php by default)

B. The payment form, which includes:

a. A form POST directed towards https://orderpage.ic3.com/... (production) or

https://orderpagetest.ic3.com/... (test)

b. Required (signed) fields passed as arguments to the insertSignature(),

insertSignature3(), or insertMapSignature() function, which may include:

i. amount

ii. currency

iii. orderPage_transactionType

iv. orderNumber

c. Optional (unsigned) fields added to the form by the merchant or customer, for example:

i. billTo_firstName

ii. billTo_lastName

// 1. Security File <?php include("HOP.php") ?> <h1>sample_product_name</h1> <p>Here, you enter the description of your product.</p> // 2. The legacy HOP endpoint <form action="https://orderpagetest.ic3.com/hop/orderform.jsp" method="post"> <?php $map; $map['amount']= "15.00";

IFrame Support with Secure Acceptance

Secure Acceptance Silent Order Post Fully supported on all major browsers as long as payer authentication is not enabled.

Secure Acceptance Web/Mobile 1. Will be supported on all major browsers for the single-page checkout flow only.

2. Will not be supported with payer authentication.

3. Tentative release date March 2014.

12

$map['currency']= "usd"; // 3. Specifying the transaction type $map['orderPage_transactionType']= "authorization"; // 4. Specifying a merchant reference code $map['orderNumber']= "12345"; // 5. Specifying pre-filled data $map['billTo_firstName']= "John";

$map['billTo_lastName']= "Doe"; // 6. Specifying non-payment related fields that simply // get passed back in the HOP response $map['VIP Customer'] = "Yes"; // 7. Specifying merchant defined fields $map['merchantDefinedData1'] = "My merchant defined data string"; // 8. Signing the data using the signature functions

InsertMapSignature($map); ?> <input type="submit" value="Buy Now"> </form>

Basic Anatomy of a legacy HOP Request Page

13

2. Update the endpoint The form action must be updated as follows:

Method Environment Endpoint

Legacy SOP

Test <form action="https://orderpagetest.ic3.com/hop/ProcessOrder.do"

method="post">

Product <form action="https://orderpage.ic3.com/hop/ProcessOrder.do" method="post">

Legacy HOP

Test <form action="https://orderpagetest.ic3.com/hop/orderform.jsp" method="post">

Production <form action="https://orderpage.ic3.com/hop/orderform.jsp" method="post">

Secure Acceptance Web/Mobile

Test <form action=”https://testsecureacceptance.cybersource.com/pay” method=”post”>

Production <form action=”https://secureacceptance.cybersource.com/pay” method=”post”>

Secure Acceptance Silent Order

Post

Test <form action=”https://testsecureacceptance.cybersource.com/silent/pay” method=”post”>

Production <form action=”https://secureacceptance.cybersource.com/silent/pay” method=”post”>

Test and Production Endpoints for legacy HOP and Secure Acceptance

3. Download, modify, and reference the new security file A. Download the new security file located within the SA documentation and deploy it to the same

location as your legacy HOP/SOP security key. By default, the naming convention of the new

security file will be security.php.

B. Open security.php and update the secret key with the value obtained from Tools & Settings ->

Secure Acceptance -> Profiles -> Security. Insert the secret key from your profile into your

security file.

14

NOTE: Any dynamic scripting language that can produce a SHA-256 signature can use SA. The

languages that are supported by CyberSource are listed in the documentation and shown above.

C. Modify the include statement to reference the new security script:

Legacy HOP/SOP // Security File

<?php include("HOP.php") ?>

Secure Acceptance // Reference the new security file <?php include ("security.php") ?>

15

4. Populate the profile_id and access_key within the form POST Populate the profile_id based on the value you assigned during profile setup and configuration in the

Business Center. The access_key can be obtained from the security section of the profile in the

Business Center.

Legacy HOP/SOP

// Signing the data using the signature functions InsertMapSignature($map); The signature functions were responsible for inserting the proper signature, serial number, and merchantID into the request form data.

Secure Acceptance

// Specifying the selected profile's access key $map['access_key']= "76555ea3221d32688f7d24730deee1af"; // Specifying the selected profile $map['profile_id']= "primer1"; With Secure Acceptance, the access key is obtained from the EBC in the security section of the profile.

5. Populate the signed_date_time SA requires transactions to be submitted with a timestamp of when the signature was created. This

timestamp needs to be within about 15 minutes of the time of the CyberSource server or the

transaction will fail. To ensure the timestamp is accurate, make sure your webserver’s clock is correct

and enabled for daylight savings time (if applicable in your time zone).

Legacy HOP/SOP

This was done by the signature function in the legacy HOP.

Secure Acceptance

//Establishing the timestamp $map['signed_date_time']= gmdate("Y-m-d\TH:i:s\Z");

6. Populate the locale More information about setting the locale can be found in the CyberSource Secure Acceptance

Web/Mobile Configuration Guide.

Legacy HOP N/A

Secure Acceptance //Specifying the locale $map['locale'] = "en";

16

7. Generate a unique transaction_uuid for each transaction request To eliminate the possibility for duplicate transactions, SA has introduced the concept of requiring a

unique transactionID to be submitted with the data to the SA endpoint. This identifier must be unique

for each transaction associated with a particular access key.

NOTE: Refer to the CyberSource Secure Acceptance Web/Mobile Configuration Guide and the

sample code of your selected language for more information on how to use the language’s built-in

functions to create a unique transactionID.

Legacy HOP/SOP

NA

Secure Acceptance

//Specifying the unique transaction id

$map['transaction_uuid'] = uniqid();

8. Populate the transaction_type NOTE: The field name which specifies the service/s you wish to execute has changed from

orderPage_transactionType to transaction_type. More information about the available transaction

types can be found in the CyberSource Secure Acceptance Web/Mobile Configuration Guide.

Legacy HOP/SOP

//Specifying the transaction type $map['orderPage_transactionType']= "authorization";

Secure Acceptance

// Specifying the transaction type $map['transaction_type']= "authorization";

9. Populate the reference_number This is the field that translates to the merchant reference code that can be found on all the

CyberSource report.

The field name has changed between the legacy HOP (orderNumber) and SA

(reference_number).

The field is now required for SA implementations and optional for legacy HOP/SOP

implementations

Although not a requirement, CyberSource recommends that this field be unique.

Legacy HOP/SOP

//Specifying a merchant reference code

$map['orderNumber']= "12345";

Secure Acceptance

//Specifying the merchant reference code

$map['reference_number']= "12345";

10. Update field names for optional fields included in form POST The field names have been modified from legacy HOP/SOP to SA. This step requires that you

simply update the field names within your form POST to accommodate the SA specification. More

information about the field mappings can be found at the CyberSource Secure Acceptance

Migration Resource Center in the Field Mapping Guide. Below is an example mapping for billing

first and last name.

Legacy HOP/SOP //Specifying pre-filled data $map['billTo_firstName']= "John"; $map['billTo_lastName']= "Doe";

Secure Acceptance //Passing prepopulated data to the SA endpoint $map['bill_to_forename']= "John"; $map['bill_to_surname']= "Doe";

17

11. Populate merchant_defined_data[0-100] fields Unlike legacy HOP/SOP, SA does not ‘echo back’ any request fields that it does not recognize.

This step simply requires that you update the field name in the form POST to one of the 100 SA-

supported merchant defined data fields.

Legacy HOP/SOP

// Specifying non-payment related fields that simply // get passed back in the HOP response $map['VIP Customer'] = "Yes";

Secure Acceptance

//Passing non-payment data that will be returned in the response $map['merchant_defined_data2'] = "Yes"

12. Specifying the Signed and Unsigned Fields ALL request fields sent to the SA endpoint, regardless if they are included as part of signing the

data or not, need to be accounted for in either the signed_field_names or unsigned_field_names

variables. Any request parameters that are not listed in either variable will simply be ignored once

the request reaches CyberSource. The signed_field_names variable is a comma delimited string

consisting of fields that will be used to generate a unique signature. This signature is used to

validate data moving between the merchant’s web server and CyberSource. Conversely, any

variable that is not included in generating the signed signature should be listed in the

unsigned_field_names variables.

NOTE: In the configuration guide, the Required API Request Fields section lists the twelve

minimum fields that must be included in the signed_field_names variable list. Other fields, such as

the bill_to_forename or bill_to_surname, can be assigned to either list.

Legacy HOP

NA since the legacy HOP signature functions provided this functionality.

Secure Acceptance

//Specifying the signed and unsigned fields $map['signed_field_names'] = "access_key,profile_id,amount,currency,transaction_type,reference_number, signed_date_time,locale,transaction_uuid,signed_field_names, unsigned_field_names"; $map['unsigned_field_names'] = "merchant_defined_data1,merchant_defined_data2,bill_to_forename, bill_to_surname,";

18

Part 3: Modify the response message

integration You must locate the section of your code which handles the reply messages from legacy HOP/SOP.

1. Accommodate new response field names The code must be updated to reflect the new SA response field names as opposed to the legacy

HOP/SOP response field names. More information about the field mappings can be found at the

CyberSource Secure Acceptance Migration Resource Center in the Field Mapping Guide.

2. Implement the new signature verification function Update any references to the old security file (HOP.php by default) to reference the new SA

security file (security.php by default).

Legacy HOP/SOP // Security File

<?php include("HOP.php") ?>

Secure Acceptance // Reference the new security file

<?php include ("security.php") ?>

The default function has been renamed from VerifyTransactionSignature() to sign().

Legacy HOP/SOP

// Specifying the verification function echo ‘<tr><td>VerifyTransactionSignature()</td><td>’ . verifyTransactionSignature(map) . ‘</td></tr>’;

Secure Acceptance

// Specifying the verification function using the sign() function

echo ‘<tr><td>VerifyTransactionSignature()</td><td>’ . sign($_POST) . ‘</td></tr>’;

You need to match the value returned from sign() to the signature returned in the SA response message.

A match represents data integrity and eliminates the possibility of tampering.

//Use the sign function in the security file and compare with the

//signature value that is posted in the response.

if (sign($_POST)==$_POST["signature"])

{ //if they match, the data is valid.

echo '<tr><td>Valid Signature:</td><td>' .'Signatures Match'. '</td></tr>';

}

else

{ //otherwise the data is invalid.

echo '<tr><td>Valid Signature:</td><td>' .'Uh oh! The signatures dont match! Invalid Response'.

'</td></tr>';

}

19

Part 4: Test your updated integration to SA Execute a SA Web/Mobile or SA SOP transaction by using a web browser to execute your updated code,

which should look similar to this:

1. Updated Request Page: // Reference the new security file

<?php include ("security.php") ?>

<h1>sample_product_name</h1>

<p>Here, you enter the description of your product.</p>

// The new Secure Acceptance Endpoint

<form action="https://testsecureacceptance.cybersource.com/pay" method="post"/>

<?php

$map;

// Specifying the selected profile's access key

$map['access_key']= "76555ea3221d32688f7d24730deee1af";

// Specifying the selected profile

$map['profile_id']= "primer1";

$map['amount']= "15.00";

$map['currency']= "usd";

// Specifying the transaction type

$map['transaction_type']= "authorization";

// Establishing the timestamp

$map['signed_date_time']= gmdate("Y-m-d\TH:i:s\Z");

// Specifying the merchant reference code

$map['reference_number']= "12345";

// Passing prepopulated data to the SA endpoint

$map['bill_to_forename']= "John";

$map['bill_to_surname']= "Doe";

// Passing non-payment data that will be returned in the response

$map['merchant_defined_data1'] = "My Merchant Defined String";

$map['merchant_defined_data2'] = "Yes";

// Specifying the locale

$map['locale'] = "en";

// Specifying the unique transaction id

$map['transaction_uuid'] = uniqid();

// Specifying the signed and unsigned fields

$map['signed_field_names'] =

"access_key,profile_id,amount,currency,transaction_type,reference_number,signed_date_time,locale,transaction_uuid,signed_field_names,unsigned_field_names";

$map['unsigned_field_names'] = "merchant_defined_data1,merchant_defined_data2,bill_to_forename,bill_to_surname,";

foreach($map as $name => $value) {

echo "<input type=\"hidden\" id=\"" . $name . "\" name=\"" . $name . "\" value=\"" . $value . "\"/>\n";

}

// And finally, generating the signature

echo "<input type=\"hidden\" id=\"signature\" name=\"signature\" value=\"" . sign($map) . "\"/>\n";

?>

<input type="submit" value="Buy Now">

</form>

20

2. Updated Receipt Page:

// Reference the new security file <?php include ("security.php") ?> <h3>Sample PHP Receipt Page</h3> <table border="1"> <tr><td><b>Field Name</b></td><td><b>Field Value</b></td></tr> <?php while(list($key, $val) = each($_POST)) { echo '<tr><td>' . $key . '</td><td>' . $val . "</td></tr>"; } // Use the sign function in the security file and compare with the // signature value that is posted in the response. if (sign($_POST)==$_POST["signature"]) { //if they match, the data is valid. echo '<tr><td>Valid Signature:</td><td>' .'Signatures Match'. '</td></tr>'; } else { //otherwise the data is invalid. echo '<tr><td>Valid Signature:</td><td>' .'Uh oh! The signatures dont match! Invalid Response'. '</td></tr>'; } ?> </table>

21

Part 5: How to Debug SA Transactions

during the Migration It is common to encounter errors due to missing required (signed) field/s or incorrect signature calculation.

At some point during the migration, you may encounter an error page when attempting to submit a

transaction to SA.

For root cause of the error, visit Transaction Search -> Secure Acceptance Search within the

CyberSource EBC, and execute a search based on the account suffix, surname/last name, merchant

reference number, transaction UUID, request id, or date range.

After receiving the results of the search, by selecting the magnifying glass of a transaction of which you

want to see more detail, you will be presented with a log that shows the data submitted for that

transaction along with any error codes and/or descriptions that would provide insight as to why the

transaction failed.

22

In the screenshot below, the details log indicates that the unique transaction ID was not submitted with

the request.

23

Part 6: SA Migration Checklist

# Task Notes Completed

Secure Acceptance Setup

1 Setup SA within the CyberSource EBC ☐

1.1 Enable SA within the EBC on your CyberSource MID(s)

☐

1.2 Determine your ability to eliminate multiple CyberSource MIDs through the introduction of SA Profiles

☐

1.3 Choose between SA Web/Mobile or SA SOP and create a profile

☐

1.4 Configure SA profile settings which translate directly from HOP/SOP settings

☐

1.5 Enable SA features and functionality which do not translate directly from HOP/SOP settings

☐

1.6 Create and activate a Security key ☐

1.7 Promote the Profiles to Active ☐

Modifying Legacy HOP/SOP Checkout Page

2 Locate and modify legacy HOP/SOP checkout page ☐

2.1 Update to new SA endpoint ☐

2.2 Download, modify, and reference the new security file

☐

2.3 Populate the profile_id and access_key within the form POST

☐

2.4 Populate the signed_date_time ☐

2.5 Populate the locale ☐

2.6 Generate a unique transaction_uuid for each transaction request

☐

2.7 Populate the transaction_type ☐

2.8 Populate the reference_number ☐

2.9 Map legacy field names to new field names ☐

2.10 Update field names for optional fields included in the form POST

☐

2.11 Populate merchant_defined_data[0-100] fields ☐

2.12 Specify the signed and unsigned fields ☐

Modifying the Receipt Page

24

# Task Notes Completed

3 Locate and modify receipt page that is referenced in your Accept and Decline URLs

☐

3.1 Map legacy field names to new field names ☐

3.2 Implement new function to validate the response signature by referencing the new security file

☐

Modifying Code Specified in Merchant POST URL (if using)

4 Locate and modify page that is referenced in your merchant POST URL

☐

4.1 Map legacy field names to new field names ☐

4.2 Implement new function to validate the response signature by referencing the new security file

☐

25

Appendix A: IFrame (Inline Frame) Support

on Secure Acceptance CyberSource has developed a proof of concept currently under security review which will enable IFrame-

based implementations on a subset of Secure Acceptance profiles. In order to prevent the impact of

session hijacking and session fixation attacks, IFrame implementations may be enabled on all profiles

except Web/Mobile multi-step checkout.

Profiles which are enabled for IFrame will observe the following impact:

1. Limited data returned by CyberSource to the transaction response page via the browser. Note

that full data will continue to be returned via the Merchant POST URL (server-to-server

connection).

2. The SA Profile -> Customer Response Pages -> Retry Limit will be fixed to 0 for declined

transactions.