Tokenization JS Library

The Pungle JS library can be used to tokenize payment card details directly on the client.

To use the library, include the script into the webpage that will handle the credit card form.

Current Versions of the library for each environment are found below. Links for older version can be found at the bottom of this page.

Staging/Integration

<script src="https://js.staging.pungle.co/resources/v1.1.0/index.js"></script>

Production

<script src="https://js.pungle.io/resources/v1.1.0/index.js"></script>

The script will create a global `Pungle` object.
You can then create an instance of the `Pungle` object using your public api key

const pungle = Pungle('<public api key>')

Tokenize

You can use create tokens in the following way

pungle.createToken(cardData)
.then(result => {
// Now you can handle the result
})

The createToken function accepts a single object as a parameter. This object contains all of the payment card details.

{
  card: {
    name: "John Smith",
    number: "4895070000003551",
    brand: "visa", 
    address_line1: "900 Metro Center Blv",
    address_country: "CAN",
    address_city: "Toronto",
    address_state: "ON",
    address_postal_code: "94404",
    expiry_month: "10",
    expiry_year: "2020",
    cvv: "022"
  }
}

All fields are required and are of type string.

FieldDescription
nameCardholder Name (3-25 Characters)
numberCard Number (13-19 Digits)
brandCurrently only 'visa'
address_line1Billing Address line 1
address_countryBilling Address Country (3 Digit ISO Code)
address_postal_codeBilling Address postal code
address_cityBilling Address City
address_stateBilling Address State/Province/Region (2 Character)
expiry_monthExpiry Month - 2 digits
expiry_yearExpiry Year - 4 digits
cvvCVV Value - 3 or 4 digits

This function returns a promise that will return an object with either a data or an error key

If the tokenization process is successful then the result object will contain a data key with a token

result.data = { token:"abc123"}

The full response body is the same as what is returned in the API Tokenization Endpoint. You an then decide based on the values returned if you would like allow transactions for this card.

If the tokenization process is NOT successful then the result object will contain a error field with the following format.

result.error = {
  message: "Invalid Card Number provided",
  code: "invalid_card_number",
  type: "validation_error",
  status_code: null
}

Error Types

There error type field will contain the following values

Error TypeDescription
validation_errorA value in the payload is formatted incorrectly and has failed a client side validation. No network request was made. Corresponding Error Codes and Messages can be found in the table below
http_errorA Tokenization request was sent to the Pungle API and the card was not tokenized successfully. Please refer to the Pungle API Documentation for Error Codes and Messages

Status Code

The value in the status_code key depends on the error_type value. The table below details what will be contained in the status code field for each error_type

Error TypeStatus Code ValueInfo
validation_errornullThis is null since no network request was made
http_errorhttp status code from network request ( ex: 400)This will contain the status code returned in the network request

Validation Error Codes

The tokenization library will validate each field in the request and return various validation errors for incorrect fields.

Error CodeMessage Description
invalid_nameInvalid Cardholder Name
invalid_card_numberInvalid Card Number
invalid_card_brandInvalid Card Brand
invalid_expiry_monthInvalid Expiry Month
invalid_expiry_yearInvalid Expiry Year
invalid_cvvInvalid CVV Value
invalid_addressInvalid Address Values Provided
invalid_address_cityInvalid City Provided
invalid_address_stateInvalid State Provided
invalid_address_countryInvalid Country Provided
invalid_postal_codeInvalid Postal Code Provided
invalid_financial_account_detailsIncorrect values provided when creating a token for a financial account (Error Returned by Server)

Using the Pungle JS Library

This library is meant to be used in a client side application to tokenize a payment card.

For Example you may have a payment form in you web application that accepts the card details

<form action="/tokenize" method="post" id="payment-card-form">
  <div>
    <label for="cc-name">Cardholder Name</label>
    <input type="text" name="cc-name">
 
    <label for="cc-number">Card Number</label>
    <input type="text" name="cc-number">
 
    <label for="address-line1">Address Line 1</label>
    <input type="text" name="address-line1">
 
    <label for="country">Country</label>
    <input type="text" name="country">
 
    <label for="city">City</label>
    <input type="text" name="city">
 
    <label for="state">State</label>
    <input type="text" name="state">
 
    <label for="postal-code">Postal Code</label>
    <input type="text" name="postal-code">
 
    <label for="cc-exp-month">Expiry Month</label>
    <input type="text" name="cc-exp-month">
 
    <label for="cc-exp-year">Expiry Year</label>
    <input type="text" name="cc-exp-year">
 
    <label for="cc-csc">CVV</label>
    <input type="text" name="cc-csc">
 
  </div>
 
  <input type="submit" value="Submit">
</form>

You can then attach the following JavaScript code to capture the payment details and pass them to the
createToken function

// Create submit handler on form
var form = document.getElementById('payment-card-form');
 
form.addEventListener('submit', (e) => {
e.preventDefault();
// Retrieve values from form
const payload = {
  card: {
    name: document.querySelector("input[name='cc-name']").value,
    brand: "visa",
    number: document.querySelector("input[name='cc-number']").value,
    address_line1: document.querySelector("input[name='address-line1']").value,
    address_country: document.querySelector("input[name='country']").value,
    address_city: document.querySelector("input[name='city']").value,
    address_state: document.querySelector("input[name='state']").value,
    address_postal_code: document.querySelector("input[name='postal-code']").value,
    expiry_month: document.querySelector("input[name='cc-exp-month']").value,
    expiry_year: document.querySelector("input[name='cc-exp-year']").value,
    cvv: document.querySelector("input[name='cc-csc']").value
  }
}
 
// Create Token using card details
pungle.createToken(payload)
  .then(result => {
    if (result.error) {
      // Handle the error response here
      const errorMessage = result.error.message
    } else {
      // A token has been created
      const token = result.data.token
    }
  })
})

Past Versions

Links to past releases for each environment

Staging/Integration

Release #Release DateLink
1.0.0Jan 1, 2019https://js.staging.pungle.co/resources/v1/index.js

Production

📘

Related pages:

Test Cards
Visa Best Practices Guide for Response Codes
DirectSend User Guide