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, visit the Card Collect GitHub repository, 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 });

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'`
`autoComplete`	No	Controls how the browser autofills the field. Common values: `cc-name`, `cc-number`, `cc-exp`
`placeholder`	No	Text displayed when the field is empty
`autoFocus`	No	Automatically focuses the field when the page loads
`disabled`	No	Disables the field
`readOnly`	No	Makes the field read-only
`ariaLabel`	No	Overrides the field’s default `aria-label` for accessibility
`icons`	No	For `card-number`/`card-security-code`. Overrides default icons with a Data URL (raw HTTP(S) URLs aren’t supported for security reasons). Keys: `cardPlaceholder`, `cvvFront`, `cvvBack`, or a brand key (`visa`, `amex`, `maestro`, etc.)
`addCardBrands`	No	For `card-number`. Extends the supported card brand list or redefines an existing brand’s pattern
`hideValue`	No	For `card-number`/`card-security-code`. Boolean — hides the entered value to prevent shoulder surfing
`separator`	No	For `card-expiration-date`. Separator between month and year. Default: `" / "`

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

Each validation rule produces a specific error message when it fails:

Rule	Error message
`required`	`is required`
`validCardExpirationDate`	`is not a valid expiration date`
`validCardNumber`	`is not a valid card number`
`validCardSecurityCode`	`is not a valid security code`
Custom RegExp	`the value doesn't match a pattern`

Styling

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

The container element receives one of these classes depending on field state:

& .invalid — the field has an invalid value
& .valid — the field has a valid value
& .empty — the field has no value
& .dirty — the user has changed the field’s value
& .touched — the field has been focused and blurred at least once

Media queries in css are calculated against the iframe’s width, not the parent window’s.

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

Card brand	`cardType`
Visa	`visa`
Visa Electron	`visaelectron`
Maestro	`maestro`
Mastercard	`mastercard`
Amex	`amex`
Discover	`discover`
Dankort	`dankort`
Diners Club	`dinersclub`
JCB	`jcb`
UnionPay	`unionpay`
Forbrugsforeningen	`forbrugsforeningen`
Elo	`elo`
Hipercard	`hipercard`

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