Forem: Square Developer

Card on File with React Native

Richard Moot — Mon, 12 Jul 2021 21:11:54 +0000

In this tutorial, we’ll show you how to accept payments in a React Native application using Square’s In-App Payments SDK and React Native plugin. I’ll also show you how to safely store customer card details so that they don’t have to be manually re-entered or re-swiped for future transactions.

In payment industry terms, this capability is known as Card on File, or CoF for short. For frequent transactions, e.g. ordering a Lyft or a Lime, having a card stored makes for a much snappier, lower-friction in-app user experience. Entering card details every time would be very tedious.

As a security-minded developer, I know you might be wondering: Is it safe to store a user’s credit card details? Is this even legal?

If you use Square, the answer is yes. Using the Square In-App Payments (IAP) SDK means that your application and database don’t actually come into contact with the real card details. Instead, your application interacts with something called a nonce.

A nonce is an encrypted payment token that can be exchanged with the Square API to process a payment. A card nonce represents a credit card and all the details the user typed in. The nonce is used to store cards and capture payments without compromising the user’s privacy or security. It’s just one of the key concepts of processing payments with Square that we’ll cover today.

In this tutorial, you’ll download and run a React Native application that processes payments using Square’s In-App Payments SDK and React Native plugin, including Card on File transactions.

Prerequisites

No prior knowledge of React Native or Square is required, but you will need a Square account. You will need to be familiar with NPM, git and the command line.

Square Account

A Square account will allow you to take payments and get your own API keys that you’ll use in this tutorial. Thankfully, this is easy. If you already have an active Square account, you can skip this step.

Use this link to sign up for a free account (pay only transaction fees):

Sign up for Square

Tip: During signup you can choose to order a magstripe reader, which you can use to take payments in person using the Square Reader SDK.

Finally, before continuing with the rest of the tutorial, your Square account will need to be enabled for payment processing, which means that you’ll need to provide information about the account’s owner. Visit squareup.com/activate to enable it. If you’d prefer not to make actual card charges, your Square account comes with a sandbox that you can use instead. If you go the sandbox route, you’ll need to use the sandbox Application ID and Location ID instead in the examples below.

Square Application and Location ID

Once you have an active Square account, you’ll need to create a new developer application in order to get your IDs and credentials.

Open the dashboard to create a new app:

Open the Square Application Dashboard

Tip: You’ll need to login with your Square account if you’re not logged in already.

Click on the “New Application” button. On the next screen, enter the name "In-App Payments SDK Quick Start" or something similar.

Next, click on the "In-App Payments SDK Quick Start" app to bring up your new Square Application’s settings page.

Open the Credentials page and copy down your Application ID and your Personal Access Token under ACCESS_TOKEN.

Next, open the Locations page and copy down the ID for a location that accepts card payments.

Keep your Application ID, Personal Access Token, and Location ID handy. You’ll need them later.

Deploy backend app to Heroku

Using the Square In-App Payments SDK requires that you have a backend that the client device connects to and where the final payment processing step takes place. For the purposes of this tutorial, we’ve created an example backend we can use called the In-App Payments Server Quickstart.

The easiest way to deploy it is with cloud hosting provider Heroku, using a Deploy to Heroku button you’ll find in the GitHub README. All of the steps you’ll need to get it up and running are here:

Complete the In-App Payments Server Quickstart Setup

Once you click the Deploy to Heroku button and signup or login to Heroku, you’ll be taken to a screen that looks like this.

Give the app a unique name and set the ACCESS_TOKEN value on the Heroku configuration page to the value from the previous step. Then click “Deploy app”.

Tip: Note down the URL of your Heroku app, you’ll need it later. The format is https://.herokuapp.com.

Set up React Native

Next, we need to install React Native and its dependencies, which include XCode (for iOS) and/or Android Studio in order to run the application on a simulator.

Tip: Only one of XCode or Android Studio is required to complete this tutorial and instructions are provided for both.

To set up React Native, I recommend following the guide in the React Native documentation.

Follow the React Native Getting Started Guide

Here are a few tips to help you get through it quickly:

Choose “React Native CLI Quickstart” and not “Expo CLI Quickstart”
Choose the right Development and Target OS (Android/iOS)
Complete the whole guide, including creating and running a new application - this will make sure your setup is working
See the Troubleshooting page if you encounter any issues

Once you’re done, you should have XCode and/or Android Simulator working, as well as the react-native NPM package installed.

Additional Requirements

The Square IAP React Native plugin has a few build requirements of its own, which you’ll want to verify against your installation. If you’ve just done a fresh install with the latest versions, you should be OK. But if not, this list will tell you what you need to upgrade before continuing.

Android

Android minSdkVersion is API 21 (Lollipop, 5.0) or higher.
Android Target SDK version: API 28 (Android 9).
Android Gradle Plugin: 3.0.0 or greater.

iOS

Xcode version: 9.1 or greater.
iOS Base SDK: 11.0 or greater.
Deployment target: iOS 11.0 or greater.

If you’re targeting Android, one more step is required to successfully simulate the app. You’ll need to create an Android virtual device based on the Android 9 version of the Android SDK.

In the Android Studio welcome screen, click “Configure”
Click “AVD Manager”
Click “Create Virtual Device”
Choose any common hardware and click “Next”
Click “Download” next to “Oreo” on the System Image screen
Once that’s done, click “Next” and finish the wizard

Pick this device to launch as the Android Simulator in the steps below.

Set up the quickstart app

So far we’ve installed and configured our dependencies. Now we can move on to installing the React Native plugin and working with the example codebase.

In a nutshell, the React Native plugin provides a convenient set of interfaces to the native code running inside the Square In-App Payments SDK. To learn more about the background of the React Native plugin, check out this announcement blog post.

Clone the repository

For the next step, we will clone the GitHub repository that the plugin lives in: square/in-app-payments-react-native-plugin.

git clone git@github.com:square/in-app-payments-react-native-plugin

After the clone is complete, change directories into the app.

 cd in-app-payments-react-native-plugin

Inside of this repository, there is a React Native application that lives in the react-native-in-app-payments-quickstart folder. This is the quickstart application we’ll use for the rest of the tutorial.

Change directories into the application directory:

cd react-native-in-app-payments-quickstart

Next, install dependencies with Yarn.

yarn

Configure the quickstart app

The quickstart app allows the user to purchase a "Super Cookie" for $1 that grants special powers (due to the high sugar amount, of course).

Before we can fire up the app (and our blood sugar level), we need to configure it with the Square Application ID we provisioned above.

Configuration variables in the quickstart app are stored in the file app/Constants.js (view on GitHub).

const SQUARE_APP_ID = 'REPLACE_ME';
// Make sure to remove trailing `/` since the CHARGE_SERVER_URL puts it
const CHARGE_SERVER_HOST = 'REPLACE_ME';
const CHARGE_SERVER_URL = `${CHARGE_SERVER_HOST}/chargeForCookie`;
const GOOGLE_PAY_LOCATION_ID = 'REPLACE_ME';
const APPLE_PAY_MERCHANT_ID = 'REPLACE_ME';
// constants require for card on file transactions
const CREATE_CUSTOMER_CARD_SERVER_URL = `${CHARGE_SERVER_HOST}/createCustomerCard`;
const CHARGE_CUSTOMER_CARD_SERVER_URL = `${CHARGE_SERVER_HOST}/chargeCustomerCard`;
const CUSTOMER_ID = 'REPLACE_ME';
module.exports = {
  SQUARE_APP_ID,
  CHARGE_SERVER_HOST,
  CHARGE_SERVER_URL,
  GOOGLE_PAY_LOCATION_ID,
  APPLE_PAY_MERCHANT_ID,
  CUSTOMER_ID,
  CREATE_CUSTOMER_CARD_SERVER_URL,
  CHARGE_CUSTOMER_CARD_SERVER_URL,
};

Open the file. On line 16, replace REPLACE_ME with the Application ID value from above.

On line 18, replace CHANGE_SERVER_HOST with the URL for your Heroku backend. Include the https:// but don’t include the trailing slash.

On line 20, replace REPLACE_ME with the Location ID value from above for the Google Pay Location ID.

Create a customer

The last thing we need to do before we use the app is to create a customer using the CreateCustomer endpoint of the Customers API. Storing cards on file requires a customer record to attach them to.

In your terminal, run this command, first substituting with the value from the ACCESS_TOKEN you noted down below.

    curl --request POST https://connect.squareup.com/v2/customers \
         --header "Content-Type: application/json" \
         --header "Authorization: Bearer <REPLACE ME>" \
         --header "Accept: application/json" \
         --data '{ "idempotency_key": <RANDOM_STRING>, "given_name": "Lauren Nobel" }'

If successful, you should see details returned that represents our new customer:

    {  
       "customer":{ 
          "id":"RPRANDHZ9RV4B77TPNGF5D5WDR",
          "created_at":"2019-06-14T15:32:50.412Z",
          "updated_at":"2019-06-14T15:32:50Z",
          "given_name":"Lauren Nobel",
          "preferences":{  
             "email_unsubscribed":false
          },
          "creation_source":"THIRD_PARTY"
       }
    }

The customer.id field from the JSON is what we’ll need to eventually store a card on file for this customer from the app.

In app/Constants.js, the file from above, set the value of the CUSTOMER_ID constant to the customer.id field above.

    const CUSTOMER_ID = “REPLACE_ME”

From the quickstart app’s perspective this will now be the Square customer who’s using it.

Start the app - iOS

You’re now ready to run the app for the first time. Before we start the app, we need to launch the iOS simulator. This comes with XCode and gives us a virtual device that looks and acts like an iPhone or iPad.

The simulator should live in your Applications folder and simply be called Simulator or Simulator.app. Once you open the app, a virtual device you have configured should boot up automatically.

Now, we’re ready to use the react-native command to run our device on the simulator. Enter this command in your terminal and hit enter:

react-native run-ios

If it’s your first time running, you’ll see a lot of output and the process will take a little while. Don’t worry, that’s normal. Ultimately, you should see the message ** BUILD SUCCEEDED ** and the process will exit cleanly.

Once that’s all complete, you should see our Super Cookie application loaded onto the virtual phone.

You might also have noticed that a new terminal window opened. This window is running the Metro Bundler, a bundler created specifically for React Native that supports fast reloads and can handle thousands of modules at a time.

Start the app - Android

The first step is to launch an AVD - Android Virtual Device - from the Android Studio. This virtual device will run our React Native application.

Open Android Studio
On the welcome screen, click “Configure”
Click “AVD Manager”
In the modal that opens, find the device running API 27 that we created above.
Click on the green Play button in the “Actions” column to launch the device.
Click the power button on the top right next to the virtual device to boot it.

In a minute or two, you should reach the Home screen of the Android device.

With the simulator running, we can now launch our React Native application, which will attach itself to and run on the virtual device. Type this in your project directory and hit enter:

react-native run-android

If it’s your first time running the app, it make take some time to install dependencies. That’s normal. Once you see BUILD SUCCESSFUL and a clean process exit, the Super Cookie app should be running on the Android virtual device.

Interacting with the app

Now since we’ve done all of this hard work installing dependencies and configuring our environment, let’s reward ourselves with a cookie. And not just any cookie - a Super Cookie 🍪 .

On either the running iOS or Android simulator app, click the green “Buy” button. This brings up a “Place your order” modal that contains example customer details, a price, and buttons that let the user choose how they want to pay: with a credit or with a digital wallet like Apple Pay or Google Pay.

Add a card on file

We’re going to pay with a stored credit card, so click ‘Pay with card’. We don’t have any cards on file yet for this customer, so you’ll see a message and an ‘Add card’ button.

Next, enter the details of a valid credit card and click ‘Save 🍪’.

If you entered a valid card, you’ll see a confirmation alert message. Otherwise you will see an error about what was invalid. When confirmed, the card will be attached to the record of the customer you created earlier.

What happens behind the scenes?

The Square IAP SDK generates a nonce that represents the credit card.
Our React Native application sends the nonce to our backend service running on Heroku.
The backend service calls the CreateCustomerCard endpoint of the Square API, passing the customer_id (from above) and the card nonce.
The information returned from the Square API is stored in our React app’s state so the card type, expiration date and last 4 digits can be shown later.

Tip: See the Save Cards on File Cookbook to learn more about this flow.

Important: Always ask for explicit permission before saving customer contact information or cards on file. This is required by Square.

Pay with a card on file

Assuming you successfully saved a card, you should now be able to see it on the previous UI. You can identify the card by its type, expiration date and by the last 4 digits of the account number.

Note: The full card number cannot be shown because it was not returned from the CreateCustomerCard endpoint for privacy and security purposes.

Click the “Pay” button and then “Purchase” to confirm that you want to buy a Super Cookie for $1.

Warning: Unless you're using the sandbox, this will charge your card and incur a transaction fee of $0.33, only $0.67 will be deposited into your linked account.

What happens behind the scenes?

The app sends the customer ID and chosen card on file ID from the previous step to the backend service.
The backend service creates a Payments API Payment request with the provided fields.
The Square Payments API Charge endpoint processes the request and returns a Payment object that represents the captured payment, or an error message explaining what went wrong.

Verify transactions on the dashboard

Now that the two payments have been processed, they will show up on your Square Dashboard. Visit the dashboard to confirm.

> View the Transactions page on your Square Dashboard

Dig into the code

Now that you’ve seen how the flow works, let’s take a quick look at the code in the Super Cookie React Native application and see what’s happening.

It will first help to understand all of the different layers of the stack.

On the device:

Super Cookie React Native Application
React Native Plugin for In-App Payments
Square In-App Payments SDK

Server-side:

In-App Payments Server Quickstart (on Heroku)
Square API

All of the custom code used in this tutorial lives inside either the Super Cookie application or IAP Server Quickstart. The Square IAP SDK and React Native Plugin for IAP are officially maintained packages from Square.

React components

The Super Cookie quickstart application has one main level component called HomeScreen.js. This component decides what is rendered based on the state of the application.

When the user first clicks ‘Buy’, a modal dialog appears from the bottom of the screen. The contents of the modal dialog change as the user walks through the flow. There are 3 views, backed by one component each:

OrderModal: Shows transaction details and buttons for payment methods
CardsOnFileModal: Shows list of cards on file and a button to add a card
PendingModal: Shows an activity indicator when a transaction is being processed

The code for these components is in the app/components folder of the quickstart application repository. The main job of these components is to build markup for the interface, apply CSS, and trigger events when certain areas of the screen are touched.

React Native IAP Plugin interfaces

Interaction with the React Native plugin and underlying native SDKs is set up in the HomeScreen component.

Up at the top of the files, we can see these interfaces being imported.

import {
  SQIPCardEntry,
  SQIPApplePay,
  SQIPCore,
  SQIPGooglePay,
} from 'react-native-square-in-app-payments';

SQIPCore is used to send your Square application ID down to the native layer.

The startCardEntryFlow() method of SQIPCardEntry is used to show the dialog for capturing credit card details. This dialog is created by the underlying native SDK so its fast and smooth. The method accepts 3 parameters - a configuration object, a success function, and a cancel function. The success function is passed a nonce that represents the card that the user entered, which can then be used to create a transaction or store a card on file.

The setIOSCardEntryTheme() is used to customize the look and feel of the dialog, and that’s how we added the 🍪 emoji to the “Save” button at the dialog. The completeCardEntry() method closes the dialog.

See the React Native plugin’s technical reference for a full list of interfaces, features and customizations that your application can take advantage of.

Conclusion

In this tutorial, we’ve shown how to take a Card on File payment within a React Native application, using the Square In-App Payments SDK and the React Native Plugin for In-App Payments SDK.

Even if you’re not selling super cookies, the instructions and example code here should help you integrate Square into your React Native application to create a great user experience for whatever you’re selling.

Once you’re ready to do that, your next step will be to read the Getting Started with the React Native Plugin for In-App Payments SDK guide on GitHub, which shows you step-by-step how to add the plugin to an existing React Native app. Square Developer Evangelist Richard Moot has even created a video to walk you through it step-by-step.

If you want to keep up to date with the rest of our guides and tutorials, be sure to follow our blog & our Twitter account, and sign up for our forums.

Thanks for reading!

Online Payments with React + Square

Richard Moot — Tue, 29 Oct 2019 22:40:35 +0000

There are a lot of ways to accept payments online. Wouldn’t it be nice to implement a single form that could accept as many payment methods as we want at a single time? Let’s take a look at implementing a custom payment form using Square and React. This form will enable us to take credit cards online, and give us support for Apple Pay, Google Pay, and Masterpass in a single payment form.

Things required to understand this post:

React (simplified with create-react-app)
Square’s Payment Form

Our final (payment) form:

React and Square’s Payment Form

If you’re familiar with React, then you’re accustomed to passing along props and controlling your component via its state. Let’s focus on how to get a basic setup up and running with Square’s payment form controlled by a React component. We’ll also demonstrate how to dynamically load the Square payment form script in case you want to simply insert the payment form component on a page. Dynamic loading the script is only relevant if you don’t want the script to only load on a checkout page (or wherever you’d like to take a payment).

If you’re not acquainted with Square’s payment form, head over to the docs and get familiar. There are some templates, explanations, and guides on getting the form set up using basic HTML, CSS, and JavaScript.

At a basic level, the payment form directly captures your customer’s card details directly on Square’s servers using an <iframe>. The payment form facilitates the generation of these <iframe> elements and provides an API for creating a nonce (a one-time-use token) to reference those details later (all without you knowing any sensitive information!).

The main problem you hit with these <iframe> elements replacing other elements in the DOM is that React usually likes to be in charge of managing all your DOM interactions. This requires doing a bit of extra setup on our components to be sure we render everything correctly, in the right order, and correctly handle different events generated by the Square payment form script.

Dynamically Load The Square Payment Form Script

Our base component is where we’ll actually manage dynamically loading:

<script src=”https://js.squareup.com/v2/paymentform”></script>

into the <head> of the DOM and trigger our child component to render. The child component will actually be responsible for assembling, formatting, and managing our payment form. This is done to ensure the script has loaded and we can pass the SqPaymentForm object down to our child component.

import React, { Component } from 'react';
import PaymentForm from './components/PaymentForm';

class App extends Component {
  constructor(props){
    super(props)
    this.state = {
      loaded: false
    }
  }

  componentWillMount(){
    const that = this;
    let sqPaymentScript = document.createElement('script');
    sqPaymentScript.src = "https://js.squareup.com/v2/paymentform";
    sqPaymentScript.type = "text/javascript"
    sqPaymentScript.async = false;
    sqPaymentScript.onload = ()=>{that.setState({
      loaded: true
    })};
    document.getElementsByTagName("head")[0].appendChild(sqPaymentScript);
  }

  render() {
    return (
      this.state.loaded &&
        <PaymentForm
          paymentForm={ window.SqPaymentForm }
        />
    );
  }
}

export default App;

You can see we’re just using some vanilla JavaScript inside the lifecycle method componentWillMount() to create a <script> element and set some attributes, and then making sure that we’re updating our React component’s state to loaded once the script has actually loaded on the page. This will trigger React to re-render and return true for this.state.loaded inside our render() method and allow our child component to render.

The other notable part of our code is how we’re passing SqPaymentForm via the paymentForm prop. We are passing in the SqPaymentForm object that is attached to the window, so rendering the payment form and triggering submission is easier to manage.
Full code example can also be found at https://github.com/mootrichard/square-react-online-payments

React Payment Form Component

To keep things simple, we’re modifying existing templates found on Square’s GitHub. For more info on customizing or setting up a Square payment form, check out our guides. We’ll focus more on the difference between those templates and wiring things into our React component.

Our render() Method

  render(){
    return (
      <div className="container">
        <div id="form-container">
          <div id="sq-walletbox">
            <button style={{display: (this.state.applePay) ? 'inherit': 'none'}}
                    className="wallet-button"
                    id="sq-apple-pay"></button>
            <button style={{display: (this.state.masterpass) ? 'block': 'none'}}
                    className="wallet-button"
                    id="sq-masterpass"></button>
            <button style={{display: (this.state.googlePay) ? 'inherit': 'none'}}
                    className="wallet-button"
                    id="sq-google-pay"></button>
            <hr />
          </div>

          <div id="sq-ccbox">
            <p>
              <span style={styles.leftCenter}>Enter Card Info Below </span>
              <span style={styles.blockRight}>
                {this.state.cardBrand.toUpperCase()}
              </span>
            </p>
            <div id="cc-field-wrapper">
              <div id="sq-card-number"></div>
              <input type="hidden" id="card-nonce" name="nonce" />
              <div id="sq-expiration-date"></div>
              <div id="sq-cvv"></div>
            </div>
            <input
              id="name"
              style={styles.name}
              type="text"
              placeholder="Name"
            />
            <div id="sq-postal-code"></div>
          </div>
          <button className="button-credit-card"
                  onClick={this.requestCardNonce}>Pay</button>
        </div>
        <p style={styles.center} id="error"></p>
      </div>
    )
  }

The key parts to note in the elements we have is the divs elements with the id’s: sq-apple-pay, sq-masterpass, sq-google-pay, sq-card-number, sq-cvv, sq-expiration-date, and sq-postal-code. We transformed the examples to use divs for everything instead of form components, since these are all the fields that will be targeted by Square’s payment form script to be replaced with <iframe> elements. Also, since we’re using React, we will have our own functions for controlling submission and triggering the request of a nonce from the payment form.

Digital Wallet Payments & Methods Supported

To adjust what digital wallet options (sometimes called mobile wallet options) you want to support, just provide different key-value pairs in your SqPaymentForm configuration object (see more on that here). You should be able to see in the render() method that we’re controlling the display of our mobile payment options using the component’s state.

callbacks: {
  methodsSupported: (methods) => {
    if(methods.googlePay){
      this.setState({
        googlePay: methods.googlePay
      })
    }
    if(methods.applePay){
      this.setState({
        applePay: methods.applePay
      })
    }
    if(methods.masterpass){
      this.setState({
        masterpass: methods.masterpass
      })
    }
    return;
  },

We are setting the state inside of the methodsSupported() callback that the Square payment form has provided to us. Since each mobile wallet option is specific to the browser that a customer is visiting from, you need to conditionally render the buttons to match what should be available based on your customer’s browser or mobile device. We also have to make these separate conditionals since the payment form calls the methodsSupport() function once for each method you’re choosing to support. Our example is trying to support Masterpass, Apple Pay, and Google Pay, so three calls will be made. It’s a little aggressive in our calls to setState(), but only three calls, so no worries — just keep it in mind if you’re calling setState() elsewhere, since every call will trigger a re-render of the component.

Linking & Controlling the Component

The main takeaway is to use state inside of the provided callback. Using state in the component allows us to react (so punny) to different events emitted by Square’s payment form script. You can learn more about all these events are in the docs. In our example, a key place for this tie-in would be the inputEventReceived() callback since it’s called on every input event. In our example component, we update the brand of the card (in the top right corner) once it has been identified by the payment form.

Thoughts and Conclusions

This is only one way of approaching implementing the Square payment form in React. Initially it seemed like a good idea to try passing in the config object as a prop, but that doesn’t work too well for configuring your callback functions, unless you’re comfortable overriding them before creating your paymentForm object (this just felt wrong).

The main place I’ve seen developers trip up is usually on not disabling autoBuild. The paymentform script is going to immediately look for elements with the provided element id’s on build, but the problem arises because React might not have rendered the elements to the DOM yet. It is better to control the build process by triggering it with a call to.build().

The implementation of the form in React is fairly straight forward (if you know React) and just requires understanding of the React lifecycle in relation to the paymentform lifecycle.

You can find a full example of this form over at: https://github.com/mootrichard/square-react-online-payments.

If you liked this post on React + Square, but would like to see this refactored using React’s Hooks API, tweet at me, respond here on Medium, or bug me in our Slack community and I’ll follow up with a post with how to refactor this example using the React Hooks API.

Want more? Sign up for our monthly developer newsletter or come hang out with us in the Square Dev Slack channel! You can also follow us on Twitter at @SquareDev.

Stop Using Servers to Handle Webhooks

Richard Moot — Fri, 11 Oct 2019 20:24:58 +0000

Webhooks are increasingly becoming the main method to get real time data from different services. GitHub, Slack, SendGrid, and even Square use webhooks to let you see data or be notified of events happening on your account. Webhooks are awesome, since they are fairly easy to deal with and prevent developers from having to build some archaic polling system that ends up being fairly wasteful in terms of network requests made vs. actual useful data retrieved.

When creating a service to process webhooks, you have a few choices available: you can extend our application to handle incoming data from a defined URL, you can create a microservice, or you can create a Function as a Service (FaaS) function for processing our webhooks. We’ll briefly go through each of those options and the possible tradeoffs, and then we’ll wrap up with an example implementation of a FaaS webhook handler for Square.

Extending your Application

Source: Giphy (CCTV Servers)

Extending your application gives you the benefit of leveraging any helpers or other libraries you already have in your application. Your helpers (or other application tools) can assist with processing this incoming data and might make it easier to manage. Your application is likely continually running anyways, so there isn’t a problem with having it also handle listening for incoming data for your webhooks. However, this approach can be a drawback, since you might be extending your application to handle something that’s not a core functionality or shouldn’t really be coupled with it. How the extension works can really depend on how your own application is structured, but it might be best to separate how your webhooks are handled to something outside of your application.

Microservice

Source: Giphy (Computer Ants)

Meanwhile, a microservice approach might help you move a step away from your application and allow it to simply communicate or process this new data to be consumed by the application later. Unfortunately, we still have the drawback of scalability and provisioning, since we would still need to be continually listening for the new data being sent to the webhook handler. Although it’s entirely possible to estimate how much data might be coming into our webhook handler and provision accordingly, it’s still pretty likely to be a lot of downtime where it’s simply just waiting to service a request.

Function as a Service

Source: Giphy (Saturday Night Live GIF)

At this point I know it’s pretty obvious that I am going to advocate for all the wonderful benefits of using FaaS for processing webhooks, though I do acknowledge there are some pretty annoying tradeoffs. First the benefits. One advantage of using FaaS for processing webhook data is that it allows for nearly unlimited scalability, so you don’t have to worry about being over or under provisioned. Your function only runs when a new event occurs, so you could be saving infrastructure costs by not having to run a server continuously just for processing webhook data. On the other hand, the drawbacks around using FaaS are usually around maintainability, testing, and cold starts. There are some tools that help with maintaining versions of your functions, deploying functions, and keeping the functions warm. Since webhooks are not directly servicing users and most webhook providers are fairly forgiving about required response times, FaaS is really well suited for processing webhooks despite the issues around cold starts.

Working Example

So this is all good in theory, but it’s better to show an example of how we could implement a webhook handler on a FaaS platform. This example will be on Google Cloud Platform using their Google Cloud Functions, but the majority of what we cover would translate across platforms since we’re using JavaScript.

For starters, we want to be sure to service the webhook request as quickly as possible since we don’t want it to timeout. If our webhook handler takes too long to service the request repeatedly and timeout, a lot of webhook systems will stop serving our webhook URL and assume that it is no longer working. Our goal is to minimize the amount of processing time before sending back our 200 response to be sure we can account for any cold start lag time our function may have.

To make things easy and work a little faster, we’re just going to write the JSON response we get for our webhook into a JSON file and upload it to Google Cloud Storage. This will allow our webhook handler to quickly respond to the request and we can just periodically check this bucket for new events or even write another Google Cloud Function that processes the new JSON files.

An easy way to get started if you’re completely new to FaaS is to use Serverless. It is a tool that helps facilitate creating and deploying functions to cloud providers. You can use their quick-start guide to get a template generated and they have guides on getting your credentials setup for each provider as well. Here, we’ll show what a slightly filled out Serverless template looks like for our webhook handler:

const fs = require('fs');
const Storage = require('@google-cloud/storage');
const BUCKET_NAME = ''; // This would actually have the name of our bucket
const storage = new Storage({
  projectId: '', // This should be your Google Cloud Project ID where you're deploying your function & have your bucket
  keyFilename: './keyfile.json'
});

exports.webhook = (request, response) => {
  const data = JSON.stringify(request.body, null, 2);
  const fileName = `/tmp/${request.body.location_id}_${request.body.entity_id}_${Date.now()}.json`;

  fs.writeFileSync(fileName, data);

  storage
    .bucket(BUCKET_NAME)
    .upload(`${fileName}`)
    .then((success) => {
      fs.unlink(fileName);
      console.log(success);
      response.status(200).send();
    })
    .catch((error) => {
      fs.unlink(fileName);
      console.log(error);
      response.status(403).send(error);
    });
};

exports.event = (event, callback) => {
  callback();
};

Our example gives a simplified version of how our final webhook handler will be functioning. We’re stringifying our JSON, writing it to the /tmp/ directory using the fs module. Then, we’re sending that right into Google Cloud Storage using their NodeSDK. Finally, we clean up the temporary JSON file we created locally and log our success before sending our 200 response.

'use strict';
require('dotenv').config();
const fs = require('fs');
const crypto = require('crypto');
const Storage = require('@google-cloud/storage');
const projectId = 'YOUR_PROJECT_ID';
const storage = new Storage({
  projectId: projectId,
  keyFilename: './keyfile.json'
});
const BUCKET_NAME = 'YOUR_BUCKET_NAME';
const REQUEST_URL = 'https://us-central1-YOUR_PROJECT_ID.cloudfunctions.net/webhook';

function isFromSquare(REQUEST_URL, request, sigKey) {
  const hmac = crypto.createHmac('sha1', sigKey);
  hmac.update(REQUEST_URL + JSON.stringify(request.body));
  const hash = hmac.digest('base64');

  return request.get('X-Square-Signature') === hash;
}

exports.webhook = (request, response) => {
  if (isFromSquare(REQUEST_URL, request, process.env.SIG_KEY)) {
    const data = JSON.stringify(request.body, null, 2);
    const fileName = `/tmp/${request.body.location_id}_${request.body.entity_id}_${Date.now()}.json`;

    fs.writeFileSync(fileName, data);

    storage
      .bucket(BUCKET_NAME)
      .upload(`${fileName}`)
      .then((success) => {
        fs.unlink(fileName);
        console.log(success);
        response.status(200).send();
      })
      .catch((error) => {
        fs.unlink(fileName);
        console.log(error);
        response.status(403).send(error);
      });
  } else {
    console.log(request);
    response.status(401).send();
  }
};

exports.event = (event, callback) => {
  callback();
};

The above webhook handler shows how to handle events coming from our Square account. We’ve added in verification of the X-Square-Signature header to validate it’s a payload coming from Square. It’s always worth being sure that a webhook service offers some way to verify the data being sent, since it’s possible for bad actors to interrupt or manipulate services by sending malicious data to your webhook handler.

Verifying our headers here lets us be sure we’re not storing arbitrary payloads into our Google Cloud Storage bucket. From here, you can choose to create another function for processing the new data as it comes in with another Google Cloud Function, or you can simply just have your application periodically check this storage bucket for new events to process.

For example, you could have it check if a refund is above a certain limit, monitor your inventory for an item that is getting too low, or look to see when a high value item has sold. You can find out more information about the events you can track using Square’s webhooks here.

I highly recommend giving Serverless a try and creating your own webhook handlers as a way to react to different events in your Square account. If you don’t already have a Square account, make sure to sign up at https://squareup.com/developers. Let us know how you’ve used FaaS or webhooks in the comments, we’d love to hear more!

Want more? Signup for our monthly developer newsletter.

Announcing Square’s New Python SDK

Richard Moot — Fri, 11 Oct 2019 20:18:11 +0000

We’re excited to announce the release of our new Python SDK. Run your business with Square APIs including Catalog, Customers, Employees, Inventory, Labor, Locations, Orders, and more.

To install the Python SDK, just pip install squareup from the command line. You can alternatively clone the SDK from GitHub and install it using python setup.py install --user. Next, all you need to do is provide your access token and you’re ready to use Square APIs.

from square.client import Client

client = Client(
    access_token='SANDBOX_ACCESS_TOKEN',
    environment='sandbox',
)

api_locations = client.locations
result = api_locations.list_locations()

One of the great features in the new Python SDK is that the response object contains new rich information about both the request and response. These details can be used for control flow and debugging.

Below are examples of checking the basic response status.

result.is_success()
#=> true

result.is_error()
#=> false

result.errors
#=> []

result.reason_phrase
#=> OK

result.status_code
#=> 200

If you were previously using the squareconnect SDK, you might be wondering how squareup compares. Let’s take a look! For example, let’s create the following customer along with their address:

customer = {
    "given_name": "Amelia",
    "family_name": "Earhart",
    "email_address": "Amelia.Earhart@example.com",
}

First, let’s look at how we used to create a customer with the legacy squareconnect SDK:

from __future__ import print_function

import squareconnect
from squareconnect.rest import ApiException
from squareconnect.apis.customers_api import CustomersApi

api_instance = CustomersApi()
api_instance.api_client.configuration.host = "https://connect.squareupsandbox.com"
api_instance.api_client.configuration.access_token = "SANDBOX_ACCESS_TOKEN"

try:
   # ListLocations
   api_response = api_instance.create_customer({
     "given_name": "Amelia",
     "family_name": "Earhart",
     "email_address": "Amelia.Earhart@example.com",
   })
   print(api_response.customer)

For comparison, let’s create the same customer with the new squareup SDK:

from square.client import Client

client = Client(
access_token='SANBOX_ACCESS_TOKEN',
environment='sandbox',
)
api_customers = client.customers
result = api_customers.create_customer({
 "given_name": "Amelia",
 "family_name": "Earhart",
 "email_address": "Amelia.Earhart@example.com",
})
print(result.body["customer"])

That’s all there is to it!

As you can see, the new squareup Python SDK interface is much simpler and less verbose. The new SDK also ships with a ton of usability and debugging features.

Give the squareup Python SDK a try today by installing it with pip install squareup.

With the new squareup SDK it’s easier than ever to use Square as a platform to run your business with Python. We can’t wait to see what you’ll build! If you have any questions or feedback, drop by our developer community. We’d love to hear from you.

Square In-App Payments SDK for React Native

Richard Moot — Tue, 30 Apr 2019 22:40:07 +0000

Since the release of our In-App Payments SDK, we’ve been getting a lot of requests for when this would be available for React Native. It is officially here! You can simply npm install —save react-native-square-in-app-payments inside your React Native project and follow the setup guide over here to start accepting payments in your React Native app.

If you’re not already familiar with the In-App Payments SDK, it enables developers to accept Square-powered payments from within their own mobile apps.

Now, it would be too easy to say just install the SDK and move on, so we’ll dig into a React Native app that I built to show how this works.

Our Order Ahead React Native App for buying Square Legos and demoed at ShopTalk.

Getting Your Developer Environment Setup

Prerequisites:

Android Studio (follow link to download and install)
Xcode (can be installed via App Store on macOS)
Square Account (sign-up here)
React Native CLI (follow guide for “Building Projects with Native Code”)

To be clear, you only need either Android Studio or Xcode if you plan on having your app work on their respective platforms and want to use their simulators for development.

Step 1: Get React Native CLI installed and set-up

npm install -g react-native-cli

Make sure to follow the React Native setup guide for “Building Projects with Native Code”. Using the react-native-square-in-app-payments plugin requires the In-App Payments SDK, which is native code for iOS and Android. Also, part of following that guide has you install the React Native CLI (command seen above), which helps facilitate linking libraries and running the simulator while developing.

Step 2: Add In-App Payments React Native Plugin to your Project

After you’ve setup React Native, you’ll want to follow the Square guide for adding In-App Payments into your React Native project. If you’re starting from scratch, you might want to take a look at the quick-start example application that shows an example app for that allows a user to buy a cookie. You can also just download that example app and modify from there.

Quick-start App for React Native In-App Payments Plugin.

Things to Understand for React Native Development with In-App Payments SDK

React Native Interfaces for the In-App Payments SDK

SQIPCore — Used to initialize the In-App Payments SDK in your React Native application.

SQIPCardEntry — Handles the standard credit card form capture. It is worth noting that if you’re wanting to store a Card on File for your user, then you’d want to only use this interface since you cannot store card details using digital wallets.

SQIPApplePay — Although fairly straightforward in the name, this interface is used for handling Apple Pay flow.

SQIPGooglePay — Same thing as the Apply Pay interface, but for handling Google Pay.

Each interface has some methods for initiating the flow, handling errors or the user closing the form, and completing authorization to get a nonce (a one-time use token). You are still required to have a backend implementation to use the nonce for either storing a card on a customer profile, or processing a transaction. You can find more on how this flow works in the Square documentation on.

Routing / Navigation

Although this can vary depending on which library you’re using, its worth explaining the one we use in our example. React Navigation is a commonly used library for routing and navigation in React Native apps.

You can add it by running:

npm install — save react-navigation react-native-gesture-handler

react-native link react-native-gesture-handler

The basic premise of the navigation library is to create a central hub at the root of your React Native app that can control which “screen” should be displayed at any given time. There are a few different types of navigation you can have with this library, but we’re just sticking with the stack navigator. It works exactly like a stack data structure that has each screen go “on” to the stack and when a user goes back it just pops them off the stack.

An Order Ahead Example Application

In order (so punny) to show what can be done with the React Native In-App Payments Plugin, we created an app to let people pick their own Square Lego person at conferences and also demonstrate how the new Orders Push Beta can push that into a Square Point of Sale (POS).

At the root of our app, we use the createAppContainer and createStackNavigator from React Navigation for wrapping our React app and handling all of our routing and navigation. This is also where we will initialize the In-App Payments SDK using SQIPCore in the componentDidMount() lifecycle method.

import React, {Component} from 'react';
import {
 createStackNavigator,
 createAppContainer
} from 'react-navigation';
import HomeScreen from './screens/Home';
import CheckoutScreen from './screens/Checkout';
import {
 SQIPCore,
} from 'react-native-square-in-app-payments';

const AppNavigator = createStackNavigator({
 Home: HomeScreen,
 Checkout: CheckoutScreen
}, {
 initialRouteName: "Home"
});

const AppContainer = createAppContainer(AppNavigator);

export default class App extends Component {
 async componentDidMount() {
   await SQIPCore.setSquareApplicationId('YOUR_APP_ID');
 }
 render() {
   return <AppContainer />;
 }
}

We kept this really simple by having only two screens. The main screen displays all of our products (in this case, lego people) and the other screen is our checkout.

A lot of the code in the application is dedicated to styling the components, which could be its own blog post. The key part to take away from this is how to interact with the In-App Payments SDK.

Next, we’ll dig into our Checkout screen and look inside our componentWillMount() method of our CheckoutScreen component. This is where we set our iOS card entry theme (you need to set these in a styles.xml in Android).

 async componentWillMount(){
   if (Platform.OS === 'ios') {
     await SQIPCardEntry.setIOSCardEntryTheme({
       saveButtonFont: {
         size: 25,
       },
       saveButtonTitle: 'Order 💳 ',
       keyboardAppearance: 'Light',
       saveButtonTextColor: {
         r: 255,
         g: 0,
         b: 125,
         a: 0.5,
       },
     });
   }
 }

Then, we have to create a few lifecycle methods for handling events after starting the credit card form flow and handle getting our nonce for processing the card details.

onCardEntryComplete() {
   // Update UI to notify user that the payment flow is completed
 }

 async onCardNonceRequestSuccess(cardDetails) {
   try {
     // take payment with the card details
     // await chargeCard(cardDetails);
     await fetch('YOUR_BACKEND_URL', {
       method: 'POST',
       headers: {
         Accept: 'application/json',
         "Content-Type": "application/json"
       },
       body: JSON.stringify({
         nonce: cardDetails.nonce,
         item: this.state.cartItem.item_data,
         customer: this.state.customer
       })
     }).then((resp)=>{
       // Handle resp
     })

     // payment finished successfully
     // you must call this method to close card entry
     console.log(cardDetails);
     await SQIPCardEntry.completeCardEntry(
       this.onCardEntryComplete(),
     );
   } catch (ex) {
     // payment failed to complete due to error
     // notify card entry to show processing error
     await SQIPCardEntry.showCardNonceProcessingError(ex.message);
   }
 }

 onCardEntryCancel() {
   // Handle the cancel callback
 }
 async onStartCardEntry() {
   const cardEntryConfig = {
     collectPostalCode: true,
   };
   await SQIPCardEntry.startCardEntryFlow(
     cardEntryConfig,
     this.onCardNonceRequestSuccess,
     this.onCardEntryCancel,
   );
 }

To break this down, at our base method for starting the card flow is the onStartCardEntry() method. We then have our onCardNonceRequestSuccess, onCardEntryCancel, and onCardEntryComplete for handling the different events in our flow.

onCardNonceRequestSuccess — handles when we’ve successfully requested a nonce using the In-App Payments SDK, so we can send it to our backend for additional processing.

onCardEntryCancel — should be used to handle if a user closes out the card entry form before filling it out and triggering a card nonce response.

onCardEntryComplete — is used to close out the form, but can also be used for handling any state updates to your application.

The React Native Order Ahead App in action.

Now, as far as our front-end is concerned(in the case our React Native App), that is all we really need for processing a payment. The app should only be concerned with using the In-App Payments SDK for securely capturing those card details, getting the nonce, passing it to the backend for further processing, then react-ing (again, so punny) to the results of what was processed.

Also, to be clear, this is only one way to implement the In-App Payments SDK Plugin in your React Native application. You could certainly also add in digital wallet support for Google Pay and/or Apple Pay, this was just focused on demonstrating the card flow.

The rest of our capabilities for creating and pushing orders into a Square POS, charging a transaction (taking a payment), and/or storing customer card details will happen in your backend. You can read more about our Orders Push Beta and our Card on File transactions by following the links if you’re interested in building your own app for that, or join our Slack community and ask for help.

If you’re plan on building something on Square using our React Native In-App Payments Plugin and want to write about it (or anything else Square related), please hop into our Slack community and let us know (you can join just to say hi too), we’re always happy to chat about whatever you’re working on.

If you want to keep up to date with the rest of our content, be sure to follow this blog & our Twitter account, and sign up for our developer newsletter! We also have a Slack community for connecting with and talking to other developers implementing Square APIs.

Making the Invisible Visible: A Look at Building Tools for Square Developers

Richard Moot — Tue, 15 Jan 2019 17:47:18 +0000

Written by Lindy Zeng on **Square Corner Blog**

At Square, the Developers team exposes APIs that allow third-party developers to build custom business-processing solutions. On October 18, we announced to developers using our APIs that webhooks would now support retries. If a webhook cannot be delivered, our system will now be able to retry multiple times until a successful delivery.

Square’s webhook delivery system is a service I’ll refer to as Webhooks. Improving Webhooks’ reliability was a project I had the opportunity to dive into the first week I started at Square as a new college graduate. From the beginning, we wanted our Webhooks upgrades to require no change on the part of our external developers, in stark contrast to the amount of research, planning and work that went into the project. In fact, the announcement we sent out assured developers that they “should not need to make any changes to support webhooks with retries.” My manager remarked that it was “the most invisible change ever” — and that is how it should be. The focus of our team is to enable developers to easily integrate with Square’s APIs and provide them with a reliable and simple-to-use experience. Perhaps it was my manager’s remark about our “invisible” project that inspired me to share some insight into not only our webhooks reliability project, but also some of our “visibility” practices here at Square.

Square Reader SDK for React Native

Richard Moot — Mon, 01 Oct 2018 18:43:31 +0000

In the beginning of August, we announced the release of our Reader SDK for iOS and Android to allow developers to build their own custom in-person payment experiences.

Now, we’ve taken that ground-breaking SDK and wrapped it up in a React Native plugin that you can use in your own React Native project. So whether you’re a cross-platform guru looking to creating the ultimate in-person payment experience or just a React hacker looking to try out something new, you can now npm install react-native-square-reader-sdk in your project (just be sure to read our quick start guide on getting the native dependencies installed).

We released a React Native plugin for our Reader SDK to allow developers to more easily and rapidly create new in-person payment applications. We know that iOS and Android developers can just as easily use the native SDK, but here we can reach any JavaScript developer. We even have a quick-start application that can give you a starting place for creating your very own point of sale, kiosk, or custom in-person payment experience. It’s as easy as tweaking some JSX, or creating your own components, and then connecting them to the interfaces we’ve provided.

It’s possible to get an app up and running locally within five minutes. I was even able to get a custom keypad, entering arbitrary values, in an hour (granted, I was a little rusty on my React Native when I was trying it). I’m also very much not a mobile developer, and having the application running on an iPhone and Android simulator simultaneously was so powerful for having a responsive feedback loop when developing. You can enable live reloading on each device and have all your changes reflected immediately upon saving.

Live reloading a React Native Square Reader app in iOS and Android simultaneously!

Let’s say you take our quick-start app out for a spin and are looking to just get your feet wet in making your own point of sale app.

You can open up [reader-sdk-react-native-quickstart/app/screens/CheckoutScreen.js](https://github.com/square/react-native-square-reader-sdk/blob/master/reader-sdk-react-native-quickstart/app/screens/CheckoutScreen.js) and start modifying some of the buttons to adjust the amounts that you’re charging.

Then add some additional buttons that look like this:

<KeyPadButton
  title="1"
  onPress={() => this.addValue(1)}
  primary
/>

The above is just a modified version of the provided CustomButton component to look a little different. We then add in our own function for adding a value:

addValue(value) {
  this.setState((prevState) => {
    return {
      currentValue: [...prevState.currentValue, value],
    };
  });
}

and add a currentValue array to the state of our CheckoutScreen component:

class CheckoutScreen extends Component {
  constructor(props) {
    super(props);
    this.state = {
      currentValue: [0, 0],
    };
  }

You now have your own keypad to enter amounts to charge.

Here you can see what a final custom keypad looks like. We have buttons for every number, we can clear values, and we’re just storing the current value we want to charge in the main CheckoutScreen component. The state even persists if we back out of the charge.

It’s so easy to modify these interfaces! You can change the text, add in some additional state, or create custom functions to tailor the application to do whatever you need. The key benefit here is that you can then deploy this to iOS and Android using the same core components.

This is really just scratching the surface, since these are only simple modifications to the quick-start application. We are looking forward to seeing what the React Native community creates with this new plugin. Whether you want to make the next self-ordering kiosk, create a whole new point of sale for your favorite industry, or just be the first to build a React Native application with it — we want to hear about it!

Tweet us at @SquareDev or join us in our slack community over at https://squ.re/slack.

Also, if you just want to contribute to the open-source project on GitHub, feel free to give it a fork and submit a PR to us!

Square API Versioning for Connect v2

Richard Moot — Fri, 13 Jul 2018 20:04:32 +0000

We’ve got an exciting update coming for our Connect v2 developers! We have released versioning for all Connect v2 endpoints for Square’s APIs. This will allow us to deliver more functionality and features faster than ever before. No need to worry though, our APIs will remain backwards-compatible and will allow you to upgrade when you’re most comfortable. This means you can safely continue using the Square APIs you already love, but allows us to bring you new or improved features without breaking your code.

What does this mean for me?

If you don’t want to upgrade your integration or use the latest and greatest, then it means you can stick with the version of the API that you’re currently using. If you do want to upgrade, you can easily test things out by setting your Square-Version header to your desired version.

How do I know what version I am on?

You can always check your developer dashboard. You can also check the response from calling an endpoint and see what your Square-Version header is set to. When you create your app, your default version (the version currently set for your application) is set to the most recent version of the API. This means that if you don’t explicitly specify the version of the API to use when making requests to Connect v2 endpoints, your default version will be used. So if the most recent version of the API is 2018-07–12 and you created your app on 2018-07–15, then you’ll be set to version 2018-07–12.

Why are you doing this?

This lets us deliver more functionality to developers while preventing negative impacts that upgrading APIs can have on developers who have already implementations.

Do I need to upgrade my SDK?

If you are upgrading your API version, you may upgrade the SDK version when you are ready. Each version of the SDK is “pinned” to a version of the API, so you never need to worry about the SDK accessing the “wrong” version, even if you change your default. As new versions of the API are released, so are new versions of our SDKs. The SDK version will follow the format 2.20180712.0 to correspond to version 2018-07–12 of the API. You’ll always know what version of the API the SDK is using by just looking at the SDK version.

The great benefit here is also that even if you don’t remember to go into your dashboard and upgrade your app’s default API version, the SDK will handle explicitly setting the Square-Version header to the API version that matches to the SDK. No more thinking about which version to be on, let the SDK do the work for you!

What does this look like?

curl https://connect.squareup.com/v2/locations/{{location_id}}/transactions \
   -X POST \
   -H "Content-Type: application/json"  \
   -H "Authorization: Bearer ACCESS_TOKEN" \
   -H "Square-Version: 2018-07-12" \
   -d '{
    "idempotency_key": "74ae1696-b1e3-4328-af6d-f1e04d947a13",
    "amount_money": {
      "amount": 200,
      "currency": "USD"
    },
    "card_nonce": "card_nonce_from_square_123",
   }'

We are really looking forward to delivering new and improved functionality to developers. Having API versioning is a key step to getting this into the hands of developers. We can now give developers the features they want more rapidly while also not breaking things for existing implementations. If there are new features that you really want or things that you want improved, come join us in our Slack community or post on StackOverflow with the tag square-connect so that we can hear from you.

Want more? Sign up for our monthly developer newsletter or come say hi in the Square dev Slack channel!

Serverless Instant Checkout Links

Richard Moot — Wed, 27 Jun 2018 21:27:57 +0000

Servers beware! Watch out containers! Our serverless overlords are here! There is a lot of hype around serverless and talk about it being the end of containers, but we’re still not seeing a whole lot of major adoption of the technology (at least not seeing many companies vocal about it). My hope is to spark a little interest on what is possible in this space by showing different ways to use serverless beyond image processing, ETL, or general async tasks (but its really great for those things!). We’re still sticking with eCommerce though.

In a previous post, I talked a bit about how to create a Super Simple Serverless eCommerce site that used AWS Lambda and S3 to do serverless checkout payments. This got me thinking about creating something a little more advanced—something almost any Square seller could use to allow customers to immediately purchase products using just a link. We’ll go over a simple version of the application I built using only four Google Cloud functions via Firebase. The idea behind switching from AWS Lambda to Firebase here is to demonstrate different platform offerings in the serverless space, but also because there were a lot more tools available on Firebase to support this kind of service. It’s also worth having some examples out there that aren’t needing to use the Serverless Framework.

The application consists of:

Warning! Clicking on this image will not actually connect your Square account.

The front-end of the application originally was just static pages, but has since been refactored into a fairly simple React application. The main focus here will be on using serverless functions for doing our processing though. The first step in getting our instant checkout links created requires setting up OAuth in order to get our user’s access token. For this, we will create our first two functions, named “authorize” and “code”. Google does a great job of explaining how to use Firebase CLI on their site so we’ll skip that.

If you’re not familiar with OAuth or want to know more about OAuth with Square, checkout (pun intended) my previous blog post “OAuth, wherefor art thou?”.

Now let’s dig into some sweet, sweet code examples.


const functions = require('firebase-functions');
const crypto = require('crypto');

exports.authorize = functions.https.onRequest((request, response) => {
  const squareAuthURL = "https://connect.squareup.com/oauth2/authorize?";
  const state = (crypto.randomBytes(32)).toString('hex');
  response.set('Set-Cookie', `__session=${state}; Secure`);

  response.send(
    squareAuthURL +
    `client_id=${functions.config().square.prod.app_id}&` +
    `response_type=code&` +
    `scope=MERCHANT_PROFILE_READ PAYMENTS_WRITE ORDERS_WRITE ITEMS_READ&` +
    `session=false&` +
    `locale=en-US&` +
    `state=${state}`
  );
});

Here we are just creating a string to send to the client-side for redirecting our user. The main purpose here is more about generating our state, creating the cookie, and passing it along for us to verify later when we get the callback from Square redirecting our user back to us.

exports.code = functions.https.onRequest((request, response) => {
  const tokenURL = "https://connect.squareup.com/oauth2/token";
  const redirectURI = "https://checkout-now.firebaseapp.com/callback";
  const cookieState = getSessionCookie(request.get('cookie'))
  const { code, state } = request.body;

  if (cookieState === state) {
    const { app_id, secret } = functions.config().square.prod;
    let access_token, id, email, name;
    return axios.post(tokenURL, {
        client_id: app_id,
        client_secret: secret,
        code: decodeURIComponent(code),
        redirect_uri: redirectURI
      })
      .then(token => {
        ({ access_token } = token.data);
        return axios.get("https://connect.squareup.com/v1/me", {
            "headers": {
              "Authorization": `Bearer ${access_token}`
            }
      }).then(user => {
        ({ id, email, name } = user.data);
        return createFirebaseAccount(id, email, name, access_token)
      }).then(firebaseToken => {
        return response.json({
          "email": email,
          "token": firebaseToken
        });
      }).catch(error => {
        console.log(error);
        return response.send(error);
      });
    });
  } else {
    console.log(`INVALID STATE: ${cookieState} === ${state}`);
    return response.send(`INVALID STATE: ${cookieState} === ${state}`);
  }
});

We’re definitely doing a bit more here than just getting our access token from the callback. We are looking up the user’s info using their access token and then creating an account in Firebase for that user’s email. The intention here was to disallow a user to create an account using any email they wanted, and strictly having it tied to the email that is set for their Square account. We’ve omitted the createFirebaseAccount() function definition, since it’s just another detail peculiar to Firebase for creating accounts.

We’re in a pretty good place! We have authorized our user, received an access token, set the user up in Firebase, stored their token, and now we can start using Square’s API’s for generating our instant checkout links.

After our user gets their sign-in link in their email and is redirected back to our app to sign in, we need to generate our links to send to the user. This is where we’ll need the catalog function.

exports.catalog = functions.https.onRequest((request, response) => {
  let uid;
  admin.auth().verifyIdToken(request.body.idToken)
    .then(decodedToken => {
      ({
        uid
      } = decodedToken);
      return admin.database()
        .ref(`/squareAccessToken/${uid}`)
        .once('value')
    }).then(userToken => {
      (SquareConnect.ApiClient.instance).authentications["oauth2"]
        .accessToken = userToken.val();
      const catalogApi = new SquareConnect.CatalogApi();
      return catalogApi.listCatalog()
    }).then(catalog => {
      let formattedResponse = catalog.objects.map((elem) => {
        return axios.post(`https://firebasedynamiclinks.googleapis.com/v1/shortLinks?` +
          `key=${functions.config().web.key}`, {
            "longDynamicLink": `https://checkout.page.link/?` +
              `link=https://checkout-now.firebaseapp.com/checkout/` +
              `${(uid.split(":"))[1]}/${elem.item_data.variations[0].id}`,
            "suffix": {
              "option": "SHORT"
            }
          }).then(resp => {
          return {
            name: elem.item_data.name,
            catalogId: elem.id,
            varId: elem.item_data.variations[0].id,
            price: elem.item_data.variations[0].item_variation_data.price_money,
            checkoutUrl: resp.data.shortLink
          }
        }).catch(err => console.log(err))
      });
      return Promise.all(formattedResponse)
    }).then(values => {
      return response.json(values);
    }).catch(error => {
      console.log(error);
      response.send(error);
    });
});

This function is a little bit dense. We’re taking the token send to us, decoding the Firebase token, looking up our user, getting their Square access token, querying the catalog API, iterating over the catalog items, creating a list of item objects, and creating short url links for checking out with.

Take a breath, there was a lot in that list.

This is a not so pretty example of our checkout link.

Okay, break’s over. Back to work.

In the catalog links, we’re constructing a URL the follows the format/merchantId/catalogVariantId/ which allows us to look up our Square merchant and then what item is being purchased. This might be a little confusing, since we haven’t looked at the final function yet. We have one more function to go over: the checkout function. Our checkout function will handle the process of looking up a merchant, looking up the catalog item, creating a Square checkout URL, and then redirecting the user to that checkout url. Let’s take a look at what this function looks like.

const app = express();
app.get('/checkout/:userId/:variantId', (request, response) => {
  admin.database()
       .ref(`/squareAccessToken/square:${request.params.userId}`)
       .once('value')
    .then( userToken => {
      (SquareConnect.ApiClient.instance).authentications["oauth2"].accessToken = userToken.val();
      const catalogApi = new SquareConnect.CatalogApi();
      return catalogApi.retrieveCatalogObject(request.params.variantId)
    }).then( item => {
      const checkoutApi = new SquareConnect.CheckoutApi();
      const idempotencyKey = crypto.randomBytes(48).toString('base64');
      const locationId = item.object.present_at_location_ids[0];
      const checkoutReq = {
        idempotency_key: idempotencyKey,
        order: {
          idempotency_key: idempotencyKey,
          reference_id: Date.now().toString(),
          line_items: [
            {
              catalog_object_id: request.params.variantId,
              quantity: "1"
            }
          ],
        }
      }
      return checkoutApi.createCheckout(locationId, checkoutReq)
    }).then( returnedCheckout => {
      return response.redirect(returnedCheckout.checkout.checkout_page_url);
    }).catch( error => response.send(error));
});
exports.checkout = functions.https.onRequest(app);

We switched things up here by wrapping our function up as an Express application. This allows an easier time in parsing route variables so we could look up our merchant and catalog IDs. Since our prices are already set in Square, all we need to do is place the item as a line item in our order, generate our checkout link, and then redirect!

Candidly: this example is missing a lot. It is meant as a proof of concept (which is why I omitted the actual URLs for the application) since there are a few scenarios we’re not really handling here that actual merchants would likely want. For starters, the catalog function for generating links entirely disregards other item variants (i.e. large, medium, small, for t-shirt sizes). The function just grabs the first variant. Clearly more could be done here to accommodate that, but the focus was to show how easily we could get instant checkout links.

To add to this, we’re best supporting a digital good or an item that had flat-rate shipping (we’d need to capture a shipping address and add a line item for the shipping charges, but the checkout API supports that). That’s all easy enough, but if we wanted dynamic shipping rates, we might need to capture their address earlier in the process to create a line item that included the shipping rate.

In my previous post on Super Simple Serverless eCommerce, I touched on the fact that cold starts can really harm something like a checkout experience since the functions not having run for a while could mean a slow startup. We would have to monitor the impact on that checkout function, since a single social media post could spike traffic drastically and cause a lot of instances of our function to be spun up to handle it all. The hope is that so many people would use this particular function that it could reasonably handle all of the traffic. The more concerning issue might be the cost of having so many calls against this function. You’d have to weigh the cost of having a lot of invocations of your function against just having your own server handling these requests. All things to consider before trying to go fully serverless!

We hope this helped spark some ideas on what you can do with serverless, but even more so, we hope it makes you want to try out Square’s APIs! If you have a project you’re working on that you want to talk about, pains with payments, or just want to chat with some devs, check out the links below to get in touch with us!

Want more? Sign up for our monthly developer newsletter or come say hi in the Square dev Slack channel!

Super Simple Serverless eCommerce

Richard Moot — Fri, 20 Apr 2018 16:43:06 +0000

A lot of companies have been taking the plunge into utilizing serverless in order to enhance their tech stacks (e.g., Nordstrom, Netflix, and Coca-Cola). It may seem like serverless is just a growing fad, but that was the same line of thought many people had about Node until Walmart launched a new site before Black Friday. We might be approaching a similar inflection point for serverless to rapidly improve the speed of development and scale that Node has been able to accomplish.

If you haven’t jumped on the serverless bandwagon yet, now is the time. We’re going to walk though a simple way to create serverless functions to allow customers to instantly checkout and buy an item from a Square store. We’ll go through creating a static site on S3, creating AWS Lambda functions, and creating AWS API Gateway endpoints to allow customers to instantly checkout using the Square Checkout API.

It’s worth clarifying that there’s a difference between The Serverless Framework and serverless computing. The Serverless Framework is just a tool that can be used to facilitate creating, deploying, and managing your serverless functions that you create with your desired cloud provider. Serverless computing is a reference to a cloud provider dynamically managing the allocation of machine resources.

We’ll be using the The Serverless Framework in this post to facilitate creating and deploying our functions more easily, but we don’t want it confused with serverless computing as a whole. We’ll explore different platforms and different tools in future posts as we build on the concepts covered here.

Things you need to build this:

Static Site Using S3

The basic structure of our little store will be a static HTML page hosted on S3 and spiffed up with CSS and JavaScript. We’ll then process our checkout through Lambda functions that allow you to just purchase the one item you clicked on. This is intended to be super basic to illustrate how to get things up and running on AWS — we can explore more advanced ways of doing this all in future posts. We’ll start with the HTML and getting that into S3 to create our static website.

<!-- start product -->
<div class='product'>
    <div class='imageContainer'>
        <img class='productImage' src="/0.jpeg" />
        <!-- insert product image url here -->
        <div class='imageOverlay'>
            <button>View Details</button>
        </div>
    </div>
    <div class='modal clearfix'>
        <button class='close'>Close</button>
        <img class='modalImage' src="/0.jpeg" />
        <!-- insert product image url here -->
        <div class='productInfo'>
            <h2 class='productTitle'>Back to Square 1 Sticker</h2>
            <!-- insert product title here -->
            <p class='productDescription'>"If only 88 was a perfect Square..."</p>
            <div class='productMeta'>
                <h2 class='productCost'>
                    <span class='green'>$1.00</span>*
                </h2>

                <!-- insert product cost here -->
                <span class='helperText'>*We're not actually going to charge you.</span>
                <form action='https://UNIQUE_ID.execute-api.us-east-1.amazonaws.com/prod/checkout' method='post'>
                    <input name='itemVarID' type='hidden' value="IBXSHR4PIMEAHHSOAKNBC5PQ" style='display: none' />
                    <input name='price' type='hidden' value="100" style='display: none' />
                    <input name='name' type='hidden' value="Back to Square 1 Sticker" style='display: none' />
                    <button type='submit' class='productPurchase'>Buy This</button>
                </form>
            </div>
        </div>
    </div>
</div>
<!-- end product -->

Take a look at the meat of our index.html by just looking at the product div elements. We’re hard coding our item’s variant id to each div and stuffing that into a hidden input field as well. This will let us easily pass this to our Lambda function with a POST request. My main reason for this approach is entirely the simplicity of it. We don’t need to write any JavaScript to handle passing the information — we can just use the native behavior of a form element to POST our item info to our function.

If we put in our 12 products, we get something similar to what we have below:

<!DOCTYPE html>
<html>

<head>
    <title>Square Swag Shop</title>
    <meta name="description" content="A Simple eCommerce Store">
    <link id="favicon" rel="icon" href="/favicon.ico" type="image/x-icon">
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name='viewport' content='width=device-width, initial-scale=1'>
    <link rel='stylesheet' href='/normalize.css'>
    <link rel='stylesheet' href='/main.css'>
</head>

<body>
    <div id="cocoon">
        <header class="container">
            <div id="square-logo">
            </div>
        </header>
        <div id="products" class="container clearfix">
            <div class='product'>
                <!-- Our other product html tags here -->
            </div>
            <div class='product'>
                <!-- Our other product html tags here -->
            </div>
            <div class='product'>
                <!-- Our other product html tags here -->
            </div>
            <div class='product'>
                <!-- Our other product html tags here -->
            </div>
        </div>
        <div class="veil"></div>
    </div>
    <script src='/modernizr-3.5.0.min.js'></script>
    <script src='https://code.jquery.com/jquery-3.2.1.min.js' integrity='sha256-hwg4gsxgFZhOsEEamdOYGBf13FyQuiTwlAQgxVSNgt4=' crossorigin='anonymous'></script>
    <script src='/plugin.js'></script>
    <script src='/main.js'></script>
</body>

</html>

We’ll skip over the stylings and the jQuery used to make modals, since that’s not really the focus here. All we have to do is upload all of our files to S3 and enable “Static website hosting” in Properties to have a publicly accessible site.

Now we should have a nice page for everyone to see our products, but we need to have a way to allow everyone to buy those products. Now we finally start digging into creating our AWS Lambda functions (serverless functions). This is what we’ll create to place in the form “action” attribute so that our form POSTs to our function.

I should hope its clear you have your own bucket name for the URL.

You should be able to access your static site by visiting the URL provided by AWS and you can see all your wonderful items on display.

Serverless Functions using AWS Lambda

For our serverless function, we’ll process the Square catalog variant ID that is being sent from our form in our static site, and then create a checkout URL to redirect our user to. To do this, we’ll use Square’s JavaScript SDK inside our function to more easily generate the URL we need. You’re more than welcome to attempt using just AWS tools for creating and deploying the function, but we’re going to just use Serverless for managing deploying the function and linking it to AWS API Gateway.

If you, too, want to use serverless to create your own functions, they have great tutorials over here. You need to have Node on your machine and install serverless with npm install -g serverless (or if you don’t want it installed globally, just use [npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b)).

You can run serverless create --template aws-nodejs to get a template going, but it creates a lot more than what’s needed. Feel free to just copy the handler.js and serverless.yml to modify into your own templates. We’ll start out with a basic function to test that our deployment is working as intended, then add in functionality for our checkout.

'use strict';
const SquareConnect = require('square-connect');

module.exports.checkout = (event, context, callback) => {
  let response = "Success! Our function is running!";
  callback(null, response);
};

This is just our example to test. Next, we want to create our serverless.yml file for deploying our function and creating the AWS API Gateway endpoint.

service: serverless-checkout # NOTE: update this with your service name

provider:
  name: aws
  runtime: nodejs8.10
  stage: prod
  memorySize: 256

package:
  include:
    - node_modules/square-connect/**
    - node_modules/superagent/**
  excludeDevDependencies: true

functions:
  checkout:
    environment:
      ACCESS_TOKEN: YOUR_ACCESS_TOKEN
      LOCATION_ID: YOUR_LOCATION_ID
    handler: handler.checkout
    events:
      - http:
          path: /checkout
          method: any

Now, it’s as simple as running serverless deploy to launch our functions into the cloud. You should see something similar to the below when you deploy:

Serverless: Packaging service...
Serverless: Excluding development dependencies...
Serverless: Uploading CloudFormation file to S3...
Serverless: Uploading artifacts...
Serverless: Uploading service .zip file to S3 (742.81 KB)...
Serverless: Validating template...
Serverless: Updating Stack...
Serverless: Checking Stack update progress...
..............
Serverless: Stack update finished...
Service Information
service: serverless-checkout
stage: prod
region: us-east-1
stack: serverless-checkout-prod
api keys:
  None
endpoints:
  ANY - https://UNIQUE_ID.execute-api.us-east-1.amazonaws.com/prod/checkout
functions:
  checkout: serverless-checkout-prod-checkout
Serverless: Removing old service versions...

You should be able to visit the URL that Serverless logged out to the console in your browser and find our message, “Success! Our function is running!” showing up in the browser. We just need to refactor our Lambda function to handle the catalog variant ID in order to request our checkout URL and redirect the user.

const SquareConnect = require('square-connect');
const crypto = require('crypto');
const querystring = require('querystring');

module.exports.checkout = (event, context, callback) => {
  (SquareConnect.ApiClient.instance).authentications["oauth2"].accessToken = process.env.ACCESS_TOKEN;
  const formData = querystring.parse(event.body);
  const locationId = process.env.LOCATION_ID;
  const checkoutRequest = {
    idempotency_key: crypto.randomBytes(48).toString('base64'),
    order: {
      idempotency_key: crypto.randomBytes(48).toString('base64'),
      reference_id: Date.now().toString(),
      line_items: [
          {
            catalog_object_id: formData.itemVarID,
            quantity: "1"
          }
      ]
    },
    merchant_support_email: "support@squareup.com"
  };
  const checkoutApi = new SquareConnect.CheckoutApi();

  checkoutApi.createCheckout(locationId, checkoutRequest).then((checkoutResponse)=>{
    const response = {
      statusCode: 302,
      headers: { Location: `${checkoutResponse.checkout.checkout_page_url}` }
    };
    callback(null, response);
  }).catch(error => {
      console.log(JSON.stringify(error, null, 2));
      callback(error)
  });
};

Here we have our fully functioning (pun intended) Lambda function that can create checkout URLs to allow users to buy our products.

Again, it’s worth reminding that this is intentionally a minimal implementation that would only work for something like a digital good (that requires no tax), but demonstrates how easy it is to create your checkout and redirect a customer without having to spin up our own servers. In fact, if you were to append your catalog variant ID as query string parameters to your function URL, you could just parse those out in your function to essentially have your own serverless “buy it now” link. Additionally, you could add a line item for shipping costs to easily handle flat rate shipping and even capture the customer’s shipping details in the checkout (see here for more details on that).

A preview of our eCommerce store. Those are our stickers we give away at developer conferences.

Serverless Misunderstandings

There seems to be widespread misunderstanding around serverless computing and what it is comprised of. Is it pay per invocation? Pay per Mb/s of memory? Just like Node, serverless is suffering a bit from the same desire to “do all the things.” True, it’s a new technology that needs to be explored, but a lot of weird uses are cropping up that come across as anti-patterns (in my opinion). Node was and is known for being really bad at handling CPU-intensive tasks due to its single-threaded nature, and the same goes for using serverless for user facing interactions or APIs. Users expect things to be responsive, and cold starts kill the expected responsiveness. You can certainly try circumvent this by keeping your functions warm as a solution to this, but smells like an anti-pattern. The whole benefit of serverless is to not have to be as concerned with your infrastructure, yet people are writing more code to modify their infrastructure’s behavior that they don’t really have control over.

If you plan to use serverless for user-facing applications, look carefully at your user traffic patterns to your endpoints, since that would play heavily into overall user experience. A constant amount of traffic would be relatively fine — functions would stay warm and a very small percentage of users would be impacted by a slow response — but if you have particularly spiky traffic, the user experience will suffer as your platform provider is spinning up additional instances of your function to service your traffic.

There are many possibilities to explore with serverless computing as the technology continues to mature, and today’s problems will diminish with time. The real reason to start now is so you can be really condescending to all the new serverless adopters of the future and tell them how much harder serverless programming was back in your day. So get started now and build something serverless!

To follow along with this post, you’ll need to sign up for a Square Developer account. Even if you don’t want to follow along, sign up anyways, its free!

Want more? Sign up for our monthly developer newsletter.

OAuth, wherefore art thou?

Richard Moot — Mon, 02 Apr 2018 21:41:50 +0000

Shakespeare’s plays are wonderful expressions of beauty and romance. His plays are also complicated, tragic, and hard to understand. Working with OAuth can feel a lot like Shakespeare. It sounds overly complicated, but the more time you spend with it, the more you see the underlying beauty and begin to truly understand it.

Let’s demystify some aspects of OAuth so you, too, can see the beauty and benefits to using it. If you’re already familiar with OAuth, skip ahead to take a look at the basic OAuth setup with Square.

Before we go into explaining OAuth , it’s worth talking about when you should be implementing it. A lot of API’s require utilizing OAuth, but sometimes you might not really need to use it. If you’re building an integration solely for your own use or your own application, you’re probably fine using your personal access token. If you’re wanting to build an application that needs access to multiple accounts or needs granular access, you’ll want to build out an OAuth integration. Even for your own infrastructure, if you have an ETL service, you might want to create an access token specifically for just that service that has read-only access.

Behind the Scenes of OAuth

To explain OAuth, we’ll walk through it like acts in a play. The first act is the authorization, the second act is the redirect, and the third act is acquisition. There’s also a prologue — getting things set up with your authorizer (in this case, Square) to register your application and get all your special credentials to use in the process.

In the first act, we’re sending the user off to the authorization server to ask for some permissions — like a kid who wants to go on a field trip. In order to attend, they’re sent to their parent with a list of what the field trip entails, and the parent has to sign off on it. For OAuth, you’re sending a user to the authorizer with your scope (permissions) that you would like to have. Then the user can see everything being requested and confirm that they would like to grant your application access for those permissions.

The second act is the redirect, which is where Square sends back a code to your application that can be used to acquire an access token. This should seem familiar if you’ve ever used SMS to log in to something. You need to provide both your password and the code that was sent via SMS in order to log in. The code sent back to your application from Square is your authorization code and is used by your application in the final act of getting the access token.

The third act is where we finally receive our access token from Square so we can process API requests for our user. Here, we need to provide the authorization code we received in the redirect to our callback url and our own application secret (which is acquired when registering with Square) in order to get our user’s access token. The access token can then be used to make API calls on behalf of our user.

The Benefits

We’ve gone through a few analogies and it’s clear that this process is a lot more complicated than simply asking a user for their password or making your user go get a special access token for you. The complexity ensures the process is secure — but it also gifts us more flexibility.

If we simply ask a user for their password, and they forget their Square password, then we’ll have to update our system with this new password and our integration would likely break in the interim (also, don’t ever ask for someone’s password). We also give the end users the ability to gracefully revoke access without having to change their password.

In addition, since we specified the scope up front, we only have to give access to whatever was specified. This means the end user can make an informed decision on what’s being granted. When providing a password, you can’t really control what’s being accessed. It’s all or nothing.

The Implementation

In order to solidify our understanding of OAuth, we’ll actually walk through an implementation of Square’s OAuth. There is a fully functional example over at https://glitch.com/~square-oauth-example. You can take a look at the source code and even remix it to have it work with your own account; just be sure to add in your own variables in the .env file. We’ll cover the core parts of the process, but we won’t be going into detail on things like storing user credentials or how best to handle session persistence.

The example is built using Express and SQLite. Express allows us to direct our users to the correct authorization URL and handle callbacks while SQLite allows us to store the token, and eventually renew or revoke the token. The last step there is important for a full implementation, since we don’t really want our users having to re-authorize our application every 30 days (the length an access token is valid for).

Before getting into writing code for our implementation we need to sign up for a Square Developer Account. We need to create an application and acquire our Application Secret and set our redirect URL. The redirect URL is where the user will be sent after they have signed-in and granted our application permission to access their account.

We’ll start off creating our route for handling sending the user to the authorization URL where we as for our permissions. Here’s what our route will look like:

Our authorize route start on line 14.

For those unfamiliar with Express, the req parameter is just our request object and the res parameter is our response object. We are also using Mozilla’s client-sessions middleware for creating encrypted cookies, which are accessible via req.auth. We start our method with checking if the user has already been authenticated, so we could skip needing to run through our whole authorization process. If the user hasn’t previously authorized with us, we initialize their state and store it in their cookie using req.auth so that we could later verify it to mitigate CSRF. After that, we’re simply constructing our authorization URL for redirecting the user. The CLIENT_ID is our application ID found at https://developer.squareup.com/apps for our specific application. Take a note of the scope and how we’re limiting this application to only read the MERCHANT_PROFILE to limit our access to read-only access on our user’s profile. If we needed more access, we could request more by adding additional values to the scope URL parameter.

Next, we want to show how to construct our redirect URL for handling the callback. Here is our example (I’ll forewarn, this part looks a little bit dense):

Our callback route starts on line 33.

We immediately start off by checking that the state in the query string matches what was stored in the user’s encrypted cookie, since we don’t want to process unauthorized requests. Then we’re simply POSTing our payload to https://connect.squareup.com/oauth2/token in order to get our access token for our user. Everything after that is simply querying Square’s API for some user information and creating our user in the database (we’re using Sequelize as an ORM to simplify things). I would like to point out as well that we’re only storing the user’s id in the cookie and no other personal information, because even though the cookie is encrypted, we don’t want to store sensitive information there. You need to treat access tokens like passwords, and you wouldn’t store passwords in unsafe places, so do the same for access tokens. In this example application, we’re going the extra step to encrypt the tokens before storing them and decrypting them when we need to use them.

Finally, we’ll cover renewal and revocation. Although these steps are optional, they’re extremely useful to implement to create a better user experience. Square allows access tokens to remain valid for 30 days, after which, you would need to renew them. You have a 15-day window to renew an access token.

Our renew route begins on line 80.

The renewal step is fairly straightforward: we just post the access token to https://developer.squareup.com/oauth2/clients/${CLIENT_ID}/access-token/renew with our application secret used in the authorization header.

You can find the detail of revoking a token starting on line 105 in our example below:

Our revoke route begins on line 105.

Revoking a token is even easier, since we just post our client id and access token to https://developer.squareup.com/oauth2/revoke.

We’ve covered each step in the process of creating an OAuth integration with Square to show how each method works, but there are a lot of libraries out there that simplify this process for you (PassportJS, Grant, and many others). If you’ve never implemented OAuth before, it’s useful to see a full integration like this in order to understand each step of the process better (which always helps with debugging down the road).

I highly encourage you to sign up for a Square developer account and try out this integration. You can just visit https://square-oauth-example.glitch.me/ and authorize your Square account there. Feel free to remix the example on Glitch to try getting your own OAuth integration working. You can also check out our OAuth guide and overview for more instruction on getting setup.

Want more? Sign up for our monthly developer newsletter.