SqPaymentForm

sqPaymentForm functions

sqPaymentForm function reference.

build

Manually builds the payment form.

Replaces InputTarget tags with corresponding iframe hosted SqPaymentForm input fields

build: function ()

Remarks

To manage the payment form initialization manually, set the autoBuild configuration option to false, and call the build function on the page where you want to initialize the payment form:

SqPaymentForm only replaces placeholder tags with input fields. when the DOMContentLoaded event is fired.

Use this function if SqPaymentForm is initialized after the page has fired the DOMContentLoaded event.

Examples

paymentForm.build();
              

destroy

Removes SqPaymentForm event listeners from a page.

destroy: function ()

Remarks

SqPaymentForm registers multiple event listeners on your webpage. These listeners go away when control is passed to a new page, but if you have a single-page web application, those listeners might remain longer than you want.

To manually remove the listeners from your webpage, add the function call where you want to clean up after the payment form.

Examples

paymentForm.destroy();
              

done

Makes a partial update to the payment request in response to a shipping contact or shipping option update in the Apple Pay or Google Pay sheet. Takes a paymentDetailsUpdate as the input.

done: function (paymentDetailsUpdate)

Remarks

done can only be called once inside of shippingContactChanged and shippingOptionChanged.

Examples

done({ total: newTotal });
              

isSupportedBrowser

Detect unsupported host browser.

Use this method to detect an unsupported browser before instantiating SqPaymentForm

isSupportedBrowser: function () {}

Return Value

boolean.

Examples

if (SqPaymentForm.isSupportedBrowser()) {
  var paymentForm = new SqPaymentForm({ ... });
} else {
  // browser not supported
}
         

masterpassImageUrl

Returns a background masterpass image url with parameters needed for SRC.

masterpassImageUrl: function (assetUrl) {}

Remarks

The assetUrl parameter is optional. When not provided, the default https://src.mastercard.com/assets/img/btn/src_chk_btn_126x030px.svg is used. The returned background image URL is used to set the background image (masterpassBtn.style.backgroundImage) of the masterpass digital wallet button.

Note: The current masterpass button URLs will be deprecated in the first half of 2020. You should update your code to use this function to set the background image instead of setting the url in a CSS class.

Examples

  methodsSupported: function (methods) {
    ...
    var masterpassBtn = document.getElementById('sq-masterpass');

    if (methods.masterpass === true) {
       masterpassBtn.style.backgroundImage = 'url('
       + sqPaymentForm.masterpassImageUrl()
       + ')';
      	masterpassBtn.style.display = 'inline-block';
    }
  },

              

recalculateSize

Forces SqPaymentForm to re-render iframes.

recalculateSize: function ()

Remarks

Re draws the payment form iframes. This function must be called when the payment form InputTarget tags are contained in a div tag that was hidden when the page DOM was loaded. After making the containing div visible, call recalculateSize

Examples

paymentForm.recalculateSize();
              

setPostalCode

The setPostalCode function sets the postal code based on information previously entered (e.g., from a billing address).

setPostalCode: function (postalCode) {}

Parameters

Remarks

Setting postalCode programmatically will make entering payment information more convenient for your customers.

Calling paymentForm.setPostalCode outside paymentFormLoaded will fail, even if the form has fully loaded. A successful call to paymentForm.setPostalCode also triggers the postalCodeChanged input event in the inputEvenReceived callback function.

Examples

paymentFormLoaded: function() {
      paymentForm.setPostalCode("POSTAL CODE FROM SHIPPING");
}
              

focus

Sets input focus on the specified SqPaymentform input field.

focus: function (field) {}

Parameters

Remarks

Examples

    paymentFormLoaded: function() {
      paymentForm.focus("cardNumber");
    }
            

requestCardNonce

Request a nonce from the SqPaymentForm

requestCardNonce: function ()

Remarks

A nonce is available after the user clicks the "Pay with credit card" button on the payment form. The requestCardNonce callback is invoked by the payment form on the button click.

Call paymentForm.requestCardNonce() to get the nonce.

Examples

The following example gets the nonce from the payment form after a user has clicked the "Pay with credit card" button and the payment form invoked the requestCardNonce callback.

function requestCardNonce(event) {

  // Don't submit the form until SqPaymentForm returns with a nonce
  event.preventDefault();

  // Request a nonce from the SqPaymentForm
  paymentForm.requestCardNonce();
}            

verifyBuyer

Verify the identity of the buyer.

Note: A TypeError is thrown if any function argument is missing or invalid.

verifyBuyer: function (source, verificationDetails, callback(err,verificationResult) {} ) {}

Parameters

Remarks

When the cardholder bank and merchant account are in the European economic area, verification is done by invoking the 3DS 2.0 flow.

Examples

The following example gets the nonce from the payment form and verifies the buyer after a user has clicked the "Pay with credit card" button and the payment form invoked the requestCardNonce callback.

   /*
     * callback function: cardNonceResponseReceived
     * Triggered when: SqPaymentForm completes a card nonce request
     */
    cardNonceResponseReceived: function (errors, nonce, cardData) {
      // Assign the nonce value to the hidden form field
      document.getElementById('card-nonce').value = nonce;
      const verificationDetails = {
        amount: '100.00',
        intent: "CHARGE",  //Allowed values: "CHARGE", "STORE"
        billingContact: {
          familyName: "Smith",
          givenName: "John",
          email: "jsmith@example.com",
          country: "GB",
          city: "London",
          addressLines: ["1235 Emperor's Gate"],
          postalCode: "SW7 4JA",
          phone: "020 7946 0532"
        }
      };
      try {
        paymentform.verifyBuyer(
          nonce,
          verificationDetails,
          function(err,verification) {
            if (err == null) {
              document.getElementById('buyerVerification-token').value = verification;
            }
        });
        // POST the nonce form to the payment processing page
        document.getElementById('nonce-form').submit();
      } catch (typeError) {
        //TypeError thrown if illegal arguments are passed
      }
    }
                

Callback functions

sqPaymentForm callback function reference.

Note: Callback functions are not asynchronous. Any function called within a callback must be synchronous or thenable. If a thenable function is called, the async/await pattern must not be used. Instead, get asynchronous results by calling the returned promise.then() function.

cardNonceResponseReceived

(required)

Invoked when SqPaymentForm receives the result of a nonce generation request. The result will be a valid credit card or wallet nonce, or an error.

cardNonceResponseReceived: function (errors, nonce, cardData, billingContact, shippingContact, shippingOption)

Parameters

Remarks

Nonce generation errors

Examples

cardNonceResponseReceived: function (errors, nonce, cardData, billingContact, shippingContact) {
  if (errors) {
    // Log errors from nonce generation to the Javascript console
    console.log("Encountered errors:");
    errors.forEach(function (error) {
      console.log('  ' + error.message);
    });

    return;
  }
  alert('Nonce received: ' + nonce); /* FOR TESTING ONLY */

  // Assign the nonce value to the hidden form field
  document.getElementById('card-nonce').value = nonce;

  // POST the nonce form to the payment processing page
  document.getElementById('nonce-form').submit();
}
            

createPaymentRequest

(required for Apple Pay, Google Pay, Masterpass)

Invoked when a digital wallet payment button is clicked.

Use this callback function to construct a paymentRequest to be returned to sqPaymentForm. The sqPaymentForm exchanges the paymentRequest for a nonce. Use cardNonceResponseReceived to get the returned nonce.

createPaymentRequest: function ()

Return Value

PaymentRequest.

Examples

createPaymentRequest: function () {
  return {
      requestShippingAddress: true,
      requestBillingInfo: true,
      shippingContact: {
        familyName: "Buyer",
        givenName: "The",
        email: "thebuyer@example.com",
        country: "USA",
        region: "CA",
        city: "San Francisco",
        addressLines: [
          "123 Main St"
        ],
        postalCode: "94114"
      },
      currencyCode: "USD",
      countryCode: "US",
      total: {
        label: "devs-Acceptance",
        amount: "5",
        pending: false
      }
  };
}
         

inputEventReceived

Invoked when visitors interact with SqPaymentForm iframe elements.

inputEventReceived: function (inputEvent)

Parameters

Remarks

The inputEventReceived callback operates independently from the main nonce generation workflow. The callback is customizable and used to take additional action when any of the following inputEvent events are detected.

• focusClassAdded - A form field gained focus, and the corresponding focus CSS class was added to the element.
• focusClassRemoved - A form field lost focus, and the corresponding focus CSS class was removed from the element.
• errorClassAdded - A form field has an invalid value, and the corresponding error CSS class was added to the element.
• errorClassRemoved - An invalid value on a form field was corrected, and the corresponding error CSS class was removed from the element.
• cardBrandChanged - The payment form detected a new likely credit card brand based on the card number.
• postalCodeChanged - The current value of the postal code form field changed.

Examples

inputEventReceived: function(inputEvent) {
  switch (inputEvent.eventType) {
    case 'focusClassAdded':
      /* HANDLE AS DESIRED */
      break;
    case 'focusClassRemoved':
      /* HANDLE AS DESIRED */
      break;
    case 'errorClassAdded':
      /* HANDLE AS DESIRED */
      break;
    case 'errorClassRemoved':
      /* HANDLE AS DESIRED */
      break;
    case 'cardBrandChanged':
      /* HANDLE AS DESIRED */
      break;
    case 'postalCodeChanged':
      /* HANDLE AS DESIRED */
      break;
  }
}
              

methodsSupported

Invoked when page is loaded

Called by SqPaymentForm when the page renders to decide which, if any, digital wallet button should be rendered in the payment form. This function will be invoked multiple times, once for each digital wallet you want to enable, with methods containing a single key (applePay, googlePay or masterpass) with a boolean value indicating whether the digital wallet is enabled or not.

methodsSupported: function (methods)

Parameters

Examples

methodsSupported: function (methods) {
  var applePayBtn = document.getElementById('sq-apple-pay');
  var applePayLabel = document.getElementById('sq-apple-pay-label');
  var masterpassBtn = document.getElementById('sq-masterpass');
  var masterpassLabel = document.getElementById('sq-masterpass-label');

  console.log(methods)
  // Only show the button if Apple Pay on the Web is enabled
  // Otherwise, display the wallet not enabled message.
  if (methods.applePay === true) {
    applePayBtn.style.display = 'inline-block';
    applePayLabel.style.display = 'none';
  }
  // Only show the button if Masterpass is enabled
  // Otherwise, display the wallet not enabled message.
  if (methods.masterpass === true) {
    masterpassBtn.style.display = 'inline-block';
    masterpassLabel.style.display = 'none';
  }
}
              

paymentFormLoaded

Invoked when SqPaymentForm is fully loaded.

paymentFormLoaded: function()

Remarks

This callback is used to set the state of Payment Form entry fields after the form has loaded. For example, use paymentForm.setPostalCode to set the postal code based on information previously entered (e.g., from a billing address).

Examples

paymentFormLoaded: function() {
  /* HANDLE AS DESIRED */
  paymentForm.setPostalCode("POSTAL CODE FROM BILLING");
}
          

unsupportedBrowserDetected

Invoked when the payment form is hosted in an unsupported browser. use the function to detect when the payment form is attempting to load in an unsupported browser. Use the callback to tell the user that the payment form cannot be loaded.

unsupportedBrowserDetected: function()

Examples

unsupportedBrowserDetected: function () {
      // update page element or show alert to tell user that payment form is not
      // supported in their browser.
}
              

shippingContactChanged

Invoked when requestShippingAddress is true in PaymentRequest and the buyer selects a shipping address in the Apple Pay or Google Pay sheet or enters a new shipping address.

Use this callback to validate a the buyer shipping contact. If validation indicates a problem, return an error message for the buyer. Update payment request details if a change in shipping address requires it.

shippingContactChanged: function (shippingContact, done)

Parameters

Return Value

Remarks

Examples

shippingContactChanged: function (shippingContact, done) {
 var valid = true;
 var shippingErrors = {};

 if (!shippingContact.postalCode) {
   shippingErrors.postalCode = "postal code is required";
   valid = false;
 }
 if (!shippingContact.addressLines) {
   shippingErrors.addressLines = "address lines are required";
   valid = false;
 }

 if (!valid) {
   done({shippingContactErrors: shippingErrors});
   return;
 }

 // Shipping address unserviceable.
 if (shippingContact.country !== 'US' || shippingContact.country !== 'CA') {
   done({error: 'Shipping to outside of the U.S. and Canada is not available.'});
   return;
 }

 // Update total, lineItems, and shippingOptions for Canadian address.
 if (shippingContact.country === 'CA') {
   done({
     total: {
       label: "MERCHANT NAME",
       amount: "UPDATED AMOUNT",
       pending: false
     },
    // Note: lineItems REPLACES the set of the line items in the PaymentRequest
     lineItems: [
       ...

       {
         label: "Tax",
         amount: "UPDATED AMOUNT",
         pending: false
       }
     ],
     shippingOptions: [
       {
         id: "1",
         label: "SHIPPING LABEL",
         amount: "SHIPPING AMOUNT"
       }
     ]
   });
   return;
 }

 // No changes are necessary.
 done();
}
              

shippingOptionChanged

Invoked when the buyer selects a shipping option in the Apple Pay or Google Pay sheet.

Use this callback to respond to a shipping option change.

shippingOptionChanged: function (shippingOption, done)

Parameters

Remarks

Examples

// Update total and line Items after user selects a shipping option
shippingOptionChanged: function(shippingOption, done) {
   // Creates a new array of line items that includes only 1 line
   // item. The item for a shipping option. Production code would get the
   // array of line items from the original PaymentRequest and add/update a line
   // item for the shippingOption argument of this callback.
   const newLineItems = [{
     label: shippingOption.label,
     amount: shippingOption.amount,
     pending: false
   }];
   const newTotal = {
     label: "MERCHANT NAME",

     // TODO: total amount to be calc'd based on difference between old and new
     // amount of this shippingOption.amount if shippingOption.amount was updated.
     // -- OR --
     // Increase total amount if the line item for this shippingOption is new.
     amount: "SOME_AMOUNT + shippingOption.amount",
     pending: false
   };

  done({
   // Note: newLineItems REPLACES the set of the line items in the PaymentRequest
   // newTotal REPLACES the original payment total.
   lineItems: newLineItems,
   total: newTotal
 });
};
              

Anonymous Functions

Anonymous callback function reference.

function(err, result)

Gets the result of the operation and any errors on failure.

function (err, result)

Parameters

Examples

verifyBuyer(nonce, verificationDetails, (err, result) => {
   if (err) {
     //handle errors
     return;
   }
   console.log(result.token);
 });
              

var paymentForm = new SqPaymentForm({
  // Initialize Google Pay InputTarget ID
  googlePay: {
    elementId: 'sq-google-pay'  //REPLACE ME
  },
  applicationId: "{REPLACE ME WITH YOUR APPLICATION ID}",
  locationId: "{REPLACE ME WITH YOUR LOCATION ID}",

    // SqPaymentForm callback functions
  callbacks: {

    /*
     * callback function: createPaymentRequest
     * Triggered when: a digital wallet payment button is clicked.
     */
    createPaymentRequest: function () {
      return {
        requestShippingAddress: true,
        requestBillingInfo: true,
        shippingContact: {
          familyName: "Buyer",
          givenName: "The",
          email: "thebuyer@example.com",
          country: "USA",
          region: "CA",
          city: "San Francisco",
          addressLines: [
            "123 Main St"
          ],
          postalCode: "94114"
        },
        currencyCode: "USD",
        countryCode: "US",
        total: {
          label: "devs-Acceptance",
          amount: "5",
          pending: false
        }
      };
    },

    /*
     * callback function: cardNonceResponseReceived
     * Triggered when: SqPaymentForm completes a card nonce request
     */
    cardNonceResponseReceived: function (errors, nonce, cardData, billingContact, shippingContact) {
      if (errors) {
        // Log errors from nonce generation to the Javascript console
        console.log("Encountered errors:");
        errors.forEach(function (error) {
          console.log('  ' + error.message);
        });

        return;
      }

      // Assign the nonce value to the hidden form field
      document.getElementById('card-nonce').innerText = nonce; //REPLACE ME
    },
    /*
     * callback function: methodsSupported
     * `methodsSupported` will be called multiple times, once for each digital
     * wallet you want to enable.
     * The `methods` object will contain a single key (applePay, googlePay or
     * masterpass) with a boolean value indicating whether the digital wallet
     * is enabled or not. For example, if Google Pay is available, `methods`
     * will be the object: {googlePay: true}.
     */
    methodsSupported: function (methods) {

      var googlePayBtn = document.getElementById('sq-google-pay');           //REPLACE ME
      var googlePayLabel = document.getElementById('sq-google-pay-label');   //REPLACE ME


      console.log(methods)
      // Only show the button if Google Pay is enabled
      // Otherwise, display the wallet not enabled message.
      if (methods.googlePay === true) {
        googlePayBtn.style.display = 'inline-block';
        googlePayLabel.style.display = 'none';
      }
    }
  }
});
      

var paymentForm = new SqPaymentForm({
  // Initialize the payment form elements
  applicationId: "{REPLACE ME WITH YOUR APPLICATION ID}",
  inputClass: 'sq-input',
  // Initialize the credit card inputTargets
  cardNumber: {
    elementId: 'sq-card-number',
    placeholder: '• • • •  • • • •  • • • •  • • • •'
  },
  cvv: {
    elementId: 'sq-cvv',
    placeholder: 'CVV'
  },
  expirationDate: {
    elementId: 'sq-expiration-date',
    placeholder: 'MM/YY'
  },
  postalCode: {
    elementId: 'sq-postal-code',
    placeholder: '12345'
  },
  // Customize the CSS for SqPaymentForm iframe elements
  inputStyles: [
    {
      backgroundColor: 'rgba(0,0,0,1)',
      boxShadow: '5px 10px 0px 0px rgb(255,255,255)',
      color: 'rgba(255,255,255,1)',
      fontFamily: 'Arial',
      fontSize: '15px',
      fontWeight: '100',
      padding: '2px',
      placeholderColor: 'rgba(255,255,255,1)'
    },
    {
      mediaMaxWidth: '800px',
      fontSize: '10px'
    },
    {
      mediaMaxWidth: '800px',
      mediaMinWidth: '600px',
      fontSize: '1px',
      backgroundColor: 'rgba(118,170,233,1)'
    },
  ],

  // SqPaymentForm callback functions
  callbacks: {

    /*
     * callback function: cardNonceResponseReceived
     * Triggered when: SqPaymentForm completes a card nonce request
     */
    cardNonceResponseReceived: function (errors, nonce, cardData, billingContact, shippingContact) {
      if (errors) {
        // Log errors from nonce generation to the Javascript console
        console.log("Encountered errors:");
        errors.forEach(function (error) {
          console.log('  ' + error.message);
        });

        return;
      }

      // Assign the nonce value to the hidden form field
      document.getElementById('card-nonce').innerText = nonce; //REPLACE ME
    },

    /*
     * callback function: unsupportedBrowserDetected
     * Triggered when: the page loads and an unsupported browser is detected
     */
    unsupportedBrowserDetected: function () {
      /* PROVIDE FEEDBACK TO SITE VISITORS */
    },

    /*
     * callback function: inputEventReceived
     * Triggered when: visitors interact with SqPaymentForm iframe elements.
     */
    inputEventReceived: function (inputEvent) {
      switch (inputEvent.eventType) {
        case 'focusClassAdded':
          $('#focus-class-added').text(inputEvent.elementId);
          break;
        case 'focusClassRemoved':
          $('#focus-class-removed').text(inputEvent.elementId);
          break;
        case 'errorClassAdded':
          $('#error-class-added').text(inputEvent.elementId);
          break;
        case 'errorClassRemoved':
          $('#error-class-removed').text(inputEvent.elementId);
          break;
        case 'cardBrandChanged':
          $('#card-brand-changed').text(inputEvent.cardBrand);
          break;
        case 'postalCodeChanged':
          $('#postal-code-changed').text(inputEvent.postalCodeValue);
          break;
      }
    },

    /*
     * callback function: paymentFormLoaded
     * Triggered when: SqPaymentForm is fully loaded
     */
    paymentFormLoaded: function () {
      var text = $('#payment-form-loaded').text();
      $('#payment-form-loaded').text(text + ' - loaded');
    }
  }
});
      

var paymentForm = new SqPaymentForm({
  // Initialize Gift Card InputTarget ID
  giftCard: {
    elementId: 'sq-gift-card',
    placeholder: "GIFT CARD NUMBER"
  },
  applicationId: "{REPLACE ME WITH YOUR APPLICATION ID}",
  locationId: "{REPLACE ME WITH YOUR LOCATION ID}",

    // SqPaymentForm callback functions
  callbacks: {


    /*
     * callback function: cardNonceResponseReceived
     * Triggered when: SqPaymentForm completes a card nonce request
     */
    cardNonceResponseReceived: function (errors, nonce, cardData, billingContact, shippingContact) {
      if (errors) {
        // Log errors from nonce generation to the Javascript console
        console.log("Encountered errors:");
        errors.forEach(function (error) {
          console.log('  ' + error.message);
        });

        return;
      }

      // Assign the nonce value to the hidden form field
      document.getElementById('card-nonce').innerText = nonce; //REPLACE ME
    }
  }
});
      

{
  requestShippingAddress: true,
  requestBillingInfo: true,
  shippingContact: {
    familyName: "CUSTOMER LAST NAME",
    givenName: "CUSTOMER FIRST NAME",
    email: "mycustomer@example.com",
    country: "USA",
    region: "CA",
    city: "San Francisco",
    addressLines: [
      "1455 Market St #600"
    ],
    postalCode: "94103"
  }
  currencyCode: "USD",
  countryCode: "US",
  total: {
    label: "MERCHANT NAME",
    amount: "TOTAL AMOUNT",
    pending: false
  },
  lineItems: [
    {
      label: "Subtotal",
      amount: "SUBTOTAL AMOUNT",
      pending: false
    },
    {
      label: "Shipping",
      amount: "SHIPPING AMOUNT",
      pending: true
    },
    {
      label: "Tax",
      amount: "TAX AMOUNT",
      pending: false
    }
  ],
  shippingOptions: [
    {
      id: "1",
      label: "SHIPPING LABEL",
      amount: "SHIPPING COST"
    }
  ]
}
    

{
 total: {
   label: "MERCHANT NAME",
   amount: "TOTAL AMOUNT",
   pending: false
 },
 lineItems: [
   {
     label: "Subtotal",
     amount: "SUBTOTAL AMOUNT",
     pending: false
   },
   {
     label: "Tax",
     amount: "TAX AMOUNT",
     pending: false
   }
 ],
 shippingOptions: [
   {
     id: "1",
     label: "SHIPPING LABEL",
     amount: "SHIPPING COST"
   }
 ]
}