Call createPayment from your backend with a Payment Type:

backend.ts

↓

Copy

const { createPayment } = await fragment.createPayment({
  ik: orderId,
  ledgerIk: 'main',
  type: 'card_payin',
  typeVersion: 1,
  parameters: {
    amount: '4999',
  },
});

if (createPayment.__typename !== 'CreatePaymentResult') {
  throw new Error(createPayment.message);
}

return { payment: createPayment.payment };

Copy

The Payment starts in needs_payment_method. No money moves until the customer confirms the card.

Use FRAGMENT's frontend SDK to render a checkout form.

Pass the Payment and the customer's email in billingDetails.email as props to the component. Mount Checkout within PaymentElements:

import {
  Checkout,
  PaymentElements,
  type Payment,
} from '@fragment-dev/payment-elements';
import { PayButton } from './PayButton';

const CheckoutPage = ({
  payment,
  email,
  onSuccess,
}: {
  payment: Payment;
  email: string;
  onSuccess: () => void;
}) => (
  <PaymentElements>
    <Checkout
      payment={payment}
      billingDetails={{ email }}
      onError={(message) => console.error('Payment failed:', message)}
      onConfirmed={onSuccess}
    >
      <PayButton />
    </Checkout>
  </PaymentElements>
);

Implement a Pay button. Call confirm() to charge the card when canConfirm is true:

import { usePayment } from '@fragment-dev/payment-elements';

export const PayButton = () => {
  const { confirm, canConfirm, isConfirming, isLoading, error } = usePayment();
  return (
    <>
      <button
        type="button"
        disabled={isLoading || !canConfirm || isConfirming}
        onClick={() => canConfirm && confirm()}
      >
        Pay
      </button>
      {error && <p role="alert">{error}</p>}
    </>
  );
};

The SDK calls onConfirmed after it charges the card. On a failure, it calls onError.

Enable savePaymentMethod on the Checkout component to save a user's card when the payment confirms:

const CheckoutPage = ({ payment, email }: { payment: Payment; email: string }) => {
  const [saveCard, setSaveCard] = useState(false);
  return (
    <Checkout
      payment={payment}
      billingDetails={{ email }}
      savePaymentMethod={saveCard}
      onError={logError}
      onConfirmed={showReceipt}
    >
      <SaveCardCheckbox checked={saveCard} onChange={setSaveCard} />
      <PayButton />
    </Checkout>
  );
};

Render a checkbox for the payer to choose during checkout:

Saved cards are tied to the user's email provided in billingDetails.email.

Save a user's card during onboarding to charge them later in a couple of steps:

1. Create a PaymentMethodSetup via the API
2. Pass the response to FRAGMENT's SavePaymentMethod component

Call createPaymentMethodSetup from your backend:

backend.ts

↓

Copy

const { createPaymentMethodSetup } = await fragment.createPaymentMethodSetup({
  ik: requestId,
  ledgerIk: 'main',
  email,
});

if (createPaymentMethodSetup.__typename !== 'CreatePaymentMethodSetupResult') {
  throw new Error(createPaymentMethodSetup.message);
}

return { paymentMethodSetup: createPaymentMethodSetup.paymentMethodSetup };

Copy

Pass the returned PaymentMethodSetup to your frontend. Render SavePaymentMethod from FRAGMENT's frontend SDK inside PaymentElements to display the card form:

Implement a Save button. Call submit() from usePaymentMethodSetup() when canSubmit is true:

import {
  PaymentElements,
  SavePaymentMethod,
  usePaymentMethodSetup,
  type PaymentMethodSetup,
} from '@fragment-dev/payment-elements';

const SaveButton = () => {
  const { submit, canSubmit, state, error } = usePaymentMethodSetup();
  return (
    <>
      <button type="button" disabled={!canSubmit} onClick={() => void submit()}>
        {state.status === 'processing' ? 'Saving…' : 'Save card'}
      </button>
      {state.status === 'declined' && <p role="alert">{state.message}</p>}
      {error && <p role="alert">{error.message}</p>}
    </>
  );
};

export const SaveCardPage = ({ setup }: { setup: PaymentMethodSetup }) => (
  <PaymentElements>
    <SavePaymentMethod
      paymentMethodSetup={setup}
      onPaymentMethodSaved={showConfirmation}
      onPaymentMethodDeclined={showDecline}
      onError={logError}
    >
      <SaveButton />
    </SavePaymentMethod>
  </PaymentElements>
);

The SDK calls onPaymentMethodSaved after it saves the card, and onPaymentMethodDeclined when the card is declined. Any other failure calls onError.

Call createPayment with the saved card's id in paymentMethod to make a payment from your backend:

backend.ts

↓

Copy

const { createPayment } = await fragment.createPayment({
  ik: renewalId,
  ledgerIk: 'main',
  type: 'card_payin',
  typeVersion: 1,
  parameters: {
    amount: '4999',
  },
  paymentMethod: { id: savedCardId },
});

Copy

The Payment starts in processing and follows the same lifecycle as a checkout Payment.

Call deletePaymentMethod with the saved card's id. After the call, the card can no longer be charged:

backend.ts

↓

Copy

await fragment.deletePaymentMethod({
  id: savedCardId,
});

Copy