Overview

PaySimpleJSv2 (PSJSv2) 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 60 minutes from creation.

PSJSv2 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 PSJSv2:

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

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

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

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

      psjs.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.
      });

      psjs.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 PSJSv2 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 PSJSv2.

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',
    },
  },
},

Events

Triggering Events

Events are triggered via:

psjs.trigger.EVENT_NAME();

The following events can be triggered:

Event Name	Input	Description
*setMode(mode)*	string	Changes the PSJSv2 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:

psjs.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,
}