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
    fontWeight: '400',
9
    style: {
10
      background: '#f9fafb',
11
      textColor: '#111827',
12
      borderRadius: 'round',
13
    },
14
    cardNumberPlaceholder: 'Card number',
15
    cvvPlaceholder: 'CVV',
16
    expirationPlaceholder: 'MM / YY',
17
    showCardIcon: true,
18
  }}
19
/>

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.