Your Company

One-time checkout

Fill in your checkout with the user's delivery address, email and payment preference, shared once

Users keep a checkout profile in their Upod: their delivery addresses, a contact email and a preferred payment method. With a one-time checkout, your shop asks for that data for one order. The user approves it in their Upod, and you receive the details exactly once. Nothing is stored as a lasting consent, and to get the data again the user has to approve again.

When to use this

  • You want a "Checkout with Upod" button on your checkout page
  • You want shoppers to skip typing their address and email
  • You don't want a lasting link to the user's Upod, only the details for this order

How it works

  1. The shopper clicks <upod-checkout-button>. If they aren't logged in with Upod on your site yet, they log in first.
  2. The browser goes to the user's Upod. They see exactly what will be shared and click Share once.
  3. Upod sends the browser back to your page with a short-lived share code.
  4. The button exchanges the code for the data with the user's access token, removes it from the URL and fires an upod-checkout event.

A share code works once and for 5 minutes. A second exchange of the same code is refused with 403 ONE_TIME_SHARE_INVALID, and the only way to get the data again is to send the user through the flow again.

The code only works together with the access token of the same user, for your client_id, so a code that leaks through browser history or logs is useless on its own.

Prerequisites

  1. A registered OIDC client (see Getting started). The page you return to must be on one of your registered redirect URL origins.
  2. The client library on your checkout page:
<script src="https://cdn.upod.eu/client/bundle.browser.js"></script>

Add the button

<upod-checkout-button
    state="cart-123"
    language="en"
    full-width
></upod-checkout-button>
AttributeDescription
stateOptional. Returned unchanged in the result; use it to find the cart again after the redirect
language"en" (default) or "nl"
variantLogo variant, "dark" (default) or "light"
full-widthMakes the button as wide as its container

The button text is "Checkout with Upod" (in Dutch: "Afrekenen met Upod"). Style it from your own CSS with upod-checkout-button::part(button).

state is never treated as a credential, so don't put secrets in it. The page is left on click, so keep what you need, for example the cart in sessionStorage, before the shopper clicks.

Handle the return

Initialize the client and call handleCallbackIfNeeded() on every load of your checkout page: after logging in, it sends the user on to their Upod. Then listen for upod-checkout. It fires once when the user is back from Upod, and not at all on a normal page load.

If your script may load after the page is ready, the event can fire before your listener exists. In that case, await client.handleOneTimeShareCallback({ resource: 'checkout' }) instead: it resolves with the same result the button got, however late you call it.

const client = upod.initialize({
    authority: 'https://account.upod.eu',
    client_id: 'your-client-id',
    redirect_uri: location.origin + location.pathname,
    post_logout_redirect_uri: location.origin + location.pathname,
});

client.handleCallbackIfNeeded();

document.addEventListener('upod-checkout', ({ detail: result }) => {
    restoreCart(result.state);

    switch (result.status) {
        case 'success':
            fillCheckoutForm(result.data);
            break;
        case 'denied':
            // The user chose not to share: let them fill in the form by hand
            break;
        case 'unavailable':
            // The user has no checkout profile yet
            break;
        case 'error':
            // result.code says what went wrong; offer to try again
            break;
    }
});
statusMeaning
successdata holds the shared checkout details
deniedThe user declined to share
unavailableThe user has no checkout profile with an address yet, and went back to your shop
errorThe exchange failed; code is the error code, e.g. ONE_TIME_SHARE_INVALID, or AUTH_REQUIRED when the user is no longer logged in

When a user without a checkout profile chooses to create one, they stay in their Upod and don't return to your shop.

Without the button

To use your own button, call client.requestOneTimeShare({ resource: 'checkout', state }) on click, and await client.handleOneTimeShareCallback({ resource: 'checkout' }) after handleCallbackIfNeeded() on page load. It resolves with the same result, or { status: 'none' } when the page wasn't opened from Upod.

The data you receive

{
    "deliveryAddress": {
        "addressType": "home",
        "streetAddress": "Kalverstraat",
        "houseNumber": 15,
        "houseNumberAddition": "B",
        "postalCode": "1012 NX",
        "addressLocality": "Amsterdam",
        "addressCountry": "NL"
    },
    "contactEmail": "jane@example.com",
    "preferredPaymentMethod": "wero"
}

You only get the user's preferred delivery address, never their other addresses. preferredPaymentMethod is null when the user hasn't picked one, and it never contains card or account details. The user's name isn't part of the profile, so ask for it in your form. See the One-time shares reference for every field and error code.

The data is meant for this order only. Upod tells the user that you can't fetch it again without asking them, so don't use it to build a profile.

Try it

The one-time checkout example is a complete demo shop that uses this flow.

On this page