(V5) How do I set up Square with Ozcart? Print

Square is a payment provider like Stripe and PayPal and enables your customers to checkout and pay for the products you sell. Square goes a bit further and offers its own Point of Sale (POS) system.

Before setting it up, please see Square's supported countries to ensure that you can use Square: https://squareup.com/help/ca/en/article/4956-international-availability

Features

The Square plugin for Ozcart supports the following important features.

Credit Card tokenization (Card On File)

This means that most of the credit card number is stored with Square and not in your store. A portion of it will be stored in your store in order to speed up subsequent checkouts done by your customers. That way, they won't have to enter their card details for the second time. This feature is only available to customers registered in your store. Registered customers can manage their credit cards via their account.

Apple Pay

Apple Pay is fully integrated with Square's plugin. No additional configuration is required. When your customers are accessing the checkout from an Apple device, they will also see the option to pay with Apple Pay.

Transaction Management

The Square plugin helps you easily manage your transactions from within the Ozcart admin area:

• Direct Payment (1-stage) or Authorization+Capture (2-stage) transaction processing.
• Voiding and Refunding transactions.
• Detailed display of transaction data, including: Transaction ID, Order ID, Status, Transaction Result, Transaction Type, Amount, Customer User Agent, Customer IP, and more.
• Inventory re-stock during refund available within the plugin.

Square Catalog and Inventory sync

The plugin ensures your Ozcart and Square product bases will always be the same. Manage your products in Ozcart, and they will appear in Square within a few minutes.

Descriptive Square Orders

With the help of Catalog Sync, the orders made with the Square plugin will contain your Square items. This allows for more accurate reporting in the Square dashboard.

Any additional information provided by Ozcart will be recorded in your Square order as an ad-hoc item/discount. Ad-hoc items are order items which do not exist in your Square inventory. This can occur if you have disabled Catalog Sync.

Fully Automated via a cron job and Webhooks

Square performs the following tasks automatically via a cron job:

• Refreshes your Square access credentials.
• Handles payments for active recurring orders.
• Voids non-captured transactions.
• Catalog and Inventory sync with the Square Catalog Library.
• Provides detailed e-mail reporting for all tasks.

The Square webhooks notify your Ozcart store about inventory changes made in the Square dashboard.

Notes & requirements for using Square

You need a Square Merchant account.

Your merchant account must have at least one location with enabled credit card processing. Please, contact Square's customer support if you have any questions about how to set this up.

Apple Pay is automatically configured by the Square payment plugin.

To learn more about how to configure the Square payment plugin and how to set up your account with Square and Ozcart, follow this tutorial:

1. Connection

Step 1: Create an application in the Square Developer Portal

You will need to have a merchant account with Square in order to set up an application to integrate it with Ozcart. Visit the following link to apply for a merchant account: https://squareup.com/signup/

Once you have created your account and logged into your Square Dashboard, follow these steps to create your application:

1. From the Sidebar, choose Apps to go to the App Marketplace.
2. In the top left-hand corner, select My Apps.
3. In the Build with Square section, click the Go to Developer Portal button which will take you to the Developer Application Dashboard.
4. Click "Create Your First Application".
5. Fill in the Application name. This name is for you to recognize the application in the developer portal and is not used by the plugin.
6. Click the Create Application button at the bottom of the page.

You will be taken to the Manage App screen for your newly created application where you can configure it. If you wish to come back to this screen at a later date, you can find it in your Square account dashboard by navigating to Sidebar > Apps > My Apps and clicking Manage App for the application you want to modify.

Step 2: Connect the Square plugin to your Square application

Once you have created an application through the Square Developer Portal, you will need to tell it about your Ozcart store, as well as fill in some details about it in the Ozcart admin area in Square's settings.

Filling out the Square Application ID field:

1. Log in into the Developer Application Dashboard and select your application.
2. Navigate to the Credentials tab.
3. Copy the Application ID text from the Credentials section.
4. Back in your Ozcart payment plugin settings, paste it in the Square Application ID field.
5. Click the Save button or continue editing the plugin settings.

Filling out the OAuth Application Secret field:

1. Log in into the Developer Application Dashboard and select your application.
2. Navigate to the OAuth tab.
3. Click the Show Secret button to reveal the contents of the Application Secret field.
4. Copy the Application Secret text.
5. Back in your Ozcart payment plugin settings, paste it in the OAuth Application Secret field.
6. Click the Save button or continue editing the plugin settings.

Filling out the Webhook Signature Key field:

1. Log in into the Developer Application Dashboard and select your application.
2. Navigate to the Webhooks tab.
3. Click to toggle to Enable Webhooks.
4. Back in your Ozcart payment plugin settings, copy the field Webhook Notification URL.
5. In Square's Developer Application Dashboard, paste it in the Notification URL field.
6. Click Save.
7. Click the Show Secret button to reveal the contents of the Signature Key field.
8. Copy the text from the Signature Key field.
9. Back in your Ozcart payment plugin settings, paste it in the Webhook Signature Key field.
10. Click the Save button or continue editing the plugin settings.

Tell your Square application about your Ozcart store:

1. On the Ozcart settings page of the Square plugin, copy the field Square OAuth Redirect URL.
2. Log in into the Developer Application Dashboard and select your application.
3. Navigate to the OAuth tab.
4. Paste the address you copied above into the Redirect URL field.
5. Click the Save button at the bottom of the screen.

Note: This plugin requires SSL to be set up correctly for your store. Ozcart comes with SSL by default. If the address for the Redirect URL is using the http protocol instead of https, the Square developer portal will refuse to accept it and you will not be able to connect the plugin to the application. If you have SSL enabled, make sure you are accessing the Ozcart admin area over https when copying the Square OAuth Redirect URL field and that it is correctly displaying an https address.

Once you have setup the Redirect URL and the Webhook Notification URL in the Square application and filled out the Square Application ID, Webhook Signature Key, and OAuth Application Secret in the plugin's administration settings, you can click the Connect button to initiate the connection. You will be redirected to https://squareup.com/ to authenticate using the credentials for the Square account you used to create your application in Step 1. If you are already logged in to your Square account in another tab or browser window, you will not be asked to provide credentials; your Square account will be automatically detected, and you will be redirected back to the plugin's administration settings. If there are any error messages, make sure you have filled out the Square Application ID, Webhook Signature Key, and OAuth Application Secret fields correctly.

Then, go back to the Developer Application Dashboard and select your application. Select Webhooks and click the "Send Test Webhooks Notification" to ensure that it can properly connect to your Ozcart Square plugin.

If you ever need to change the Square account or application that the Square Payment Services plugin is connected to, create a new application while following Step 1, fill in your new Application ID, Application Secret, Sandbox Application ID, Sandbox Access Token, and Redirect URL as described in Step 2, and then click the Reconnect button in your Ozcart plugin settings.

If you followed all the steps above, you should have now successfully activated Square with Ozcart.

Make sure to configure the rest of the plugin's settings as you see fit. More information about them can be found below.

2. Cron Settings

• Cron methods: Configuration for setting up a cron job. A cron job must be set up, either by us or by you. You must choose between method #1 and #2. If you choose method #1, Ozcart will set it up for you. Should you wish to use Method #2, you are free to do so.
  
  
  • Method 1 - Using a cron job: Ozcart support can set this up for you. Please contact us to have us set it up. A cron job runs periodically on your server to perform scheduled operations, such as refreshing the Access Token so that it never expires, processing of recurring billing, and Catalog/Inventory sync. More information on cron jobs can be found here: https://en.wikipedia.org/wiki/Cron.

  • Method 2 - Using a remote cron service: A remote cron service periodically visits a URL on your site which allows you to execute scheduled operations when you cannot or don't want to set up a local cron job. You will have to provide that external service with the URL from the Method 2 - Remote cron field in the cron Settings section of the administration settings of the Square plugin. A security token is added to the URL to prevent unauthorized access. Important: If you regenerate the security token using the refresh icon next to that field, make sure you save the Square settings before using the new URL in that external service.

• Setup confirmation: Check to confirm that there is a cron job set up. The plugin will not be functional without this checked.
• Send e-mail summary: Enable or disable the sending of an e-mail notification that includes a summary of actions performed by the cron job. By default, these emails will go to the administrator email, but you can change the e-mail to a different one in the Send task summary to this e-mail field.

3. Basic Settings

• Location: This setting allows you to select the location that should be used for all transactions. You will find that in your Square account. This plugin will not work if you have selected a location that doesn't support online card processing.
• Transaction type: This setting controls whether transactions are carried out automatically upon checkout or whether they require manual capture. Selecting Sale will result in charges being done automatically, while Authorize will result in the store only authorizing the charge, while transactions will need to be captured manually.
• Catalog Sync: Use this to enable/disable synchronization of your Ozcart catalog with your Square catalog.
• Inventory Sync: Use this to enable/disable synchronization of your Ozcart inventory (product quantities) with your Square inventories.

4. Order Status Settings

• Order status for Authorized: The status applies to orders whose card transaction has been authorized but not yet captured.
• Order status for Captured: The status applies to orders whose card transaction has been authorized and subsequently captured (i.e., completed).
• Order status for Voided: The status applies to orders whose card transaction is authorized and subsequently voided (i.e., cancelled).
• Order status for Failed: The status applies to orders whose card transaction failed.
• Order status for Partially Refunded: The status applies to orders that have been partially refunded.
• Order status for Fully Refunded: The status applies to orders that have been fully refunded.

5. Advanced Settings

• Payment method name: This text is the name of the payment method your customers will see during checkout. Default: Credit / Debit Card.
• Geo Zone: Specify the Geo Zone for which this payment method will be active.
• Sort Order: The sort order of this payment plugin relative to your other active payment plugins.
• Debug Logging: Use this only for debugging purposes and only if Ozcart support requests it.
• Security icon: Enabling this setting will display an icon in the checkout credit card form. Only visible for customers that are entering a new credit card.
• Merchant name: You cannot modify this setting. It is there for you to verify that you have connected the plugin to the Square account you intended to.
• Access token expires: You cannot modify this setting. It is there to let you know when the access token used by the plugin to make authenticated calls to Square will expire. If you have not enabled automatic renewal of this token with the cron job, you will see a warning 5 days before it expires, and you will have to refresh it manually.
• Catalog Sync Period (in minutes): How often your Square cron job will automatically synchronize products between Ozcart and Square.
• Cron Status: This is an information field, updated every 5 seconds. It displays the current state of your cron job. To the right of this field, there is a button used to download a log of the latest changes. This log will contain only the changes from the last sync. If no changes were made during the last sync, the list will be empty.

Recurring Billing Settings

You can enable recurring billing in the Recurring Billing tab of the administration settings for the Square plugin using the Status of recurring billing dropdown. In the Customer notifications section, you can enable or disable the sending of emails to customers when a recurring transaction has succeeded or failed.

Transactions

All transactions processed by your Square plugin are listed here. The table holds the following columns:

• Transaction ID: The Square transaction ID, which matches the one in your Square dashboard.
• Customer: The name of the Ozcart customer who performed the transaction.
• Order ID: The Order ID of the transaction. This is a link leading to the detailed order information.
• Type: The type of Square transaction:
  
  
  • Authorized: The card transaction has been authorized but not yet captured.
  • Captured: The card transaction was authorized and subsequently captured (i.e., completed).
  • Voided: The card transaction was authorized and subsequently voided (i.e., cancelled).
  • Failed: The card transaction failed.
  • Fully Refunded: A full refund was issued for this transaction and it has been processed.
  • Fully Refunded (Refund Pending): A full refund was issued for this transaction, but it has not yet been processed.
  • Partially Refunded: A partial refund was issued for this transaction and it has been processed.
  • Partially Refunded (Refund Pending): A partial refund was issued for this transaction, but it has not yet been processed.
    
    
• Amount: The transaction amount.
• Refunds: The number of refunds that were applied to this transaction.
• IP: The IP address from which this transaction was made.
• Date Created: Date and time when the transaction was made.
• Action: Quick action buttons for viewing more information, capturing, voiding, and refunding transactions.

You can refund and void transactions using the buttons in the Transactions table as well as in the individual transaction view. See below.

View a transaction

To view a specific transaction go to Payment Plugins > Square > Transactions and click on the "View" icon next to a transaction. You will be redirected to a page containing all relevant transaction data:

• Transaction ID: The Square transaction ID. It is a link that leads to the transaction in your Square dashboard.
• Merchant ID: The Merchant ID to which this transaction has been made.
• Order ID: The Order ID of the transaction. This is a link leading to the detailed order information.
• Transaction Type: The type of Square transaction:
  
  
  • Authorized: The card transaction has been authorized but not yet captured.
  • Captured: The card transaction was authorized and subsequently captured (i.e., completed).
  • Voided: The card transaction was authorized and subsequently voided (i.e., cancelled).
  • Failed: The card transaction failed.
  • Fully Refunded: A full refund was issued for this transaction and it has been processed.
  • Fully Refunded (Refund Pending): A full refund was issued for this transaction, but it has not yet been processed.
  • Partially Refunded: A partial refund was issued for this transaction and it has been processed.
  • Partially Refunded (Refund Pending): A partial refund was issued for this transaction, but it has not yet been processed.
    
    
• Amount: The monetary amount of this transaction, displayed with a floating-point. Example: 76.00
  
  
  • If the transaction is Authorized, there will be Capture and Void buttons at the top of the page.
  • If the transaction is Captured, there will be a Refund button at the top of the page.
    
    
• Billing company: The company field from the billing address.
• Billing street: The street field from the billing address.
• Billing City: The city field from the billing address.
• Billing ZIP: The post code field from the billing address.
• Billing Province/State: The province field from the billing address.
• Billing Country: The ISO 3166-1-alpha-2 country code from the billing address.
• Customer User Agent: The user agent (browser) of your customer.
• Customer IP: The IP address from which this transaction was made.
• Date Created: Date and time when the transaction was made.

How to issue refunds

At some point, you may want to issue a refund to your customers. The refunds can only be performed on Captured transactions. You can access the refund window by clicking the Refund button on a transaction.

The refund can be performed in two separate ways: Refund Only Amount or Itemized Refund. The result of both approaches is that the customer will have their money refunded. The difference is that Itemized Refund will give you more control over which product is being refunded and re-stocked to your Square inventory.

Refund Only Amount

This is a basic refund flow. With it, you can only return the customer's money. This approach only requires a return reason and the refunded amount.

Itemized Refund

This is a more complex flow which requires two additional steps: per-item refund and per-item re-stock.

Itemized Refund - per-item refund

This step requires you to insert the number of items which need to be refunded. The refund amount will be calculated automatically. You also have the option to alter the final refund value.

Important: The order items can be refunded only once. Example: If the order contains 6 batteries, you can do a refund of 2 batteries. The next time you try to do a refund, you will be able to refund only the remaining 4 batteries.

Itemized Refund - per-item re-stock

Here is where you can re-stock items you have refunded.

Important

• The order items can be re-stocked only once.
• You can re-stock at most as many items as you have refunded in the previous screen (per-item refund).
• The re-stock will increase the product count in your Square inventory. It will also increase the product count of your Ozcart product quantity.
• You are not allowed to re-stock ad-hoc items. Ad-hoc items are order items which do not exist in your Square inventory. This can occur if you have disabled Catalog Sync.

Catalog Sync

The Square plugin can synchronize your Ozcart products with your Square item library. What is synchronized are Products and Categories.

Catalog Sync ensures your Square orders will contain items from your Square catalog. This allows for more accurate sales reporting within the Square dashboard.

Sync Direction (Ozcart ⇒ Square)

The Square plugin can only do Catalog Sync in the direction Ozcart ⇒ Square. This means that you must not edit your Square library from within the Square dashboard, because any changes you make will be overwritten by Ozcart. You must edit your products only from within Ozcart.

Sync Frequency

How often Catalog Sync will happen depends on the value you set in Catalog Sync Period (in minutes).

On-Demand Sync

On-Demand Sync does the same as Catalog Sync, but it runs manually instead of at a time interval. You can force an On-Demand Sync using the "Refresh" icon at the top right of the Square plugin in Ozcart.

Synced Fields

Not all Ozcart product fields will be synced to Square because of the differences between both systems. For example, Square does not work with the product Weight or the ISBN field.

Ad-Hoc Items/Discounts in Orders

In some cases, the Square order may contain additional ad-hoc items/discounts to account for Ozcart product special prices, or rounding differences resulting from currency conversions. Ad-hoc items are order items which do not exist in your Square inventory.

Options and Taxes

Ozcart Options and Taxes are not synced with Square. Nevertheless, Options and Taxes will still be visible in your Square orders but as ad-hoc items, not part of your Square library. Ad-hoc items are order items which do not exist in your Square inventory.

Sync During Checkout

During checkout, if an Ozcart item has a different price than the item in Square, or if the item in Square does not exist at all, the Square plugin will try to upload only this product to the Square catalog. After that, it will automatically continue processing the order.

Products

The Square plugin will sync only your enabled Ozcart products. After the sync, they will become visible in your Square Item Library.

Products - Square Variations

Note that if the Ozcart product has any required Select or Radio options, they are mapped to a Square item variation.

Products - Required Option Prices

If a required Select or Radio option alters the product price, the end-price is applied to the Square variations.

Categories

Your Ozcart categories will be synced during Catalog Sync.

Note that if a product in Ozcart is assigned to more than one category, in Square it will appear as assigned to only the first Ozcart category. This is because a Square item cannot be assigned to more than one category within Square.

Inventory Sync

Inventory Sync deals only with the Ozcart and Square product quantities. It ensures your Ozcart and Square inventories will remain in sync.

Sync Direction (Square ⇒ Ozcart)

The Square plugin can only do Inventory Sync in the direction Square ⇒ Ozcart. This means that you must not modify product quantities in Ozcart. Instead, you should use the Square dashboard to modify your inventory (product quantity). Any changes will be pushed to Ozcart automatically in a matter of seconds (or at most, a minute).

In case an Ozcart product is already synced with Square, you will see a warning in the product edit page in Ozcart.

Sync Frequency

Inventory Sync is performed automatically every 15 minutes.

Enabling Inventory Sync

Inventory Sync only works on Ozcart products which have the setting Subtract Stock set to Yes. In case a product has required Select or Radio options (for more information, see Catalog Sync above), their option values must also have Subtract Stock set to Yes. Otherwise, Inventory Sync will be disabled for this product.

Setting all Subtract Stock options to Yes in Ozcart will enable Inventory Tracking in Square.

Likewise, enabling Inventory Tracking in Square will automatically update your Ozcart product (and required Select or Radio options) by setting Subtract Stock to Yes.

Inventory changes from Ozcart

The Square plugin ensures all inventory made by other payment plugins will be pushed to Square. For example, if an Ozcart product has been purchased via PayPal, the Square plugin will detect this inventory change and account for it in the Square inventories.

The same occurs for any re-stocks performed within Ozcart as a result of a refund.

Frequently Asked Questions (FAQs)

What cards does the Square plugin support?

Square supports any card bearing a Visa, MasterCard, American Express, Discover, JCB, or UnionPay logo, including credit, corporate, debit (processed like credit), prepaid and rewards cards. For more information, visit the Square Help Website:

• USA: https://squareup.com/help/us/en/article/5085-accepted-cards
• Australia: https://squareup.com/help/au/en/article/5085-accepted-cards
• Canada: https://squareup.com/help/ca/en/article/5085-accepted-cards
• UK: https://squareup.com/help/gb/en/article/5085-accepted-cards

What processing fees are applied to transactions?

Square applies its own fee. Ozcart does not charge a fee for using Square or any other payment method. For up-to-date information, see the official Square Fees and Payments FAQ:

• USA: https://squareup.com/help/us/en/article/5068-what-are-square-s-fees
• Australia: https://squareup.com/help/au/en/article/5068-what-are-square-s-fees
• Canada: https://squareup.com/help/ca/en/article/5068-what-are-square-s-fees
• UK: https://squareup.com/help/gb/en/article/5068-what-are-square-s-fees

Can I enable recurring billing if I use method #2 to set up my own cron  job?

Yes, just make sure to set up a remote cron service.

How can I test Square if there is no sandbox mode?

You can enable the "Authorize" method in 'Transaction type'. This will ensure that funds are not captured upon order creation. After placing the test order, you can void the transaction from the Square admin panel.

When I check out on the store side I see SyntaxError: JSON Parse error: Unrecognized token '<', but on the admin side, the transaction is processed successfully and an order is created. How do I fix this?

This error usually means that there is an issue with your Ozcart mail system. Contact Ozcart support by submitting a ticket if you see this message.

I get this error: There are no locations capable of online card processing set up in your Square account. How do I fix it?

This issue is related to the locations you have set up in your Square account. To make use of the Square payment plugin, you must have at least one location in your Square account with enabled online credit card processing. For more information on how to configure this, please refer to Square's support center.