ArcenEmbed reference

ArcenEmbed is a drop-in billing surface that renders checkout, portal, plan management, and payment flows. Configure it in the dashboard and render it anywhere in your React app.

Props

Prop	Type	Default	Description
`mode`	`"modal"` \	`"inline"`	`"modal"`	Display as a full-screen overlay or inline element.
`initialView`	`"portal"` \	`"checkout"` \	`"payment"` \	`"unsubscribe"` \	`"success"`	`"portal"`	Starting view.
`accessToken`	`string`	—	Server-minted JWT. When set, `ArcenPayProvider` context is skipped for this embed.
`componentId`	`string`	Provider default	Override the component ID from the dashboard.
`onViewChange`	`(view) => void`	—	Called whenever the embed switches views.
`onPlanChange`	`(planId: string) => void`	—	Called when a customer picks a different plan in checkout or portal.
`hideBranding`	`boolean`	`false`	Hides the “Secured by ArcenPay” footer. Use for first-party or white-label embeds.
`className`	`string`	—	Additional CSS classes for the wrapper.
`style`	`React.CSSProperties`	—	Inline styles for the wrapper.

Views

Portal (`initialView="portal"`)

The default view. Shows the customer’s active plan, usage meters, add-on status, and invoice history. From here, customers can upgrade, downgrade, cancel, or pay invoices.

<ArcenEmbed mode="inline" initialView="portal" />

Checkout (`initialView="checkout"`)

Shows plan selection and payment flow for new subscriptions or upgrades. Use when a new customer needs to pick a plan:

<ArcenEmbed mode="modal" initialView="checkout" />

Unsubscribe (`initialView="unsubscribe"`)

Shows the self-serve cancellation flow with confirmation:

<ArcenEmbed mode="modal" initialView="unsubscribe" />

Payment (`initialView="payment"`)

Shows the payment confirmation and token approval screen. Typically used when you need to pre-select a plan and skip the selection step:

<ArcenEmbed mode="modal" initialView="payment" />

When mode="modal", ArcenEmbed renders as a full-screen overlay automatically — no separate open prop is needed. Render it conditionally when the customer should see it:

import { useState } from "react";
import { ArcenEmbed } from "@arcenpay/react";

function BillingButton() {
  const [showBilling, setShowBilling] = useState(false);

  return (
    <>
      <button onClick={() => setShowBilling(true)}>Manage Billing</button>
      {showBilling && (
        <ArcenEmbed
          mode="modal"
          onViewChange={(view) => {
            if (view === "success") {
              setShowBilling(false);
              window.location.reload();
            }
          }}
        />
      )}
    </>
  );
}

Inline mode

When mode="inline", ArcenEmbed renders as part of the page layout:

<div className="grid grid-cols-3 gap-8">
  <div className="col-span-2">
    <h1>Settings</h1>
    {/* App settings form */}
  </div>
  <aside>
    <h2>Your Plan</h2>
    <ArcenEmbed mode="inline" initialView="portal" />
  </aside>
</div>

Server-issued tokens

For stronger security, mint a token on your backend and pass it to ArcenEmbed. When accessToken is set, the embed uses it directly — no ArcenPayProvider session is needed for this instance:

// Server: mint token
const session = await client.identify({
  company: { id: "company_123", wallet: "0xabc..." },
  user: { id: "user_123", wallet: "0xabc..." },
  expiresIn: 3600,
});

return { token: session.token };

// Client: pass token
<ArcenEmbed
  accessToken={token}
  componentId="cmp_123"
  mode="modal"
  initialView="portal"
/>

Handling success

Watch the view change to "success" to run logic after a payment or activation completes:

<ArcenEmbed
  mode="modal"
  onViewChange={(view) => {
    if (view === "success") {
      // Refresh entitlements
      router.refresh();
      // Or navigate to a success page
      router.push("/billing/success");
    }
  }}
/>

Embedded components integration — configuration and workflow guide
Customer portal — building a self-serve billing center
Sessions — when to use server-issued tokens

React SDK

Node.js SDK

Agent SDK

ArcenEmbed reference

Props

Views

Portal (`initialView="portal"`)

Checkout (`initialView="checkout"`)

Unsubscribe (`initialView="unsubscribe"`)

Payment (`initialView="payment"`)

Inline mode

Server-issued tokens

Handling success

​Props

​Views

​Portal (initialView="portal")

​Checkout (initialView="checkout")

​Unsubscribe (initialView="unsubscribe")

​Payment (initialView="payment")

​Modal mode

​Inline mode

​Server-issued tokens

​Handling success

​Related

Props

Views

Portal (`initialView="portal"`)

Checkout (`initialView="checkout"`)

Unsubscribe (`initialView="unsubscribe"`)

Payment (`initialView="payment"`)

Modal mode

Inline mode

Server-issued tokens

Handling success

Related