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
Production
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.
| Field | Description |
|---|---|
| name | Cardholder Name (3-25 Characters) |
| number | Card Number (13-19 Digits) |
| brand | Currently only 'visa' |
| address_line1 | Billing Address line 1 |
| address_country | Billing Address Country (3 Digit ISO Code) |
| address_postal_code | Billing Address postal code |
| address_city | Billing Address City |
| address_state | Billing Address State/Province/Region (2 Character) |
| expiry_month | Expiry Month - 2 digits |
| expiry_year | Expiry Year - 4 digits |
| cvv | CVV 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 can 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 Type | Description |
|---|---|
| validation_error | A 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_error | A 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 Type | Status Code Value | Info |
|---|---|---|
| validation_error | null | This is null since no network request was made |
| http_error | http 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 Code | Message Description |
|---|---|
| invalid_name | Invalid Cardholder Name |
| invalid_card_number | Invalid Card Number |
| invalid_card_brand | Invalid Card Brand |
| invalid_expiry_month | Invalid Expiry Month |
| invalid_expiry_year | Invalid Expiry Year |
| invalid_cvv | Invalid CVV Value |
| invalid_address | Invalid Address Values Provided |
| invalid_address_city | Invalid City Provided |
| invalid_address_state | Invalid State Provided |
| invalid_address_country | Invalid Country Provided |
| invalid_postal_code | Invalid Postal Code Provided |
| invalid_financial_account_details | Incorrect 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 Date | Link |
|---|---|---|
| 1.0.0 | Jan 1, 2019 | https://js.staging.pungle.co/resources/v1/index.js |
Production
Related pages:
Test Cards
Visa Best Practices Guide for Response Codes
DirectSend User Guide