Customer Details & Shipping

Collect contact and billing details

Set the fields to collect when creating a hosted session or embedded payment:

customerCollection: {
	email: 'required',
	name: 'optional',
	phone: 'optional',
	billingAddress: 'none',
}

• Each field accepts none, optional, or required.
• An omitted policy or null uses merchant defaults. An explicit object sets omitted fields to none, and {} disables collection.
• Prefill values through customer.email, name, phone, billingAddress, and shippingAddress.

Read accepted details from customer on session or payment status reads. These are shopper-supplied details, not verified identity.

Offer fixed delivery options

Pass shippingOptions when creating the payment or hosted session:

shippingOptions: {
	dynamic: false,
	options: [{
		id: 'standard',
		label: 'Standard delivery',
		price: 300,
		amount: 1500,
		tax: 200,
		countries: ['CZ', 'SK'],
	}],
}

The form and the wallet sheets collect a delivery address and offer the matching options. Without shippingOptions, the creation amount stays fixed.

If a quote changes the displayed total during submission, card checkout asks the shopper to review the new amount and select Pay again. Read the selected option and revision through shippingQuote.

Approve dynamic delivery

When delivery depends on the address, set dynamic: true and approve each quote revision from your server. Embedded Checkout asks through browser handlers; Hosted Checkout calls your server directly.

import type { ShippingChangeEvent } from '@tapayadot/checkout/client'

const approveDelivery = async (event: ShippingChangeEvent) => {
	const response = await fetch('/api/delivery', {
		method: 'POST',
		headers: { 'content-type': 'application/json' },
		body: JSON.stringify(event),
	})
	if (!response.ok) throw new Error('Delivery could not be approved.')
}

const payment = browserTapaya.createPayment({
	clientSecret,
	wallets: { amount: 1200, currency: 'EUR', shippingRequired: true },
	onShippingAddressChange: approveDelivery,
	onShippingOptionChange: approveDelivery,
	onShippingQuoteChange: ({ amount, currency }) => updateOrderTotal(amount, currency),
})

await tapaya.checkout.sessions.approveShippingQuote(paymentId, {
	revision,
	options,
	selectedOptionId,
	expiresAt: Math.floor(Date.now() / 1000) + 300,
})

Verify the accepted total

Read the payment on your server and compare its order reference, currency, and amount with the final total your backend approved. Persist that total with the accepted quote revision. Comparing only with the initial subtotal rejects legitimate delivery changes.

checkout.sessions.prepare() validates the original creation input through replay when a delivery quote changes the read amount. Your fulfillment check still uses the accepted final total. The accepted address is in customer.shippingAddress, and the selected delivery option is in shippingQuote.

Test wallets on real devices

Wallet shipping uses native address and option callbacks. A changed total needs another authorization, and an expired quote is refused before charging. Apple Pay shipping requires supported native shipping callbacks; if they are unavailable, card entry remains available.

Test shipping, contact collection, and cancellation in both wallets on real supported devices before enabling delivery in production. The go-live checklist lists the checks.