Payment Elements (SDK)

Payment Elements is a React SDK that renders the payment-method form for one payment intent and confirms it from the browser. Your server creates the intent and hands the clientSecret to the page; the SDK does the rest. You keep full control of the surrounding checkout UI, including the email, name, and billing-address fields. Requires React 18 or 19.

npm install @slashfi/elements-react

Overview

Your server calls POST /payments/payment-intent and returns the clientSecret to the browser. The secret is scoped to that one intent and is only issued on the create response; the SDK uses it both to load the intent and to confirm the payment on the buyer’s behalf.
Wrap your checkout in <PaymentProvider clientSecret={...}>, render <PaymentElement /> where the payment-method form should appear, and render the required <BrandingElement />.
Collect email, name, and billing address in your own fields, then call confirm() from usePaymentElements().
Treat the result as “the buyer is done”, not “the payment settled”. Fulfill from your server when the intent’s status becomes succeeded, via the payments.payment_intent.updated webhook.

Components

`<PaymentProvider>`

Loads the payment intent for the given clientSecret and provides state to everything inside it. Render one provider per payment intent.

Prop	Type	Description
`clientSecret`	`string`	Required. From the `POST /payments/payment-intent` response. Changing it remounts the provider’s children with fresh, isolated state.
`locale`	`string \| 'auto'`	Optional BCP 47 locale for the payment form (for example `"en"`, `"fr"`). Unsupported values and `'auto'` fall back to English.
`children`	`ReactNode`	Your checkout UI.

The provider is safe to render on the server: it emits non-interactive placeholders until it runs in the browser.

`<PaymentElement>`

The payment-method form. Renders the card input and any wallets enabled for your account. Billing details are not collected here; you own those fields and pass them to confirm(). The element reports its completeness to the provider, which drives canConfirm.

`<BrandingElement>`

Renders the required payment-processing attribution.

<BrandingElement /> is required. It must be rendered inside the <PaymentProvider> on every page that renders <PaymentElement />. Payments from pages that omit it will be blocked. Place it near your pay button.

React hooks

`usePaymentElements()`

Returns the current PaymentInitializationState. Must be called inside a <PaymentProvider>. The state is a discriminated union on state:

`state`	Fields	Meaning
`'loading'`	—	The payment intent is being loaded. Show a spinner and keep the pay button disabled.
`'error'`	`error: PaymentInitializationError`	The form could not be initialized. See Initialization errors.
`'ready'`	`canConfirm`, `confirm()`, `fetchUpdates()`	The form is mounted and interactive.

In the 'ready' state:

canConfirm: boolean — true once the buyer has filled in a complete payment method. Bind your pay button’s disabled to !canConfirm.
confirm(input): Promise<PaymentResult> — see Static methods.
fetchUpdates(): Promise<void> — see Static methods.

Static methods

Available on the 'ready' state returned by usePaymentElements().

`confirm()`

Tokenizes the payment method, confirms the intent, and runs any buyer step (such as 3-D Secure) inline. Resolves to a PaymentResult once the buyer is done or the attempt failed. Takes a single object with the buyer details you collected. Missing or malformed fields are rejected before any network call with a validation_error listing each offending field.

string

required

Buyer’s email.

string

required

Buyer’s name as it appears on the card.

object

required

Billing address for the payment method.

Show properties

string

required

Street address.

string

Apartment, suite, or unit.

string

City.

string

State, province, or region.

string

required

Postal or ZIP code.

string

required

ISO 3166-1 alpha-2 country code, for example "US".

string

https:// URL the buyer is sent back to if a payment method requires a full-page redirect. Provide it if you enable wallets or redirect-based methods.

`fetchUpdates()`

Reloads the intent’s current amount, currency, and allowed payment methods. Call it after your server changes the intent (for example after applying a discount) so the form reflects the new amount, and after a payment_intent_updated error before asking the buyer to confirm again. Overlapping calls share one request.

Results and errors

`PaymentResult`

confirm() never throws for payment outcomes; it resolves to exactly one of:

`type`	Fields	Meaning
`'processing'`	`paymentIntentId: string`	The buyer’s step is complete (including any redirect handoff). This is not a settlement guarantee. Leave the checkout, and let your server fulfill on `status: "succeeded"`. Do not start another attempt on this intent.
`'error'`	`error: PaymentError`	Confirmation did not complete. Show `error.message` and let the buyer try again where the error allows it (see below).

Repeated confirm() calls for the same intent while one is in flight share the same pending promise.

`PaymentError`

`type`	`code`	Retryable?	Meaning
`validation_error`	`invalid_customer_details`	Yes	One or more `confirm()` input fields are missing or invalid. `issues[]` lists `{ field, code: 'missing' \| 'invalid', message }` per field, with `field` values such as `email`, `name`, `billingAddress.postalCode`, `returnUrl`.
`payment_error`	`payment_method_declined`	Yes	The card was declined. `declineCode` may carry the network reason. The intent returns to `pending`; the buyer can try another card.
`payment_error`	`payment_failed`	Yes	The payment attempt failed for a non-decline reason.
`invalid_request_error`	`invalid_client_secret`	No	The `clientSecret` is wrong or no longer valid. Create a new payment intent.
`invalid_request_error`	`payment_intent_updated`	Yes, after `fetchUpdates()`	The intent changed on the server since the form loaded (for example the amount). Call `fetchUpdates()` and ask the buyer to confirm again.
`invalid_request_error`	`terminal_payment_intent`	No	The intent is already `succeeded` or `canceled`.
`api_error`	`unknown`	Check server first	A network or provider error. The attempt may still be locked server-side, so read the intent from your server before retrying.

Initialization errors

When usePaymentElements() returns state: 'error', error is a PaymentInitializationError:

`type`	`code`	Meaning
`invalid_request_error`	`invalid_client_secret`	The `clientSecret` is wrong or expired.
`invalid_request_error`	`terminal_payment_intent`	The intent is already `succeeded` or `canceled` and cannot be paid.
`api_error`	`load_failed`	The payment form assets could not be loaded.
`api_error`	`unknown`	Any other failure while loading the intent.

Full example

import { useState } from 'react';
import {
  BrandingElement,
  PaymentElement,
  PaymentProvider,
  usePaymentElements,
  type PaymentError,
} from '@slashfi/elements-react';

function CheckoutForm() {
  const payment = usePaymentElements();
  const [email, setEmail] = useState('');
  const [name, setName] = useState('');
  const [postalCode, setPostalCode] = useState('');
  const [error, setError] = useState<PaymentError | null>(null);
  const [submitting, setSubmitting] = useState(false);

  if (payment.state === 'loading') return <p>Loading…</p>;
  if (payment.state === 'error') return <p>{payment.error.message}</p>;

  async function handlePay() {
    setSubmitting(true);
    setError(null);

    const result = await payment.confirm({
      email,
      name,
      billingAddress: { line1: '123 Main St', postalCode, country: 'US' },
      returnUrl: 'https://merchant.example/checkout/complete',
    });

    setSubmitting(false);

    if (result.type === 'error') {
      setError(result.error);
      return;
    }

    // The buyer is done. Your server fulfills when the intent is `succeeded`.
    window.location.assign(`/orders/pending?pi=${result.paymentIntentId}`);
  }

  return (
    <>
      <input value={email} onChange={(e) => setEmail(e.target.value)} placeholder="Email" />
      <input value={name} onChange={(e) => setName(e.target.value)} placeholder="Name on card" />
      <input value={postalCode} onChange={(e) => setPostalCode(e.target.value)} placeholder="ZIP" />

      <PaymentElement />

      {error && <p role="alert">{error.message}</p>}

      <button
        type="button"
        disabled={!payment.canConfirm || submitting}
        onClick={() => void handlePay()}
      >
        Pay
      </button>

      {/* Required. Payments are blocked if this is not rendered. */}
      <BrandingElement />
    </>
  );
}

export function Checkout({ clientSecret }: { clientSecret: string }) {
  return (
    <PaymentProvider clientSecret={clientSecret}>
      <CheckoutForm />
    </PaymentProvider>
  );
}

Gotchas

processing is not success. Confirmation resolving means the buyer’s part is over. Settlement happens asynchronously; the only signal to fulfill on is the intent’s status reaching succeeded, read from your server. Never grant goods or services based on a browser-side result alone.
Declines are retryable in place. A payment_method_declined result returns the intent to pending, so the buyer can enter another card and confirm() again without a new intent.
After an api_error, check before retrying. The attempt may still hold the intent’s processing lock. Read the intent from your server; if it is pending, the buyer can retry.
Redirect-based methods. If the payment method sends the buyer to another page, confirm() resolves processing at the moment of handoff and the buyer returns to returnUrl. Treat that landing page like any other post-checkout page: wait for the webhook.
One intent per provider. To switch intents, render a new <PaymentProvider> with the new clientSecret; state does not carry over.

Payment Processing

Entities

Payment Intent

Refund

Payment Elements (SDK)

Overview

Components

`<PaymentProvider>`

`<PaymentElement>`

`<BrandingElement>`

React hooks

`usePaymentElements()`

Static methods

`confirm()`

`fetchUpdates()`

Results and errors

`PaymentResult`

`PaymentError`

Initialization errors

Full example

Gotchas

​Overview

​Components

​<PaymentProvider>

​<PaymentElement>

​<BrandingElement>

​React hooks

​usePaymentElements()

​Static methods

​confirm()

​fetchUpdates()

​Results and errors

​PaymentResult

​PaymentError

​Initialization errors

​Full example

​Gotchas

Overview

Components

`<PaymentProvider>`

`<PaymentElement>`

`<BrandingElement>`

React hooks

`usePaymentElements()`

Static methods

`confirm()`

`fetchUpdates()`

Results and errors

`PaymentResult`

`PaymentError`

Initialization errors

Full example

Gotchas