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
| Resource | What is shared |
|---|---|
checkout | Preferred delivery address, contact email and payment method |
Lifecycle
| Step | Rule |
|---|---|
| Approve | The user approves in their Upod. A share code is minted for your client_id. |
| Lifetime | The code is valid for 5 minutes. |
| Exchange | The first exchange uses the code up, whatever its outcome. A failed exchange means asking again. |
| Data | Read from the user's Upod at the moment of the exchange. |
| Consent | Nothing is stored in the user's consent settings. |
Consent URL
The user's Upod (https://me.upod.eu) shows the consent screen at:
/consent/{clientId}?resource=checkout&consent=once&redirectUrl={url}&state={state}| Parameter | Required | Description |
|---|---|---|
resource | yes | A supported resource |
consent | yes | once. (temporary and unlimited are the other kinds of consent, for per-property raw data.) |
redirectUrl | yes | Where to return; its origin must be one of your registered redirect URL origins |
state | no | Returned unchanged |
Return parameters
Upod sends the browser back to redirectUrl with these query parameters:
| Parameter | When |
|---|---|
upod_share_code | The user approved |
upod_share_error | access_denied when the user declined, unavailable when there is nothing to share yet |
upod_share_state | Your 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
| Field | Type | Description |
|---|---|---|
deliveryAddress.addressType | home | work | |
deliveryAddress.streetAddress | string | |
deliveryAddress.houseNumber | integer | |
deliveryAddress.houseNumberAddition | string, optional | e.g. B |
deliveryAddress.postalCode | string | |
deliveryAddress.addressLocality | string | City |
deliveryAddress.addressCountry | string | ISO 3166-1 alpha-2, e.g. NL |
contactEmail | string | The user's contact email, or their Upod email if they set none |
preferredPaymentMethod | string | null | See 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
| Status | code | Meaning |
|---|---|---|
| 401 | AUTH_REQUIRED | No valid access token; the code is not used up |
| 401 | SOLID_SESSION_EXPIRED | The user's Upod can't be reached right now and they need to log in again |
| 403 | ONE_TIME_SHARE_INVALID | Unknown, expired or already used code, or a token of another user or another client |
| 403 | ONE_TIME_SHARE_UNAVAILABLE | The user removed the data between approving and the exchange |
| 500 | POD_ERR_GET | Reading 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.