Gateway

Orders & payments

The plugin uses Square's Orders API to create orders in Square before processing payments. This allows us to pass line items, fees, taxes, and discounts to be displayed in the Square dashboard for tracking and analytics purposes. The flow goes like this:

1. Customer clicks Place Order, their card is validated, and the payment token is passed to the server
2. WooCommerce calls ->process_payment() just like any other gateway to begin the transaction process
3. The gateway first creates a new Square order using the WooCommerce order data
4. Square's API responds with the created order data, and the gateway stores the Square order ID to the WooCommerce order's meta
5. The gateway sets the payment total to match the total calculated by the Square API
6. The gateway creates a Square payment, including the Square order ID so the payment is tied to the order
7. Processing complete

It's important to note a few things about this process:

• If creating the Square order fails for some reason, like a temporary API outage, the gateway still processes the payment normally
• Square's API does not allow us to set an order's grand total - we can only set line item, fee, tax, and discount totals, and their API calculates the grand total
• A Square payment will fail if the total they calculated does not exactly match the payment total, so we have to respect whatever total they calculate in case there are any small rounding discrepancies between WooCommerce's calculation and Square's.

Product line items

There are two types of line items the gateway can set for a Square order:

• Ad-hoc: the gateway defines the name, quantity, and price of the line item for Square's calculation
• Catalog: the gateway sets the Square item ID and quantity. The price is defined by whatever is currently set in the Square catalog.

During order creation, if a product is synced with Square then it will be added to the Square order as a Catalog item, and its price will be determined by the latest price synced with Square. Otherwise, for non-synced products, ad-hoc items are added and the price will be as defined in the WooCommerce order.

Testing

The plugin generally only operates on production, as Square doesn't provide a complete sandbox solution for all of its APIs. However, it is still possible to test payments in sandbox.

1. Add this snippet to override credentials.
2. Replace the filtered values with those listed for a sandbox app at connect.squareup.com

Note that sync will not work, and you won't be able to view transactions, orders, or customers in a merchant account.