Design your custom payment form with SqPaymentForm

Heads up, we’ve moved! If you’d like to continue keeping up with the latest technical content from Square please visit us at our new home https://developer.squareup.com/blog

Do you currently use the SqPaymentForm, but you want it to look sleek and professional? Now is your chance to figure out how to make it look like anything you want! Let’s get started.

An aside: I assume that you have at least looked over the SqPaymentForm Overview page on Square’s doc site: https://docs.connect.squareup.com/payments/sqpaymentform/sqpaymentform-overview. If not, please do so now, because this article will refer to items from the doc site.

Each individual input field in the SqPaymentForm will be an iFrame that is embedded from Square. This is done to protect sensitive credit card information from malicious actors, and ensures that you don’t have to worry about PCI compliance, because Square handles it all for you.
To customize the SqPaymentForm, we need to think about the areas inside the individual iFrames and also outside the iFrames, as these are handled separately.

The exterior focuses on the actual text input fields (such as border, margins, and element width), while the interior focuses on the inner-text (such as font size, font color, placeholder, and background color). Here’s a quick visual aid to showcase what I mean:

Let’s see how we can edit the exterior designs first.

Exterior designs are defined in your own CSS file(in our Setup Guide, we suggest a file named sqpaymentform.css). When creating the SqPaymentForm you will need to specify the inputClass, which is the name of the class given to the text input fields that are used in the form. This could literally be named anything. You just need to make sure it matches in the sqpaymentform.css file. For example:

This is just to point out where the the name should match!

We’re going to add the following styles:

• Blue borders & slightly curved around the inputs
• Box-shadow due to curved borders (instead of outline)
• Increasing size and weight of the labels ( Note:.label is the class name I gave to the text labels for each input (ie “Card Number:”)
• Background color and font color of the button
• Different colored borders for focus and error validation

After adding these changes, we end up with the following:

Since the exterior design lives in the CSS file, you can customize any CSS style! The “smoothing” at the top of the file ensures the best quality across browsers

One thing to point out that can be seen above is the use of .sq-input--error and sq-input--focus (this should match whatever your inputClass is set to. Ex: your-cool-input-class-name--focus). These can be used to change the appearance of your input boxes when you select them, or when there’s been some validation error returned by the SqPaymentForm. They’re great, and you should use them!

Over in the sqpaymentform.js file we need to make sure to reference it, which is easy enough; just use the same name for the inputClass as mentioned earlier:

This is just a small snippet, you need more code to have the form actually load (see docs)

Let’s jump to interior designs. The SqPaymentForm only supports certain properties for the interior, and must be supplied via the inputStyles array in your sqpaymentform.js file. For the full list of properties, take a look a look at this page: https://docs.connect.squareup.com/payments/sqpaymentform/sqpaymentform-overview#inputstyle-objects

Now, say we want to make the fields have the following styles:

• 18px text
• Dark-grey text
• 15px padding
• Light-grey placeholder text.

It’s fairly straight forward to accomplish this. After adding the changes, we end up with this:

Again, this is just a small snippet, you need more code to have the form actually load (see docs)

If we combined both the interior and exterior designs that we’ve quickly gone through, we’ll get something that looks like this:

“Card Number” is selected to show off the box-shadow style. Simple, yet elegant!

That wraps it up! With this knowledge you should be able to build your very own SqPaymentForm to your liking.

Want more? Sign up for our monthly developer newsletter or join our Slack community at here.