Payment Method Element Overview

The payment method element lets a subscriber replace the card their Subscription is charged with, inside your own page. Card data goes straight to Fungies; your page never handles it.

The element loads only on domains in your Authorized Domains list. The feature must also be enabled for your workspace: minting a session returns 403 until it is.

How it works

Your server mints a short-lived session for one subscription.
Your page passes that session to the JavaScript SDK, which opens the element as an overlay or inside a container you choose.
The customer enters a new card. Fungies saves it as the subscription's payment method.
The SDK fires a browser event on your page, and Fungies sends the subscription_payment_method_updated webhook to your server.

Mint a session

Call this from your backend. The secret key must never reach the browser.

curl -X POST "https://api.fungies.io/v0/subscriptions/L8VQK3N2M7KpQ9nR/paymentMethodSession" \
  -H "x-fngs-public-key: pub_your_public_key" \
  -H "x-fngs-secret-key: sec_your_secret_key"

{
  "status": "success",
  "data": {
    "sessionToken": "pmst_...",
    "expiresAt": 1790000000000,
    "url": "https://yourstore.fungies.io/payment-method-element"
  }
}

Field	What it is
`sessionToken`	Bearer token for this one subscription. Hand it to the SDK; never log it or put it in a URL.
`expiresAt`	When the token stops working at the latest (Unix time in milliseconds). Tokens live 15 minutes.
`url`	The page the SDK loads. It carries no token.

Mint a fresh token for each attempt rather than storing one. Minting is rate-limited per subscription and returns 429 over the limit. The subscription must be active, trialing, past_due, unpaid or paused; any other state returns 400.

Know when the card changed

In the browser: the SDK fires fungies:payment-method:updated. See JavaScript SDK.
On your server: subscribe your webhook to subscription_payment_method_updated. It carries the new method's type (plus brand and lastDigits for cards), and fires for every card change on a subscription that is not trialing, including ones made in the customer portal. It is not sent for any card change while the subscription is trialing. Deduplicate on setupIntentId.

Use the webhook for anything that must happen, like clearing a dunning flag. The browser event only fires while your page is open.

Payment Method Element Overview

How it works

Mint a session

Know when the card changed

On this page