Hepsipay

The Hepsipay component integrates the Hepsipay iframe-based payment system into your checkout flow. It handles validation, SDK initialization, payment triggering, and success callbacks.

Installation Method

You can use the following command to install the extension with the latest plugins:

npx @akinon/projectzero@latest --plugins

Props

Prop	Type	Required	Description
initOptionsOverrides	Partial<InitOptions>	Optional	Object to override default Hepsipay SDK init() options.
agreementCheckbox	React.ReactElement	Optional	Checkbox component (e.g., for user agreements or KVKK) connected to the form.
translations	Record<string, HepsipayTranslationsProps>	Optional	Object for customizing UI texts like placeholders, warnings, and error messages.
customUIRender	(props: CustomUIRenderProps) => React.ReactNode	Optional	Custom UI render function. If provided, it overrides the default UI.

CustomUIRender Parameters

A function to fully customize the Hepsipay component's appearance. If provided, the default UI will not be shown; instead, the JSX returned by this function will be rendered.

Parameter	Type	Description
onSubmit	() => void	Callback to trigger payment when form is submitted.
control	any	Control object from react-hook-form, used to bind form inputs.
errors	any	Error object from react-hook-form, used for validation feedback.
frameUrl	string	URL of the Hepsipay iframe, provided from backend context data.

InitOptionsOverrides

initOptionsOverrides is an object used to partially override the default settings passed to the Hepsipay SDK's init function. This allows customization of many options such as iframe behavior and appearance, as well as callback functions.

Property	Type	Required	Description
frameUrl	string	Yes	The URL of the payment iframe
frameDivId	string	No	The ID of the HTML div where the iframe will be embedded.
paymentStatusCallback	(isPaymentAllowed: boolean) => void	No	Called when the payment status changes.
frameFailureCallback	() => void	No	Called if the iframe fails to load or an error occurs.
onPaymentSuccessCallback	(payload: any) => void	No	Callback function called when the payment is successfully completed.
maxHeight	string	No	Maximum height for the iframe (e.g., '800').
disableDynamicHeight	boolean	No	Enables or disables dynamic height adjustment for the iframe.
showFramePaymentButton	boolean	No	Shows or hides the payment button inside the iframe.
useApiCallOnSuccessCallback	boolean	No	Determines whether to perform an API call on payment success.
selectedPaymentInfoCallback	(payload: any) => void	No	Called when the selected payment information changes.
overrideFontFamily	string	No	Custom font family to be used inside the iframe.
hideHeader	boolean	No	Shows or hides the header section of the iframe.

Default Translations

{
   placeholderInput: 'PLACE ORDER',
   availableWarning:
     'Hepsipay is not available for this user. Please choose another payment method.',
   agreementError: 'This Field is Required'
 }

Update Payment Step

File Path:

views/checkout/steps/payment/index.tsx

import HepsiPay from './options/hepsipay';

export const PaymentOptionViews: Array<CheckoutPaymentOption> = [
  {
    slug: 'hepsipay',
    view: HepsiPay
  }
  // Other payment methods can be added here
];

Usage Examples

Default Usage

File Path:

views/checkout/steps/payment/options/hepsipay.tsx

import PluginModule, { Component } from '@akinon/next/components/plugin-module';
import CheckoutAgreements from '../agreements';

export default function Hepsipay() {
  return (
    <PluginModule
      props={{
        agreementCheckbox: (
          <CheckoutAgreements control={null} error={null} fieldId="agreement" />
        )
      }}
      component={Component.Hepsipay}
    />
  );
}

Custom UI Render Usage

import { Button } from '@/components/ui/button';
import { Icon } from '@/components/ui/icon';
import Script from 'next/script';

<PluginModule
 props={{
   customUIRender: ({ onSubmit, errors, control }) => (
     <>
       <div id="hepsipay-frame" data-testid="hepsipay-frame"></div>
       <form onSubmit={onSubmit}>
         <div className="flex items-start flex-col border-t border-solid border-gray-400 py-4 space-y-4">
           <CheckoutAgreements
             control={control}
             error={errors.agreement}
             fieldId="agreement"
           />
           <Button
             className="group uppercase mt-4 inline-flex items-center justify-center w-full"
             type="submit"
             data-testid="checkout-bank-account-place-order"
           >
             <span>Place Order</span>
             <Icon
               name="chevron-end"
               size={12}
               className="fill-primary-foreground ml-2 h-3 group-hover:fill-primary"
             />
           </Button>
         </div>
       </form>

       <Script
         src="https://images.hepsiburada.net/hepsipay/packages/pf/hepsipay-latest.min.js"
         defer
       />
     </>
   )
 }}
 component={Component.Hepsipay}
/>;