Configuration: Linked Refunds for Square

Owned by Leigh Bush
Last updated: Nov 13, 2024 by Sarah Holst
6 min read

This guide will review how to set up Linked Refunds for Square in Aspenware Commerce, Unity, and RTP.

Overview

Switching to linked refunds in Aspenware will result in orders no longer showing the ‘Aspenware clearing’ payment method and will instead show an actual credit card payment method attached to the transaction in RTP. This also allows for the use of RTP’s ‘Return/Refund a Transaction’ tool to process a return or refund to the credit card. Aspenware’s additional payments (vouchers, gift card and stored value) will continue using the ‘Aspenware clearing’ payment method.

  • Customers can use American Express cards on Aspenware Commerce - Square platforms

    • (formerly limited due Square-Amex policies forbidding unlinked refunds)

  • RTP admins can easily refund/return deposit/fulfillment transactions “original payment”

    • Lowers charge-back risk

    • Lowers fraud risk

    • More secure

  • Square admins can see refunds linked to original transaction

  • Removal of the Aspenware clearing payment

Key Terms

Clearing Payment

Currently, and without linked refunds enabled, RTP uses an “Aspenware clearing” as payment type when paying for an order that comes through the Commerce platform. If the new setting is enabled, RTP will no longer have to use this payment type.

Payment ID

Once a customer is created, Square can create a payment ID (in the form of an alphanumeric value) that safely links the customer with their card on file. You can learn more about this process here: https://developer.squareup.com/docs/cards-api/walkthrough/card-from-payment-id .

Feature Detail

RTP

With this update, Aspenware Commerce can:

  • put the payment ID on the order deposit transaction (via a token)

  • put the card_on_file_ID on the alternate CC profile

    • for additional charges (payment plan future charges, gift card transactions, voucher transactions)

    • unlinked refunds

Below is an example of an order that shows Visa instead of Aspenware Clearing for the initial deposit transaction.

Configuration Guide

Prerequisite Steps

POS Tasks

IMPORTANT: Due to recent development by Active Network to accommodate the payment ID, your resort must be using RTP which must be on version 2022.4.2.144 or later.

RTP

Aspenware will look up which credit payment method to use based on the setup in RTP’s Credit Card Validation table. Some customers have unique credit card payment methods defined in this area of admin while others have a generic ‘credit card’ payment method. Regardless of which is used, Aspenware will select the first entry for each card type based on the Aspenware credit providers card brand mapping to this area of RTP administration. For example if a Mastercard is used in Aspenware, the Payment Method assigned to the first entry below for Mastercard will be used.

System Administration / System Management / Credit Card Validation

This table is used by Aspenware to determine which credit card to use on deposit transactions. Each credit card related entry below will need a Payment Method defined. Define the resorts generic ‘credit card’ payment method on each entry or the specific payment method for each type (i.e. Visa, Mastercard, AMEX, etc.) if the resort has this setup.

Additional entries may need to be added to RTP’s Credit Card Validation if all card types accepted on Aspenware are not accounted for in the admin table below. For example, RTP does not deliver Union Pay in this area of admin so this will need to be added with the prefix, 6222.

Aspenware recommends creating an ‘Unknown’ entry in Credit Card Validation with the values below (the Prefix does not matter on this entry). This will be used as a catch-all for any card type that get accepted on the site that is not mapped in the RTP admin page above.

Location Administration / Location Management / Payment

Ensure the Aspenware audit location is added on the Locations tab for each payment type (e.g. Visa) and on the Payment Authorization Profiles tab (i.e. you must select the payment type to see the Locations popup below)

 

 

Location Administration / Location Management / Audit Location Credit Card Authorization

Ensure the Aspenware audit location is added for all card types including the <None> type.

Location Administration / Client Management / Client / Client Configuration Settings

Ensure the Aspenware Client has the Configuration Settings, Terminal ID, Terminal Number, Square Access Token, Square App Id, and Square Location Id added. The Terminal ID and Terminal Number values do not matter but the settings must be added. This data will populate into the TransactionPaymentAuthorization table when an order is created.

The Square related Client Configuration Settings (Square Access Token, Square App Id and Square Location Id) do not need to be added to the Client being used by Aspenware but do need to be added to any client that is processing sales and refunds directly in RTP.

Unity

Linked refunds is enabled in the Unity rtp-config.json file by adding the following setting. Once this setting is added, Unity will no longer use the ‘Aspenware clearing’ payment method for orders. Orders will fail if the setting below is enabled but the RTP admin setup above is not setup properly.

 

"LinkedRefundsEnabled": true,

Note: If enabling linked refunds, you must complete RTP configuration prior to enabling the setting or your orders will fail. Please ensure you have tested this set up in your test environment prior to enabling.

These settings also need to be added in the rtp-config.json file under the “Stores” section:

"UsePaymentCardTokenTable": "true",
"EncryptPaymentCardTokenValue": "false"

Without these settings, the data goes into the Token table instead of the PaymentCardToken table, which RTP's return process references.

Commerce Tasks

The only requirement of Commerce is that you are using the Square Payment Gateway.

Settings, Language Strings, and HTML Widgets

There are no language strings or html widgets that apply to enabling Linked Refunds unless you would like to introduce a “save credit card” warning or checkbox. The following settings need to be added and set to TRUE.

  • ecommercesettings.allowstorageofcc

  • ecommercesettings.allowtransferofcc

Common Troubleshooting Guide

Q: Do I need to tell my guests that we are creating a card on file?

A: While this is not required, and many resorts do in fact save guest credit cards to the alternate credit card profile to assist with returns, Aspenware and Square recommend that resorts ask customers for permission before saving their card information. For example, include a checkbox in your purchase flow that customers can select to specify that they want to save their card information for future purchases.

Linking cards on file without obtaining customer permission can result in your application being disabled without notice.