Split Card Elements

Separate elements for card number, expiry, and CVC - mount each one wherever you want. Gives you complete control over the card form layout and styling.

How it works

1 Create session (server)

2 Initialise SDK (client)

3 Create & mount each field

4 Submit payment

cardNumber, cardExpiry, cardCvc - each individually mountable

Full layout control between fields

teya.elements.submitPayment() to process

Independent validation per field

Automatic 3DS challenge handling

Works with HTML/JS and React

Before getting started

1. Get your credentials

1 Request a development store with an ecommerce subscription from your Teya contact

2 Log in to the Staging Business Portal with your Teya ID

3 Select your store and go to Integrations

4 Create ecommerce API credentials and configure webhook URLs

You'll receive a Client ID and Client Secret for OAuth authentication

Use client_credentials grant to obtain access tokens

Each store has its own set of credentials

Staging vs Production

Use Staging for development and testing. When ready to go live, repeat the credential setup in Production. Keep separate credentials and token caches for each environment.

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

Integrating on behalf of the merchants you serve?

Partners and platforms get credentials through the merchant registration flow instead. See Take payments online for partners.

Install the SDK

npm install @teyaproduct/teya-blocks-js

For React applications:

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 field options
Card Element - Single unified card input
Apple Pay - Native Apple Pay button
Webhooks - Receive payment confirmation notifications
Testing - Test cards and integration checklist

Try it - Split Card Elements

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

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-number { margin: 20px 0 8px; }
    #pay-button { width: 100%; padding: 12px; margin-top: 16px; 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-number"></div>
  <div style="display:flex;gap:8px">
    <div id="card-expiry" style="flex:1"></div>
    <div id="card-cvc" style="flex:1"></div>
  </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 cardNumber = teya.elements.create('cardNumber', {
  onReady: () => console.log('Card number ready'),
  onChange: (event) => console.log('Number valid:', event.complete),
});

const cardExpiry = teya.elements.create('cardExpiry', {
  onChange: (event) => console.log('Expiry valid:', event.complete),
});

const cardCvc = teya.elements.create('cardCvc', {
  onChange: (event) => console.log('CVC valid:', event.complete),
});

cardNumber.mount('#card-number');
cardExpiry.mount('#card-expiry');
cardCvc.mount('#card-cvc');

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