Payment Form: Cookbook

Customize Payment Form Appearance

The SqPaymentForm library offers two ways to configure a payment form in your website as shown:

PaymentFormTwoConfigOptions

  • Multi-element payment form. You build the payment form with multiple DOM elements and map each element to a SqPaymentForm configuration field (cardNumber, cvv expirationDate, and postalCode).

  • Build a single-element payment form. You build the payment form with one DOM element and map it to the card configuration field provided by the SqPaymentForm library.

For an example, see Walkthrough: Integrate Square Payments In a Website. The following topics explain what the library does for the look and feel of the payment form and how you might customize it to conform to your page styles.

Customize the appearance of the multi-element payment form
Permalink Get a link to this section

The SqPaymentForm library renders HTML input elements inside iframes. When you want to customize the appearance of these inputs, note the following caveat:

  • An iframe is an element in your HTML page and therefore you can customize the iframe styles, for example, customize the height of the iframe and the border drawn around the iframe.

  • However, the area where the buyers type input (such as card number, expiration date), is Square’s HTML within the iframe that your CSS cannot customize. Instead, you direct the SqPaymentForm library to customize this portion.

For example, if you inspect any of the payment form elements in your browser, you will see html page containing <iframe> elements in the <body>. Each <iframe> element has an <html> child (Square’s HTML) that contains the <input> element. The following is an example HTML fragment:

<body>
   <div id="form-container">
   <iframe id="sq-card-number" name="sq-card-number" class="sq-input" frameborder="0" width="100%" scrolling="no" height="56" src="https://pci-connect.squareupsandbox.com/v2/iframe?type=cardNumber&amp;version=b5165b172b">
      <html>
         <head>...</head>
         <body>
            <form novalidate="true"><input autocomplete="cc-number" placeholder="Card Number" style="font-size: 16px; line-height: 24px; padding: 16px; background-color: blue;"></form>
         </body>
      </html>
   </iframe>
   <iframe id="sq-expiration-date" ... class="sq-input third">...</iframe>
   <iframe id="sq-cvv"      ...        class="sq-input third">...</iframe>
   <iframe id="sq-postal-code"     ... class="sq-input third">...</iframe>
   ...
</body>

Therefore, to customize the appearance of the multi-element payment form, the SqPaymentForm library provides the following two Configuration fields.

  • inputClass - Identifies CSS class name. You declare the class somewhere in your project and reference the containing .css file in the HTML head section. The library uses the specified CSS class to customize styles of the iframe element. \

  • inputStyles - An array of InputStyle objects that provide styles that library uses to customize the <input> rendered inside the iframe. The library supports a set of styles to choose for this customization.

You specify these configuration fields when you initialize the SqPaymentForm object.

An Example
Permalink Get a link to this section

To explore customization of the multi-element payment form appearance do the following:

  1. Complete the SqPaymentForm walkthrough to create a multi-element payment form. For more information, see Walkthrough: Integrate Square Payments In a Website. Do not follow the additional steps provided at the end of the walkthrough to Build a single-element payment.

  2. Review the following code components:

    • Layout of the iframe elements. You see the following layout of the SqPaymentForm iframe elements:

      multi-element payment form-iframes-layout

      This layout is defined by the following <div> block in the index.html. Three of the iframe elements (sq-expiration-date, CVV and sq-postal-code) specify a class (third). The styles defined in the class cause the elements appear on the same line.

      /* 
    Defines the order of iFrames on the page. 
    The class "third" defines the size, and  position of x axis ..see the .css file 
*/
<div id="form-container">
    <div id="sq-card-number"></div>
    <div class="third" id="sq-expiration-date"></div>
    <div class="third" id="sq-cvv"></div>
    <div class="third" id="sq-postal-code"></div>
    ...
</div>

      If you inspect these payment form elements in your browser, you see the corresponding iframe elements with class attribute showing the third class.

  • Customize iframe styles. In index.html, the SqPaymentForm initialization specifies the inputClass configuration field that sets the CSS class to use for the iframe styles.

     const paymentForm = new SqPaymentForm({
     ...
     inputClass: 'sq-input',
    ...
 });

    The sq-input class is defined in the mysqpaymentform.css file as follows:

    .sq-input {
height: 56px;
box-sizing: border-box;
border: 1px solid #E0E2E3;
background-color: white;
border-radius: 6px;
display: inline-block;
-webkit-transition: border-color .2s ease-in-out;
    -moz-transition: border-color .2s ease-in-out;
    -ms-transition: border-color .2s ease-in-out;
        transition: border-color .2s ease-in-out;
}

    You can explore customization by changing these CSS styles and review the resulting payment form.

  • Customize the input styles within the iframe. The SqPaymentForm initialization specifies the inputStyles configuration field to define custom styles for the <input> element in the iframe.

    // Customize the CSS for the SqPaymentForm iframe elements INTERNAL styles.
const paymentForm = new SqPaymentForm({
…
           inputStyles: [{
               fontSize: '16px',
               lineHeight: '24px',
               padding: '16px',
               placeholderColor: '#a0a0a0',
               backgroundColor: 'transparent',
           }], 

   …
});

    The style applies to all the four SqPaymentForm input fields in the iframes. The inputStyles defines the internal styles applied to the rendered iframes. For a list of input style properties SqPaymentForm supports, see InputStyle.

Customize the appearance of the single-element payment form
Permalink Get a link to this section

To build the single-element payment form, you use the the card configuration field of the SqPaymentForm. The look and feel you get is defined by the default CSS configuration the the library provides with the card element. You can optionally customize the appearance using the card.inputStyle (of type InputStyle) as described in this section.

The following screenshot shows a single-element payment form with custom styles. It screenshot also highlights components you can customize.

single-element-form-dark-ui

As the diagram illustrate, you can customize:

  • Payment form background color, shape, etc.

  • Font and color of the placeholder text

  • Font and color of the text as user enters the data

  • In the event of a user data input error, you can define the font and color of the following :

    • Incorrect user data text

    • Helper text message

An example
Permalink Get a link to this section

If you want to test the custom styling of the single-element payment form using the card.inputStyle, do the following:

  1. Complete the SqPaymentForm example walkthrough. For more information, see Walkthrough: Integrate Square Payments In a Website. Make sure you complete the Build a single-element payment form (Beta) step described at the end of the walkthrough. The resulting payment form you see uses the default CSS styling the card configuration element provides. Now you can apply custom styles.

  2. Set the background color of the page.

    1. Open mysqpaymentform.css.

    2. Set the background color of the page

      body, html {
        background-color: #2F2F2F;
}

  3. Add custom styles so the payment form appears as shown in the preceding screenshot. Open index.html and add the card.inputStyle configuration field as shown:

  card:
  {
    elementId: 'sq-card',
    inputStyle:
    {
      //Set font attributes on card entry fields
      fontSize: '16px',
      fontWeight: 500,
      fontFamily: 'futura',
      placeholderFontWeight: 300,
      autoFillColor: '#FFFFFF',    //Sets color of card nbr & exp. date
      color: '#FFFFFF',            //Sets color of CVV & Zip
      placeholderColor: '#A5A5A5', //Sets placeholder text color
      //Set form appearance
      backgroundColor: '#000',  //Card entry background color
      cardIconColor: '#A5A5A5', //Card Icon color
      borderRadius: '50px',
      boxShadow: "0px 2px 6px rgba(0,0,0,.02)," +
        "0px 4px 8px rgba(0,0,0, 0.04), 0px 8px 30px " +
        "rgba(0,0,0, 0.04), 0px 1px 2px rgba(0,0,0, 0.08)",
      //Set form appearance in error state
      error:
      {
        cardIconColor: '#FF1ADA', //Sets color of card icon
        color: '#FF4DB8',         //Sets color of card entry text
        backgroundColor: '#000',  //Card entry background color
        fontWeight: 500,
        fontFamily: 'futura'      //Font of the input field in error
      },
      //Set appearance of hint text below form
      details:
      {
        hidden: false,    //Shows or hides hint text
        color: '#A5A5A5', //Sets hint text color
        fontSize: '12px', //Not inherited from parent, Sets size of
        //text, defaults to 12px
        fontWeight: 500,  //Not inherited from parent
        fontFamily: 'futura', //Not inherited from parent, required to render form
        error:
        { //Sets attributes of hint text in when form
          color: '#FF4DB8', //is in error state
          fontSize: '12px'
        }
      }
    }
  }

Test the app and you will see the payment form with custom styles you specified.