PaymentFields Integration
Preczn PaymentFields is a client-side (browser) script which helps reduce the PCI scope of your software by eliminating the need for your server-side software to transmit or store payment account data.
The PaymentFields script binds to existing input controls on your payment form and generates a secure single-use token, which you can then safely transmit from your client-side web application to your server-side for use processing a transaction.
1. Include the client on your page
Add the secure, hosted JavaScript reference in the <head> of your page:
<script src="https://api.preczn.com/v1/clients/paymentFields.min.js"></script>
2. Define the required form and controls
Ensure the form containing your payment information input fields is assigned an id attribute:
<form id="paymentForm">
Add the following 3 payment information input fields to your form, or add the their respective data-preczn attributes to your existing input fields:
<input type="text" data-preczn="number" />
<input type="text" data-preczn="expiration" />
<input type="text" data-preczn="cvv" />
Notes
- PaymentFields form controls (with
data-precznattributes) are prohibited from havingidornameattributes in order to ensure that sensitive payment data is never posted to your servers- The
data-preczn="number"field is expected to be 12-19 numeric characters and a valid credit card number- The
data-preczn="expiration"field is expected to be 4 numeric characters inMMYYformat- The
data-preczn="cvv"field is expected to be 3-4 numeric characters
3. Define the required JavaScript callback function
Define a JavaScript callback function for token results:
var tokenCallback = function(result) {
if (result.errors)
{
// Handle errors
// result.errors is an array of strings
}
else
{
// Utilize the token here
var token = result.token;
}
}
4. Obtain a payment token
Public Key Authentication
Ensure that you're using a public API key with PaymentFields, and not exposing and potentially compromising a sensitive private API key!
Call the getToken() function with your public API key, payment form ID, and token callback method:
Preczn.PaymentFields.getToken("Your-Public-API-Key", "paymentForm", tokenCallback);
The result object received by your callback method looks like this:
{
"type": "CREDIT",
"brand": "VISA",
"bin": "432100",
"last4": "0012",
"token": "tkn_apkwm89dr8br9zvqw4b3xgktk",
}
{
"errors": [
"Missing form field: number",
"Form controls are prohibited from having ID or NAME attributes: cvv"
]
}
Check out the following Recipe for an example implementation:
PaymentFields Data Flow
- Your frontend web application requests a payment token by calling
Preczn.PaymentFields.getToken(). - The PaymentFields library securely calls the Preczn API to obtain a payment token.
- The PaymentFields library calls your self-defined callback function with the resulting payment token.
- Your frontend web application sends the payment token along with the rest of your order information to your backend server.
- Your backend service securely sends the transaction request with payment token to the Preczn API and receives the transaction result response.
- Your backend service returns the transaction result and order status to your frontend web application.
When properly implemented, your frontend and backend applications never touch any sensitive account data! 🚫 💳
Additional Helpful Functions!
- Validate Credit Card Number
The Preczn PaymentFields client provides a function to validate your credit card input field.
Call the Preczn.PaymentFields.isValidCardNumber(formId) function and provide your payment form ID, the Preczn client will find the input field with the data-preczn="number" and validate that the contents are a valid credit card number.
var isValidCard = Preczn.PaymentFields.isValidCardNumber("paymentForm");
| Return Value | Description |
|---|---|
null | - Unable to find a form control with the provided ID formId. - Unable to find an input field with data-preczn="number" attribute within the provided form. |
true | Valid card number. |
false | Invalid card number. |
- Get Card Brand
The Preczn PaymentFields client provides a function to tell you the card brand for the value in the input field with the data-preczn="number" attribute.
Call the Preczn.PaymentFields.getCardBrand(formId) function and provide your payment form ID as the formId parameter, the Preczn client will find the input field with the data-preczn="number" and return a string representing the card brand of the current field value.
var cardBrand = Preczn.PaymentFields.getCardBrand("paymentForm");
| Return Value | Description |
|---|---|
null | - Unable to find a form control with the provided ID value formId. - Unable to find an input field with data-preczn="number" attribute within the provided form. - Field content length is less than 4 numeric characters. |
VISA | Visa. |
MASTERCARD | Mastercard. |
AMEX | American Express. |
DISCOVER/JCB | Discover or JCB. |
OTHER | Other unidentified card type. |
Implementation Advice
You can add real-time card brand display to your interface by calling your own function from the card number input field's
onkeyupevent property, and from that function callingPreczn.PaymentFields.getCardBrand("paymentForm"). Use the returned value to automatically display the card brand once a minimum of 4 digits have been entered into the card number field!
<script>
function displayCardBrand() {
var cardBrand = Preczn.PaymentFields.getCardBrand('paymentForm');
if (cardBrand) {
// Display icon for card brand
} else {
// Hide card brand icons
}
}
</script>
...
<input type="text" data-preczn="number" onkeyup="displayCardBrand()" />
Use your token to process a payment
You can now use your newly acquired payment token to process a transaction from your server using the Process Transaction endpoint with a Direct API Integration!
Using with a Content Security Policy
If you are using a Content Security Policy to secure your client-side web application, you will need to extend your policy to allow paymentFields.min.js to load and connect to the Preczn API.
Please add the following directives to your content security policy:
| Directive | Value |
|---|---|
script-src | api.preczn.com |
connect-src | api.preczn.com |
Updated about 2 months ago