DEV Community: Richard Moot

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.

The Squavenger Hunt

Richard Moot — Fri, 31 May 2019 00:21:36 +0000

https://twitter.com/SquareDev/status/1134083181324296194

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.

Introducing Square In-App Payments SDK

Richard Moot — Sun, 13 Jan 2019 00:16:57 +0000

https://medium.com/square-corner-blog/introducing-square-in-app-payments-sdk-1fc93b32814c

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!

Would you appreciate an SDK being written in TypeScript?

Richard Moot — Fri, 06 Jul 2018 00:09:16 +0000

I'm curious if Node/JavaScript developers would appreciate an SDK having been written in TypeScript, even if only wanting to use the transpiled JavaScript. My inclination is the additional type checking would be appreciated and help save developers from odd mistakes of data type being passed back from the SDK.

I know its a little extra overhead and adds a bit to the package size, but would you use it? (For context, this would be an SDK for interacting with a RESTful API).

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!