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 [email protected] 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.