Collect Cards

When building an e-commerce application or subscription service, or enabling one-time purchases, one of the critical requirements is collecting and storing cardholder data securely. However, it can be challenging to navigate the complex regulatory landscape, particularly PCI DSS, and ensure that your application meets all the necessary security standards.

In this guide, we will set up SDKs to capture cards in the frontend, Web or Mobile, and securely store the cardholder data as tokens with the Basis Theory Platform. This will completely remove our user-facing applications and database from the compliance scope.

Getting Started

To get started, you will need a Basis Theory account and a Tenant.

Sign Up

Sign In

Creating a Public Application

Next you will need you'll need a Public Application using our PCI-compliant template Collect PCI Data. Click here to create one.

This will create an application with the following Access Controls:

• Permissions: token:create, token:update
• Containers: /pci/
• Transform: mask

Save the API Key from the created Public Application as it will be used later in this guide.

Configuring Basis Theory Elements

Basis Theory Elements is available for the following technologies. Click below for detailed instructions on how to install and configure it.

Javascript

React

iOS

Android

Adding Card Elements

Once properly installed and configured, add the Card Elements to your application. This will enable users to type in their card data in your form, while refraining from your systems to come in contact with it.

JavaScript

index.html

<div id="cardNumber"></div>
<div style="display: flex;">
  <div id="cardExpirationDate" style="width: 100%;"></div>
  <div id="cardVerificationCode" style="width: 100%;"></div>
</div>

index.js

import { BasisTheory } from '@basis-theory/basis-theory-js';

let bt;
let cardNumberElement;
let cardExpirationDateElement;
let cardVerificationCodeElement;

async function init() {
  bt = await new BasisTheory().init('test_1234567890', { elements: true });

  // Creates Elements instances
  cardNumberElement = bt.createElement('cardNumber', {
    targetId: 'myCardNumber' // (custom) used for tracking validation errors
  });
  cardExpirationDateElement = bt.createElement('cardExpirationDate', {
    targetId: 'myCardExpiration'
  });
  cardVerificationCodeElement = bt.createElement('cardVerificationCode', {
    targetId: 'myCardVerification'
  });

  // Mounts Elements in the DOM in parallel
  await Promise.all([
    cardNumberElement.mount('#cardNumber'),
    cardExpirationDateElement.mount('#cardExpirationDate'),
    cardVerificationCodeElement.mount('#cardVerificationCode'),
  ]);

  // Binds card brand to verification code element
  cardNumberElement.on('change', ({ cardBrand }) => {
    cardVerificationCodeElement.update({ cardBrand });
  });
}

init();

React

App.jsx

import React, { useRef, useState } from 'react';
import {
  BasisTheoryProvider,
  CardNumberElement,
  CardExpirationDateElement,
  CardVerificationCodeElement,
  useBasisTheory,
} from '@basis-theory/basis-theory-react';

export default function App() {
  const { bt } = useBasisTheory('test_1234567890', { elements: true });
  // Refs to get access to the Elements instance
  const cardNumberRef = useRef(null);
  const cardExpirationRef = useRef(null);
  const cardVerificationRef = useRef(null);

  // stores the current card brand in state, to pass to CardVerificationCodeElement
  const [cardBrand, setCardBrand] = useState();

  return (
    <BasisTheoryProvider bt={bt}>
      <CardNumberElement
        id="myCardNumber"
        ref={cardNumberRef}
        onChange={({ cardBrand }) => setCardBrand(cardBrand)}
      />
      <div style={{ display: 'flex' }}>
        <div style={{ width: "100%" }}>
          <CardExpirationDateElement
            id="myCardExpiration"
            ref={cardExpirationRef}
          />
        </div>
        <div style={{ width: "100%" }}>
          <CardVerificationCodeElement
            id="myCardVerification"
            ref={cardVerificationRef}
            cardBrand={cardBrand}
          />
        </div>
      </div>
    </BasisTheoryProvider>
  );
}

iOS

ViewController.swift

import Foundation
import UIKit
import BasisTheoryElements
import Combine

class ViewController: UIViewController {
    @IBOutlet weak var cardNumberTextField: CardNumberUITextField!
    @IBOutlet weak var expirationDateTextField: CardExpirationDateUITextField!
    @IBOutlet weak var cvcTextField: CardVerificationCodeUITextField!

    override func viewDidLoad() {
        super.viewDidLoad()

        // Binds card brand to verification code element
        let cvcOptions = CardVerificationCodeOptions(cardNumberUITextField: cardNumberTextField)
        cvcTextField.setConfig(options: cvcOptions)
    }
}

Android

activity_main.xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <LinearLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_margin="20dp"
        android:orientation="vertical"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent">

        <com.basistheory.android.view.CardNumberElement
            android:id="@+id/card_number"
            android:layout_width="match_parent"
            android:layout_height="wrap_content" />
        <com.basistheory.android.view.CardExpirationDateElement
            android:id="@+id/expiration_date"
            android:layout_width="match_parent"
            android:layout_height="wrap_content" />
        <com.basistheory.android.view.CardVerificationCodeElement
            android:id="@+id/cvc"
            android:layout_width="match_parent"
            android:layout_height="wrap_content" />
    </LinearLayout>

</androidx.constraintlayout.widget.ConstraintLayout>

MainActivity.kt

class MainActivity : AppCompatActivity() {

    private lateinit var cardNumberElement: CardNumberElement
    private lateinit var cardExpirationDateElement: CardExpirationDateElement
    private lateinit var cardVerificationCodeElement: CardVerificationCodeElement

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        cardNumberElement = findViewById(R.id.card_number)
        cardExpirationDateElement = findViewById(R.id.expiration_date)
        cardVerificationCodeElement = findViewById(R.id.cvc)

        // Binds card brand to verification code element
        cardVerificationCodeElement.cardNumberElement = cardNumberElement
    }
}

Using a single Card Element

Alternatively, you can declare a single Card Element that features all three basic cardholder data inputs in a single element.

JavaScript

index.html

<div id="card"></div>

index.js

import { BasisTheory } from '@basis-theory/basis-theory-js';

let bt;
let cardElement;

async function init () {
  bt = await new BasisTheory().init('test_1234567890', { elements: true });
  cardElement = bt.createElement('card');
  await cardElement.mount('#card');
};

init();

React

App.jsx

import React, { useRef } from 'react';
import {
  BasisTheoryProvider,
  CardElement,
  useBasisTheory,
} from '@basis-theory/basis-theory-react';

export default function App() {
  const { bt } = useBasisTheory('test_1234567890', { elements: true });
  // Ref to get access to the Element instance
  const cardRef = useRef(null);

  return (
    <BasisTheoryProvider bt={bt}>
      <CardElement
        id="myCard"
        ref={cardRef}
      />
    </BasisTheoryProvider>
  );
}

iOS

CardElement is not yet available for iOS. If you need this feature, please let us know.

https://basistheory.com/contact

Android

CardElement is not yet available for Android. If you need this feature, please let us know.

https://basistheory.com/contact

Storing Cards

Now that you are securely capturing the cardholder data in your user-facing application(s), it is time to store it in your Basis Theory Tenant.

To do this, we will call the Create Token endpoint from the SDK, passing the Card Elements as data points in the payload. This way, the card information is securely transferred from the frontend Elements to the Basis Theory vault, where they will reside in the encrypted form.

Add a submit function along with a button to trigger it:

JavaScript

index.html

<div id="cardNumber"></div>
<div style="display: flex;">
  <div id="cardExpirationDate" style="width: 100%;"></div>
  <div id="cardVerificationCode" style="width: 100%;"></div>
</div>
<button onclick="submit();">Submit</button>

index.js

import { BasisTheory } from '@basis-theory/basis-theory-js';

let bt;
let cardNumberElement;
let cardExpirationDateElement;
let cardVerificationCodeElement;

async function init () { ... }

async function submit () {
  try {
    const token = await bt.tokens.create({
      type: 'card',
      data: {
        number: cardNumberElement,
        expiration_month: cardExpirationDateElement.month(),
        expiration_year: cardExpirationDateElement.year(),
        cvc: cardVerificationCodeElement,
      }
    });
    // store token.id in your database
  } catch (error) {
    console.error(error);
  }
}

init();

React

App.jsx

import React, { useRef, useState } from 'react';
import {
  BasisTheoryProvider,
  CardNumberElement,
  CardExpirationDateElement,
  CardVerificationCodeElement,
  useBasisTheory,
} from '@basis-theory/basis-theory-react';

export default function App() {
  const { bt } = useBasisTheory('test_1234567890', { elements: true });
  // Refs to get access to the Elements instance
  const cardNumberRef = useRef(null);
  const cardExpirationRef = useRef(null);
  const cardVerificationRef = useRef(null);
  // stores the current card brand in state, to pass to CardVerificationCodeElement
  const [cardBrand, setCardBrand] = useState();

  const submit = async () => {
    try {
      const token = await bt.tokens.create({
        type: 'card',
        data: {
          number: cardNumberRef.current,
          expiration_month: cardExpirationRef.month(),
          expiration_year: cardExpirationRef.year(),
          cvc: cardVerificationRef.current,
        }
      });
      // store token.id in your database
    } catch (error) {
      console.error(error);
    }
  }

  return (
    <BasisTheoryProvider bt={bt}>
      ...
      <button onClick={submit}>Submit</button>
    </BasisTheoryProvider>
  );
}

iOS

ViewController.swift

import Foundation
import UIKit
import BasisTheoryElements
import Combine

class ViewController: UIViewController {
    @IBOutlet weak var cardNumberTextField: CardNumberUITextField!
    @IBOutlet weak var expirationDateTextField: CardExpirationDateUITextField!
    @IBOutlet weak var cvcTextField: CardVerificationCodeUITextField!

      @IBAction func tokenize(_ sender: Any) {
        let body: [String: Any] = [
            "type": "card",
            "data": [
                "number": self.cardNumberTextField,
                "expiration_month": self.expirationDateTextField.month(),
                "expiration_year": self.expirationDateTextField.year(),
                "cvc": self.cvcTextField
            ]
        ]

        BasisTheoryElements.tokenize(body: body, apiKey: config.btApiKey!) { token, error in
            guard error == nil else {
                print(error)
                return
            }
            // store token.id in your database
        }
    }

    override func viewDidLoad() { ... }

}

Android

activity_main.xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <LinearLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_margin="20dp"
        android:orientation="vertical"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent">

        ...

        <Button
            android:id="@+id/submit_button"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:layout_marginTop="20dp"
            android:backgroundTint="#00A4BA"
            android:text="Submit" />
    </LinearLayout>

</androidx.constraintlayout.widget.ConstraintLayout>

MainActivity.kt

class MainActivity : AppCompatActivity() {

    private lateinit var cardNumberElement: CardNumberElement
    private lateinit var cardExpirationDateElement: CardExpirationDateElement
    private lateinit var cardVerificationCodeElement: CardVerificationCodeElement
    private lateinit var button: Button;

    private val bt = BasisTheoryElements.builder()
        .apiKey("test_1234567890")
        .build()


    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        cardNumberElement = findViewById(R.id.card_number)
        cardExpirationDateElement = findViewById(R.id.expiration_date)
        cardVerificationCodeElement = findViewById(R.id.cvc)
        button = findViewById(R.id.submit_button)
        button.setOnClickListener {
            submit()
        }

        // Binds card brand to verification code element
        cardVerificationCodeElement.cardNumberElement = cardNumberElement
    }

    private fun submit() {
      val token = runBlocking {
        bt.tokens.create(object {
          val type = "card"
          val data = object {
            val number = cardNumberElement
            val expiration_month = cardExpirationDateElement.month()
            val expiration_year = cardExpirationDateElement.year()
            val cvc = cardVerificationCodeElement
          }
        })
      }
      // store token.id in your database
    }
}

Customizing the Card Token

Deduplication

Aliasing

Masking

Conclusion

By following the best practices prescribed in this guide, you can ensure that your user-facing applications are compliant with the latest security standards while protecting your users' sensitive data. The token.id obtained at the end of the Storing Cards section is a synthetic replacement for the sensitive data and can be safely stored in your database, meeting compliance requirements and reducing the risk of exposure in case of data breaches.

TODO: add next steps