@akinon/pz-masterpass-rest 2.0.0-beta.12 → 2.0.0-beta.14

package/docs/USAGE.md

@@ -0,0 +1,1176 @@
+# Masterpass REST - Usage Guide
+
+## Table of Contents
+
+- [Installation](#installation)
+- [SDK Setup](#sdk-setup)
+- [Basic Usage](#basic-usage)
+- [Props Reference](#props-reference)
+- [Custom Rendering](#custom-rendering)
+  - [Available Custom Render Slots](#available-custom-render-slots)
+  - [PaymentMethodSelector](#1-paymentmethodselector)
+  - [CardList](#2-cardlist)
+  - [CreditCardForm](#3-creditcardform)
+  - [InstallmentList](#4-installmentlist)
+  - [LinkModal](#5-linkmodal)
+  - [OTPModal](#6-otpmodal)
+  - [ConfirmationModal](#7-confirmationmodal)
+  - [ErrorDisplay](#8-errordisplay)
+  - [LoadingState](#9-loadingstate)
+  - [EmptyState](#10-emptystate)
+  - [Full Render](#11-fullrender)
+- [Text Customization](#text-customization)
+- [Exported Hooks](#exported-hooks)
+- [Exported Utilities](#exported-utilities)
+- [Type Definitions](#type-definitions)
+- [Payment Flow](#payment-flow)
+
+---
+
+## Installation
+
+```bash
+npx @akinon/projectzero@latest --plugins
+```
+
+## SDK Setup
+
+Copy the Masterpass JavaScript SDK to your project's `public` folder:
+
+```bash
+cp node_modules/@akinon/pz-masterpass-rest/assets/masterpass-javascript-sdk-web.min.js public/
+```
+
+The SDK file must be accessible at `/masterpass-javascript-sdk-web.min.js` in your application.
+
+## Basic Usage
+
+```tsx
+// src/views/checkout/steps/payment/options/masterpass-rest.tsx
+import { useLocalization } from '@akinon/next/hooks'
+import PluginModule, { Component } from '@akinon/next/components/plugin-module'
+
+const MasterpassRest = () => {
+  const { locale, currency } = useLocalization()
+
+  return (
+    <PluginModule
+      component={Component.MasterpassRest}
+      props={{ locale, currency }}
+    />
+  )
+}
+
+export default MasterpassRest
+```
+
+## Props Reference
+
+`MasterpassRestOption` is the main component. It accepts:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `locale` | `string` | `'en'` | Language locale (`'en'`, `'tr'`) |
+| `currency` | `string` | `'usd'` | Currency code (`'usd'`, `'try'`) |
+| `sdkUrl` | `string` | `undefined` | Custom Masterpass SDK URL |
+| `environment` | `'production' \| 'development'` | `undefined` | SDK environment |
+| `texts` | `MasterpassRestOptionTexts` | `defaultTexts` | UI text overrides for localization |
+| `customRender` | `MasterpassRestOptionCustomRender` | `undefined` | Custom render functions |
+
+```tsx
+<PluginModule
+  component={Component.MasterpassRest}
+  props={{
+    locale: 'tr',
+    currency: 'try',
+    environment: 'production',
+    texts: { title: 'Masterpass ile Ode' },
+    customRender: { /* ... */ }
+  }}
+/>
+```
+
+---
+
+## Custom Rendering
+
+The `customRender` prop lets you override individual UI sections or the entire component. Each render function receives the same props as the default component, so you have full access to state and handlers.
+
+### Available Custom Render Slots
+
+```typescript
+type MasterpassRestOptionCustomRender = {
+  paymentMethodSelector?: (props: PaymentMethodSelectorProps) => ReactElement
+  cardList?: (props: CardListProps) => ReactElement
+  creditCardForm?: (props: CreditCardFormProps) => ReactElement
+  installmentList?: (props: InstallmentListProps) => ReactElement
+  linkModal?: (props: LinkModalProps) => ReactElement
+  otpModal?: (props: OTPModalProps) => ReactElement
+  confirmationModal?: (props: ConfirmationModalProps) => ReactElement
+  errorDisplay?: (props: ErrorDisplayProps) => ReactElement
+  loadingState?: (props: LoadingStateProps) => ReactElement
+  emptyState?: (props: EmptyStateProps) => ReactElement
+  fullRender?: (props: MasterpassRestOptionRenderProps) => ReactElement
+}
+```
+
+---
+
+### 1. PaymentMethodSelector
+
+Toggles between saved cards and new card entry. Only rendered when the user has stored cards.
+
+**Props:**
+
+```typescript
+type PaymentMethodSelectorProps = {
+  cards: any[]                                                // User's stored cards array
+  selectedMethod: 'stored_card' | 'new_card'                  // Currently active method
+  onMethodChange: (method: 'stored_card' | 'new_card') => void // Switch handler
+  texts: MasterpassRestOptionTexts                            // Merged text strings
+}
+```
+
+**Example:**
+
+```tsx
+<PluginModule
+  component={Component.MasterpassRest}
+  props={{
+    locale,
+    currency,
+    customRender: {
+      paymentMethodSelector: ({ cards, selectedMethod, onMethodChange, texts }) => (
+        <div className="flex gap-4 border-b pb-4">
+          <button
+            className={selectedMethod === 'stored_card' ? 'font-bold border-b-2 border-primary' : 'text-gray-500'}
+            onClick={() => onMethodChange('stored_card')}
+          >
+            {texts.savedCardsText} ({cards.length})
+          </button>
+          <button
+            className={selectedMethod === 'new_card' ? 'font-bold border-b-2 border-primary' : 'text-gray-500'}
+            onClick={() => onMethodChange('new_card')}
+          >
+            {texts.newCardText}
+          </button>
+        </div>
+      )
+    }
+  }}
+/>
+```
+
+---
+
+### 2. CardList
+
+Displays the user's saved cards with selection, CVC input, and remove functionality.
+
+**Props:**
+
+```typescript
+type CardListProps = {
+  cards: any[]                               // Array of CardModel objects
+  onCardSelect: (card: any) => void          // Called when a card is selected
+  selectedCard?: any | null                  // Currently selected card
+  onRemove?: (card: any) => void             // Called to initiate card removal
+  removingCardId?: string | null             // Card being removed (shows loader)
+  cvc?: string                               // Current CVC input value
+  onCvcChange?: (cvc: string) => void        // CVC input change handler
+  cvcRequired?: boolean                      // Whether CVC field is shown
+  texts: MasterpassRestOptionTexts
+}
+```
+
+**CardModel structure (each item in `cards` array):**
+
+```typescript
+interface CardModel {
+  cardAlias: string               // 'My Visa Card'
+  maskedCardNumber: string        // '534261******1234'
+  uniqueCardNumber: string        // Unique identifier
+  cardType: 'Credit' | 'Debit' | 'Unknown' | ''
+  cardBin: string                 // First 6 digits
+  isDefaultCard: boolean
+  expireSoon: boolean
+  isExpired: boolean
+  cardValidationType: 'OTP' | 'RTA' | '_3D' | 'Unknown' | ''
+  // ...more fields
+}
+```
+
+**Example:**
+
+```tsx
+customRender: {
+  cardList: ({ cards, onCardSelect, selectedCard, onRemove, cvc, onCvcChange, texts }) => (
+    <div className="space-y-2">
+      {cards.map((card) => (
+        <div
+          key={card.uniqueCardNumber}
+          className={`p-4 border cursor-pointer ${
+            selectedCard?.uniqueCardNumber === card.uniqueCardNumber
+              ? 'border-primary bg-primary/5'
+              : 'border-gray-200'
+          }`}
+          onClick={() => onCardSelect(card)}
+        >
+          <div className="flex justify-between items-center">
+            <div>
+              <span className="font-medium">{card.cardAlias}</span>
+              <span className="ml-2 text-gray-500">{card.maskedCardNumber}</span>
+              {card.isDefaultCard && (
+                <span className="ml-2 text-xs bg-green-100 text-green-700 px-2 py-0.5">
+                  {texts.defaultCardText}
+                </span>
+              )}
+            </div>
+            <button
+              onClick={(e) => { e.stopPropagation(); onRemove?.(card) }}
+              className="text-red-500 text-sm"
+            >
+              Remove
+            </button>
+          </div>
+
+          {/* CVC input for selected card */}
+          {selectedCard?.uniqueCardNumber === card.uniqueCardNumber && (
+            <input
+              type="text"
+              maxLength={4}
+              value={cvc || ''}
+              onChange={(e) => onCvcChange?.(e.target.value)}
+              placeholder={texts.cvcPlaceholder3}
+              className="mt-2 border px-2 py-1 w-20"
+            />
+          )}
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+---
+
+### 3. CreditCardForm
+
+The new card entry form with validation, BIN checking, and optional card saving.
+
+**Props:**
+
+```typescript
+type CreditCardFormProps = {
+  onSaveCard?: (data: CreditCardFormData) => void  // Submit handler
+  isLoading?: boolean                              // Disables form during API calls
+  showSaveOption?: boolean                         // Shows "save card" checkbox
+  initialValues?: Partial<CreditCardFormData>      // Pre-fill form fields
+  onBinChange?: (bin: string) => Promise<void>     // Called with first 6 digits for installment lookup
+  texts: MasterpassRestOptionTexts
+}
+```
+
+**CreditCardFormData (form submit payload):**
+
+```typescript
+interface CreditCardFormData {
+  cardNumber: string       // '5342610000001234'
+  cardholderName: string   // 'John Doe'
+  expiryDate: string       // '12/27'
+  cvv: string              // '123'
+  saveCard: boolean        // true
+  cardAlias: string        // 'My Card'
+}
+```
+
+**Example:**
+
+```tsx
+customRender: {
+  creditCardForm: ({ onSaveCard, isLoading, showSaveOption, onBinChange, texts }) => (
+    <MyCustomCardForm
+      onSubmit={(formData) => onSaveCard?.(formData)}
+      disabled={isLoading}
+      showSave={showSaveOption}
+      onCardNumberChange={(number) => {
+        // Trigger installment lookup when 6+ digits entered
+        const digits = number.replace(/\D/g, '')
+        if (digits.length >= 6) {
+          onBinChange?.(digits.substring(0, 6))
+        }
+      }}
+      labels={{
+        cardNumber: texts.cardNumberLabel,
+        name: texts.cardholderNameLabel,
+        expiry: texts.expiryDateLabel,
+        cvc: texts.cvcLabel,
+        submit: texts.addCardButton
+      }}
+    />
+  )
+}
+```
+
+> **Important:** When implementing a custom card form, you must call `onBinChange` with the first 6 digits of the card number to trigger installment options loading. The default form does this automatically.
+
+---
+
+### 4. InstallmentList
+
+Shows available installment options after a card/BIN is selected, plus the "Proceed to Payment" button.
+
+**Props:**
+
+```typescript
+type InstallmentListProps = {
+  installments: Installment[]                         // Available installment options
+  cardType: CardType | null                           // Detected card type info
+  onInstallmentSelect: (installment: Installment) => void
+  selectedInstallment?: Installment | null
+  isLoading?: boolean                                 // Loading installments or preparing order
+  onProceedToPayment?: () => void                     // Triggers payment flow
+  paymentLoading?: boolean                            // Payment in progress
+  texts: MasterpassRestOptionTexts
+}
+```
+
+**Installment structure:**
+
+```typescript
+interface Installment {
+  pk: number
+  installment_count: number                    // 1 = single payment, 2+ = installments
+  label: string
+  price_with_accrued_interest: string          // Total price (e.g. '1500.00')
+  monthly_price_with_accrued_interest: string  // Monthly amount (e.g. '500.00')
+}
+```
+
+**CardType structure:**
+
+```typescript
+interface CardType {
+  name: string   // 'Visa'
+  slug: string   // 'visa'
+  logo: string   // URL to card logo
+}
+```
+
+**Example:**
+
+```tsx
+customRender: {
+  installmentList: ({
+    installments,
+    cardType,
+    onInstallmentSelect,
+    selectedInstallment,
+    isLoading,
+    onProceedToPayment,
+    paymentLoading,
+    texts
+  }) => (
+    <div>
+      {cardType && (
+        <div className="mb-4 text-sm text-gray-500">
+          {texts.cardTypeLabel} {cardType.name}
+        </div>
+      )}
+
+      <div className="space-y-2">
+        {installments.map((inst) => (
+          <label
+            key={inst.pk}
+            className={`flex items-center justify-between p-3 border cursor-pointer ${
+              selectedInstallment?.pk === inst.pk ? 'border-primary' : 'border-gray-200'
+            }`}
+          >
+            <div className="flex items-center gap-2">
+              <input
+                type="radio"
+                checked={selectedInstallment?.pk === inst.pk}
+                onChange={() => onInstallmentSelect(inst)}
+              />
+              <span>
+                {inst.installment_count === 1
+                  ? texts.singlePaymentText
+                  : texts.installmentsText?.replace('{count}', String(inst.installment_count))}
+              </span>
+            </div>
+            <span className="font-medium">{inst.price_with_accrued_interest} TL</span>
+          </label>
+        ))}
+      </div>
+
+      <button
+        onClick={onProceedToPayment}
+        disabled={!selectedInstallment || isLoading || paymentLoading}
+        className="w-full mt-4 py-3 bg-primary text-white disabled:opacity-50"
+      >
+        {paymentLoading ? texts.processingPaymentText : texts.proceedToPaymentText}
+      </button>
+    </div>
+  )
+}
+```
+
+---
+
+### 5. LinkModal
+
+Shown when the user has a Masterpass account but it's not linked to the current merchant.
+
+**Props:**
+
+```typescript
+type LinkModalProps = {
+  open: boolean
+  onClose: () => void
+  onConfirm: () => void     // Links account to merchant
+  texts: MasterpassRestOptionTexts
+}
+```
+
+**Example:**
+
+```tsx
+customRender: {
+  linkModal: ({ open, onClose, onConfirm, texts }) => {
+    if (!open) return null
+
+    return (
+      <div className="fixed inset-0 bg-black/50 flex items-center justify-center z-50">
+        <div className="bg-white p-6 max-w-md">
+          <p className="mb-4">{texts.linkModalDescription}</p>
+          <div className="flex gap-3">
+            <button onClick={onConfirm} className="flex-1 bg-primary text-white py-2">
+              {texts.linkAccountButton}
+            </button>
+            <button onClick={onClose} className="flex-1 border py-2">
+              {texts.linkModalCancelButton}
+            </button>
+          </div>
+        </div>
+      </div>
+    )
+  }
+}
+```
+
+---
+
+### 6. OTPModal
+
+Handles 3 types of verification: RTA (security verification), OTP (bank SMS), and CVV.
+
+**Props:**
+
+```typescript
+type OTPModalProps = {
+  open: boolean
+  onClose: () => void
+  onSubmit: (otp: string) => Promise<{
+    success: boolean
+    requiresOTP?: boolean
+    message?: string
+  }>
+  type: 'RTA' | 'OTP' | 'CVV'          // Determines labels/placeholders
+  responseCode?: string
+  description?: string
+  texts: MasterpassRestOptionTexts
+}
+```
+
+**Example:**
+
+```tsx
+customRender: {
+  otpModal: ({ open, onClose, onSubmit, type, texts }) => {
+    if (!open) return null
+
+    const titles = {
+      RTA: texts.rtaVerificationTitle,
+      OTP: texts.bankOtpVerificationTitle,
+      CVV: texts.cvvVerificationTitle
+    }
+
+    const descriptions = {
+      RTA: texts.rtaVerificationDescription,
+      OTP: texts.bankOtpVerificationDescription,
+      CVV: texts.cvvVerificationDescription
+    }
+
+    let inputValue = ''
+
+    const handleSubmit = async () => {
+      const result = await onSubmit(inputValue)
+      if (!result.success && result.message) {
+        alert(result.message)
+      }
+    }
+
+    return (
+      <div className="fixed inset-0 bg-black/50 flex items-center justify-center z-50">
+        <div className="bg-white p-6 max-w-sm w-full">
+          <h3 className="font-bold text-lg mb-2">{titles[type]}</h3>
+          <p className="text-sm text-gray-600 mb-4">{descriptions[type]}</p>
+          <input
+            type="text"
+            maxLength={type === 'CVV' ? 4 : 6}
+            onChange={(e) => { inputValue = e.target.value }}
+            className="w-full border px-3 py-2 mb-4"
+            placeholder={
+              type === 'CVV'
+                ? texts.cvvVerificationPlaceholder
+                : texts.rtaVerificationPlaceholder
+            }
+          />
+          <div className="flex gap-3">
+            <button onClick={handleSubmit} className="flex-1 bg-primary text-white py-2">
+              {texts.verifyButton}
+            </button>
+            <button onClick={onClose} className="flex-1 border py-2">
+              {texts.otpModalCancelButton}
+            </button>
+          </div>
+        </div>
+      </div>
+    )
+  }
+}
+```
+
+---
+
+### 7. ConfirmationModal
+
+Used for card removal confirmation. Receives the card alias in the message.
+
+**Props:**
+
+```typescript
+type ConfirmationModalProps = {
+  open: boolean
+  onClose: () => void
+  onConfirm: () => void
+  title: React.ReactNode | string    // Can be JSX (default: Masterpass logo image)
+  message: string                    // Pre-formatted with card alias
+  confirmText?: string
+  cancelText?: string
+  isLoading?: boolean
+  loadingText?: string
+  texts: MasterpassRestOptionTexts
+}
+```
+
+**Example:**
+
+```tsx
+customRender: {
+  confirmationModal: ({ open, onClose, onConfirm, title, message, isLoading, texts }) => {
+    if (!open) return null
+
+    return (
+      <div className="fixed inset-0 bg-black/50 flex items-center justify-center z-50">
+        <div className="bg-white p-6 max-w-sm">
+          <div className="mb-4">{title}</div>
+          <p className="mb-4">{message}</p>
+          <div className="flex gap-3">
+            <button
+              onClick={onConfirm}
+              disabled={isLoading}
+              className="flex-1 bg-red-600 text-white py-2"
+            >
+              {isLoading ? texts.removeCardLoadingText : texts.removeCardConfirmText}
+            </button>
+            <button onClick={onClose} className="flex-1 border py-2">
+              {texts.removeCardCancelText}
+            </button>
+          </div>
+        </div>
+      </div>
+    )
+  }
+}
+```
+
+---
+
+### 8. ErrorDisplay
+
+Shown at the bottom of the payment area when an error occurs.
+
+**Props:**
+
+```typescript
+type ErrorDisplayProps = {
+  error: any
+  onDismiss: () => void
+  getErrorInfo: (error: any) => { message: string; type: string } | null
+}
+```
+
+**Example:**
+
+```tsx
+customRender: {
+  errorDisplay: ({ error, onDismiss, getErrorInfo }) => {
+    const info = getErrorInfo(error)
+    if (!info) return null
+
+    return (
+      <div className="mt-4 p-4 bg-red-50 border border-red-200 flex justify-between items-start">
+        <div>
+          <h4 className="font-semibold text-red-800">{info.type}</h4>
+          <p className="text-sm text-red-700">{info.message}</p>
+        </div>
+        <button onClick={onDismiss} className="text-red-500 text-xl leading-none">&times;</button>
+      </div>
+    )
+  }
+}
+```
+
+---
+
+### 9. LoadingState
+
+Shown during initial token fetch and SDK loading.
+
+**Props:**
+
+```typescript
+type LoadingStateProps = {
+  message: string    // Either texts.loadingMessage or texts.scriptLoadingMessage
+}
+```
+
+**Example:**
+
+```tsx
+customRender: {
+  loadingState: ({ message }) => (
+    <div className="flex items-center justify-center h-48">
+      <div className="animate-pulse text-center">
+        <div className="w-12 h-12 border-4 border-primary border-t-transparent rounded-full animate-spin mx-auto" />
+        <p className="mt-3 text-gray-500">{message}</p>
+      </div>
+    </div>
+  )
+}
+```
+
+---
+
+### 10. EmptyState
+
+Shown in the installment area when no installments are available yet.
+
+**Props:**
+
+```typescript
+type EmptyStateProps = {
+  paymentMethod: 'stored_card' | 'new_card'
+  cardNumberLength: number        // Number of digits entered (for new card)
+  isCheckoutLoading: boolean
+}
+```
+
+**Example:**
+
+```tsx
+customRender: {
+  emptyState: ({ paymentMethod, cardNumberLength }) => (
+    <div className="flex items-center justify-center h-64 border-2 border-dashed border-gray-200">
+      <div className="text-center text-gray-400">
+        {paymentMethod === 'stored_card'
+          ? 'Select a card to view installment options'
+          : cardNumberLength < 6
+            ? `Enter ${6 - cardNumberLength} more digits to see installments`
+            : 'No installment options available'}
+      </div>
+    </div>
+  )
+}
+```
+
+---
+
+### 11. FullRender
+
+Takes over the entire component rendering. You get all state, handlers, and default components as props.
+
+**Props:**
+
+```typescript
+type MasterpassRestOptionRenderProps = {
+  // State
+  paymentMethod: 'stored_card' | 'new_card'
+  hasStoredCards: boolean
+  shouldShowDirectForm: boolean
+  cvc: string
+  error: any
+
+  // Data
+  accountData: AccountAccessSuccessResponse | null
+  accountStatus: any
+  modalState: ModalState
+  paymentState: PaymentState
+
+  // Handlers
+  handlePaymentMethodChange: (method: 'stored_card' | 'new_card') => void
+  handleCardSelect: (card: any) => Promise<void>
+  updateModalState: (updates: Partial<ModalState>) => void
+  handleRemoveCard: (card: any) => void
+  confirmRemoveCard: () => Promise<void>
+  handleCvcChange: (cvc: string) => void
+  handleSaveCard: (cardData: CreditCardFormData) => Promise<void>
+  handleBinChange: (bin: string) => Promise<void>
+  handleInstallmentSelect: (installment: Installment) => Promise<void>
+  handleProceedToPayment: () => Promise<void>
+  handleLinkConfirm: () => Promise<void>
+  handleOTPSubmit: (otp: string) => Promise<{ success: boolean; message?: string }>
+  onCloseError: () => void
+
+  // Loading States
+  isCheckoutLoading: boolean
+  isInstallmentLoading: boolean
+  isPrepareLoading: boolean
+  isFinalizeLoading: boolean
+
+  // Texts
+  texts: MasterpassRestOptionTexts
+
+  // Default Components (use these to avoid reimplementing everything)
+  components: {
+    PaymentMethodSelector: React.ComponentType<PaymentMethodSelectorProps>
+    CardList: React.ComponentType<CardListProps>
+    CreditCardForm: React.ComponentType<CreditCardFormProps>
+    InstallmentList: React.ComponentType<InstallmentListProps>
+    LinkModal: React.ComponentType<LinkModalProps>
+    OTPModal: React.ComponentType<OTPModalProps>
+    ConfirmationModal: React.ComponentType<ConfirmationModalProps>
+  }
+}
+```
+
+**Example - Custom layout with default components:**
+
+```tsx
+customRender: {
+  fullRender: (props) => {
+    const {
+      paymentMethod,
+      hasStoredCards,
+      shouldShowDirectForm,
+      accountData,
+      paymentState,
+      modalState,
+      handlePaymentMethodChange,
+      handleCardSelect,
+      handleCvcChange,
+      handleSaveCard,
+      handleBinChange,
+      handleInstallmentSelect,
+      handleProceedToPayment,
+      handleLinkConfirm,
+      handleOTPSubmit,
+      handleRemoveCard,
+      confirmRemoveCard,
+      updateModalState,
+      cvc,
+      isCheckoutLoading,
+      isInstallmentLoading,
+      isPrepareLoading,
+      isFinalizeLoading,
+      texts,
+      components
+    } = props
+
+    const { CardList, CreditCardForm, InstallmentList, LinkModal, OTPModal } = components
+
+    return (
+      <div className="my-custom-layout">
+        {/* Your custom header */}
+        <h1 className="text-2xl mb-6">Secure Payment</h1>
+
+        {/* Use default components with custom layout */}
+        {hasStoredCards && !shouldShowDirectForm && (
+          <div className="tabs mb-4">
+            <button onClick={() => handlePaymentMethodChange('stored_card')}>
+              Saved Cards
+            </button>
+            <button onClick={() => handlePaymentMethodChange('new_card')}>
+              New Card
+            </button>
+          </div>
+        )}
+
+        <div className="flex gap-8">
+          <div className="flex-1">
+            {paymentMethod === 'stored_card' && hasStoredCards ? (
+              <CardList
+                cards={accountData?.result?.cards || []}
+                onCardSelect={handleCardSelect}
+                selectedCard={paymentState.selectedCard}
+                onRemove={handleRemoveCard}
+                removingCardId={modalState?.removingCardId}
+                cvc={cvc}
+                onCvcChange={handleCvcChange}
+                texts={texts}
+              />
+            ) : (
+              <CreditCardForm
+                onSaveCard={handleSaveCard}
+                isLoading={isCheckoutLoading}
+                showSaveOption={true}
+                onBinChange={handleBinChange}
+                texts={texts}
+              />
+            )}
+          </div>
+
+          <div className="flex-1">
+            {paymentState.installments.length > 0 && (
+              <InstallmentList
+                installments={paymentState.installments}
+                cardType={paymentState.cardType}
+                onInstallmentSelect={handleInstallmentSelect}
+                selectedInstallment={paymentState.selectedInstallment}
+                isLoading={isInstallmentLoading || isPrepareLoading}
+                onProceedToPayment={handleProceedToPayment}
+                paymentLoading={isFinalizeLoading}
+                texts={texts}
+              />
+            )}
+          </div>
+        </div>
+
+        {/* Modals - use default components */}
+        <LinkModal
+          open={modalState?.showLinkModal ?? false}
+          onClose={() => updateModalState({ showLinkModal: false })}
+          onConfirm={handleLinkConfirm}
+          texts={texts}
+        />
+        <OTPModal
+          open={modalState?.showOTPModal ?? false}
+          onClose={() => updateModalState({ showOTPModal: false })}
+          onSubmit={handleOTPSubmit}
+          type={modalState?.otpType ?? 'OTP'}
+          texts={texts}
+        />
+      </div>
+    )
+  }
+}
+```
+
+---
+
+## Text Customization
+
+All user-facing strings can be overridden via the `texts` prop. Pass only the keys you want to change; the rest will use defaults.
+
+```tsx
+<PluginModule
+  component={Component.MasterpassRest}
+  props={{
+    locale: 'tr',
+    currency: 'try',
+    texts: {
+      // Titles
+      title: 'Masterpass ile Ode',
+      selectCardTitle: 'Kart Secin',
+      newCardTitle: 'Yeni Kart ile Ode',
+      installmentOptionsTitle: 'Taksit Secenekleri',
+      enterCardDetailsTitle: 'Kart Bilgilerini Girin',
+
+      // Form labels
+      cardNumberLabel: 'Kart Numarasi',
+      cardholderNameLabel: 'Kart Uzerindeki Isim',
+      expiryDateLabel: 'Son Kullanma Tarihi',
+      cvcLabel: 'CVC/CVV',
+      saveCardLabel: 'Bu karti gelecek odemeler icin kaydet',
+      addCardButton: 'Kart Ekle',
+
+      // Payment method
+      savedCardsText: 'Kayitli Kartlar',
+      newCardText: 'Yeni Kart',
+
+      // Installments
+      singlePaymentText: 'Tek Cekim',
+      installmentsText: '{count} Taksit',    // {count} is replaced dynamically
+      noInterestText: 'Faizsiz',
+      proceedToPaymentText: 'Odemeye Devam Et',
+      processingPaymentText: 'Odeme Isleniyor...',
+
+      // Card list
+      defaultCardText: 'Varsayilan',
+      expiresSoonText: 'Suresi Yakinda Dolacak',
+
+      // Modals
+      linkModalDescription: '<PHONE_NUMBER> numarasi ile Masterpass hesabinizdaki kartlari gormek ister misiniz?',
+      linkAccountButton: 'Evet, istiyorum',
+      linkModalCancelButton: 'Hayir, istemiyorum',
+      removeCardMessage: '<{cardAlias}> kartini Masterpass altyapisindan silmek istediginize emin misiniz?',
+
+      // Verification
+      rtaVerificationTitle: 'Guvenlik Dogrulamasi',
+      bankOtpVerificationTitle: 'Banka Dogrulamasi',
+      cvvVerificationTitle: 'CVV Dogrulamasi',
+      verifyButton: 'Dogrula',
+
+      // Errors
+      paymentErrorTitle: 'Odeme Hatasi',
+      cardNumberRequiredText: 'Kart numarasi zorunludur',
+      cardNumberInvalidText: 'Gecerli bir kart numarasi girin',
+
+      // Loading
+      loadingMessage: 'Odeme sistemi hazirlaniyor...',
+      scriptLoadingMessage: 'Odeme altyapisi yukleniyor...',
+
+      // Session
+      sessionExpiredTitle: 'Oturum Suresi Doldu',
+      sessionExpiredMessage: 'Oturumunuz zaman asimina ugradi. Devam etmek icin islemi yeniden baslatin.',
+      sessionExpiredButton: 'Yeniden Basla'
+    }
+  }}
+/>
+```
+
+### Dynamic Text Placeholders
+
+Some text keys support placeholders:
+
+| Key | Placeholder | Description |
+|-----|------------|-------------|
+| `installmentsText` | `{count}` | Installment count |
+| `savedCardsDescription` | `{count}` | Number of saved cards |
+| `removeCardMessage` | `{cardAlias}` | Name of the card being removed |
+| `cvcHelpText` | `{length}`, `{side}` | CVC digit count and card side |
+| `linkModalDescription` | `<PHONE_NUMBER>` | User's phone number (auto-replaced by SDK) |
+
+---
+
+## Exported Hooks
+
+These hooks can be imported independently for advanced use cases:
+
+### `useMasterpassScript`
+
+Manages Masterpass SDK script loading and initialization.
+
+```typescript
+import { useMasterpassScript } from '@akinon/pz-masterpass-rest'
+
+const { isScriptLoaded, isMasterpassInitialized } = useMasterpassScript({
+  locale: 'tr',
+  sdkUrl: 'https://mp-sdk.masterpassturkiye.com',
+  environment: 'production',
+  onScriptLoaded: () => console.log('SDK ready'),
+  onScriptError: (error) => console.error('SDK failed', error)
+})
+```
+
+### `useMasterpassToken`
+
+Fetches and manages the JWT token for Masterpass API authentication.
+
+```typescript
+import { useMasterpassToken } from '@akinon/pz-masterpass-rest'
+
+const { token, tokenData, isLoading, error, refetch } = useMasterpassToken({
+  useThreeD: false,
+  onTokenReady: (data) => console.log('Token ready', data)
+})
+
+// Token data includes: MerchantId, AccountKey, UserId, Hash, exp, etc.
+```
+
+### `useMasterpassAccount`
+
+Manages account access, linking, card operations, and OTP verification.
+
+```typescript
+import { useMasterpassAccount } from '@akinon/pz-masterpass-rest'
+
+const {
+  accountData,       // User's account with cards
+  accountStatus,     // Linked/unlinked/not found
+  modalState,        // All modal visibility states
+  initializeAccount,
+  refreshAccountData,
+  handleLinkConfirm,
+  handleOTPSubmit,
+  handleRemoveCard,
+  confirmRemoveCard,
+  handleAddCard
+} = useMasterpassAccount()
+```
+
+### `useMasterpassPayment`
+
+Handles the payment processing flow.
+
+```typescript
+import { useMasterpassPayment } from '@akinon/pz-masterpass-rest'
+
+const {
+  paymentState,          // selectedCard, selectedInstallment, installments, etc.
+  isCheckoutLoading,
+  isInstallmentLoading,
+  isPrepareLoading,
+  isFinalizeLoading,
+  handleCardSelect,      // Select a saved card (triggers BIN check)
+  handleInstallmentSelect,
+  processPayment,        // Stored card payment
+  processDirectPayment   // New card payment
+} = useMasterpassPayment()
+```
+
+---
+
+## Exported Utilities
+
+```typescript
+import {
+  // Card utilities
+  formatCardNumber,    // '5342610000001234' -> '5342 6100 0000 1234'
+  formatExpiryDate,    // '1227' -> '12/27'
+  formatCVV,           // Strips non-digits, max 4 chars
+  detectCardType,      // Returns 'visa' | 'mastercard' | 'amex' | 'troy' | 'discover' | 'unknown'
+  getCvcLength,        // Returns 3 (or 4 for Amex)
+  maskCardNumber,      // '5342610000001234' -> '****1234'
+  validateCardNumber,  // Luhn algorithm validation
+  getCardBIN,          // Returns first 6 digits
+  getCardIcon,         // Returns logo image object by BIN
+
+  // Payment utilities
+  isTokenExpired,             // Check JWT token expiration
+  getTransactionType,         // Returns 'PURCHASE' or 'PURCHASE_3D'
+  formatAmountForPayment,     // '1500.00' -> '150000'
+  createPaymentRequest,       // Builds stored card payment request
+  createDirectPaymentRequest, // Builds new card payment request
+
+  // Validation
+  createCreditCardFormSchema  // Returns Yup validation schema
+} from '@akinon/pz-masterpass-rest'
+```
+
+---
+
+## Type Definitions
+
+All types are exported and can be imported for use in custom components:
+
+```typescript
+import type {
+  // Component props
+  PaymentMethodSelectorProps,
+  CardListProps,
+  CreditCardFormProps,
+  InstallmentListProps,
+  LinkModalProps,
+  OTPModalProps,
+  ConfirmationModalProps,
+  ErrorDisplayProps,
+  LoadingStateProps,
+  EmptyStateProps,
+  MasterpassRestOptionRenderProps,
+  MasterpassRestOptionCustomRender,
+  MasterpassRestOptionTexts,
+
+  // Data types
+  CardModel,
+  CardType,
+  Installment,
+  PaymentState,
+  ModalState,
+  OrderData,
+  OTPType,
+  TransactionType,
+  InformationModalData,
+
+  // Account types
+  AccountAccessRequest,
+  AccountAccessResponse,
+  AccountAccessSuccessResponse,
+  AccountAccessErrorResponse,
+  CardResponse,
+
+  // Payment types
+  PaymentProcessRequest,
+  DirectPaymentRequest,
+  DirectPaymentResponse,
+  MPResponse,
+
+  // Environment
+  MasterpassEnvironment
+} from '@akinon/pz-masterpass-rest'
+```
+
+---
+
+## Payment Flow
+
+### Stored Card Payment
+
+```
+1. Component mounts
+   -> Token fetched from backend
+   -> Masterpass SDK loaded
+   -> Account access requested
+
+2. Account status determined:
+   - Account found & linked -> Show saved cards
+   - Account found & NOT linked -> Show LinkModal
+   - Account not found -> Show new card form only
+
+3. User selects a saved card
+   -> BIN check sent to backend
+   -> Installment options returned
+
+4. User selects installment option
+
+5. User clicks "Proceed to Payment"
+   -> Order prepared (gets order number)
+   -> Payment request sent via Masterpass SDK
+
+6. Payment result:
+   - Success -> Order finalized
+   - 3D Secure required -> Redirect to bank page
+   - OTP required -> Show OTP modal (RTA/OTP/CVV)
+   - Error -> Show error display
+```
+
+### New Card Payment
+
+```
+1. User enters card number (6+ digits)
+   -> BIN check sent automatically
+   -> Installment options shown
+
+2. User fills remaining card fields
+
+3. User selects installment option
+
+4. User clicks "Proceed to Payment"
+   -> Direct payment request via Masterpass SDK
+
+5. Same result handling as stored card flow
+```
+
+### OTP Verification
+
+```
+1. OTP modal shown with type-specific UI (RTA/OTP/CVV)
+2. User enters verification code
+3. Code submitted to Masterpass
+4. Result:
+   - Success -> Order finalized
+   - Another OTP needed -> Modal updates
+   - Session expired -> Information modal shown
+   - 3D Secure needed -> Redirect
+```