Configuration: Payment Gateway - Square

Feature Notes

Linked Refunds (Release 2.42)

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.

• Customers can use American Express cards on AW 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

To configure this feature, please see Configuration: Linked Refunds for Square.

Square SDK Upgrade (Release 2.29)

Square has been upgraded to the latest Web Payments SDK including a modern web styling and updated security. For Square customers, any release after Aspenware Commerce 2.28 will include this latest integration as the SqPaymentForm library is deprecated as of May 13, 2021, and will only receive critical security updates until it is retired. See the Square SDK Upgrade Configuration Guide for any changes that may be made during your upgrade.

Transaction Search Features (Release 2.28)

With the 2.28 version or later, Aspenware Commerce passes two searchable identifiers as part of the transaction data, Aspenware Order ID, and the RTP IP Code, so use of the Square Dashboard.

 The Aspenware Order ID is displayed on a customer email confirmation.

Open

The Aspenware Order ID is also displayed in the Orders list in nopCommerce.

Open

The RTP IP Code is displayed in the Customer Profile in RTP|One.

Either field can be used to search in the Square Dashboard. Simply open the transactions display in the Square dashboard, and change the search filter to “Item”, then paste in the Aspenware Order ID or RTP IP Code. Click Return.

Square returns the orders associated with the specific RTP IP code.

Clicking on an individual code displays the details of that transaction.

Setup Checklist

Detailed Setup Guide

POS Tasks

• Complete POS accounting tasks for products sold online.

• If you are on RTP|One 2022.4.2 or later, and would like to transact refunds using the Square token, then the following actions must be taken in RTP|One:

  1. Go to RTP Admin > Location Administration > Client Management > Client

  2. Add the following Client Configuration settings:

     1. Square Access Token: Found in your Square developer dashboard and required to be input in both Aspenware Commerce payment method configuration as well as upgraded RTP|One (after 2022.4.2)

     2. Square App Id: Found in your Square developer dashboard and required to be input in both Aspenware Commerce payment method configuration as well as upgraded RTP (after 2022.4.2)

     3. Square Location Id: Found in your Square developer dashboard and required to be input in both Aspenware Commerce payment method configuration as well as upgraded RTP (after 2022.4.2)

Payment Provider Tasks

• You will need a Square Merchant account. If you don't already have one, you can sign up here: https://squareup.com/signup/

• Sign in to your Square Developer Portal at https://connect.squareup.com/apps; use the same sign-in credentials as your merchant account.

• Click on '+New Application' and fill in the Application Name. This name is for you to recognize the application in the developer portal and is not used by the extension. Click 'Create Application' at the bottom of the page.

• In the Square Developer admin go to 'Credentials' tab. Copy the Application ID and paste it into Application ID below.

• In the Square Developer admin go to 'OAuth' tab. Click 'Show Secret'. Copy the Application Secret and paste it into Application Secret below. Click 'Save' on this page.

• Copy this URL: https://shop.YOURRESORT.com/Plugins/PaymentSquare/AccessToken. Go to the Square Developer admin, go to 'OAuth' tab, and paste this URL into Redirect URL. Click 'Save'.

• On this page click 'Obtain access token' below; the Access token field should populate. Click 'Save' below.

• Choose the business location. Location is a required parameter for payment requests.

• Fill in the remaining fields and save to complete the configuration.

Commerce Tasks

1. Update Settings

• If you are running version 2.27 or later, update the following settings in Aspenware Admin

  • Go to Configuration > Settings > All settings (advanced)

    1. Search for ecommercesettings.allowtransferofcc

        

       1. Click Edit.

           

       2. Set the Value to TRUE if of RTP|One 2022.4.2 or later and you wish to use the token-passing feature for refunds or FALSE if on an earlier version of RTP|Oneand. Click Update.

           

    2. Search for ecommercesettings.allowstorageofcc

        

       1. Click Edit.

           

       2. Set the Value to TRUE and click Update.

2. Set Up GL Report

Work with your Aspenware Representative to set up the GL Report so you can reconcile GL reporting in the POS and payment gateway.

3. Configure Payment Gateway

• Go to Configuration > Payment Methods in Admin.

• Click Edit on the Square payment gateway.

• Check Is active and save.  Ensure that only the desired payment method is set to ‘Is active.’

• Select Configure on the desired payment method. 

• To change or set up a payment account, fill in the following fields:

  1. Use Sandbox: Should be checked for test and unchecked for prod.

  2. Square Application ID: Obtain from Square

  3. Square Application Secret: Obtain from Square

  4. Store Location:  Only used for production, a drop-down of locations will appear after you’ve confirmed access token - select the location created in steps above for e-commerce transactions. Note, this step is completed after step d (below) for production sites.

  5. Square Access Token: Provided by Square for Sandbox. For production configuration, select Obtain Access Token. This selection will prompt you to log in to Square and the access token will be auto-generated after you authenticate. Click Save after the Access token has been retrieved, then proceed to complete steps c and f-j.

  6. Transaction Mode: Authorize (v 2.34 or later)

     1. Note: If running an earlier version, please refer to the following:

        1. In Aspenware version 2.30 the options are:

           1. authorize only (CORRECT)

           2. authorize and capture (INCORRECT)

        2. In Aspenware version 2.31 - 2.33 the options are:

           1. Authorize (CORRECT)

           2. Charge (INCORRECT)

  7. Additional Fee: Leave blank

  8. Additional Fee (Use percentage): Unchecked

  9. Is fee a percentage? Check if fee is a percentage.

  10. API Version: Obtain from Square

  11. Requires Phone Number: Check if phone number is required for checkout.

  12. Requires Billing Address: Check.
      
      

       

• Click Save.

Test a live credit card for each type of accepted credit card (Visa, Amex, Mastercard) to ensure the gateway is processing payments properly once setup is completed.

4. Review Language Strings

Check that all language strings have been added to your language string library.

Common Troubleshooting

Q: My token expired and I don’t have the scheduled task set up to refresh this. What are my options to fix this?

A: From the Square Payment method configuration page click ‘Obtain access token.’ the Access token field should populate. Click ‘Save' below. Then choose the business location. Location is a required parameter for payment requests. Finally, fill in the remaining fields and click 'Save’ again to complete the configuration. Note you must have a valid square log in with the correct permissions to complete this.

Q: My token in Aspenware Commerce doesn’t match what’s in my Square portal, but payments are processing fine. Should I be worried?

A: That it is expected that the tokens will not match. As long as the "Get Token" step returns a success message at the top of the Square Payment configuration screen, everything should be configured correctly.

Q: How do I get the token refresh scheduled task configured in my environment?

A: Reach out to your Aspenware Representative and they can enable and schedule that Schedule Task for you. All Aspenware Commerce stores have that Schedule Task, it’s created automatically when the Square payment plugin is installed.

Q: What functionality is and isn’t available to me because of having Square as a Payment Provider?

A: Good news is that using Square allows you to enable a number of advanced features, most notably Payment Plans and Subscriptions. Some limitations on the Square side are that in order to store a token for being charged at a later date, a minimum $1 transaction must be completed to store the card, so any product that enrolls you in a Subscription or Payment Plan must have a minimum $1 deposit. Unfortunately, because some functionality is made possible by having a token stored in the POS, and neither RTP|One nor Siriusware support storing Square tokens, resort charge, direct to lift, and capturing tokens for refunds in the POS is not supported. Also, Apple Pay, Google Pay, Pay Pal and Storing CC for future purchases are not currently supported with Square.

Q: When I look at an order status in Aspenware Commerce Order Details, the status is set to pending rather than complete? What’s wrong with this order?

A:  The true indicator of whether a product made it to RTP|One successfully is the order queue. If you see orders showing as Pending in the Sales>Orders area, check if any products in these orders have Shipping checked on the product editor

This won't cause problems per se, but is really only used for retail products that are shipped, so it shouldn't be checked.  Because nopCommerce is often used as a retail platform, what processing means in Nop is similar to what Open means in RTP|One. The order is paid for, but the order has not been fulfilled, aka shipped. For ski, we send the order to RTP|One for fulfillment and don't do any fulfillment in NOP - we use the delivery plugin for shipping ski media and ignore nopCommerce shipping, so it's not a problem, but my guess is that if you uncheck shipping on these products and save it, you will start seeing these orders show as completed.

Q: What is my location and how do I select the correct one?

A: Your resort should only have one Square account and therefore one location. This should be the default and the only option in your Aspenware Commerce Square dashboard.

To see your location in Square:

a. Log into https://connect.squareup.com/apps
b. Go to your application
c. Select “Locations” in the left-hand side bar
d. Note location shown

Q: If I am upgrading from a previous version of Square will I need to obtain a new access token?

A: No, you will not. There is an automatic migration process. However, if issues do come up (like a failed payment) then try the obtain access token flow and that may resolve the issue.

Q: A Payment Plan payment is failing and the message reads “ProcessPayment failed: HTTP Response Not OK.” What does this mean?

A: The Square API log should be referenced to determine the cause but it often has to do with things like "VOICE_FAILURE" for those cardholders that have voice confirmation enabled on each purchase.  In some cases, the cardholder has reached "TRANSACTION LIMIT" meaning that the amount of the transaction is over the cardholder's threshold.

Q: Where can I find the Square API logs?

A: The Square API logs are within your own resort Square account under “Developer Dashboard.”