SecureFrame Integration Guide Secure Frame

User Manual:

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

Download
Open PDF In Browser	View PDF

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



Added responsive template



Added details for TLS encryption

1.5

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

Surcharge Result Fields

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
© SecurePay Pty Ltd

Page 3 of 32

Introduction

 American Express
 BankWest

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.

 Commonwealth Bank
 Diners Club
 National Australia Bank
 St George (including Bank of SA)
 Westpac
SecureFrame supports card transactions only.

1.2 Intended Audience

It is a fully hosted service and comes with a variety of
options to help you integrate such as:

This document is intended for developers, integrating
SecurePay’s SecureFrame with their applications or
shopping cart.



Full page templates



Call-back of results to your application

It is recommended that someone with web site, HTML
and application programming experience reads this
guide and implements SecureFrame.



Redirect options for receipt page



FraudGuard



Surcharging

1.3 System Overview



Card storage and tokenisation

SecurePay’s SecureFrame provides merchants with the
ability to process card payments in a secure
environment.



3D Secure

1.4 Feedback

SecurePay partners with the following major banks and
financial institutions in the provision of the SecurePay
Payment Gateway:

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.

 ANZ

If you wish to leave feedback, please click here.

Page 4 of 32

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 5 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
login/registration page.
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 6 of 32

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:

…

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 7 of 32

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

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

Page 8 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

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 9 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 10 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”

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 11 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

name="store_type” value=”payor”>
name="payor” value=”MyCustomer”>

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

name="store_type” value=”TOKEN”>
name="payor_ref” value=”123456”>

In this example, the Payment Reference ID
Reference for future triggering are the same.

and

the

stored

Transaction

Page 12 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
• 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.
merchant_id|TransactionPassword|txn_type|store_type|payor|fp_timestamp

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 13 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

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 14 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 15 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 16 of 32

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

surcharge_fee

return_url_text

txn_type
amount

Card Storage

surcharge_rate_v

return_url_target

primary_ref

Store

surcharge_fee_v

callback_url

surcharge_rate_m

cancel_url

Card Storage (Optional)

surcharge_fee_m

cancel_url_text

store_type

surcharge_rate_a

cancel_url_target

payor

surcharge_fee_a

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

fp_timestamp
fingerprint

delivery_country
email_address

confirmation

page_footer_image
page_title
card_types
page_style_url

Page 17 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:










TYPICAL USE:

“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

Page 18 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:

TYPICAL USE:

Page 19 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 20 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 21 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 22 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:

return_url_text
CLASS:

Optional

FORMAT:

String, length up to 30 characters

DEFAULT:

none

Page 23 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:

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 24 of 32

TYPICAL USE:

Page 25 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

page_footer_image
CLASS:

Optional

Page 26 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

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:

Fraud Guard Fields
billing_country
CLASS:

Optional

FORMAT:

String, length 2, country code

DEFAULT:

None

Page 27 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 28 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 29 of 32

cardtype

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

“Visa”



“MasterCard”



“American Express”



“Diners”



“JCB”



“PayPal”

Page 30 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 preauthorisation 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 31 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.

Page 32 of 32

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : No
Page Count                      : 32
Language                        : en-AU
Tagged PDF                      : Yes
Title                           : SecureFrame Integration Guide
Author                          : SecurePay
Creator                         : Microsoft® Word 2016
Create Date                     : 2017:02:28 16:59:04+11:00
Modify Date                     : 2017:02:28 16:59:04+11:00
Producer                        : Microsoft® Word 2016

EXIF Metadata provided by EXIF.tools

SecureFrame Integration Guide Secure Frame

Navigation menu

Versions of this User Manual:

Views

Navigation