PMT Library

Payment Method Tokenization JavaScript library helps you collect payments and vault cards or bank accounts on your site while reducing PCI burden.

Overview

Payment Method Tokenization allows you to accept credit card or bank account payments on your website while limiting your PCI compliance burden. It achieves this by transmitting payment information directly from the payer's web browser to PaySimple servers without ever passing through your servers.

Payment data such as card number, expiration date and CVV will all be associated with a one-time use (nonce) payment_method_token. The payment_method_token can be submitted via a Payments API to create a new sale transaction, or to vault the card or bank account for use making future payments. The token is valid for 15 minutes from creation.

PMT supports key-entered cards, swiped cards via the IdTech encrypted swiper, and bank accounts. To switch between the entry modes, trigger the setMode event.

Initialization

The following is the minimum amount of code to be able to use PMT:

<html>
  <head>
    <meta charset="utf-8" />
    <title>Payment Method Tokenization</title>
	<!-- change url to https://api.paysimple.com/pmt/v1/host/host.js for the production environment -->
    <script src="https://sandbox-api.paysimple.com/pmt/v1/host/host.js"></script>
  </head>

  <body>
    <div id="pmt" style="background: #f9f9fb"></div>

    <script>
      var pmt = window.paymentMethodTokenization({
        container: document.querySelector('#pmt'),
        merchantKey: '<YOUR MERCHANT KEY>',
      });

      pmt.trigger.setMode('cc-input');

      pmt.on('add-payment-method-succeeded', function(message) {
         // Logic to post to your server, which will then post to PaySimple
         // to make a payment or vault the card goes here.
      });

      pmt.on('add-payment-method-failed', function(message) {
          // Logic to display error message goes here
      });
    </script>
  </body>
</html>

Initialization Properties

PropertyTypeDescription
containerHTML ElementRequired The HTML element that the PMT iframe will be attached to
merchantKeystringRequired Identifies you with PaySimple, not a secret. Can be retrieved via Get Merchant. Also returned in merchant_activated_for_payment_type webhook
showPlaceholdersbooleanIndicates whether to show the placeholders in the inputs (default: true)
acceptInternationalPostalCodesbooleanIndicates whether to accept international postal codes
singleColumnLayoutBreakpointnumberIndicates a custom breakpoint (in pixels) for form column layout (default: 768)
stylesStyles objectAllows you to customize the look and feel of PMT
localizationLocalization objectAllows you to customize the labels, placeholders and validation messages

Styles Object

The Styles object allows you to customize the look and feel of PMT.

Any valid CSS property is allowed. CSS properties can be in kebab-case (must be wrapped in quotation marks) or camelCase.

{
  // Allows you to style the iframe's <body> element
  body: {
    backgroundColor: '#c0c0c0',
    // 'background-color': '#c0c0c0', This is alwo valid

    // Allows you to style the :hover pseudo style
    ':hover': {
      'marginTop': '30px',
      'margin-bottom': '30px',
    },
  },

  // Wraps each label/field/validation message
  container: {
    // Default styles that every container will get
    default: {
      'margin-bottom': '15px',
      'width': '100%',

      // Allows you to style the :hover pseudo style
      ':hover': {
        'margin-bottom': '30px',
      }
    },

    // Extends the default styles for the cardNumber container
    cardNumber: {
      'color': 'gray',
    },

    // Other containers:
    // for Credit Card: cardholderName, expiration, cvv, postalCode
    // for ACH: accountHolder, routingNumber, accountNumber, accountType, companyName
  },

  // Styles the labels
  label: {
    // Default styles that every label will get
    default: {
      'color': '#8f8f8f',
      'margin-bottom': '5px',

      // Allows you to style the :hover pseudo style
      ':hover': {
        color: '#cccccc',
        cursor: 'pointer',
      },
    },

    // Extends the default styles for the cardNumber label
    cardNumber: {
      color: '#0f0',
    },

    // Other labels:
    // for Credit Card: cardholderName, expiration, cvv, postalCode
    // for ACH: accountHolder, routingNumber, accountNumber, accountType, companyName
  },

  // Styles the inputs
  input: {
    // Default styles that every input will get
    default: {
      'border': '1px solid #ccc',
      'color': '#000',
      'background': '#fff',
      'padding': '5px',

      // Allows you to style the :focus pseudo style
      ':focus': {
        background: '#cccccc',
      },

      // Allows you to style the :hover pseudo style
      ':hover': {
        background: '#cccccc',
      },

      // Allows you to style the :placeholder pseudo style
      ':placeholder': {
        color: '#000',
      },
    },

    // Labels:
    // for Credit Card: cardholderName, cardNumber, expiration, cvv, postalCode
    // for ACH: accountHolder, routingNumber, accountNumber, companyName
  },

  // Styles the select fields
  select: {
    // Default styles that every select field will get
    default: {
      'border': '1px solid #ccc',
      'color': '#000',
      'background': '#fff',
      'padding': '5px',

      // Allows you to style the :focus pseudo style
      ':focus': {
        background: '#cccccc',
      },

      // Allows you to style the :hover pseudo style
      ':hover': {
        background: '#cccccc',
      },

      // Allows you to style the :placeholder pseudo style
      ':placeholder': {
        color: '#000',
      },
    },

    // Labels:
    // for Credit Card: none
    // for ACH: accountType
  },

  // Styles the validation messages
  validation: {
    // Default styles that every validation message will get
    default: {
      'background': '#f2dede',
      'color': '#b94a48',
    },

    // Validation messages:
    // for Credit Card: cardholderName, cardNumber, expiration, cvv, postalCode
    // for ACH: accountHolder, routingNumber, accountNumber, accountType, companyName
  },
}

Localization Object

The Localization object allows you to customize the labels, placeholders and validation messages.

{
  label: {
    cardholderName: 'Cardholder Name CUSTOM',
    cardNumber: 'Credit Card CUSTOM',
    expiration: 'Expiration CUSTOM',
    cvv: 'Security Code CUSTOM',
    postalCode: 'Zip/Postal Code CUSTOM',
    routingNumber: 'Routing Number CUSTOM',
    accountNumber: 'Account Number CUSTOM',
    accountHolder: 'Account Holder CUSTOM',
    accountType: 'Account Type CUSTOM',
    companyName: 'Company Name CUSTOM',
  },

  placeholder: {
    cardholderName: 'Cardholder Name CUSTOM',
    cardNumber: 'Key enter credit card CUSTOM',
    expiration: 'mm/yy CUSTOM',
    cvv: 'CVV CUSTOM',
    postalCode: '12345 CUSTOM',
    routingNumber: 'Enter routing number CUSTOM',
    accountNumber: 'Enter account number CUSTOM',
    accountHolder: 'Enter account holder CUSTOM',
    companyName: 'Enter company name CUSTOM',
    // note: no placeholder for accountType
  },

  validation: {
    invalidCardholderName: 'Cardholder Name is invalid CUSTOM',
    invalidCardNumber: 'Credit Card is an invalid card number CUSTOM',
    invalidCardType: 'Credit Card is an invalid card type CUSTOM',
    invalidExpiration: 'Expiration is invalid CUSTOM',
    invalidCvv: 'Security Code is invalid CUSTOM',
    invalidPostalCode: 'Zip/Postal Code is invalid CUSTOM',
    invalidRoutingNumber: 'Routing Number is invalid CUSTOM',
    invalidAccountNumber: 'Account Number is invalid CUSTOM',
    invalidAccountHolder: 'Account Holder is invalid CUSTOM',
    invalidAccountType: 'Account Type is invalid CUSTOM',
    invalidCompanyName: 'Company Name is invalid CUSTOM',
    required: {
      default: 'Field is required CUSTOM',
      cardholderName: 'Cardholder Name is required CUSTOM',
      cardNumber: 'Credit Card is required CUSTOM',
      expiration: 'Expiration is required CUSTOM',
      cvv: 'Security Code is required CUSTOM',
      postalCode: 'Zip/Postal Code is required CUSTOM',
      routingNumber: 'Routing Number is required CUSTOM',
      accountNumber: 'Account Number is required CUSTOM',
      accountHolder: 'Account Holder is required CUSTOM',
      accountType: 'Account Type is required CUSTOM',
      companyName: 'Company Name is required CUSTOM',
    },
  },
},

Destroy

The PMT object can be destroyed at runtime using the destroy() function exposed on the object the window.paymentMethodTokenization(...) call returns. A contrived example of using this function is found below:

var pmt = window.paymentMethodTokenization({
    container: document.querySelector('#pmt'),
    merchantKey: '<YOUR MERCHANT KEY>',
});

pmt.destroy();

Calling destroy() removes the DOM element and other resources created when PMT is initialized. A call to window.paymentMethodTokenization(...) will create a new PMT object to be used after the previous one has been destroyed. It's up to the developer implementing the PMT integration to manage PMT objects created and destroyed at runtime in this way.

Events

Triggering Events

Events are triggered via:

pmt.trigger.EVENT_NAME();

The following events can be triggered:

Event NameInputDescription
setMode(mode)stringChanges the PMT mode (valid modes: 'cc-input', 'cc-swiper', 'ach-input', 'klarna-input')
submitForm()Submits the form
setFormToSubmitted()Set form to submitted, meaning validation messages will be displayed
resetForm()Resets the form

Handling Events

Events are handled via:

pmt.on('EVENT NAME', function(message) {
  // Logic goes here
});

The following events can be handled:

Event NameMessage TypeDescription
add-payment-method-succeededAddPaymentMethodSucceededMessageTriggered when a payment method has been added successfully
add-payment-method-failedAddPaymentMethodFailedMessageTriggered when adding a payment method has failed
validity-changedValidityChangedMessageTriggered when the validity of the form has changed (useful when you want to disable your submit button until the form is valid)

AddPaymentMethodSucceededMessage

{
  paymentMethodToken: string,
  expiresAt: string,
  cardholderName: string,
  accountHolder: string,
  companyName: string,
}

AddPaymentMethodFailedMessage

{
  statusCode: number,
  message: string,
  error: object,
}

ValidityChangedMessage

{
  valid: boolean,
}