> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paybyrd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
npm install @paybyrd/card-collect
```

or

```bash theme={null}
yarn add @paybyrd/card-collect
```

Then import the module into your project:

```javascript theme={null}
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.

```javascript theme={null}
const form = await CardCollect({ options });
```

or for web

```javascript theme={null}
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.

```javascript theme={null}
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.

```json theme={null}
{
 "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:

```bash theme={null}
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"
 }
}'
```

```json theme={null}
{
 "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

```javascript theme={null}
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

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

## Submitting

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

### Response

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```javascript theme={null}
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       |