SDK v3 Reference

Use this page when you need the exact browser SDK contract for Payment Element v3.

Load the SDK

<script src="https://js.pagou.ai/payments/v3.js"></script>

The script exposes window.Pagou.

Pagou.setEnvironment("sandbox");

Supported environments:

Environment	Use
`production`	Default. Uses production collection endpoints.
`sandbox`	Use for test public keys and sandbox transactions.
`local`	Local development only.

Initialize Elements

const elements = Pagou.elements({
  publicKey: "pk_test_your_public_key",
  locale: "en",
  origin: window.location.origin,
});

Options:

Option	Required	Description
`publicKey`	Yes before submit	Company public key. Use `pk_test_` in sandbox and `pk_live_` in production.
`locale`	No	Locale forwarded to the hosted card field. Defaults to `pt-BR`.
`origin`	No	Checkout origin stored on the Element session. Defaults to `window.location.origin`.

You can update an existing instance before submit:

elements.update({
  publicKey: "pk_live_your_public_key",
  locale: "en",
});

Create and mount the card field

<div id="card-element"></div>

const card = elements.create("card", {
  theme: "default",
  locale: "en",
});

card.mount("#card-element");

elements.create("card") creates one hosted card field. If a card field already exists on the same elements instance, the SDK unmounts it before creating the new one. Card options:

Option	Description
`theme`	`default`, `night`, or `flat`.
`locale`	Overrides the Elements locale for this card field.
`style`	Style object forwarded to the hosted field.
`mountTimeoutMs`	Mount timeout in milliseconds. Defaults to `8000`.
`telemetry`	Sends best-effort mount failure telemetry when supported. Defaults to `true`.

Card events

card.on("ready", () => {
  messageEl.textContent = "";
});

card.on("change", (event) => {
  submitButton.disabled = !event.valid;
  brandEl.textContent = event.brand ?? "";
  errorEl.textContent = Object.values(event.errors ?? {})[0] ?? "";
});

card.on("error", (event) => {
  errorEl.textContent = event.message;
});

Supported events:

Event	Payload	Use
`ready`	`{}`	Hosted iframe loaded and completed the SDK handshake.
`change`	`{ valid, brand, errors }`	Enable submit only when `valid` is `true`.
`error`	`{ code, message }`	Show initialization, mount, or card field errors.

Remove handlers during component teardown when the same card instance can stay alive:

card.off("change", handleCardChange);

Submit a payment

elements.submit(...) is the main SDK action. It creates an Element session, tokenizes the hosted card field, calls your createTransaction callback, completes any card authentication the payment requires, and resolves the final result.

const result = await elements.submit({
  createTransaction: async (tokenData) => {
    const response = await fetch("/api/pay", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        external_ref: "order_2001",
        amount: 2490,
        currency: "BRL",
        method: "credit_card",
        token: tokenData.token,
        installments: 1,
      }),
    });

    const payload = await response.json();
    return payload.data ?? payload;
  },
});

createTransaction receives:

{
  "token": "pgct_token_from_browser",
  "brand": "visa",
  "last4": "4242",
  "exp_month": "12",
  "exp_year": "2029"
}

Only send token to your backend as the payment credential. Treat brand, last4, exp_month, and exp_year as display or bookkeeping metadata.

Submit result

{
  "status": "pending",
  "transaction": {
    "id": "018f1f2e-7b43-7c9a-8d3e-1a2b3c4d5e70",
    "status": "pending"
  }
}

Possible status values include:

Status	Meaning
Transaction status	When nothing further is required, the SDK returns the transaction status from your backend response.
`completed`	Fallback when the backend response has no `status`.
`processing`	The payment is still resolving. Wait for webhook or reconciliation.
`requires_action`	Further action is required and automatic handling is disabled for the Element session.
`requires_reentry`	Returned by `resume()` when a pre-charge 3DS payment needs the card re-entered after a reload. Re-mount a `CardElement` and call `resume()` again with the same `transactionId`.
`succeeded`	The payment was approved.
`failed`	The payment failed, or required card authentication could not be completed.
`refused`	Card authentication was refused.
`canceled`	Buyer closed the authentication window.
`timed_out`	Authentication did not finish within the SDK timeout.
`error`	Tokenization, session creation, callback, or SDK flow failed.

Do not fulfill an order from the browser status alone. Use webhook delivery or server-side reconciliation as the final source of truth.

3D Secure

elements.submit(...) completes card authentication for you when the payment requires it, using the buyer and products your server already sends when it creates the transaction. You collect nothing extra in the browser. See 3D Secure. Return your transaction payload from the backend unchanged. If it asks for further action, the SDK detects it and continues the flow. If you already created the transaction server-side and only need the SDK to finish an action it reported, pass that action straight through:

const result = await Pagou.handleNextAction(transaction.next_action);

Or pass the transaction to an Elements instance:

const result = await elements.submit({
  transaction,
  createTransaction: async () => transaction,
});

Resume after a reload

If the page reloads or the buyer navigates away mid-payment, resume the same transaction instead of starting a new checkout attempt. resume() recreates the Element session from your public key, so it works even after a full page load.

const result = await elements.resume({
  transactionId: "018f1f2e-7b43-7c9a-8d3e-1a2b3c4d5e70",
});

Option	Required	Description
`transactionId`	Yes	Id of the transaction to resume.

resume() returns the same result shape as submit(). It picks up an outstanding action when one is still pending, returns the terminal status when the payment already finished, and returns processing when the outcome has not arrived yet. Persist the transaction id before the buyer can navigate away so you have it on the way back.

Card re-entry (auto-heal)

A payment that was waiting on card authentication (pre-charge 3DS) was bound to the Element session that captured the card; a reload starts a new session and the original challenge can no longer run. resume() self-heals this by default — the element/SDK owns the whole recovery, identical for hosted checkout and raw integrators. Your only responsibility: keep a CardElement mounted and call resume().

const card = elements.create("card");
card.mount("#card-element");

const result = await elements.resume({ transactionId }); // terminal result

On a stale-session pre-charge challenge, resume() asks the buyer to re-enter the card in the mounted element, re-tokenizes it under the current session, supersedes the stale challenge, runs the fresh one, and resolves to a terminal status. No new transaction is created.

Option	Required	Description
`manualReentry`	No	Opt out of auto-heal. `resume()` returns `status: "requires_reentry"` so you can run your own re-collect UX, then call `resume()` again.
`reentryTimeoutMs`	No	Auto-heal only. How long to wait for the buyer to re-enter the card. Defaults to 3 minutes.

Only the same card can supersede the payment — a different card is refused. With no card element mounted, or if the buyer does not re-enter within the timeout, resume() resolves to a clear terminal result telling the buyer to start a new payment attempt. It never loops or hangs.

Token mode

Pass a mode to submit to declare the caller’s intent and select the resulting token type:

`mode`	Token	When to use
`payment` (default)	single-use `pgct_`	One-off charge
`upsell`	reusable `pgpm_`	Initial purchase + one-click upsell
`subscription`	single-use `pgct_`	Card capture to start a subscription

// Upsell flow — same card charged twice (initial + upsell)
const result = await elements.submit({
  mode: "upsell",
  createTransaction: async (tokenData) => createPaymentWithToken(tokenData.token),
});

// Subscription flow
const result = await elements.submit({
  mode: "subscription",
  createTransaction: async (tokenData) => createSubscriptionWithToken(tokenData.token),
});

Cleanup

Unmount a card field when leaving the checkout screen:

card.unmount();

Destroy the Elements instance when the entire payment flow is gone:

elements.destroy();

Production rules

Use pk_test_* only with Pagou.setEnvironment("sandbox").
Use pk_live_* with the default production environment.
Never send raw card data to your backend.
Never log pgct_* or pgpm_* tokens, or card data.
Disable duplicate submits while elements.submit(...) is running.
Persist the transaction id so you can resume(...) after a reload.
Return your transaction payload from the backend without removing id, status, or next_action.
Treat browser status as provisional until webhook or reconciliation confirms the final payment state.

Start with Payment Element

Build a Card Checkout

Launch and Migrate

Load the SDK

Initialize Elements

Create and mount the card field

Card events

Submit a payment

Submit result

3D Secure

Resume after a reload

Card re-entry (auto-heal)

Token mode

Cleanup

Production rules

​Load the SDK

​Initialize Elements

​Create and mount the card field

​Card events

​Submit a payment

​Submit result

​3D Secure

​Resume after a reload

​Card re-entry (auto-heal)

​Token mode

​Cleanup

​Production rules

Load the SDK

Initialize Elements

Create and mount the card field

Card events

Submit a payment

Submit result

3D Secure

Resume after a reload

Card re-entry (auto-heal)

Token mode

Cleanup

Production rules