PayWay Net hand-off developers guide

Introduction

The Hosted Payment Page is a PayWay-hosted webpage for accepting credit card and PayPal payments. Your webserver can securely send a shopping cart to PayWay. When your customer visits PayWay to pay, the shopping cart is displayed. Once the payment is accepted, your website receives notification of the payment.

This page describes how to implement this solution.

Alternatively, if you are not a software developer, you may wish to set up a simple link from your website to the PayWay hosted page.

Your PayWay login name and password

You will require a login to PayWay to:-

• Configure PayWay Net Hosted Payment Page,
• Link a PayPal account to your PayWay facility,
• View test payments you have conducted.

Sign In to PayWay. On first sign in, you will be asked to change your password and answer security questions. Keep a copy of your username and password in a secure location. If you require a password reset, you can do this online by answering your security questions.

Free test facility

For a free test facility Create a test sign in.

Configuring PayWay Net

To configure PayWay Net hosted payment page:

1. Sign in to PayWay
2. Click Setup Net
3. Click Hosted Payment Page and follow the wizard

Bill Payments/Shopping Cart

This section describes only the deprecated "Bill Payments/Shopping Cart" option.

Required technology:

• A dynamic back-end which can send a HTTPS POST directly to PayWay server,
• The ability to make an outbound HTTPS connection to PayWay through your proxy and firewall (for secure token request),
• A valid TLS certificate issued by a trusted certificate authority (for server to server payment notification),
• A dynamic back-end which can receive and parse HTTPS requests with parameters or can parse XML (for customising receipt page),
• The ability to decrypt and verify data encrypted using AES with Cipher Block Chaining (for customising receipt page)

You can pass parameters for information fields to display to the customer, hidden fields to be displayed on internal invoices and products in the shopping cart. You can request a server-to-server payment notification for straight-through processing, and customise the receipt page. Look and feel can be changed by uploading images and a custom style sheet to PayWay.

Linking a PayPal account

If you wish to accept live payments via PayPal you will require a PayPal Business or Premier account. You can use an existing one or create a new one.

Your PayPal Business or Premier account is linked to PayWay as follows:-

1. Sign-in to PayWay
2. Click on Administration and then Manage PayPal Accounts
3. Click Link Another PayPal Account
4. Enter the email address of your account and click Next. You will be redirected to PayPal.
5. Sign in to PayPal using your PayPal email address and password
6. Click Grant Permissions to allow PayWay to use your PayPal account. This informs PayPal that you allow PayWay to process on your behalf.
7. In order to enable PayPal, add the parameter paypal_email with the value of the email address you linked above when sending parameters from your website to PayWay.

Sending parameters to PayWay

Secure token request

The shopping cart parameters are passed directly from your server to PayWay. This means that the customer cannot tamper with parameters. The secure token request works as follows:

1. Your customer's browser requests the checkout page from your server
2. Your server sends a cart token request directly to PayWay. The request contains all fields from your shopping cart (e.g. total payment amount, products) and other parameters.
3. PayWay stores the cart details and responds with a cart token.
4. Your site returns a HTML page to the browser including a form containing your biller code and the token. The HTML form instructs the browser to POST directly to the PayWay server when submitted.
5. The customer's browser displays the HTML form to the customer.
6. The customer submits the HTML form, and the browser sends it directly to PayWay.
7. PayWay looks up the details based on the cart token and the payment flow continues.

What is a cart token?

After sending the shopping cart parameters to PayWay through a cart token request, you will receive a randomly generated string of characters which is called a cart token. When the customer arrives at the PayWay website via their browser, PayWay looks-up the shopping cart details from the cart token. Cart tokens are valid for 1 hour after they have been created, and can only be used once each.

How do I request a card token?

To request a cart token, your server sends a HTTPS POST to:

URL for Westpac PayWay

https://www.payway.com.au/RequestToken

URL for St. George PayWay

https://payway.stgeorge.com.au/RequestToken

The request body contains parameters in application/x-www-form-urlencoded format. You must provide your biller_code, username and password as parameters in your token request.

In addition you may provide other parameters described in this document. Tokens are only accepted for a list of IP addresses that you must configure on the Security Information page in the Setup Hosted Payment Page wizard.

3-D Secure

Token request parameters that are required to process the transaction with EMV 3-D Secure Version 2.

Send these parameters:

• Authentication Purpose: the reason for authenticating the card
• Purchase Information: the amount and frequency of intended payments
• Merchant Risk Indicator: parameters to allow the risk of the transaction be to calculated
• Cardholder Contact Details: email and phone numbers for your customer
• Billing Address: your customer's billing address
• Shipping Address: the address where you will ship physical goods
• Cardholder Account: information about the cardholder's account on your website

Authentication purpose

Purchase information

If you will immediately conduct a payment or conduct a recurring series of payments, send these parameters:

Merchant risk indicator

We strongly recommend you send these parameters:

Cardholder Contact Details

Use international format for phone numbers. e.g. +61499999999

Billing Address

These required parameters contain the billing address associated with the credit card.

Shipping Address

Send these parameters if you will ship physical goods to the cardholder:

Cardholder Account Information

These parameters contain optional information about the Cardholder Account on your website. Parameters used to define a time period can be included as either the specific date or an approximate indicator for when the action occurred. You can use either format.

If the cardholder has not signed in to your website, send these parameters:

If the cardholder has signed in to your website, send these parameters:

Parameters

The built-in parameters you can pass to PayWay are listed in PayWay Request Parameters. You can create your own parameters for information fields, hidden fields and products.

Use this URL to conduct hosted payment page transactions:

URL for Westpac PayWay

https://www.payway.com.au/MakePayment?BillerCode=XXXXXX&token=TTTTT

URL for St. George PayWay

https://payway.stgeorge.com.au/MakePayment?BillerCode=XXXXXX&token=TTTTT

Your Biller Code can be found in the Setup Net wizard. You obtain a token as described above.

Information fields

Information fields are additional fields that you wish to display on the payment pages. You provide a list of information fields using built-in parameters information_fields and suppress_field_names as follows:

These parameters will appear in a tabular format as transaction details on the payment page. If you do not wish to display the label of an information field (say, for Address2) you can suppress field names. This is done with suppress_field_names, in the same format as information_fields.

Hidden fields

Hidden fields contain information that is not displayed to the customer but may be returned to your website via:

• server to server payment notification,
• browser redirect after payment (if specified in URL).

Hidden fields are visible when you sign-in to PayWay and view transactions. You can instruct PayWay to hide fields using the hidden_fields parameters as shown in the example below. In this example, PromotionCode and PartnerCode are hidden fields.

Product fields

Parameters which are not built-in parameters and not listed as hidden fields or information fields will be interpreted as product fields.

The format of product fields is as follows:-

These examples:

• Add 5 DVDs worth $20.50 each to the transaction.
• Add one OLED TV worth $9999.99 to the transaction.

PayWay will calculate the total product costs based on all products. There are options for calculating and displaying GST using gst_rate, gst_added and gst_exempt_fields. See PayWay Request Parameters.

Receiving payment notification

PayWay Net can notify you with the result of each individual payment to allow you to process the order. This notification can be sent:-

• Via email to your nominated email address,
• Directly from PayWay to your server over HTTPS for straight-through processing.

Configure these options using the Setup Net menu option. The remainder of this chapter discusses the HTTPS payment notification option.

Pre-requisites

In order to use server to server payment notification, your website must have:

• a valid TLS certificate issued by a trusted certificate authority,
• a dynamic back-end which can receive and parse HTTPS requests with Basic Auth and parameters or can parse XML.

Security

It is important for you to verify that the notification originated from the PayWay server and not a fraudster. To allow you to verify this, a username and password are included in each notification.

Your website must check that the Basic Auth username and password in the Authorization header match your credentials in PayWay for each notification to ensure that the request came from the PayWay server. If the username or password is not correct, you must ignore the notification. To find your PayWay Net server to server payment notification username and password refer to the Configuration section below. This is not the same password that you use to sign-in to the PayWay website.

Configuration

To configure server to server payment notifications use the Setup Net pages in PayWay. You must be using the Billing Payments/Shopping Cart configuration. Enter your URL under the Server-to-Server Payment Notification section. Your server to server payment notification username and password are shown on the next page.

PayWay will send parameters listed in Payment Notification Parameters. This configuration is recommended.

If you leave the Notification Post Type blank, PayWay will send parameters that you request in your URL. See Default Post Type.

Processing the payment notification

The page you write to receive the payment notification request must return an HTTP status of 200 ( success), or PayWay will post the same notification to you again. You should only return a status of 200 if you have successfully processed the response and saved the payment to your database.

You should check that your server has not previously processed a notification for the given receipt number.

If after three retries your server does not return a HTTP 200 response we will send you an email notification and stop retrying that particular payment notification.

Customer receipts

After making a payment, your customer can email themselves a receipt. To change the details shown on the receipt:

1. Sign-in to PayWay.
2. Click on the gear icon for Settings.
3. Click on Company Details.

Browser return links and redirect

The purpose of Browser Returns Links and Redirect is to display appropriate web pages to your customer. PayWay Net can be configured with:-

• A button linking back to your website if the customer decides to continue shopping rather than completing the payment,
• A button linking back to your website on the payment receipt page,
• To redirect the browser to your website instead of displaying a payment receipt page (advanced).

When redirecting after payment, PayWay will provide an encrypted list of ampersand delimited parameters and instruct the customer's browser to pass them to your site. The encrypted parameters include details about the outcome of the transaction. Use this method to display a customised receipt page.

Pre-requisites

To create a customised receipt based on the outcome of the transaction, your website must have:-

• a dynamic back-end which can receive parsed GET parameters,
• the ability to decrypt and verify data encrypted using AES 128 with Cipher Block Chaining, using PKCS-7 Padding.

Configuration

To configure browser redirect use the Setup Net pages in PayWay. You must be using the Billing Payments/Shopping Cart configuration. Enter your URL under the Browser Return section. If you wish to receive information and hidden fields, specify the name of the fields as shown in this example:

www.example.com?PromotionCode&Name&Address

If you wish to decrypt the payment information, step to the Security Information page in the Setup Net wizard and note the HTTP Parameter Encryption key.

Decrypting Parameters

The parameters are encrypted using AES 128 with Cipher Block Chaining, using PKCS-7 Padding. The decryption algorithm should be initialised with a 16 byte, zero-filled initialization vector, and should use your encryption key (which can be found on the Security page of PayWay Net Shopping Cart setup).

Before decryption, the parameters passed with the redirect will appear as follows:

EncryptedParameters=QzFtdn0%2B66KJV5L8ihbr6ofdmrkEQwqMXI3ayF7UpVlRheR7r5fA6IqBszeKFoGSyR7c7J4YsXgaOergu5SWD%2FvL%2FzPSrZER9BS7mZGckriBrhYt%2FKMAbTSS8FXR72gWJZsul9aGyGbFripp7XxE9NQHVMWCko0NlpWe7oZ0RBIgNpIZ3JojAfX7b1j%2F5ACJ79SVeOIK80layBwCmIPOpB%2B%2BNI6krE0wekvkkLKF7CXilj5qITvmv%2FpMqwVDchv%2FUNMfCi4uUA4igHGhaZDQcV8U%2BcYRO8dv%2FnqVbAjkNwBqxqN3UPNFz0Tt76%2BP7H48PDpU23c61eM7mx%2FZh%2Few5Pd0WkiCwZVkSZoov97BWdnMIw5tOAiqHvAR3%2BnfmGsx

Signature=huq1shmZ6k7L5BYxjGI2lJvQxffqa%2FogZR5oO8Ln2oc%3D

The signature is generated through the following procedure:

1. Convert the query parameters string to UTF-8 bytes
2. Perform an MD5 hash on the bytes
3. Encrypt the hash using AES-128 in CBC mode
4. Encode the encryption output to Base-64

This signature can be used to verify that the text was transmitted correctly. After decryption, the parameters will appear as follows:

bank_reference=1234&card_type=VI&payment_amount=100&PromotionCode=ABCD&...

For details of parameters, see Browser Redirect Parameters.

Testing and going live

To test your software, create a free test facility.

When you are ready to use your live facility:-

• Click Setup Net in the menu
• Click Hosted Payment Page in the menu
• Follow the wizard until and end and click the Go Live button
• Modify your application to pass your live biller_code
• Modify your application to pass your live merchant_id, rather than TEST
• If you wish to use PayPal, link your PayPal account to PayWay
• Modify your application to pass your live paypal_email, rather than test@example.com
• If your live system is hosted separately to your test system and you are using secure token requests, you must add additional IP addresses through the Hosted Payment Page wizard.

You can continue to use your test facility after you have gone live.

Test card numbers

When using the test merchant, only the card numbers below are valid. All other card numbers will return a response of "42 No Universal Account". Each card number will return a specific response.

If you want to test a card which has low funds, you would use card number 4564710000000020 with an amount higher than $10. Note that if you enter an incorrect expiry date for one of the test cards, you will get a response of 54. If you enter an incorrect CVN, you will get a response of 01 or 05 depending on the card type.

Cards listed as "Fraud Guard" will decline if you have Fraud Guard enabled on your facility.

The test merchant simulates a live gateway but may be used without any risk of transactions actually being processed through the banking system.

Test PayPal transactions

You can test the integration between your website and PayWay using a simulation of PayPal provided by PayWay (PayWay does not make use of the PayPal Sandbox.) You can use any details for the buyer on the PayPal simulation page.

Refund transactions

PayWay Net transactions can only be refunded through the PayWay portal screens. See the PayWay User Guide for more detailed instructions on how to achieve this.

Card types accepted

PayWay Net accepts the following card types via your Merchant Facility:

• Visa
• MasterCard
• UnionPay

You may also accept the following card types if you have a merchant facility with the charge card company. You can contact the charge card company on the number below to arrange a merchant facility:

• American Express: 1300 363 614
• Diners Club: 1300 360 500
• JCB: 1300 363 614

Refer to the PayWay User Guide for information on setting up these in PayWay once you have established your charge card merchant facility.

Support

For issues relating to your Merchant agreement with American Express, contact Amex on 1300 363 614.

For issues relating to your Merchant agreement with Diners Club, contact Diners on 1300 360 060.

For issues relating to your PayPal agreement visit www.paypal.com.au and click on the Help Centre or Contact Us links.

For issues relating to your PayWay facility setup, contact your Implementation Manager. Any actions listed on the "Go Live" page are completed by your implementation manager.

For issues relating to PayWay Net development, email PayWay Technical Support and provide:

• your client number or biller code,
• a description of the issue,
• date/time when the issued occurred,
• a receipt number and dollar value of a sample transaction,
• a screenshot if relevant,
• the web technology you are using.

PayWay request parameters

surcharge_rates

In general, surcharges should be configured as follows:-

1. Sign-in to PayWay
2. Click on "Administration" in the menu
3. Click on "Surcharges" in the menu

The format of this field is as follows: VI/MC=0.6,UP=1.0,AX=1.5,DC=2.0.

This would set the surcharge rate to 0.6% for Visa/MasterCard, 1% for UnionPay, 1.5% for American Express and 2.0% for Diners Club.

Valid codes to use are:

• VIC = Visa Credit
• VID = Visa Debit
• VI = Both Visa Credit and Visa Debit
• MCC = Mastercard Credit
• MCD = Mastercard Debit
• MC = Both Mastercard Credit and Mastercard Debit
• VI/MC = Visa Credit, Visa Debit, Mastercard Credit and Mastercard Debit
• UP = UnionPay
• AX = American Express
• DC = Diners Club

Payment reference parameters

These are generally used for Bill Payments, Donations and Membership Renewals where a payment is collected against a reference number. Use payment_reference for a shopping cart to track the cart number.

Token lookup parameters

This field is used to instruct PayWay to make a payment against a token requested earlier.

Credit card parameters

These are used to provide PayWay with the credit card details. These fields can only be provided via a HTML form post. If you pass these parameters, then you must also pass the token parameter.

Product field parameters

These fields can be used to display a list of products.

Browser return and redirect parameters

In general, these settings should be configured through the PayWay Setup Net Wizard. These fields are only valid when requesting a token.

Server-to-server payment notification parameters

In general, these should be configured through the PayWay Setup Net Wizard. These fields are only valid as part of a token request.

Payment notification parameters

This appendix lists the PayWay built-in parameters that are returned as part of a server to server Payment Notification. The parameters you will receive depend on the configuration.

Extended and XML post types

XML post rype

If set to xml, the parameters will be built into a XML document and passed to your server as the body of a request of content-type application/xml.

The document will be of the form:

<PaymentResponse>
  <cd_source>net</cd_source>
  <no_receipt>1002431909</no_receipt>
  <payment_reference>Invoice No. 5</payment_reference>
  <cd_community>PAYWAY</cd_community>
  <cd_supplier_business>QXXXXX</cd_supplier_business>
  <am_payment>11.00</am_payment>
  <am_surcharge>1.00</am_surcharge>
  <nm_card_scheme>VISA</nm_card_scheme>
  <dt_payment>20120627</dt_payment>
  <tx_response>Approved or completed successfully</tx_response>
  <cd_summary>0</cd_summary>
  <ti_payment>27 Jun 2012 16:02:47</ti_payment>
  <cd_response>00</cd_response>
  <TruncatedCardNumber>456471...004</TruncatedCardNumber>
  <nm_card_holder>Tommy Testman</nm_card_holder>
  <fl_success>1</fl_success>
  <parameter>
    <name>test field</name>
    <value>test value</value>
  </parameter>
  <username>QXXXXX</username>
  <password>XXXXXXXXX</password>
</PaymentResponse>

Default post type

Parameters for the default post type are the same as the parameters listed in Browser Redirect Parameters. The parameters are sent as POST parameters. In order to request parameters, you must include them in your Notification URL as follows:

www.example.com?payment_reference&payment_status

Hidden and information fields are always included.

Browser redirect parameters

The following is a list of the parameters that are returned as part of the browser redirect. Parameters are passed as an encrypted string.

Common response codes

• See Credit card status codes.
• See Direct debit status codes.