Using the Secure Fields Form

API Reference

For an overview of all methods supported by the Secure Fields Form, see the Secure Fields Form Reference.

The Secure Fields Form is an HTML form that you can include in your site to collect a user’s card information. When using this option, PaymentsOS generates the card details input fields and handles the logic of grabbing the card information submitted by the user. This option further reduces your PCI scope compared to the JavaScript API, requiring you to be SAQ A compliant.

You can style the form as you desire. Here’s an example:

When card information is submitted through the Secure Fields Form, PaymentsOS returns a token representation of the card to your site. If you added additional fields to the form, then these fields are included in the token representation of the card as well. You must use the token when accepting payments.

Note

There are a few details you should be aware of when it comes to tokenization. What you should know about tokenization.

Embedding the Secure Fields Form in your Site

To get started, include the Secure Fields Javascript SDK in your checkout page. You can find the SDK at https://js.paymentsos.com/v2/latest/secure-fields.min.js. Also provide your public key to authenticate yourself by calling POS.setPublicKey().

<body>
  <script language="JavaScript" type="text/javascript" src="https://js.paymentsos.com/v2/latest/secure-fields.min.js"></script>
  <script>POS.setPublicKey("99346d84-5186-4221-9c16-dc51a8de27fb");
  </script>
  ...
</body>

Now embed the Secure Fields form and set your environment (either "test" or "live") by calling POS.setEnvironment(). Then display the form's fields by calling POS.initSecureFields(). As a last step, attach a click event to the form that is invoked when the form is submitted. Pass the event a function that will send the card information to PaymentsOS, tokenize the information and return the token to your site.

<body>
  ...
  <!-- Embed the form after loading the Secure Fields Javascript SDK and setting your public key -->
  <form id="payment-form">
    <input type="text" id="cardholder-name" placeholder="John Doe" />
    <div id="card-secure-fields">
      <!-- The payment form will be displayed here -->
    </div>
    <button type=”submit”>Pay</button>
  </form>

  <!-- After embedding the form, set your environment, initialize the form's fields
   and send the data to PaymentsOS when the form is submitted -->
  <script>

    // Set your environment. Values are either "test" or "live".
    // If omitted, the test environment will be used.
    POS.setEnvironment("test");

    // Initialize the form's fields
    POS.initSecureFields('card-secure-fields');

    // Attach a click event to the form that is invoked when the
    // form is submitted. On submit, pass the card information to
    // PaymentsOS and receive the token representing the card
    // information in your site.
    document.getElementById('payment-form').addEventListener('submit', function(event) {
      event.preventDefault();
      const additionalData = {
        holder_name: document.getElementById('cardholder-name').value // This field is mandatory
      }
      POS.createToken(additionalData, function(result) {

        // Grab the token here

      });
    });
  </script>
</body>

Note

By default, the Secure Fields Form will show input fields for the card’s number, the card’s expiration date and the card’s CVV code. You must add a field for the cardholder’s name, since this field is mandatory (the field itself is not part of the iFrame generated by PaymentsOS).

Adding Additional Fields to the Form

Depending on the provider that you are transacting against, you may need to add additional fields to the form. These fields will then be included in the token representing the customer’s card.

Note

For a list of additional fields that can be included, see the Create Token API.

To add an additional field, simply add it as an input field to the form. Then include its key and value in the additionalData object. The key must be identical to the attribute name required by the Create Token API.

Here’s an example of adding number and type fields that define a user’s identity card.

<!-- Here's our payment form-->
<form id="payment-form">
  ...
  <input type="text" id="cardholder-name" placeholder="John Doe" />

  <!-- Add the additional fields as input fields to the form -->
  <input type="text" id="idnumber" placeholder="ID Number" />
  <input type="text" id="idtype" placeholder="Passport, Driver's License" />
  <div id="card-secure-fields">
    <!-- This is where the payment form will be displayed -->
  </div>
  <button type=”submit”>Pay</button>
</form>

<script>
  // Initialize the form’s fields
  POS.initSecureFields('card-secure-fields');

  document.getElementById('payment-form').addEventListener('submit', function(event) {
        event.preventDefault();
        const additionalData = {
          holder_name: document.getElementById('cardholder-name').value,

          // Add the additional field here. In this example, we are adding
          // identity document fields. Notice that the key is identity_document and that the value
          // is of type object.
          identity_document: {
            number: document.getElementById('idnumber').value,
            type: document.getElementById('idtype').value
          }
          POS.createToken(additionalData, function(result) {

            // Grab the token here

          });
        });
</script>

Configuring Form Options

You can configure a number of options that change the form’s behavior and appearance. For example, you can disable the security code input field or disable the Luhn check for validating a card's number. You configure these options by calling the relevant method before initializing the form’s fields. Here’s an example:

<script>
...
// Disable the security number field
POS.disableSecurityNumber();
// Now initialize the fields
POS.initSecureFields('card-secure-fields');
</script>

The following table lists the options you can configure:

Option Set by calling:
Disable card formatting. This options disables auto-formatting of the credit card number into groups of digits. POS.disableCardFormatter();
Disable the card image field. This option prevents the card’s image from appearing. POS.disableCardImage();
Disable the security number (cvv, cvc etc.) field. When you set this option, the security number input field will not appear on the form. POS.disableSecurityNumber();
Disable the Luhn check for validating a card's number. POS.disableLuhnValidation();
Set the card number's input field placeholder text. Default placeholder text is "card number". POS.setCardNumberPlaceholder("Your Text");
Set the expiration date's input field placeholder text. Default placeholder text is "mm / yy". POS.setExpirationDatePlaceholder("Date Format");
Set the fields' display direction from right to left. POS.setDirectionRtl();
Set the security code's input field placeholder text. Default placeholder text is "CVV". POS.setSecurityNumberPlaceholder("security code name");

Customizing the Form's Look and Feel

Customizing the form’s look and feel is easy. Simply add a style constant in which you define the styles for the form’s input fields. Make sure to use camelCase for the style attributes (and not kebab-case, as you are accustomed to when writing css).

Note

You can only use the style constant to style the form's default fields. If you add any additional fields to the form, you will need to provide your own css to style them.

Here’s an example. Notice that the base attributes are common to all input fields. You need to call POS.setStyle() for your changes to take effect.

<script>

  // Make sure to use camelCase for the style attributes

  const style = {
    base: { // Common to all input fields
      color: 'green',
      lineHeight: '40px',
      fontWeight: 400,
      fontSize: '13px',

      // Here you can style the span element that wraps the secure fields.
      // The default values are shown below.
      secureFields: {
        position: absolute,
        top:0
      }

      // The Primary Account Number (PAN) field is always included in the form.
      // You can style it here.
      pan: {
        fontSize: '13px'
      },

      // The expirationDate field is always included in the form.
      // You can style it here.
      expirationDate: {
        color: 'blue',
        fontSize: '13px',
        // width: '70px'
      },

      // Unless you disable the cvv field, it will be included in the form.
      // You can style it here.
      cvv: {
        color: 'red',
        fontSize: '13px',
      }
    }
  };

  // Done styling? Let us know, so that we can apply your changes.
  POS.setStyle(style);

  // Make sure to initialize the fields after setting your styles
  POS.initSecureFields('card-secure-fields');
  ...
</script>

What's next?

Now that you've collected your customer's card information, proceed to accept a payment.

results matching ""

    No results matching ""