Skip to main content
This guide explains how to integrate the Paybyrd Card Collect widget.

​
Overview

Card Collect is a JavaScript plugin that lets you process credit card payments without handling card data directly, so your integration does not require PCI compliance. The widget provides secure, customizable fields where the cardholder enters their card details. The widget converts those details into a temporary token you can use with any Paybyrd API that requires card data.

​
Installation

Install the package: 
npm install @paybyrd/card-collect
or 
yarn add @paybyrd/card-collect
Then import the module into your project: 
import CardCollect from "@paybyrd/card-collect";
For usage in the browser please visit github, download dist/cardCollect-web.js and include it in your HTML file.

​
Quick Start

Designate the HTML elements where your fields will render, then initialize the library. 
const form = await CardCollect({ options });
or for web 
const form = await cardCollect({ options });
You can pass the following options when initializing the library:
PropertyDescription
onStageChangedThis handler will be called whenever the form state changes. The only argument passed is a state object with the current status of the form fields. You can use this handler to enable/disable the submit button to prevent the user from misusing your form.
Finally, you can create fields and configure the submit handler. 
form.cardCollect_field({
 id: '#cc-number',
 type: 'card-number',
 name: 'card_number',
 placeholder: 'Card number',
 showCardIcon: true,
 validations: ['required', 'validCardNumber'],
});

const submitButton = document.getElementById("submit-button");
submitButton.onclick = handleSubmit;

function handleSubmit() {
 form.cardCollect_submit().then(({ status, response }) => {
   console.log(response);
 }).catch((error) => console.log(error));
}
You should have at least one field with the name card_number and one with card_exp. These are mandatory. The response is a JSON object that will contain the TokenId. These tokens are different from tokenization API tokens. Card Collect tokens are short-lived and are discarded after use. 
{
 "tokenId": "ecf4a873-59fd-4300-a6e6-330d267ebbb2",
 "correlationId": "5c9b4c3a-9602-4c4e-9a3d-4e4af8a3d872"
}
With the TokenId, you can call any Paybyrd API that requires card data. Inside the Card node, instead of sending the raw card data, you will send the TokenId as shown in the sample below: 
curl --request POST \
 --url https://gateway.paybyrd.com/api/v2/payment \
 --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --header 'x-api-key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B' \
 --data '
{
 "type": "Card",
 "amount": "8.15",
 "currency": "EUR",
 "orderRef": "ABC12345",
 "redirectUrl": "https://your-shop-url?orderRef=ABC12345",
 "card": {
   "tokenId": "ecf4a873-59fd-4300-a6e6-330d267ebbb2"
 }
}'

{
 "transactionId": "0e443bff-9052-4eec-a5f1-9db474f2077a",
 "type": "Card",
 "currency": "EUR",
 "orderRef": "ABC12345", 
 "brand": "VISA",
 "fingerprint": "b53b68c8-43af-4acc-bc79-e892dd6a9a38",
 "amount": "8.15",
 "isPreAuth": false,
 "redirectUrl": "https://your-shop-url?orderRef=ABC12345",
 "action": {
   "type": "redirect",
   "url": "https://link-s.paybyrd.com/3ds_Q44clBT77"
 },
 "card": {
   "number": "420000******0000",
   "expiration": "12/25",
   "cvv": "***",
   "holder": "Peter Parker"
 },
 "code": "BYRD207",
 "description": "Pending redirect"
}

​
Adding fields

form.cardCollect_field({
  id: '#cc-number',
  type: 'card-number',
  name: 'card_number',
  placeholder: 'Card number',
  showCardIcon: true,
  validations: ['required', 'validCardNumber'],
});

​
Mandatory fields

You must include at minimum:
  • card_number (type: 'card-number')
  • card_exp (type: 'card-expiration-date')

​
Field properties

PropertyRequiredDescription
nameYesField identifier
typeYestext, card-number, card-expiration-date, card-security-code
validationsNoArray of validation rules
cssNoStyle object with CSS properties
classesNoCSS class mapping for states: dirty, empty, focused, valid, invalid, touched
serializersNoData transformation rules applied before submission
showCardIconNoDisplay the detected card brand icon
yearLengthNoFor expiry fields: '2' or '4'

​
Supported validations

RuleDescription
requiredField must not be empty
validCardNumberLuhn algorithm check
validCardExpirationDateValidates date format and future date
validCardSecurityCodeCVV/CVC validation
Custom RegExpPass a regular expression for custom pattern matching

​
Styling

form.cardCollect_field({
  // ...
  css: {
    'color': '#1b1d1f',
    'border': 'solid 1px #1b1d1f',
    '&:focus': { 'border-color': '#11bef5' },
    '&.invalid.touched': { 'color': 'red' },
    '@font-face': { /* custom font */ }
  }
});

​
Submitting

form.cardCollect_submit()
  .then(({ status, response }) => {
    // response.tokenId contains the token
    console.log(response.tokenId);
  })
  .catch((error) => console.error(error));

​
Response

{
  "tokenId": "ecf4a873-59fd-4300-a6e6-330d267ebbb2",
  "correlationId": "5c9b4c3a-9602-4c4e-9a3d-4e4af8a3d872"
}

​
Using the token in a payment

Pass tokenId in place of raw card fields: 
{
  "type": "Card",
  "isoAmount": 815,
  "currency": "EUR",
  "orderRef": "ORDER-001",
  "card": {
    "tokenId": "ecf4a873-59fd-4300-a6e6-330d267ebbb2"
  }
}

​
Supported card brands

Visa, Mastercard, Amex, Maestro, Discover, Diners Club, JCB, UnionPay, Elo, and others.

​
Advanced: Smart CVC

Link the CVC field to the card number field for brand-specific CVC length validation: 
cardNumber.setCVCDependency(cvc);

​
Advanced: Data serializers

Use serializers to transform field data before submission:
SerializerDescription
replaceFind-and-replace on the field value
separateSplit value at a delimiter
toBase64Base64-encode the field value