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

Property	Type	Description
container	HTML Element	Required The HTML element that the PMT iframe will be attached to
merchantKey	string	Required Identifies you with PaySimple, not a secret. Can be retrieved via Get Merchant. Also returned in `merchant_activated_for_payment_type` webhook
showPlaceholders	boolean	Indicates whether to show the placeholders in the inputs (default: true)
acceptInternationalPostalCodes	boolean	Indicates whether to accept international postal codes
singleColumnLayoutBreakpoint	number	Indicates a custom breakpoint (in pixels) for form column layout (default: 768)
styles	Styles object	Allows you to customize the look and feel of PMT
localization	Localization object	Allows 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 Name	Input	Description
*setMode(mode)*	string	Changes the PMT mode (valid modes: 'cc-input', 'cc-swiper', 'ach-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 Name	Message Type	Description
add-payment-method-succeeded	AddPaymentMethodSucceededMessage	Triggered when a payment method has been added successfully
add-payment-method-failed	AddPaymentMethodFailedMessage	Triggered when adding a payment method has failed
validity-changed	ValidityChangedMessage	Triggered 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,
}