Skip to main content

Use Your Own Card Inputs

Tokenize with your inputs for flexibility and secure tokenization.

Despite Basis Theory Elements being highly customizable and providing the most secure and efficient solution for collecting cards in user-facing applications, we understand that some companies are experienced with PCI DSS and feel comfortable having their frontend, or parts of it, handle cardholder data and be in scope for such compliance.

Using custom inputs with Basis Theory is fully supported but requires SAQ D PCI compliance due to handling cardholder data. For simpler SAQ A compliance, try our Elements guide unless you need full control over your form.

In this guide, we will set up Basis Theory SDKs to receive cards from your frontend application and securely store the cardholder data as tokens with the Basis Theory Platform. This practice is well-positioned to substantially de-scope your servers, networking resources and database from PCI DSS compliance, while retaining full control of the sensitive data. If you want to learn more how Basis Theory can help you achieve that, reach out to our team!

Use your own inputs Diagram

Getting Started​

To get started, you will need to create a Basis Theory Account and a TEST Tenant.

Be sure to use your work email (e.g., john.doe@yourcompany.com)

Public Application​

You will need a Public Application to authenticate requests. Click here to create one using the Basis Theory Customer Portal.

This will create an application with the following Access Controls:

  • Permissions: token-intent:create
Save the key from the created Public Application as it will be used later in this guide.

Configure the SDK​

We will perform cardholder data tokenization by calling the Basis Theory API and passing the values from your inputs. The use of SDKs is optional, you can use your preferred HTTP Client in your frontend application.

For Javascript, React and React Native:

Node

For Android:

Java

For iOS, use your preferred HTTP client to call the Basis Theory API.

Tokenization​

We won't get into details about particular frontend libraries or custom input implementations, but show how to call the API to store cards in your Basis Theory Tenant.

To do this, we will invoke the Create Token Intent endpoint from the frontend, passing the cardholder data in the payload. This will securely create a card token intent by transferring the card information from your frontend to the Basis Theory API, where the data will be strongly encrypted and stored in a compliant environment.

Let's use a submit function to make the request, triggered from a button:

<button onclick="submit();">Submit</button>
import { BasisTheoryClient, BasisTheory } from "@basis-theory/node-sdk";

const client = new BasisTheoryClient({ apiKey: "<PUBLIC_API_KEY>", environment: BasisTheoryEnvironment.Test });

async function submit () {
try {
// get these values from your inputs
const intent = await client.tokenIntents.create({
type: "card",
data: {
number: '4242424242424242',
expiration_month: 12,
expiration_year: 2025,
cvc: '123'
},
});
// TODO post the intent object to your backend
} catch (error) {
console.error(error);
}
}

init();
Be sure to replace <API_KEY> with the Public API Key you created in the Public Application step.

The created Token Intent is a short-lived tokenized card object which carries only non-sensitive information following the Token Intent Object specification:

Token Intent sample
{
"id": "d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4",
"type": "card",
"tenant_id": "4aee08b9-5557-474b-a120-252e01fc7b0f",
"fingerprint": "BKJYqf2tcvhTHSXN7EvBJLviN3PBYRgwoJgce8VAfnSr",
"card": {
"bin": "424242",
"last4": "4242",
"expiration_month": 10,
"expiration_year": 2028,
"brand": "visa",
"funding": "credit",
"authentication": "sca_required",
"issuer_country": {
"alpha2": "GB",
"name": "UNITED KINGDOM OF GREAT BRITAIN AND NORTHERN IRELAND",
"numeric": "826"
}
},
"created_by": "0bc89db5-fadd-4d57-af93-10472e35ebd3",
"created_at": "2025-03-10T14:23:56.5580574+00:00",
"expires_at": "2025-03-11T14:23:56.5580575+00:00"
}
You can either post the complete object to your backend for processing or fetch it using its ID.

Authentication

Once the Token Intent has been created, merchants may need to authenticate the cardholder to comply with PSD2’s Strong Customer Authentication (SCA) requirements and reduce fraud. The specific authentication steps depend on the card’s region, issuer requirements, and the merchant’s risk strategy.

3D Secure

3D Secure (3DS) is the protocol used to meet SCA mandates in the EEA, the UK and other regulated markets, and to seek liability shift to the issuer. The card.authentication field on the token intent tells you whether the card's issuing country mandates authentication. It covers the issuer side only; whether your acquirer is in a regulated market is something you track per merchant account.

if (intent.card.authentication === 'sca_required') {
// trigger the 3DS authentication flow
}

Triggering 3DS explains how to combine this flag with your acquirer's jurisdiction, which exemptions you can request, and when to authenticate when nothing mandates it. The 3DS guides cover the implementation.

Next Steps​

Now that you are securely storing your users' sensitive card data with Basis Theory, the next step is to process payments using your newly tokenized card data. Check out the following guides to complete your integration: