Your Company

One-time shares

Contract for sharing a resource once, with the consent URL, the exchange endpoint, payloads and error codes

A one-time share gives your platform a fixed set of a user's data for a single use. The user approves it in their Upod, you exchange a share code once, and nothing is stored as a lasting consent. For a step-by-step integration, see One-time checkout.

<upod-checkout-button>, or the client library's requestOneTimeShare() and handleOneTimeShareCallback(), handle everything below for you. This page is for when you need the details.

Supported resources

ResourceWhat is shared
checkoutPreferred delivery address, contact email and payment method

Lifecycle

StepRule
ApproveThe user approves in their Upod. A share code is minted for your client_id.
LifetimeThe code is valid for 5 minutes.
ExchangeThe first exchange uses the code up, whatever its outcome. A failed exchange means asking again.
DataRead from the user's Upod at the moment of the exchange.
ConsentNothing is stored in the user's consent settings.

The user's Upod (https://me.upod.eu) shows the consent screen at:

/consent/{clientId}?resource=checkout&consent=once&redirectUrl={url}&state={state}
ParameterRequiredDescription
resourceyesA supported resource
consentyesonce. (temporary and unlimited are the other kinds of consent, for per-property raw data.)
redirectUrlyesWhere to return; its origin must be one of your registered redirect URL origins
statenoReturned unchanged

Return parameters

Upod sends the browser back to redirectUrl with these query parameters:

ParameterWhen
upod_share_codeThe user approved
upod_share_erroraccess_denied when the user declined, unavailable when there is nothing to share yet
upod_share_stateYour state, when you passed one

Exchange

POST https://account.upod.eu/storage/{resource}/share/exchange
Authorization: Bearer <access token>
Content-Type: application/json

{ "code": "…" }

The access token must belong to the user who approved the share, and to the client_id it was approved for. The response is the resource's payload.

checkout payload

FieldTypeDescription
deliveryAddress.addressTypehome | work
deliveryAddress.streetAddressstring
deliveryAddress.houseNumberinteger
deliveryAddress.houseNumberAdditionstring, optionale.g. B
deliveryAddress.postalCodestring
deliveryAddress.addressLocalitystringCity
deliveryAddress.addressCountrystringISO 3166-1 alpha-2, e.g. NL
contactEmailstringThe user's contact email, or their Upod email if they set none
preferredPaymentMethodstring | nullSee below; null when the user hasn't picked one

Payment methods: wero, credit-card, paypal, klarna, apple-pay, google-pay, bancontact, sepa-direct-debit, bank-transfer.

Error codes

StatuscodeMeaning
401AUTH_REQUIREDNo valid access token; the code is not used up
401SOLID_SESSION_EXPIREDThe user's Upod can't be reached right now and they need to log in again
403ONE_TIME_SHARE_INVALIDUnknown, expired or already used code, or a token of another user or another client
403ONE_TIME_SHARE_UNAVAILABLEThe user removed the data between approving and the exchange
500POD_ERR_GETReading the data failed

Apart from AUTH_REQUIRED and SOLID_SESSION_EXPIRED, the code is used up, so recover by sending the user through the consent flow again.

On this page