Heads up, we’ve moved! If you’d like to continue keeping up with the latest technical content from Square please visit us at our new home https://developer.squareup.com/blog
Background and introduction
Hello! I’m Nikola Gavrić, a Software Engineer in Niš, Serbia. I was using Square for several projects and after searching to find a library for the Laravel framework (there were basically no Square integrations with Laravel), I decided to create my own. After receiving emails from developers requesting various features, I decided to make Laravel Square developer-friendly and easy-to-use with low-effort required to setup.
What is Laravel Square?
Laravel Square is a package for Laravel/Lumen that adds basic payment functionality, as well as support for adding a customer and itemization to orders on a transaction with discounts and taxes. The package depends on Laravel or Lumen ≥ 5.5.
How do I setup Laravel Square in my application?
This tutorial doesn’t include setting up your payment form — you can check that out in Square’s official documentation here.
laravel new square-test// orcomposer create-porject laravel/laravel square-test
After you have your project set, install your library and configure it to your needs.
composer require nikolag/laravel-square
Right now, the current version is
Now that we’ve installed the library, we need to configure it to work with our application. The first thing to do is to generate a basic configuration file using the following command:
php artisan vendor:publish --tag=nikolag_config
There are a couple key concepts that will help you with next steps once you publish the configuration file:
default option represents the default payment implementation, which will be used when utilizing contracts instead of a Facade approach. The
connections option describes all possible connections and their settings, designed with the idea that the core package can be used to create other payment implementations, thus requiring an array of connections and their configurations.
After library installation and configuration, we need to set up a few environment variables for our project.
What is the Laravel Square library used for?
Use cases include:
- One-time payments (single transactions)
- Payments with customers
- Payments with orders
- Payments with orders and customers
How do I use the Laravel Square library?
In order to charge customers, we need to add a trait to our User class (merchant) and then run
php artisan migrate to generate the tables required for the library to work.
Now that you have everything set up, you can start using one-time charges and charging your customers. The next step is to create routes which will trigger our charges. Let’s register these new routes within web routes inside
With routes set up, let’s create a controller to handle our calls using the following command:
php artisan make:controller ChargeController
Then we need to create and implement our charging methods, as seen below:
You’ll notice a familiar pattern in how you can chain methods and build your charge. If you’re looking for more info on our methods, check the wiki pages for a clear description. Now that we have our controller configured and our methods implemented, we can test our calls by actually triggering these routes that were defined and see what responses we get. I strongly recommend that you use your sandbox credentials when testing.
We can see in the above example how our transaction builds up as we feed it more information. We can also see that both our transaction and our customer have
payment_service_id. This is because we are actually saving these entities/models/objects in the payment Vault (in this case, Square Vault).
Okay, but what if my customers are placing orders, using one-time discounts, and then I have to apply tax?
This is where our charging process with ordering systems comes in handy.
Charging your customers through Orders is simple. All you have to do is define your Order model, use the
HasProducts trait that we offer, and update your environment file.
After defining the Order class, you can add as many additional fields to it as you want. You can create your own migration file, customize your own Order in any way that you want, and you can update your environment file accordingly, as long as you use our trait
Next we should look at migrations:
We have added a new column called “Total” to store orders’ total value, so we don’t have to re-calculate every time. Again: you can add as many columns/attributes to your Order class as you want, but for the purpose of this tutorial, we will be adding Total.
After finishing both migrations and the model itself, it’s time to update our environment and tell our application which model we will be using for Orders system.
The first two environment variables are clear: first is the fully qualified class name (namespace) and second is the primary key of our Order model. These two variables are by default set to
id. If you don’t have any composite key as your primary key or string and your namespace is grouped under
App, you can just skip this step. The third variable
SQUARE_PAYMENT_IDENTIFIER represents the name of the column in which we will store the ID of the order saved inside Square service. The
SQUARE_PAYMENT_IDENTIFIER variable also has a default value, but if for some reason it is already taken, you can define your own name. To view all the variables we are using, you can take a look at
Our next step is to implement our endpoints we created earlier inside our web routes by simply creating a new controller. So let’s run this command:
php artisan make:controller OrderController
Now it is time to implement our methods (seen below):
Looks like a big chunk of code to analyze! Nope, not really — if you just look at the method names it’s pretty clear what we are trying to do. It’s even easier if you see our chained methods on the
Square facade and we can chain these methods in any order that we want.
We won’t cover taxes and discounts in this how-to guide — you can refer to our wiki pages and check out the concrete examples for each scenario there.
You must be asking yourself now, what are these products he is getting from a request itself?
What are Products?
Products can be an associative array or a collection of eloquent models. Why? Because we don’t want to always re-create our existing products, we want to store and remember them somewhere and just reuse them when we need them. In that case, we will be using Eloquent models; on the other hand, if we are just creating a new item or a customized version of a product, we can always create that as a unique product itself.
Above we can see a minimalist example of products as an associative array. All these products will be created and stored for us and used in a transaction. We could retrieve these same products later and reuse them if we wanted to.
Now we will retrieve and reuse the products we already saved.
As you can see, we are retrieving them as a normal Eloquent model, and querying them accordingly.
Bottom line: this library can give you as much flexibility as you need as a developer. It gives you back time and resources that you can invest in your own implementation. With less worrying about compliance, integration, exception handling, and the like.
Finally! A lot of time, knowledge and effort went into building this seemingly small library to make it flexible, rewarding, fast, reliable, and developer friendly. My goal was to create a reliable package that’s payment gateway agnostic.
Thank you for reading through this tutorial on how to use
laravel-square library to charge your customers with ease. Just implement the library and enjoy.