Embedded Checkout

Embed the Solifyn Checkout component directly in your React applications

Solifyn provides a dedicated React SDK (solifyn) that lets you embed secure checkout flows directly into your website or web application. This allows your customers to complete purchases without ever leaving your site.

Installation

Install the Solifyn SDK package using your preferred package manager:

npm

npm install @solifyn/checkout

Basic Usage

To mount the embedded checkout, first create a checkout session using our API (e.g. POST /checkout/create or POST /checkout/collection/create). Then, import and render the SolifynCheckout component:

import React from 'react';
import { SolifynCheckout } from '@solifyn/checkout/react';

interface CheckoutViewProps {
  sessionId: string; // The database checkout/payment session ID
}

export default function CheckoutView({ sessionId }: CheckoutViewProps) {
  return (
    <div className="w-full max-w-2xl mx-auto border border-zinc-200 rounded-2xl overflow-hidden p-6">
      <SolifynCheckout
        sessionId={sessionId}
        theme="light"
        environment="production" // Use "sandbox" for testing
        onComplete={(id) => {
          console.log('Payment completed successfully!', id);
          window.location.href = `/checkout/success?id=${id}`;
        }}
      />
    </div>
  );
}

---

Component Properties

The SolifynCheckout component accepts the following props:

Prop	Type	Description	Default
sessionId	string	The ID of the active checkout/payment session.	Required
theme	'light' | 'dark' | 'system'	The visual theme applied to the checkout iframe.	'light'
environment	'production' | 'sandbox'	The execution environment.	'production'
prefill	object	Auto-fill customer details (e.g., { email, address }).	undefined
labels	object	Custom labels to override checkout texts. See below.	undefined
hideEmail	boolean	Hide the email input field (useful when email is prefilled).	false
disableEmail	boolean	Disable editing of the prefilled email.	false
hideAddressForm	boolean	Hide the shipping/billing address input fields.	false
hideSubmitButton	boolean	Hide the built-in submit/pay button to use custom triggers.	false
onComplete	(id: string, extra?: any) => void	Callback triggered when the payment completes successfully.	undefined
onStateChange	(state: 'loading' | 'success' | 'error' | any) => void	Callback triggered when the checkout lifecycle state changes.	undefined
onAddressValidationError	(error: any) => void	Callback triggered on shipping or billing address validation failure.	undefined
onCurrenciesAvailable	(snapshot: any) => void	Callback triggered when the list of available checkout currencies is retrieved.	undefined
onCurrencyChanged	(event: any) => void	Callback triggered when the customer changes the display currency.	undefined

Customizing Labels

You can pass a labels object to customize the user-facing text strings:

<SolifynCheckout
  sessionId={sessionId}
  labels={{
    initializing: "Setting up your checkout...",
    processing: "Processing payment...",
    payNow: "Complete Purchase",
    secured: "Encrypted Secure Payment",
    orderProcessedBy: "Order processed via partner Merchant of Record. Powered by solifyn.com"
  }}
/>

---

Imperative Control (Ref Forwarding)

You can forward a React ref to SolifynCheckout to access imperative controls:

import React, { useRef } from 'react';
import { SolifynCheckout } from '@solifyn/checkout/react';

export default function CustomCheckoutView({ sessionId }) {
  const checkoutRef = useRef<any>(null);

  const triggerPayment = () => {
    if (checkoutRef.current) {
      // Imperatively submit/pay the checkout form
      checkoutRef.current.submit();
    }
  };

  const updateCustomerEmail = (newEmail: string) => {
    if (checkoutRef.current) {
      checkoutRef.current.setEmail(newEmail);
    }
  };

  return (
    <div>
      <SolifynCheckout
        ref={checkoutRef}
        sessionId={sessionId}
        hideSubmitButton={true} // Hide built-in button
      />
      
      <button 
        onClick={triggerPayment}
        className="mt-4 px-6 py-2 bg-zinc-900 text-zinc-200 rounded-lg"
      >
        Pay Now
      </button>
    </div>
  );
}

---

The forwarded ref exposes the following methods:

• submit(): Submits the checkout form programmatically.
• getEmail(): Retrieves the current customer email input value.
• setEmail(email: string): Programmatically updates the customer email value.
• getAddress(): Retrieves the customer’s current billing/shipping address.
• setAddress(address: any): Programmatically sets the customer address fields.
• getAvailableCurrencies(): Returns the list of supported currencies.
• setDisplayCurrency(currency: string): Updates the currency code shown to the user.