use-payment-request

Collect payments with a typed Payment Request API wrapper.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { usePaymentRequest } from "@vizejs/composable/use-payment-request";

Try it

Offer the browser payment sheet

Check whether the reader can pay with a browser payment method before offering it.

Open the interactive example

What to observe: Check payment options reports whether a saved method is available; otherwise the example points to the regular checkout.

show() opens the sheet and complete() closes it after your server confirms. Always keep a regular checkout. Every example renders a neutral message until it mounts, so server and client markup match, and then explains what to do when the browser lacks the API.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { ref } from "vue";
import { useMounted } from "@vizejs/composable/use-mounted";
import { usePaymentRequest } from "@vizejs/composable/use-payment-request";

const mounted = useMounted();
const { supported, canMakePayment } = usePaymentRequest({
  methods: [{ supportedMethods: "https://google.com/pay" }],
  details: { total: { label: "Workshop ticket", amount: { currency: "EUR", value: "49.00" } } },
});
const available = ref<boolean>();

async function check() {
  available.value = await canMakePayment();
}
</script>

<template>
  <div class="composable-example">
    <p>Offer a browser payment sheet only when the reader can pay with it.</p>
    <button type="button" :disabled="!mounted || !supported" @click="check">
      Check payment options
    </button>
    <output aria-live="polite">{{
      !mounted
        ? "Checking browser support…"
        : !supported
          ? "The Payment Request API is not available; show your regular checkout."
          : available === undefined
            ? "Payment Request is available."
            : available
              ? "The reader can pay with the browser's payment sheet."
              : "No saved payment method; show your regular checkout."
    }}</output>
  </div>
</template>

Runtime contract

API

usePaymentRequest

Collect payments with a typed Payment Request API wrapper. Every show() constructs a fresh request from the reactive methods, details, and paymentOptions, wires the shipping hooks (which call updateWith synchronously when they return an update), and resolves to a discriminated PaymentShowResult. Call complete() after processing a "completed" result. A showing sheet is aborted when the owning reactive scope stops; outside a scope call abort(). Server rendering: nothing is constructed, supported is false and state is "idle". Inside a component supported turns true only after mounting, so hydration renders this server state first.

function usePaymentRequest(options: UsePaymentRequestOptions): PaymentRequestControls

const payment = usePaymentRequest({ methods, details: { total } });
const result = await payment.show();
if (result.status === "completed") await payment.complete(await charge(result.response));

Types

PaymentAmount

Monetary amount.

PaymentLineItem

Line item shown on the payment sheet.

PaymentShippingOption

Selectable shipping option.

PaymentMethod

Accepted payment method.

PaymentDetails

Initial payment details.

PaymentDetailsUpdate

Details passed to updateWith after a shipping change.

PaymentRequestOptionsInit

Payer information requested from the sheet.

PaymentResponseLike

Minimal PaymentResponse.

PaymentRequestLike

Minimal PaymentRequest instance.

PaymentShippingChange

Context passed to shipping change hooks.

UsePaymentRequestOptions

Options for usePaymentRequest.

PaymentRequestControls

Reactive state and actions returned by usePaymentRequest.