Card Form Components

Coinflow’s Card Form components provide a streamlined, PCI-compliant way to collect credit card information directly in your application. Instead of managing separate card number, CVV, and expiration inputs, these components bundle everything into a single embeddable form with one tokenize() method.

When to Use Card Form Components

Use these components when you want to:

• Collect card details for a new card checkout without building your own form layout
• Tokenize a card number with expiration for use with the Card Checkout API
• Re-collect a CVV only for a saved card before calling the Saved Card Checkout API
• Apply custom theming (fonts, colors, placeholders) to match your brand

Available Components

All three components expose a tokenize() method via a ref that returns a token you can pass to the Coinflow checkout APIs.

Installation

$
npm install @coinflowlabs/react

Tokenizing a New Card

Use CoinflowCardForm to collect the full card details (number, expiration, CVV) and tokenize them in a single call.

1
import {useRef} from 'react';
2
import {
3
  CoinflowCardForm,
4
  CardFormRef,
5
  CoinflowEnvs,
6
} from '@coinflowlabs/react';
7
8
function NewCardCheckout() {
9
  const cardFormRef = useRef<CardFormRef>(null);
10
11
  const handleTokenize = async () => {
12
    try {
13
      const result = await cardFormRef.current?.tokenize();
14
      if (!result) return;
15
16
      console.log('Token:', result.token);
17
      console.log('Exp Month:', result.expMonth);
18
      console.log('Exp Year:', result.expYear);
19
20
      // Pass result.token, result.expMonth, result.expYear
21
      // to the Card Checkout API endpoint
22
    } catch (err) {
23
      console.error('Tokenization failed:', err);
24
    }
25
  };
26
27
  return (
28
    <div>
29
      <CoinflowCardForm
30
        ref={cardFormRef}
31
        merchantId="your-merchant-id"
32
        env="sandbox"
33
      />
34
      <button onClick={handleTokenize}>Pay</button>
35
    </div>
36
  );
37
}

Refreshing a Saved Card Token (CVV Only)

When a customer pays with a saved card, you need to re-collect the CVV and refresh the token. Use CoinflowCvvForm with the saved card’s token from the Get Customer endpoint.

1
import {useRef} from 'react';
2
import {CoinflowCvvForm, CardFormRef} from '@coinflowlabs/react';
3
4
function SavedCardCheckout({savedCardToken}: {savedCardToken: string}) {
5
  const cvvFormRef = useRef<CardFormRef>(null);
6
7
  const handleTokenize = async () => {
8
    try {
9
      const result = await cvvFormRef.current?.tokenize();
10
      if (!result) return;
11
12
      // Pass result.token to the Saved Card Checkout API endpoint
13
      console.log('Refreshed token:', result.token);
14
    } catch (err) {
15
      console.error('CVV tokenization failed:', err);
16
    }
17
  };
18
19
  return (
20
    <div>
21
      <CoinflowCvvForm
22
        ref={cvvFormRef}
23
        merchantId="your-merchant-id"
24
        env="sandbox"
25
        token={savedCardToken}
26
      />
27
      <button onClick={handleTokenize}>Pay with Saved Card</button>
28
    </div>
29
  );
30
}

Tokenizing Card Number Only (No CVV)

Use CoinflowCardNumberForm when you only need to collect the card number and expiration — for example, when saving a card for future use without an immediate charge.

1
import {useRef} from 'react';
2
import {CoinflowCardNumberForm, CardFormRef} from '@coinflowlabs/react';
3
4
function SaveCardForLater() {
5
  const cardNumberRef = useRef<CardFormRef>(null);
6
7
  const handleTokenize = async () => {
8
    const result = await cardNumberRef.current?.tokenize();
9
    if (!result) return;
10
11
    // Store result.token, result.expMonth, result.expYear for later use
12
    console.log('Token:', result.token);
13
  };
14
15
  return (
16
    <div>
17
      <CoinflowCardNumberForm
18
        ref={cardNumberRef}
19
        merchantId="your-merchant-id"
20
        env="sandbox"
21
      />
22
      <button onClick={handleTokenize}>Save Card</button>
23
    </div>
24
  );
25
}

tokenize() Response

The tokenize() method returns a CardFormTokenResponse:

Theming

All card form components accept a theme prop to customize the look and feel. Theme values are passed as a MerchantTheme object.

1
<CoinflowCardForm
2
  ref={cardFormRef}
3
  merchantId="your-merchant-id"
4
  env="sandbox"
5
  theme={{
6
    font: 'Inter',
7
    fontSize: '14px',
8
    background: '#ffffff',
9
    textColor: '#111827',
10
    style: MerchantStyle.Rounded,
11
    showCardIcon: true,
12
    cardNumberPlaceholder: 'Card number',
13
    cvvPlaceholder: 'CVV',
14
    expirationPlaceholder: 'MM / YY',
15
  }}
16
/>

Responsive Layout

CoinflowCardForm automatically adapts its layout to the width of the container you place it in — no configuration is required.

• Wide containers — the card number, expiration, and CVV render together on a single row.
• Narrow containers — when there isn’t enough horizontal space for all three fields, the form reflows to two rows: the card number on the first row, with the expiration and CVV on the second.

This is especially useful in mobile checkout UIs, where a single-row layout can clip the card number in narrow viewports. The form measures its own container and switches layouts on the fly, including when the viewport is resized or rotated.

Because the form’s height changes when it reflows, the embedded iframe reports its content height back to the SDK, which resizes the iframe automatically so the fields are never clipped.

Component Props Reference

CoinflowCardForm / CoinflowCardNumberForm

CoinflowCvvForm

Token Expiration

Tokens expire if not used within 7 days of creation. Once used, a token is valid for 5 minutes in production. In the sandbox environment, tokens remain valid indefinitely. If a token expires, call tokenize() again to generate a new one.

Migrating from Legacy Card Inputs

If you are currently using CoinflowCardNumberInput and CoinflowCvvInput, the new Card Form components simplify your integration:

The legacy components continue to work but are deprecated. New integrations should use the Card Form components.