fluveo.js

fluveo.js is the one script Fluveo gives the browser. It puts the payment form on your own page, confirms the payment and reads how it ended. The form is a frame of Fluveo's, so your page never holds a card number. Custom checkout builds a whole checkout with it, step by step. Payment Element explains the form itself: its payment methods, its layouts, its look and its options.

Load the script#

<script src="https://elements.fluveo.com/v1/"></script>

The script defines the global Fluveo. Load it from this address on every page that uses it, never from a copy: it makes no network call of its own, sets no cookie, and holds no card code. A test key works on any page, http://localhost included. A live key needs an https page.

A page that sends a Content-Security-Policy needs two entries for the form, and nothing else:

Content-Security-Policy: script-src https://elements.fluveo.com; frame-src https://elements.fluveo.com

npm packages#

A page with no build step needs only the script tag of Load the script. With a bundler or React, install two packages. They only load that same script, so they hold no card code, and a checkout needs no other payments package.

npm install @fluveo/fluveo-js @fluveo/react-fluveo-js

@fluveo/fluveo-js has loadFluveo() and the TypeScript types of the script. @fluveo/react-fluveo-js has the components Elements and PaymentElement and the hooks useFluveo() and useElements(), for React 16.8 or newer.

loadFluveo(publishableKey) adds the script tag to the page once and resolves with the object that Fluveo(publishableKey) returns. It uses the script the page already loaded with a script tag, when there is one. On a server, where there is no window, it resolves with null. It rejects when the script cannot load, and with the error of a key that Fluveo() refuses.

import { loadFluveo } from "@fluveo/fluveo-js";

const fluveo = await loadFluveo("pk_test_...");
const elements = fluveo.elements({ clientSecret });

In React, call loadFluveo() once per page and give what it returns, the promise itself, to <Elements>.

A prop that a component does not take throws wrong_prop, and a part used outside <Elements> throws elements_provider_missing. The React tab of Custom checkout is a whole checkout written with both packages.

Fluveo(publishableKey)#

Returns the object the other calls hang on. publishableKey is your pk_test_... or pk_live_... key. It throws on a secret key, a restricted key or a webhook secret, on anything that is not a publishable key, and when the script was not loaded from its own address.

const fluveo = Fluveo("pk_test_...");

fluveo.elements(options)#

Starts the form for one PaymentIntent and returns an elements group.

It also takes appearance, locale and loader: see Form options.

const elements = fluveo.elements({ clientSecret });

A group made with mode has no PaymentIntent: see Mount the form before its PaymentIntent.

The payment element#

The payment element is the form: the card number, the expiration date and the security code, the country and, for the US, Puerto Rico, Canada and the UK, the postal code. Each error shows once: a field's under that field and a declined card's under the card number, or, with condensed inputs, all of them under the block of fields. It shows a placeholder of its own size while it loads, takes its container's width and sets its own height.

elements.create("payment") also takes layout, fields and defaultValues: see Form options.

Every handler gets one object with elementType: "payment".

Your page learns complete and empty and nothing else of the card: no digit, no brand, no last four. Enable your Pay button on complete when you want to.

const element = elements.create("payment");
element.on("change", (event) => {
  document.getElementById("submit").disabled = !event.complete;
});
element.mount("#payment-element");

Form options#

Every option here is optional: the form works with clientSecret alone. A name or a value that an option does not take throws option_not_supported, and its message lists what the option takes.

const elements = fluveo.elements({
  clientSecret,
  appearance: {
    theme: "night",
    labels: "floating",
    variables: { colorPrimary: "#0f766e", borderRadius: "8px" },
  },
});

const elements = fluveo.elements({ clientSecret, locale: "pt-BR" });

const elements = fluveo.elements({ clientSecret, loader: "never" });

const element = elements.create("payment", {
  layout: { type: "accordion", defaultCollapsed: true, spacedAccordionItems: true },
});

const element = elements.create("payment", {
  fields: { billingDetails: { address: { postalCode: "never" } } },
});

const element = elements.create("payment", {
  defaultValues: { billingDetails: { address: { country: "US", postal_code: "94107" } } },
});

elements.update(options)#

Changes a group that is already made, before or after its form is mounted.

locale and fonts throw not_available_yet. Any other name, clientSecret and mode among them, throws option_not_supported. For another language or another PaymentIntent, call fluveo.elements() again.

elements.update({ appearance: { theme: "flat", inputs: "condensed" } });

element.update(options)#

Changes a payment element that is already made. It takes layout, as elements.create() does: the card fields keep what the buyer typed, and a method the buyer opened stays open.

fields and defaultValues throw not_available_yet: elements.create() reads them once. Any other name throws option_not_supported. For other fields, call element.destroy() and create the element again.

element.update({ layout: { type: "accordion", radios: "always" } });

fluveo.confirmPayment(options)#

Confirms the PaymentIntent with what the buyer typed. Call it when the buyer presses your Pay button. A second call while one is running returns the first call's promise, so a double press pays once.

The promise never rejects for a payment that fails. What happens next depends on how the payment ended:

After an error the form stays usable: the buyer corrects the card or types another, and the next confirmPayment() confirms the same PaymentIntent. The form itself shows the message of a card_error or a validation_error, so showing error.message yourself is your choice.

const { error } = await fluveo.confirmPayment({
  elements,
  confirmParams: { return_url: location.origin + "/complete" },
});
if (error) document.getElementById("error-message").textContent = error.message;

The error object#

An error of the API also carries message, param, doc_url and payment_intent when the API sent them.

The return address#

Fluveo adds three parameters to return_url, in place of any parameter of the same name:

redirect_status is a hint for the page. Read the PaymentIntent to show the buyer how the payment ended, and mark the order paid only on the payment_intent.succeeded webhook.

Mount the form before its PaymentIntent#

fluveo.elements() takes { mode: "payment", amount, currency } in place of clientSecret. The form mounts with your publishable key alone, and your server creates the PaymentIntent when the buyer presses Pay. Use it when the amount can change while the form is on the page; with a settled amount, clientSecret is the shorter way.

1. fluveo.elements({ mode: "payment", amount, currency }) makes the group, with amount in the smallest unit of the currency. Mounting creates nothing. A payment your account cannot take comes as the loaderror event.
2. elements.update({ amount, currency }) sets the cart's new amount.
3. At the press of Pay, await elements.submit() first. It checks the fields, shows their errors and sends nothing. It resolves with {}, or with { error }, a validation_error: stop there. Before mount() it throws submit_not_mounted.
4. Your server creates the PaymentIntent and gives the page its client_secret.
5. fluveo.confirmPayment({ elements, clientSecret, confirmParams }) confirms it and ends as confirmPayment() says. Without clientSecret it throws confirm_client_secret_missing, and without the submit() of its press, submit_required.

const fluveo = Fluveo("pk_test_...");
const elements = fluveo.elements({ mode: "payment", amount: 2000, currency: "usd" });
elements.create("payment").mount("#payment-element");

document.getElementById("payment-form").addEventListener("submit", async (event) => {
  event.preventDefault();
  const { error: invalid } = await elements.submit();
  if (invalid) return;

  const { clientSecret } = await fetch("/create-payment-intent", { method: "POST" })
    .then((r) => r.json());
  const { error } = await fluveo.confirmPayment({
    elements,
    clientSecret,
    confirmParams: { return_url: location.origin + "/complete" },
  });
  if (error) document.getElementById("error-message").textContent = error.message;
});

The buyer pays the PaymentIntent's amount, whatever the group holds. A PaymentIntent in another currency than the group's is not paid: confirmPayment() resolves { error } with the code currency_mismatch. After a decline the next press runs the whole handler again. Disable Pay while it runs.

fluveo.retrievePaymentIntent(clientSecret)#

Reads a PaymentIntent by its client secret, as the return page does. It resolves with { paymentIntent } or { error }.

const clientSecret = new URLSearchParams(location.search).get("payment_intent_client_secret");
const { paymentIntent, error } = await fluveo.retrievePaymentIntent(clientSecret);

The PaymentIntent in the browser#

The PaymentIntent that fluveo.js returns, from retrievePaymentIntent() and from confirmPayment(), holds only what a buyer may see:

It never holds metadata, customer or latest_charge. Read those on your server with the secret key.

Errors in your code#

A mistake in the code that calls fluveo.js throws at the call, as a FluveoIntegrationError with a code and a doc_url. Nothing is ignored in silence: an option or a call the script does not have throws an error that names it. fluveo.js errors has the cause and the fix of each code.

Test mode#

With a test key, the form shows a Test mode line with the card 4242 4242 4242 4242, and the first mount prints one line to the browser console with the PaymentIntent's id, or deferred_intent for a form made with mode, its payment methods and your page's origin. Testing lists the card numbers to type for a decline and for 3D Secure.

For a browser test, the form is the frame with the title Fluveo payment form, the card fields are frames in its slots #card-number, #card-expiry and #card-cvc, and the postal code is its input #postal. Custom checkout has a function that types into them. retrievePaymentIntent() adds one hidden frame with the title Fluveo payment status.

Next#