<AccruPay> Provider

AccruPay is a React context provider that must wrap your entire checkout form. It fetches session configuration from the AccruPay public API, initializes the payment provider's SDK, and makes state available to child components via useAccruPay.

Props

Prop	Type	Required	Default	Description
merchantPublicId	string	yes	—	Your merchant public ID. Safe to include in client-side code.
children	ReactNode	yes	—	Your checkout form. Must contain the field components.
transactionSessionId	string	no	—	Session ID returned by your backend's session.start() call.
preloadProvider	TRANSACTION_PROVIDER	no	—	Initialize the provider SDK before a session exists.
environment	'production' | 'sandbox'	no	'production'	AccruPay API environment.
url	string	no	—	Override the AccruPay API base URL. Advanced use only.

Basic usage

import {
  AccruPay,
  CardholderName,
  CardNumber,
  CardExpiry,
  CardCVC,
  SubmitButton,
  useAccruPay,
} from '@accrupay/react';

export function Checkout({ sessionId }: { sessionId: string }) {
  return (
    <AccruPay
      merchantPublicId={process.env.NEXT_PUBLIC_ACCRUPAY_MERCHANT_ID!}
      transactionSessionId={sessionId}
    >
      <CheckoutForm />
    </AccruPay>
  );
}

function CheckoutForm() {
  const { isReady, error } = useAccruPay();

  return (
    <div>
      <CardholderName placeholder="Name on card" />
      <CardNumber />
      <CardExpiry />
      <CardCVC />
      {error && <p className="error">{error}</p>}
      <SubmitButton disabled={!isReady}>Pay now</SubmitButton>
    </div>
  );
}

transactionSessionId vs preloadProvider

Use transactionSessionId for standard checkout flows. Your backend creates a session, returns the ID to the browser, and you pass it here. The provider SDK initializes using the session's configuration.

Use preloadProvider when you want to initialize the provider SDK before the session exists — for example, while the user is still filling in cart or shipping details. This reduces perceived load time by the time the user reaches the payment step.

import { TRANSACTION_PROVIDER } from '@accrupay/node';

// Preload while user completes earlier steps
<AccruPay
  merchantPublicId={merchantId}
  preloadProvider={TRANSACTION_PROVIDER[process.env.ACCRUPAY_PROVIDER_TYPE as keyof typeof TRANSACTION_PROVIDER]}
>
  <CheckoutForm />
</AccruPay>

// Once the session is ready, swap in the session ID
<AccruPay
  merchantPublicId={merchantId}
  transactionSessionId={sessionId}
>
  <CheckoutForm />
</AccruPay>

note

When transactionSessionId is set, it takes precedence over preloadProvider and the provider is re-initialized with full session data.

Mount behavior

On mount, AccruPay requests session or provider configuration from the AccruPay public API. It then loads the payment provider's JavaScript SDK from the provider's CDN and initializes the embedded secure card fields.

isReady becomes true once all three card fields — CardNumber, CardExpiry, and CardCVC — have signaled that they are interactive. See useAccruPay for details.

Error states

If the session is not found, has expired, or the provider SDK fails to initialize:

• isReady stays false
• error is set to a descriptive string
• The form remains visible but submission is blocked

Always render the error value so users can see what went wrong.

function CheckoutForm() {
  const { isReady, error } = useAccruPay();

  return (
    <div>
      <CardholderName />
      <CardNumber />
      <CardExpiry />
      <CardCVC />
      {error && <p className="error">{error}</p>}
      <SubmitButton disabled={!isReady}>Pay now</SubmitButton>
    </div>
  );
}