SDK Installation

Full setup guide for the Flintn Payment Checkout SDK (flintn-checkout).

Installation

npm install flintn-checkout

Quick Start

Vanilla JavaScript

import { FlintNPayment } from 'flintn-checkout';

const payment = new FlintNPayment({
  config: {
    clientSessionId: 'your_client_session_id',
  },
  onReady: () => {
    document.getElementById('loading').style.display = 'none';
  },
  onPayment: (result) => {
    if (result.status === 'PAYMENT_SUCCESS') {
      console.log('Payment succeeded:', result.data);
    } else {
      console.log('Payment failed:', result.error);
    }
  },
  onExpressPayment: (result) => {
    console.log('Express payment:', result);
  },
  onError: (err) => {
    console.error('SDK error:', err.message);
  },
});

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

// When done (e.g., page navigation)
payment.unmount();

React

import { useFlintNPayment } from 'flintn-checkout/react';

function Checkout() {
  const { containerRef, isReady, paymentResult, error } = useFlintNPayment({
    config: {
      clientSessionId: 'your_client_session_id',
    },
    onPayment: (result) => {
      if (result.status === 'PAYMENT_SUCCESS') {
        console.log('Payment succeeded:', result.data);
      } else {
        console.log('Payment failed:', result.error);
      }
    },
    onExpressPayment: (result) => {
      console.log('Express payment:', result);
    },
  });

  if (error) return <div>Error: {error.message}</div>;
  if (paymentResult?.status === 'PAYMENT_SUCCESS') return <div>Payment successful!</div>;

  return (
    <div style={{ display: 'flex', justifyContent: 'center' }}>
      {!isReady && <div>Loading...</div>}
      <div ref={containerRef} style={{ width: '100%', height: '600px' }} />
    </div>
  );
}

Configuration

Option	Type	Required	Default	Description
clientSessionId	string	✅	—	Client session ID from your backend
isCardHolderRequired	boolean	❌	true	Require cardholder name field
successRedirectUrl	string	❌	—	Redirect URL after successful payment

Note: isCardHolderRequired only applies when using Primer as the payment provider.

Callbacks

Callback	Description
onPayment	Fired when card payment completes (success or error)
onExpressPayment	Fired when express payment completes (Apple Pay, Google Pay, PayPal)
onReady	Fired when widget is loaded and ready
onError	Fired on SDK initialization error

React Hook

Options

The useFlintNPayment hook accepts the same config and callbacks as the vanilla SDK. onReady and onError are managed internally — use the returned isReady and error values instead.

Return Values

Value	Type	Description
containerRef	RefObject<HTMLDivElement>	Ref to attach to container element
isReady	boolean	Widget is loaded and ready
paymentResult	PaymentResult | null	Result after payment attempt
error	PaymentError | null	SDK error if any

Types

PaymentResult

interface PaymentResult {
  status: 'PAYMENT_SUCCESS' | 'PAYMENT_ERROR' | 'PAYMENT_CANCELLED';
  data?: string; // Payment ID on success
  error?: {
    code: string;
    message: string;
  };
}

PaymentError

interface PaymentError {
  code: string;
  message: string;
}

SDK Options

Option	Type	Required	Description
config	FlintNConfig	✅	Checkout configuration (see Configuration above)
origin	string	❌	Override checkout URL (default: https://pay.flintn.com)
onPayment	function	❌	Card payment callback
onExpressPayment	function	❌	Express payment callback
onReady	function	❌	Widget ready callback
onError	function	❌	Error callback
debug	boolean	❌	Enable console debug logs

Vanilla JavaScript API

mount(selector)

Mount the checkout widget to a DOM element.

// Using a CSS selector
payment.mount('#payment-container');

// Using an element reference
payment.mount(document.getElementById('payment-container'));

unmount()

Remove the widget and clean up event listeners.

payment.unmount();

getIsReady()

Check if the widget is loaded and ready.

if (payment.getIsReady()) {
  console.log('Widget is ready');
}

Debug Mode

Enable debug logs to see SDK activity in the console:

// Vanilla JS
const payment = new FlintNPayment({
  config: { clientSessionId: '...' },
  debug: true,
});

// React
useFlintNPayment({
  config: { clientSessionId: '...' },
  debug: true,
});

Supported Payment Methods

• 💳 Credit/Debit Cards (Visa, Mastercard, Amex, Discover)

• 🍎 Apple Pay

• 🔵 Google Pay

• 🟡 PayPal

Test Cards

Card Number	Result
4111 1111 1111 1111	Success
4000 0000 0000 0002	Declined

Use any future expiry date and any 3-digit CVV.

Browser Support

• Chrome (latest)

• Firefox (latest)

• Safari (latest)

• Edge (latest)

Next Steps

For direct iframe integration without the SDK, see Manual Installation.