Card Element

A single card input field that collects card number, expiry, and CVC in one compact element. Ideal when you want a simple card form with your own submit button and surrounding layout.

How it works

1 Create session (server)

2 Initialise SDK (client)

3 Create & mount card element

4 Submit payment

All-in-one card input field

Your own submit button and form layout

element.submitPayment() to process payment

Real-time validation and error display

Automatic 3DS challenge handling

Works with HTML/JS and React

Before getting started

1. Get merchant credentials

As a partner you take payments on behalf of the merchants you serve. Each merchant's Client ID and Client Secret are delivered to your registrationWebhook when the merchant connects Teya to your platform, along with the store_id and payment_webhook_public_key.

Use client_credentials grant to obtain access tokens

Each merchant store has its own set of credentials

Store credentials securely and never expose them in client-side code

A separate Client ID and Client Secret per merchant

Unlike POSLink credentials, these aren't shared across your merchant base. Each merchant you serve gets its own Client ID and Client Secret, delivered to your registrationWebhook when they connect - keep each merchant's credentials separate and don't reuse one set across multiple merchants.

Not registered yet?

Set up your partner account and implement the merchant registration flow first. Teya sends each merchant's credentials to your registration webhook.

2. API URLs

Service	Staging	Production
Online Payments API	`https://api.teya.xyz`	`https://api.teya.com`
OAuth	`https://id.teya.xyz/oauth/v2/oauth-token`	`https://id.teya.com/oauth/v2/oauth-token`
Business Portal	`https://business.teya.xyz`	`https://business.teya.com`

3. Required scopes

Request these scopes when obtaining your access token:

Scope	Description
`transactions/online/create`	Process an online transaction
`transactions/online/id/get`	Get online transaction details
`checkout/sessions/create`	Create a session for the SDK

Install the SDK

npm install @teyaproduct/teya-blocks-js

For React applications, also install the React wrapper:

npm install @teyaproduct/teya-blocks-js @teyaproduct/teya-blocks-react

See SDK Initialization for initTeyaBlocks() options, including developmentMode for staging.

Customize - Themes, CSS variables, and element options
Split Card - Separate card number, expiry, and CVC fields
Apple Pay - Native Apple Pay button
Webhooks - Receive payment confirmation notifications
Testing - Test cards and integration checklist

Try it - Card Element

Follow the interactive quickstart below to build a working integration with the Card Element.

Frontend

Backend

Environment

0 / 0 steps

server.js — staging

import express from 'express';

const app = express();
let cachedToken = null;
let tokenExpiry = 0;

async function getAccessToken() {
  if (cachedToken && Date.now() < tokenExpiry) return cachedToken;

  const res = await fetch('https://id.teya.xyz/oauth/v2/oauth-token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: process.env.TEYA_CLIENT_ID,
      client_secret: process.env.TEYA_CLIENT_SECRET,
      scope: 'checkout/sessions/create',
    }),
  });

  const data = await res.json();
  cachedToken = data.access_token;
  tokenExpiry = Date.now() + (data.expires_in - 60) * 1000;
  return cachedToken;
}

app.get('/api/session', async (req, res) => {
  const token = await getAccessToken();
  const sessionRes = await fetch(
    'https://api.teya.xyz/v2/checkout/sessions',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${token}`,
        'Idempotency-Key': crypto.randomUUID(),
      },
      body: JSON.stringify({
        store_id: process.env.TEYA_STORE_ID,
        amount: { currency: 'EUR', value: 1000 },
        type: 'SALE',
      }),
    }
  );

  const session = await sessionRes.json();
  res.json(session);
});

app.listen(3000, () => console.log('Server running on :3000'));

index.html — staging

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Payment</title>
  <style>
    body { font-family: sans-serif; max-width: 480px; margin: 40px auto; padding: 0 20px; }
    #card-container { margin: 20px 0; }
    #pay-button { width: 100%; padding: 12px; background: #008BB9; color: #fff; border: none; border-radius: 6px; font-size: 16px; cursor: pointer; }
  </style>
</head>
<body>
  <h1>Complete your payment</h1>
  <div id="card-container"></div>
    <button id="pay-button">Pay Now</button>
  <script type="module" src="app.js"></script>
</body>
</html>

app.js — staging

import { initTeyaBlocks } from '@teyaproduct/teya-blocks-js';

// Fetch session token from your backend
const res = await fetch('/api/session');
const { session_token } = await res.json();

// Initialize the SDK
const teya = await initTeyaBlocks(session_token, {
  locale: 'en-GB',
  appearance: {
    theme: 'default',

  },
  // Routes SDK calls to Teya staging. Remove for production.
  developmentMode: true,
});

// Create and mount the element
const card = teya.elements.create('card', {
  onReady: () => console.log('Card element ready'),
  onChange: (event) => {
    document.getElementById('pay-button').disabled = !event.complete;
  },
  onSuccess: (response) => console.log('Paid:', response),
  onError: (error) => console.error('Card error:', error),
});

card.mount('#card-container');

// Handle payment submission
document.getElementById('pay-button')
  .addEventListener('click', async () => {
    try {
      const result = await card.submitPayment();
      console.log('Payment result:', result);
    } catch (error) {
      console.error('Payment failed:', error);
    }
  });