use-payment-request

Collect payments with a typed Payment Request API wrapper.


Package	`@vizejs/composable/use-payment-request`
Own the source	`vize lib pull composable:use-payment-request`
Runtime exports	`usePaymentRequest`
Gzip budget	2304 B

Usage

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

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`usePaymentRequest`	capability	experimental	deterministic-fallback	caller-managed	caller, reactive-scope	web, desktop	`window`	`tryOnScopeDispose`

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.

Member	Type	Description
`currency`	`string`	ISO 4217 currency code.
`value`	`string`	Decimal amount, for example `"9.99"`.

`PaymentLineItem`

Line item shown on the payment sheet.

Member	Type	Description
`label`	`string`	Human-readable label.
`amount`	`PaymentAmount`	Amount.
`pending`?	`boolean`	Whether the amount is not final yet.

`PaymentShippingOption`

Selectable shipping option.

Member	Type	Description
`id`	`string`	Option id reported back in `shippingOption`.
`label`	`string`	Human-readable label.
`amount`	`PaymentAmount`	Price of the option.
`selected`?	`boolean`	Whether the option is preselected.

`PaymentMethod`

Accepted payment method.

Member	Type	Description
`supportedMethods`	`string`	Payment method identifier (URL or standardized name).
`data`?	`unknown`	Method-specific data.

`PaymentDetails`

Initial payment details.

Member	Type	Description
`id`?	`string`	Request id.
`total`	`PaymentLineItem`	Total amount.
`displayItems`?	`readonly PaymentLineItem[]`	Line items.
`shippingOptions`?	`readonly PaymentShippingOption[]`	Shipping options.

`PaymentDetailsUpdate`

Details passed to updateWith after a shipping change.

Member	Type	Description
`total`?	`PaymentLineItem`	Updated total.
`displayItems`?	`readonly PaymentLineItem[]`	Updated line items.
`shippingOptions`?	`readonly PaymentShippingOption[]`	Updated shipping options (empty to reject the address).
`error`?	`string`	Error message shown to the user.
`shippingAddressErrors`?	`Readonly<Record<string, string>>`	Per-field shipping address errors.

`PaymentRequestOptionsInit`

Payer information requested from the sheet.

Member	Type	Description
`requestPayerName`?	`boolean`	Request the payer name.
`requestPayerEmail`?	`boolean`	Request the payer email.
`requestPayerPhone`?	`boolean`	Request the payer phone.
`requestShipping`?	`boolean`	Request a shipping address.
`shippingType`?	`PaymentShippingType`	Shipping category.

`PaymentResponseLike`

Minimal PaymentResponse.

Member	Type	Description
`requestId`	`string`	Request id.
`methodName`	`string`	Method the payer chose.
`details`	`unknown`	Method-specific response data.
`payerName`?	`string \| null`	Payer name, when requested.
`payerEmail`?	`string \| null`	Payer email, when requested.
`payerPhone`?	`string \| null`	Payer phone, when requested.
`shippingAddress`?	`unknown`	Shipping address, when requested.
`shippingOption`?	`string \| null`	Selected shipping option id.
`complete`	`(result?: PaymentCompletion) => Promise<void>`	Close the sheet with an outcome.

`PaymentRequestLike`

Minimal PaymentRequest instance.

Member	Type	Description
`shippingAddress`?	`unknown`	Current shipping address.
`shippingOption`?	`string \| null`	Current shipping option id.
`canMakePayment`	`() => Promise<boolean>`	Whether a method can be used.
`show`	`() => Promise<PaymentResponseLike>`	Show the payment sheet (needs user activation).
`abort`	`() => Promise<void>`	Abort a showing sheet.

`PaymentShippingChange`

Context passed to shipping change hooks.

Member	Type	Description
`request`	`PaymentRequestLike`	Request that fired the change.
`shippingAddress`	`unknown`	Current shipping address.
`shippingOption`	`string \| null`	Current shipping option id.

`UsePaymentRequestOptions`

Options for usePaymentRequest.

Member	Type	Description
`methods`	`MaybeRefOrGetter<readonly PaymentMethod[]>`	Accepted payment methods. Reactive; read when a request is created.
`details`	`MaybeRefOrGetter<PaymentDetails>`	Payment details. Reactive; read when a request is created.
`paymentOptions`?	`MaybeRefOrGetter<PaymentRequestOptionsInit>`	Payer information to request.
`PaymentRequest`?	`MaybeRef<PaymentRequestHost \| null \| undefined>`	`PaymentRequest` constructor for alternate runtimes and tests. A ref (not a getter) because the host is a constructor function.
`onShippingAddressChange`?	`PaymentShippingChangeHook`	Called on `shippingaddresschange`.
`onShippingOptionChange`?	`PaymentShippingChangeHook`	Called on `shippingoptionchange`.

`PaymentRequestControls`

Reactive state and actions returned by usePaymentRequest.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether the Payment Request API is available.
`state`	`Readonly<ShallowRef<PaymentRequestState>>`	Sheet lifecycle.
`response`	`Readonly<ShallowRef<PaymentResponseLike \| undefined>>`	Most recent response, cleared when a new sheet is shown.
`error`	`Readonly<ShallowRef<unknown>>`	Most recent failure (not dismissals).
`canMakePayment`	`() => Promise<boolean>`	Whether the configured methods can be used.
`show`	`() => Promise<PaymentShowResult>`	Show the payment sheet. Aborts a sheet that is still showing.
`complete`	`(result?: PaymentCompletion) => Promise<boolean>`	Close the sheet after processing the response.
`abort`	`() => Promise<boolean>`	Abort the showing sheet.