SecureFrame Integration Guide Secure Frame

User Manual:

Open the PDF directly: View PDF .
Page Count: 32

SecureFrame Integration Guide

Document Control

This is a control document

DESCRIPTION

SecureFrame Integration Guide

CREATION DATE

02/10/2013

CREATED BY

SecurePay

VERSION

1.6

DATE UPDATED

28/02/2017

CHANGES

1.6

 New Production and Test URLs

 Removed reference to DirectPost parameters

1.5

 Added responsive template

 Added details for TLS encryption

 
© SecurePay Pty Ltd 
Page 3 of 32 
Table of Contents 
1 Introduction............................................................ 4 
1.1 About this Guide ............................................ 4 
1.2 Intended Audience ........................................ 4 
1.3 System Overview ........................................... 4 
1.4 Feedback ....................................................... 4 
2 Additional Payment Choices .................................. 5 
2.1 Payment Choice - PayPal .............................. 5 
 Technical Overview - PayPal  6 
3 Integration.............................................................. 7 
3.1 General Information ...................................... 7 
 TLS Support  7 
 Case Sensitivity  7 
 Sending Data  7 
 Acceptable Input Fields  7 
3.2 Transaction URLs .......................................... 7 
 Test URL  8 
 Live URL  8 
3.3 Mandatory Input Fields ................................. 9 
 Bill Name  9 
 Merchant ID  9 
 Transaction Type  9 
 Transaction Reference  9 
 Transaction Amount  10 
 GMT Timestamp  10 
 Fingerprint  11 
3.4 Transaction Options ................................... 11 
 Receipt Page Redirect  11 
 Card Storage  12 
 Currency  13 
 Surcharging  13 
 Template  14 
 Look and Feel  14 
 PayPal  14 
 FraudGuard  15 
 3D Secure  15 
3.5 Receiving Result Parameters .................... 15 
3.6 Testing ........................................................ 16 
 Test Card Number, Type and Expiry 16 
 Simulating  Approved  and  Declined 
Transactions  16 
4 Appendices .......................................................... 17 
4.1 Appendix 1: Accepted Input Fields ............ 17 
4.2 Mandatory Fields ........................................ 18 
 Transaction Fields  20 
 Card Storage Fields  21 
 Surcharge Fields  22 
 Transaction Flow Fields  23 
 Look and Feel Fields  26 
 Fraud Guard Fields  27 
4.3 Appendix 2: Result Fields .......................... 28 
 Standard Result Fields  28 
 Preauthorisations  31 
 FraudGuard Result Fields  31 
 Card Storage Result Fields  31 
 Surcharge Result Fields  32 
 

Page 4 of 32

1 Introduction

1.1 About this Guide

This guide provides technical information about

integrating and configuring SecurePay’s SecureFrame

within your shopping cart or application.

SecureFrame offers a secure and flexible hosted

service that helps you meet your PCI DSS obligations.

1.2 Intended Audience

This document is intended for developers, integrating

SecurePay’s SecureFrame with their applications or

shopping cart.

It is recommended that someone with web site, HTML

and application programming experience reads this

guide and implements SecureFrame.

1.3 System Overview

SecurePay’s SecureFrame provides merchants with the

ability to process card payments in a secure

environment.

SecurePay partners with the following major banks and

financial institutions in the provision of the SecurePay

Payment Gateway:

 ANZ

 American Express

 BankWest

 Commonwealth Bank

 Diners Club

 National Australia Bank

 St George (including Bank of SA)

 Westpac

SecureFrame supports card transactions only.

It is a fully hosted service and comes with a variety of

options to help you integrate such as:

 Full page templates

 Call-back of results to your application

 Redirect options for receipt page

 FraudGuard

 Surcharging

 Card storage and tokenisation

 3D Secure

1.4 Feedback

Continuous improvement is one of SecurePay's core

values. We welcome any feedback you have on our

integration guides as a way to help us improve any

future changes to our products.

If you wish to leave feedback, please click here.

Page 5 of 32

2 Additional Payment Choices

SecureFrame also provides the following payment options. Please contact the Payment Choice provider for

details on how to sign-up.

 PayPal

2.1 Payment Choice - PayPal

If you wish to enable your SecurePay account to accept PayPal transaction via SecureFrame please follow the

steps below:

Step 1: Inform the SecurePay Support team of your intention to use PayPal.

Step 2: If you don’t have a Business PayPal account, establish an account with PayPal.

Step 3: Login to the SecurePay Merchant Login.

Step 4: Navigate to the following location:

 Click on [Manage] dropdown list and click on [PayPal Settings].

 Click on [Change Settings] button.

Step 5: Click on the [Retrieve API Credentials] link on the page.

Note: A popup window will appear. Please ensure you have popups enabled in your web browser.

Step 6: Login to PayPal using your credentials.

Step 7: Copy and paste the credentials into [Step 8] and close the popup window.

Step 8: Add the following PayPal credentials obtained from [Step 7] to the SecurePay PayPal settings page:

 API Username

 API Password

 API Signature

Step 9: Add the company logo URL. The URL must be publically accessible and securely hosted (HTTPS).

Step 10: Save changes.

Note: Once PayPal has been enabled and configured successfully, you can view PayPal transactions

processed via SecureFrame through the SecurePay Merchant Login.

Page 6 of 32

Technical Overview - PayPal

PayPal uses a secure page, hosted by PayPal and presented to your customer as part of the payment

authorisation. To enable PayPal transactions through SecureFrame (from your end), the website must pass

through the tender type of “PAYPAL” within the “card_types” SecureFrame input field.

Step 1: Generate a Fingerprint

A Fingerprint is generated in your website code by a SHA1 hash comprised of your SecurePay

Merchant ID and transaction password, transaction type, transaction reference, your payment amount

and a timestamp. This value is then presented on your payment form as a hidden field.

Step 2: Website submits transaction to SecureFrame

Your website submits the transaction details to SecureFrame, which will interpret the optional

“card_types” input to determine if “PAYPAL” is included.

If included, SecureFrame will render the alternative payment page, which allows the customer to

select either to pay with any of the accepted card types, or to select PayPal.

If the customer selects PayPal and the “Continue” button, they will be presented with the PayPal

Step 3: Customer’s PayPal account

Your customer logs into or registers their PayPal account, confirms shipping and billing details (as

required), and selects the payment tender. Your customer will then submit the payment for

processing.

Step 4: Redirect to SecureFrame result page

Upon completion of the transaction, the customer is redirected to the SecureFrame result page.

Step 5: Customer returned to the online store

The customer selects to “Continue” from the SecureFrame result page and using the “return_url” or

“return_url_target” they will be redirected to the URL specified. This also passes the result

parameters back to your system. Your system should check the Fingerprint, update your database and

display the receipt to the Customer.

Note: to ensure that the result is passed back to your system successfully, it is recommended that you

use the “callback_url” field. This passes the results back to your system as soon as the transaction is

complete, rather than waiting for the customer to select the “Continue” button. This prevents missing

transactions caused by customers closing the web browser without selecting to “Continue”.

Important Information: Processing a PayPal transaction

 Only “txn_type=0” is supported to process a PayPal transaction.

Any other transaction type, used in conjunction with

“card_types=PAYPAL” will return the error: “Unsupported Transaction

Type for PayPal”

 SecurePay FraudGuard and 3D Secure (Verified by Visa and MasterCard

SecureCode) cannot be used in conjunction with PayPal payments.

Page 7 of 32

3 Integration

3.1 General Information

TLS Support

SecurePay takes security very seriously. As such, TLS 1.0 is the minimum HTTPS protocol that is accepted

for your return_url and callback_url.

It is strongly recommended that TLS 1.2 with a minimum of sha-265 cipher strength is used as this will

become mandatory in late 2017.

SecurePay's trust stores will require that the certificate is installed correctly and with proper chaining, if you

are having issues with your application receiving a response please confirm that your certificate is correctly

installed.

Below is a list of supported certificate vendors:

• Verisign

• GeoTrust

• Thawte

Case Sensitivity

All field “name” and “value” attributes should be treated as case sensitive.

Sending Data

SecureFrame accepts POST or GET data from your application to initiate a transaction, however POST is the

preferred action type.

When using an HTML form, the following “form” tags are used to encapsulate SecureFrame inputs:

…

</form>

All INPUT fields must occur between the “form” tags for correct submission of information to the

SecureFrame Live and Test servers.

You may also add the “name” attribute or any other form functionality that you require.

Acceptable Input Fields

Any HTML form tags may be used to submit information to SecureFrame.

This document deals predominantly with the “input” tag, however, you may use any form tag to create the

necessary name/value data pairs that form the information interpreted by the service.

Most data is normally passed as “hidden” type input fields. Some fields that may be entered by your

Customer are typically passed as “text” type input fields.

Form inputs follow the structure:

3.2 Transaction URLs

Listed below are the live and test URLs for performing several functions.

Page 8 of 32

Test URL

https://test.payment.securepay.com.au/secureframe/invoice

Live URL

https://payment.securepay.com.au/secureframe/invoice

Page 9 of 32

3.3 Mandatory Input Fields

Bill Name

The Bill Name defines the flow of the transaction process.

“bill_name” must be set to “transact”

Example: Set the bill name for the default transaction process:

Merchant ID

The Merchant ID field, “merchant_id”, is mandatory. It is the SecurePay account used to process payments.

SecurePay Customer Support will supply your Merchant ID when your account is activated. The Merchant ID

will be of the format “ABC0010”, where ABC00 is your unique account code.

Example: Setting the SecurePay Merchant ID:

Transaction Type

The “txn_type” defines the payment process. It allows switch of the payment type, as well as addition of

optional services such as FraudGuard and 3D Secure. It also forms part of the Fingerprint.

Payment

Payments are real-time, immediately authorised card transactions. Transaction information is submitted by

your customer via SecureFrame to your SecurePay account for immediate processing.

Example: Form fields required to make a card payment

<input type="hidden" name="fingerprint"

value="e5a507d5cb7c76fc11712a57ed134e518a8d264c">

Pre-Authorisation

A pre-authorisation is a transaction that reserves funds on a card account. The Merchant can then complete

the transaction at a later date and receive the funds. If the pre-authorisation is never completed, it expires,

usually after five days. After this, the reserved funds are again available to the card holder.

Pre-authorisations are often used by hotels to reserve funds at booking time and then completed when the

guest checks out.

To pre-authorise an amount, submit all the fields exactly as they were for the PAYMENT transaction type

above and set:

Transaction Reference

The "primary_ref" mandatory field is used to tag orders with an identifier meaningful to you. This may be your

invoice number, or could be a unique tracking number produced as part of your own web site.

Page 10 of 32

The Payment Reference is available to the Result URL and emails, and appears as the Transaction Reference

in the SecurePay Merchant Log In.

It is recommended that the Transaction Reference is unique to aid in reconciliation.

Example: Defining a Transaction Reference

Scenario: Your Company wants to include its invoice numbers with every

payment.

Transaction Amount

The "amount" mandatory field is the amount that will be transacted through your SecurePay account. By

default the currency is AUD (Australian Dollars).

It must be passed in the base unit of the currency. For Australian Dollars this is cents. For example, $1.00

AUD would be passed as “100”. 100 Yen would be passed as “100”.

Example: Setting the transaction amount

Scenario: A customer chooses items from your shopping cart totalling

AUD$53.20.

GMT Timestamp

You must pass a valid Greenwich Mean Time (GMT) timestamp in the field "fp_timestamp" (also known as

UTC).

The timestamp used to generate the fingerprint must exactly match the one

sent with the associated transaction.

It must be of the format "YYYYMMDDHHMMSS" where:

YYYY is the current year

MM is the current two digit month 01 – 12

DD is the current two digit day 01 - 31

HH is the current two digit hour in 24-hour format 01 - 24

MM is the current two digit minute 00 – 59

SS is the current two digit second 00 – 59

Example: Setting the GMT timestamp

Scenario: Your system has generated a Fingerprint. It is currently 22:35:05

on 20/06/2011 in Sydney (+10 hours from GMT). The time in GMT is

12:35:05 on the same day.

Page 11 of 32

Fingerprint

The Fingerprint is a protected record of the amount to be paid. It must be generated and then included as

an input field to SecureFrame. It prevents a customer modifying the transaction details when submitting

their card information.

The Fingerprint is a SHA1 hash of the above mandatory fields, plus the SecurePay Transaction Password in

this order with a pipe separator “|”:

 “merchant_id”

 Transaction Password (supplied by SecurePay Support)

 “txn_type”

 “primary_ref”

 “amount”

 “fp_timestamp”

Example: Setting the fingerprint

Fields joined with a | separator:

ABC0010|txnpassword|0|Test Reference|100|20110616221931

SHA1 the above string:

697e7f7a26b709f39e7251dc6800a2a165621227

<input type="hidden" name="fingerprint"

value="697e7f7a26b709f39e7251dc6800a2a165621227">

For methods of generating a SHA1 hash in your language please visit:

http://code.wikia.com/wiki/SHA_checksum

3.4 Transaction Options

Receipt Page Redirect

Display of the receipt page and button options on the hosted receipt page can be optionally controlled.

By default, SecureFrame will display the receipt page to the customer.

To redirect to your own receipt page, set “display_receipt=no”.

If SecureFrame displays the receipt (default), you can control the button on the receipt page via the following

optional parameters:

 return_url – the fully qualified URL to embed in the button link. The system will append result parameters

to this link by default.

 return_url_text – the text of the button

 return_url_target – the target of the button. This can be one of “self”, “new”, “parent” or “top”. “parent”

is useful when using the iFrame template to take the browser back to full screen.

Example: Set the button to say “Continue...” and take the browser out of

the iFrame when clicked.

By default, the return_url is used when a Cancel button is clicked by the card holder. This url can be explicitly

set by using the “cancel_url” parameter.

Page 12 of 32

Card Storage

The card number used in the transaction may be optionally stored for subsequent batch or XML transaction

triggering.

By setting the field "store=yes”, the card will be stored in SecurePay’s Payor system using the “primary_ref”

as the Payor ID by default.

Payor

This is the default card storage method.

With Payor storage, you define the Payor ID to store with the card. Cards and Payor ID’s can be edited via

the Merchant Login.

You may also set “store_type=payor” to use this storage type.

You may optionally pass in an alternative value for the stored Payor ID to override the use of “primary_ref”.

Set “payor” to your required value.

Example: Set card storage with type Payor and my own Payor ID

Token

A Token is a string that represents a stored card number. If the card number changes, so does the token,

therefore card numbers and tokens cannot be edited, they may only be added or deleted.

Tokens can be used in 3rd party systems to represent card numbers.

If a card is passed to the system for storage several times, the same token is always returned.

To have SecurePay generate a token for a card, or return an existing token for a pre-stored card set

“store_type=token”.

SecureFrame will return the token in the result parameters.

Example: Set card storage with type Token

Stored Transaction Reference

When triggering a payment from a stored card of either type Payor or Token via batch or API, the Transaction

Reference defaults to the Payor ID (or Token). This can be overridden by setting a specific Transaction

Reference at the time of storage.

Set the “payor_ref” field to store your desired Transaction Reference against the stored card.

This is particularly useful; for tokens, as the token does not necessarily represent your Customer.

Example: Set card storage with type Token and your own Transaction Reference

In this example, the Payment Reference ID and the stored Transaction

Reference for future triggering are the same.

Page 13 of 32

Store Only

When you choose to store a customer’s card details in SecurePay’s card storage system when a Direct Post

transaction is processed, you can optionally choose to store their card details without charging their card.

This is known as the Store Only method.

When you use Store Only, the amount included is ignored and is not stored against the customer’s details.

Note: As there is no transaction processed with this option, the card number, expiry date and cvv are not

validated with the bank at this step.

To use Store Only, additional to the standard mandatory fields you must:

• Pass through the txn_type value of 8 in your requests. This value is defined further in Section 4.2.1.3.

TYPICAL USE <input type=”HIDDEN” name=”txn_type” value=”8”>

• Set display_receipt to false – See section 4.2.5.1 for more details.

• Set confirmation to false – See section 4.2.5.7 for more details.

• Set store_type to “payor”.

• Set store to “yes”.

• Pass through payor to set the value for the payor id.

• Generate a fingerprint and pass this through as the fingerprint value in your requests. This is a protected

record of the transaction details and prevents a customer modifying the details when submitting their card

information. Your system will need to create a SHA1 hash of the following fields in order, separated by “|”.

These fields are different to the standard fingerprint fields described in Section 4.2.1.7.

Example:

ABC0001|abc123|8|payor|PayorTest|20151124062343

TYPICAL USE <input type=”HIDDEN” name=”fingerprint” value=”

bc4a4bd7ed72937ec86a510c85852f1610224439”>

When you use Store Only, only the following result fields are returned:

• strestext

• fingerprint

• strescode

• payor

• summarycode

Currency

If your bank supports multicurrency, you may optionally set the currency of the transaction to one other than

AUD.

Set the field “currency” to any ISO three letter currency value.

Example: Set the currency to USD

Surcharging

Surcharging may be applied across all card types (Visa, MasterCard, etc.), or set individually per card type

Surcharging can be either or both:

 A percentage rate of the invoice total (E.g. 1%)

Page 14 of 32

 A flat fee (E.g. $2.00). The fee is added on top of any rate.

To activate surcharging set “surcharge=yes”. This will not apply any surcharging unless rates and/or fees

have been set. It will turn on optional result parameters.

To set a surcharge rate of 1%, set “surcharge_rate=1”.

Example: Set a surcharge rate of 1% for all cards

Individual rates and fees may be also set per card.

Example: Set a surcharge rate of 1% for Amex only

Template

There are several options to control how the hosted pages are displayed to your customers. This is controlled

by the optional “template” parameter. Responsive is the recommended template.

Set “template=responsive” to use the responsive version. This version displays only the input fields,

confirmation text and form buttons. It also will perform well on multi form devices and has friendly CSS

tagging.

Set “template=default” to use the full screen payment option. If the template parameter is omitted, this is

the default.

Tip: use the Return URL text and target options to control the payment flow from within the iFrame.

Example: Set the template to responsive

Look and Feel

Several options can be passed to the system to change the look and feel. These include the header logo,

the page title and the primary reference name, among others.

Example: Set the logo, title and primary reference values

<input type="hidden" name="page_header_image"

value="https://www.mysite.com.au/header.jpg">

For more look and feel options, please see the Appendices.

PayPal

SecureFrame contains the ability to pass customers to PayPal to complete their transaction through their

PayPal account. If your SecurePay account is enabled to use this feature and your website passes through

“PAYPAL” under “card_types”, the SecureFrame payment page will render differently to normal, enabling a

tender selection between the accepted card types and PayPal.

Without passing through “PAYPAL” under “card_types” the normal SecureFrame credit card payment page

will be rendered, which will accept the “card_types” passed through.

To enquire about enabling this feature on your SecurePay account please speak to SecurePay’s Payment

Gateway Advisors on 1300 786 756 (option 2).

Example: Set the accepted tenders to Visa, MasterCard and PayPal

Page 15 of 32

FraudGuard

FraudGuard is an optional service offered by SecurePay. It must be activated on your SecurePay account,

before it can be enabled by setting the “txn_type” field.

See the Appendices for more details.

Please contact SecurePay Sales for pricing and more information.

3D Secure

The 3D Secure service is a combined offering of Verified by Visa and MasterCard SecureCode. It must be

activated on your SecurePay account, before it can be enabled by setting the “txn_type” field.

See the Appendices for more details.

Please contact SecurePay Sales for pricing and more information.

3.5 Receiving Result Parameters

The system will send back to your URL’s a predefined set of result parameters.

Some parameters will only be returned if an option is activated, such as “store”.

The system will POST result parameters the first time it calls your server, but will send result parameters

using the GET method based on RFC 2616 standards after being redirected.

Result parameters are available to you via two methods:

 Return URL – When you specify a result URL, result parameters are appended to the URL. This occurs

for both receipt page redirect and for the return button on the hosted receipt page.

 Call-back URL – SecureFrame contacts your system in the background and sends result parameters

In addition, you can configure a unique cancel URL which overrides the return_url when the Cancel button

is clicked on the page.

All result parameters are listed in the Appendices.

Page 16 of 32

3.6 Testing

As you build your system, you can test functionality when necessary by submitting parameters to the test

URL. You can generate a fingerprint and then complete the transaction by using the card details listed below.

Test Card Number, Type and Expiry

Use the following information when testing transactions:

Card Number: 4444333322221111

Card Type: VISA

Card CCV: 123

Card Expiry: 08 / 13 (or any date greater then today)

Simulating Approved and Declined Transactions

You can simulate approved and declined transactions by submitting alternative payment amounts.

If the payment amount ends in 00, 08, 11 or 16, the transaction will be approved once card details are

submitted. All other options will cause a declined transaction.

Payment amounts to simulate approved transactions:

$1.00 (100)

$1.08 (108)

$105.00 (10500)

$105.08 (10508)

(or any total ending in 00, 08)

Payment amounts to simulate declined transactions:

$1.51 (151)

$1.05 (105)

$105.51 (10551)

$105.05 (10505)

(or any totals not ending in 00, 08)

Note that when using the live URL for payments, the bank determines the transaction result, independent of

the payment amount.

Page 17 of 32

4 Appendices

4.1 Appendix 1: Accepted Input Fields

Mandatory

Transaction

Surcharging

Flow

bill_name

currency

surcharge

display_receipt

merchant_id

display_cardholder_name

surcharge_rate

return_url

txn_type

surcharge_fee

return_url_text

amount

Card Storage

surcharge_rate_v

return_url_target

primary_ref

Store

surcharge_fee_v

callback_url

fp_timestamp

surcharge_rate_m

cancel_url

fingerprint

Card Storage (Optional)

surcharge_fee_m

cancel_url_text

store_type

surcharge_rate_a

cancel_url_target

payor

surcharge_fee_a

confirmation

payor_ref

surcharge_rate_d

Look and Feel

surcharge_fee_d

template

Fraud Guard (Optional)

surcharge_rate_j

primary_ref_name

billing_country

surcharge_fee_j

page_header_image

delivery_country

page_footer_image

email_address

page_title

card_types

page_style_url

Page 18 of 32

4.2 Mandatory Fields

bill_name

CLASS:

Mandatory

FORMAT:

Fixed value “transact”

DESCRIPTION:

Defines the transaction process.

TYPICAL USE:

merchant_id

CLASS:

Mandatory

FORMAT:

Alpha-numeric, length 7

DESCRIPTION:

A unique identifier for the Merchant within the Payment Gateway. This Merchant identifier value is an

alphanumeric string allocated to you by SecurePay. This merchant identifier value is not the same as the

merchant number provided by your bank.

TYPICAL USE:

txn_type

CLASS:

Mandatory

FORMAT:

Numeric

DESCRIPTION:

Used to determine the processing type for an individual transaction. May be one of the following:

 “0” - PAYMENT: A card payment/purchase transaction. Note: This is the only accepted transaction type

for PayPal payments.

 “1” - PREAUTH: Used to pre-authorise an amount on a card. The result parameters include the

“preauthid” which must be stored and used when completing the pre-authorisation

 “2” – PAYMENT with FRAUDGUARD: A card payment/purchase transaction with the optional

FraudGuard service

 “3” – PREAUTH with FRAUDGUARD: A card preauthorisation transaction with the optional FraudGuard

service

 “4” – PAYMENT with 3D Secure: A card payment/purchase transaction with the optional 3D Secure

service

 “5” – PREAUTH with 3D Secure: A card preauthorisation transaction with the optional 3D Secure

service

 “6” – PAYMENT with FRAUDGUARD and 3D Secure: A card payment/purchase transaction with the

optional FraudGuard and 3D Secure services

 “7” – PREAUTH with FRAUDGUARD and 3D Secure: A card preauthorisation transaction with the

optional FraudGuard and 3D Secure services

 “8” – STORE ONLY: This will store the card details without taking a payment or preauthorisation. See

section 3.4.4.4. for more details

TYPICAL USE:

Page 19 of 32

amount

CLASS:

Mandatory

FORMAT:

Numeric, integer, from 1 to 99999999

DESCRIPTION:

The total amount of the purchase transaction. This value must be a positive integer in the base unit of the

currency, such as cents for AUD. Please be careful to correctly specify the amount as the system has no

method of determining whether an amount has been correctly specified.

TYPICAL USE:

primary_ref

CLASS:

Mandatory

FORMAT:

String, min length 1, max length 60

DESCRIPTION:

A string that identifies the transaction. This string is stored by SecurePay as the Transaction Reference. This

field is typically a shopping cart id or invoice number and is used to match the SecurePay transaction to your

application.

TYPICAL USE:

fp_timestamp

CLASS:

Mandatory

FORMAT:

String, format "YYYYMMDDHHMMSS" in GMT (UTC).

DESCRIPTION:

The GMT time used for Fingerprint generation. This value must be the same submitted to generate a

fingerprint as submitted with the transaction. SecurePay validates the time to within one hour of current time.

The time component must be in 24 hour time format.

TYPICAL USE:

fingerprint

CLASS:

Mandatory

FORMAT:

String, length up to 60

DESCRIPTION:

A SHA1 hash of

Where the “TransactionPassword” is obtained from SecurePay Support and maybe changed via the

SecurePay Merchant Log In. All other fields must be exactly as sent.

TYPICAL USE:

<input type="hidden" name="fingerprint"

value="01a1edbb159aa01b99740508d79620251c2f871d">

Page 20 of 32

Transaction Fields

currency

CLASS:

Optional

FORMAT:

String, length 3, ISO 4217 three letter currency code

DEFAULT:

AUD

DESCRIPTION:

Used to set the transaction currency sent to the bank for processing. You must have a bank merchant facility

that accepts currencies other than AUD before using this feature.

Set the currency to any ISO 4217 three letter currency code. E.g. USD, NZD, GBP, etc.

The format of the amount must match the currency. E.g. Yen has no decimal place.

TYPICAL USE:

display_cardholder_name

CLASS:

Optional

FORMAT:

String, values “yes” or “no”

DEFAULT:

yes

DESCRIPTION:

By default, a Cardholder name input field is not displayed to the cardholder.

Setting the “display_cardholder_name” field to “yes” will display the cardholder name input field on the

payment form. This will allow the cardholder to enter their name as part of the payment.

TYPICAL USE:

Page 21 of 32

Card Storage Fields

store

CLASS:

Mandatory for Card Storage

FORMAT:

String, values “yes” or “no”

DEFAULT:

DESCRIPTION

“yes” to enable card storage

TYPICAL USE

store_type

CLASS:

Optional

FORMAT:

String, values “PAYOR” or “TOKEN”

DEFAULT:

PAYOR

DESCRIPTION

Type PAYOR will store the card in the SecurePay Payor database. The “primary_ref” field will be used as the

Payor ID unless overridden with “payor”.

Type TOKEN will either create and store a new token that represents the card number ro return a pre-existing

token if the card has been stored previously. Tokens are stored as non-editable Payors.

TYPICAL USE:

payor

CLASS:

Optional if store_type=PAYOR

FORMAT:

String, length up to 20

DEFAULT:

If not specified, “primary_ref” is used

DESCRIPTION

The Payor ID to store with the Payor. This will become the Transaction Reference for future triggered payments

against that Payor unless overridden with “payor_ref”

TYPICAL USE:

payor_ref

CLASS:

Optional

FORMAT:

String, length up to 30

DESCRIPTION

Sets the Transaction Reference for future triggered payments. If not set, the system will log the Payor as the

Transaction Reference when a payment is triggered

TYPICAL USE:

Page 22 of 32

Surcharge Fields

surcharge

CLASS:

Mandatory for Surcharging

FORMAT:

String, values “yes” or “no”

DEFAULT:

DESCRIPTION

“yes” to enable surcharge calculation and result parameters

TYPICAL USE

surcharge_rate

CLASS:

Optional

FORMAT:

Numerical, 0.0001 to 99.9999

DEFAULT:

DESCRIPTION

Percentage surcharge to apply across all card types. May be overridden by applying individual card type rates.

TYPICAL USE

surcharge_fee

CLASS:

Optional

FORMAT:

Numerical, integer, 0 to 999999 cents (or base currency unit)

DEFAULT:

DESCRIPTION

Fee amount to be added to the payment amount for all card types.

TYPICAL USE

surcharge_rate_v/m/a/d/j

CLASS:

Optional

FORMAT:

Numerical, 0.01 to 99.9

DEFAULT:

DESCRIPTION

Percentage surcharge to apply to a specific card type. Overrides “surcharge_rate”.

TYPICAL USE

Page 23 of 32

surcharge_fee_v/m/a/d/j

CLASS:

Optional

FORMAT:

Numerical, 0 to 999999 cents (or base currency unit)

DEFAULT:

DESCRIPTION

Fee amount to be added to the payment amount for a specific card type. Overrides “surcharge_fee”.

TYPICAL USE

Transaction Flow Fields

display_receipt

CLASS:

Optional

FORMAT:

String, values “yes” or “no”

DEFAULT:

yes

DESCRIPTION

Define which system displays the receipt page to the card holder. “Yes” means SecurePay displays the receipt

page. To redirect to your own receipt page set this value to “no” and use the return_url parameter.

TYPICAL USE

return_url

CLASS:

Optional

FORMAT:

String, fully-qualified URL

DESCRIPTION:

The URL of the page on the Merchant web site that accepts transaction result data as POST elements.

The page may be almost any form of web page, including static HTML pages, CGI scripts, ASP pages, JSP

pages, PHP scripts, etc, however cookies or other forms of additional information will not be passed through

the Payment Gateway.

The “return_url” must be a URL for a publicly visible page on a web server within a domain that is delegated

to a public IP number. Internal machine names, such as "localhost", Windows-style machine names, and

privately translated IP numbers will fail.

If “display_receipt” is set to “yes”, this is the URL of the button on the hosted result page.

If “display_receipt” is set to “no”, this is the redirect URL following a transaction.

Your web host cannot use Server Name Indicators (SNIs) for determining which SSL certificate to serve. This

is not supported by SecurePay’s systems.

TYPICAL USE:

<input type="hidden" name="return_url"

value="http://www.myserver.com.au/result.asp">

return_url_text

CLASS:

Optional

FORMAT:

String, length up to 30 characters

DEFAULT:

none

Page 24 of 32

DESCRIPTION

Defines the text on the hosted result page button that takes the card holder to the next step in the process.

TYPICAL USE

return_url_target

CLASS:

Optional

FORMAT:

String, values “self”, “top”, “parent” or “new”

DEFAULT:

none

DESCRIPTION

Defines the target of the hosted result page button that takes the card holder to the next step in the process.

Useful for iFramed pages to take the process out of the iFrame.

TYPICAL USE

callback_url

CLASS:

Optional

FORMAT:

String, fully-qualified URL

DESCRIPTION:

The URL of the page on the Merchant web site that accepts transaction result data as POST elements.

The page may be almost any form of web page, including static HTML pages, CGI scripts, ASP pages, JSP

pages, PHP scripts, etc, however cookies or other forms of additional information will not be passed through

the Payment Gateway.

The “callback_url” must be a URL for a publicly visible page on a web server within a domain that is delegated

to a public IP number. Internal machine names, such as "localhost", Windows-style machine names, and

privately translated IP numbers will fail.

Your web host cannot use Server Name Indicators (SNIs) for determining which SSL certificate to serve. This

is not supported by SecurePay’s systems.

TYPICAL USE:

<input type="hidden" name="callback_url"

value="http://www.myserver.com.au/result.asp">

cancel_url

CLASS:

Optional

FORMAT:

String, fully-qualified URL

DEFAULT:

Uses the return_url if not present.

DESCRIPTION:

The URL of the page on the Merchant web site that accepts transaction result data as POST elements when

the card holder clicks a Cancel button on a hosted page.

The page may be almost any form of web page, including static HTML pages, CGI scripts, ASP pages, JSP

pages, PHP scripts, etc, however cookies or other forms of additional information will not be passed through

the Payment Gateway.

The “cancel_url” must be a URL for a publicly visible page on a web server within a domain that is delegated

to a public IP number. Internal machine names, such as "localhost", Windows-style machine names, and

privately translated IP numbers will fail.

Note: some result parameters may not be populated depending on the point of cancellation of the process.

Your web host cannot use Server Name Indicators (SNIs) for determining which SSL certificate to serve. This

is not supported by SecurePay’s systems.

Page 25 of 32

TYPICAL USE:

<input type="hidden" name="cancel_url"

value="http://www.myserver.com.au/result.asp">

Page 26 of 32

confirmation

CLASS:

Optional

FORMAT:

String, values “yes” or “no”

DEFAULT:

yes

DESCRIPTION:

By default, a Confirmation page is displayed to the cardholder, after the card details have been entered. This

is to allow the cardholder to review the details (and edit as required) prior to initiating the payment.

Setting the “confirmation” field to “no” will bypass this default confirmation step.

TYPICAL USE:

Look and Feel Fields

template

CLASS:

Optional

FORMAT:

String, values “default”

DEFAULT:

default

DESCRIPTION

Defines which hosted page template is displayed to card holders.

TYPICAL USE

primary_ref_name

CLASS:

Optional

FORMAT:

String, length up to 30 characters

DEFAULT:

Invoice Number

DESCRIPTION

Defines the label on the hosted pages for the Primary Reference field.

TYPICAL USE

page_header_image

CLASS:

Optional

FORMAT:

String, fully-qualified URL. HTTPS method only. Must end in one of gif, jpeg, jpg, png. Valid images only.

DEFAULT:

none

DESCRIPTION

URL of an image to be used as the header of the hosted pages.

TYPICAL USE

<input type="hidden" name="page_header_image" value="

http://www.myserver.com.au/result.asp/header.jpg">

page_footer_image

CLASS:

Optional

Page 27 of 32

FORMAT:

String, fully-qualified URL. HTTPS method only. Must end in one of gif, jpeg, jpg, png. Valid images only.

DEFAULT:

none

DESCRIPTION

URL of an image to be used as the footer of the hosted pages.

TYPICAL USE

<input type="hidden" name="page_footer_image" value="

http://www.myserver.com.au/result.asp/header.jpg">

page_title

CLASS:

Optional

FORMAT:

String, length up to 30 characters

DEFAULT:

Invoice Payment

DESCRIPTION

Defines the title text on the hosted pages.

TYPICAL USE

card_types

CLASS:

Optional

FORMAT:

String, bar “|” separate values from VISA, MASTERCARD, AMEX, DINERS, JCB, PAYPAL

DEFAULT:

Visa, MasterCard

DESCRIPTION

Defines the card types accepted. This must be a subset of the card types you accept.

TYPICAL USE

page_style_url

CLASS:

Optional

FORMAT:

String, fully-qualified URL

DESCRIPTION:

The URL of the page on the Merchant web site that provides styling for the hosted page. Styles override the

default page styles. Images embedded by be fully qualified URL’s. All JavaScript and malicious code will be

removed.

TYPICAL USE:

<input type="hidden" name="page_style_url"

value="http://www.myserver.com.au/hppstyles.css">

Fraud Guard Fields

billing_country

CLASS:

Optional

FORMAT:

String, length 2, country code

DEFAULT:

None

Page 28 of 32

DESCRIPTION

Payee’s Country two letter code

TYPICAL USE

delivery_country

CLASS:

Optional

FORMAT:

String, length 2, country code

DEFAULT:

None

DESCRIPTION

Order delivery country two letter code

TYPICAL USE

email_address

CLASS:

Optional

FORMAT:

String, length less than 30

DEFAULT:

none

DESCRIPTION

Payee’s email address

TYPICAL USE

4.3 Appendix 2: Result Fields

Standard Result Fields

summarycode

The one digit summary of the transaction result:

1 = Approved

2 = Declined by the bank

3 = Declined for any other reason

4 = Cancelled by user

Use “rescode” and “restext” for more detail of the transaction result.

rescode

The primary indicator of the transaction result.

Bank response or internal error code numbers used to determine the transaction result. Rescode's of 00,

08 and 11 indicate approved transactions, while all other codes represent declines. A full list of response

codes is available for download from the SecurePay web site.

restext

The associated text for each "rescode". For bank response codes 00 – 99, this field is generated by the

bank's payment systems. All other codes have the "restext" generated by SecurePay.

Page 29 of 32

refid

The value of the primary_ref parameter from the transactions request. This value is returned to the

Merchant's processing system to allow matching of the original transaction request.

txnid

The bank transaction ID. This string is unique at least per terminal, per bank and per settlement date. This

value is required to be re-entered along with other details of the original payment when processing refunds.

settdate

The bank settlement date. This is the date the funds will be settled into the merchant's account. The date

will correspond to today's date until the bank's cut-off time (typically 6-11pm), then roll to the following

business day. The settlement date is returned in the format "YYYYMMDD".

pan

The masked card number of format first six…last three. E.g. 444433…111

expirydate

The four digit expiry date entered by the customer. E.g. 0813

merchant

The merchant_id value used for the transaction

timestamp

The GMT (UTC) time used for the response fingerprint of the format "YYYYMMDDHHMMSS". This value must

be used when generating a string to compare to the response “fingerprint” value to validate the response.

The time component must be in 24 hour time format.

amount

The amount in the base unit of the currency, typically cents for Australian Dollars. E.g. $104.23 will be

10423.

fingerprint

A string used to validate the transaction output.

A SHA1 hash of the following fields in order, separated by “|”:

For txn_type 0-7:

merchant, transaction password, reference, amount, timestamp, summarycode

For Example:

ABC0010|mytxnpasswd|MyReference|1000|201105231545|1

is SHA1 hashed to give:

3f97240c9607e86f87c405af340608828d331e10

For txn_type 8:

merchant, transaction password, reference, amount, timestamp, summarycode

Page 30 of 32

For Example:

ABC0010|mytxnpasswd|payor|TestPayorID|20151124233909|1

is SHA1 hashed to give:

23af337d9cff81933c34696691436a34d84f395b

cardtype

The card type used for the transaction. This will be one of:

 “Visa”

 “MasterCard”

 “American Express”

 “Diners”

 “JCB”

 “PayPal”

Page 31 of 32

Preauthorisations

Preauth fields are only returned when “txn_type” is set to a preauth transaction type on input.

preauthid

The bank pre-authorisation ID returned by the payment gateway. This value is used when sending a pre-

authorisation complete transaction via XML or Batch.

FraudGuard Result Fields

FraudGuard fields are returned in addition to the Standard Result Fields if your account is enabled for

FraudGuard by the SecurePay Support team and the “txn_type” includes the FraudGuard option.

afrescode

FraudGuard response code if “txn_type” includes FraudGuard. Returns “400” if the transaction passes

FraudGuard tests. Returns a different string depending on the type of fraud detected.

afrestext

FraudGuard response text. Used if the “afrescode” is not 000. Contains a description of the FraudGuard

result.

Card Storage Result Fields

Card storage fields are returned in addition to the Standard Result Fields if the input field “store” “yes” on

input.

stsummarycode

The one digit summary of the storage result:

1 = Successful

2 = Unsuccessful

4 = Cancelled by user

Use “strescode” and “strestext” for more detail of the storage result.

strescode

Storage code Returns “800” if the Payor or Token was successfully stored. Returns a different string if the

storage failed. The “strestext” describes the failure reason.

strestext

Storage response text. Contains a description of the storage result.

payor

If “store_type” is set to “payor” (or absent - default), the “payor” field will be returned in this result field.

token

If “store_type” is set to “token”, the system-generated token will be returned in this field. If the card has

never been stored before, this will be a new value. If the card has been stored previously, the stored value

will be returned.

Page 32 of 32

Surcharge Result Fields

If “surcharge” is set to “yes” on input or the fields are set in your account, the following additional fields are

returned:

baseamount

The amount passed to the system, prior to the addition of the surcharge, in the base unit of the currency,

typically cents for Australian Dollars. E.g. $104.23 will be 10423. This amount added to the “suramount”

equals the “amount”.

suramount

The surcharge amount in the base unit of the currency, typically cents for Australian Dollars. E.g. $104.23

will be 10423. This amount added to the “baseamount” equals the “amount”.

surrate

The surcharge rate in percent used to calculate the surcharge. E.g. 1% = “1”.

surfee

The surcharge fee added to the amount amount in the base unit of the currency, typically cents for Australian

Dollars. E.g. $104.23 will be 10423.

SecureFrame Integration Guide Secure Frame

Navigation menu

Versions of this User Manual:

Views

Navigation