Card Collect

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

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:

Property	Description
onStageChanged	This 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: {your_api_key}' \
 --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

Property	Required	Description
`name`	Yes	Field identifier
`type`	Yes	`text`, `card-number`, `card-expiration-date`, `card-security-code`
`validations`	No	Array of validation rules
`css`	No	Style object with CSS properties
`classes`	No	CSS class mapping for states: `dirty`, `empty`, `focused`, `valid`, `invalid`, `touched`
`serializers`	No	Data transformation rules applied before submission
`showCardIcon`	No	Display the detected card brand icon
`yearLength`	No	For expiry fields: `'2'` or `'4'`

Supported validations

Rule	Description
`required`	Field must not be empty
`validCardNumber`	Luhn algorithm check
`validCardExpirationDate`	Validates date format and future date
`validCardSecurityCode`	CVV/CVC validation
Custom RegExp	Pass 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:

Serializer	Description
`replace`	Find-and-replace on the field value
`separate`	Split value at a delimiter
`toBase64`	Base64-encode the field value

Embed Paybyrd

E-commerce

Point of Sale

Overview

Installation

Quick Start

Adding fields

Mandatory fields

Field properties

Supported validations

Styling

Submitting

Response

Using the token in a payment

Supported card brands

Advanced: Smart CVC

Advanced: Data serializers

​Overview

​Installation

​Quick Start

​Adding fields

​Mandatory fields

​Field properties

​Supported validations

​Styling

​Submitting

​Response

​Using the token in a payment

​Supported card brands

​Advanced: Smart CVC

​Advanced: Data serializers

Overview

Installation

Quick Start

Adding fields

Mandatory fields

Field properties

Supported validations

Styling

Submitting

Response

Using the token in a payment

Supported card brands

Advanced: Smart CVC

Advanced: Data serializers