Yatta Checkout User Guide

Web API

On this page you can find detailed information on how to add the drop-in API, as well as details about its methods, parameters and fields.

Adding the JavaScript library

Yatta Checkout is provided as a UMD (universal module deﬁnition for JavaScript modules). You can integrate this as a plain JavaScript library into your system.

The Yatta Checkout drop-in does all the work for server-side and client-side integration. For the integration you need to make sure that the Document Object Model (DOM) is already rendered. This can be done by including between the and tags in your HTML and before calling any of our functions like :

Note: If you test the web integration on your local machine, you must ensure that the website is served by an HTTP server. (Otherwise, it’s not possible to test the integration properly.) To do this, you can use Python’s http.server module or another server module with equivalent functionality.

Start Checkout

Starts the Checkout. If the user is already subscribed to your product, the relevant subscription management is opened. Similarly, if the user already purchased your product and it can only be purchased once, the purchase information is opened. If multiple one-time purchases are allowed, a user who already purchased is able to purchase again.

This example code snippet starts the Checkout in the live environment for a user who does not yet have rights to access the product, pre-selecting a yearly subscription, passing custom metadata through the purchase, setting metadata context IDs for—and a redirect after—a successful purchase or closing the checkout.

This example starts the Checkout in the live environment for a user who might not yet have rights to access the product, pre-selecting a one-time purchase with quantity two and limited term of three years starting on 1 January 2024. It passes custom metadata through the purchase, setting metadata context IDs for—and a redirect after—a successful purchase or closing the checkout.

productId	Required String This is the ID of the product for which the Checkout should be started.
environment	Optional String with value 'LIVE' or 'PREVIEW' Set to 'LIVE' by default, but 'PREVIEW' should be used for testing purposes. Note: If your product is not yet live, the environment parameter will be ignored and the preview environment will be used by default.
locale	Optional String with value 'en' or 'de' Set to your vendor's global default or to the user's browser language by default. To override, set the locale using the values 'en' or 'de'.
manageAssetHint	Optional Boolean False by default. Set to true if the user has the right to access the product and is not allowed to buy multiple times. They will not be notified again by the Checkout that they have usage rights. This is recommended if your website adapts to the user's asset status—e.g., your "Purchase" button text changes to "Manage" if the user already has a license and is not allowed to own multiple ones.
type	Required String with value 'ONE_TIME_PURCHASE' or 'SUBSCRIPTION' This can be defined to pre-select a one-time purchase or subscription. One-time purchase mode is set by default.
subscriptionInterval	Optional String with value 'MONTHLY' or 'YEARLY' This can be defined to pre-select a subscription interval. Monthly is set by default. This is only used for type 'SUBSCRIPTION'.
quantity	Optional Number This can be defined to select the quantity of your product to be purchased. This is only used for type 'ONE_TIME_PURCHASE'.
term	Optional String with value 'UNLIMITED' or object with runtime, unit (and startOfTerm) This can be defined to select the term of the product to be purchased. If set to 'UNLIMITED' the purchase is valid for lifetime. Alternatively, an object can be set with a runtime number, a unit set to 'DAY', 'WEEK', 'MONTH' or 'YEAR', and an optional startOfTerm date in ISO-8601 format, e.g., 2019-09-26T00:00:00+0200. This is only used for type 'ONE_TIME_PURCHASE'.
forceSignIn	Optional Boolean False by default. Set to true if the user should be signed out and required to sign in again.
metadataId / metadata	Optional String containing ID or (not recommended) metadata object The metadataId can be set to an ID retrieved via the metadata backend API. This can be called by your backend via yatta.startCheckout(...) in your frontend. The ID refers to a metadata object as explained below. Alternatively, you can pass the metadata object directly to yatta.startCheckout(...) using the metadata key. metadataId overrules metadata.

Metadata object

Contains parameters to configure the individual checkout session and additional custom data to be passed through a transaction to the purchase callback.

Security note: We recommend handling metadata via the metadata backend API—setting only the metadataId key instead of the full metadata object in the yatta.startCheckout(...) params. This way, sensitive data like billing information is not passed through any frontends where it could be manipulated or inspected by a third party.

contexts	Optional List The checkout can be configured with several contexts. Note: Contexts can only be set when persisting metadata via REST API—not via Web API.
customMetadata	Optional Object with up to 64 key-value pairs: Keys are strings, values are of any type This can be defined to pass any required data through the purchase process and, after a successful purchase, to you via callback. Maximum 64 key-value pairs. Keys are strings up to 42 characters. Values can be of any kind, but must be shorter than 1024 characters when stringified.
onClose	Optional Object with optional redirectUrl On a closing, certain actions might be desired. Therefore this object can be set containing a redirectUrl string, defining the URL the user will be redirected to after closing the Checkout drop-in. If included inside the URL, any occurance of $$SESSION_TOKEN$$ will be replaced by the CheckoutSession session token.
onSuccess	Optional Object with optional redirectUrl On a successful purchase, certain actions might be desired. Therefore this object can be set containing a redirectUrl string, defining the URL the user will be redirected to after making a purchase and closing the Checkout drop-in. The onClose handling is overwritten in this case. If included inside the URL, any occurance of $$SESSION_TOKEN$$, will be replaced by the CheckoutSession session token.

Subscribe to changes to the current user's sign-in status.

callback

Required (signedIn: boolean) => void

Function called whenever the user's signed-in boolean changes.

Asset status change

Subscribe to changes to the asset status of the current user for a given product.

productId	Required String Value is the ID of the product for which the asset status should be retrieved.
callback	Required (assetStatus: AssetStatus \| null) => void Function that is called whenever the user's asset status changes. The parameter for the callback has the type AssetStatus.
environment	Optional String with value 'LIVE' or 'PREVIEW' Sets whether to retrieve the user's asset status for 'LIVE' or 'PREVIEW' environments. Note: If your product is not yet live, the environment parameter will be ignored and the preview environment will be used by default.

AssetStatus object

The asset status for a specified product provided to the callback in the drop-in interface if the user is signed in and has the right to access the asset.

Note: When the AssetStatus object is null, the user does not have a license.

type	String with value 'ONE_TIME_PURCHASE' or 'SUBSCRIPTION' This identifies if the type of the asset is a one-time purchase or a subscription.
bookingStatus	String with value 'ONGOING' or 'CANCELED' Provides the booking status of the subscription. This is only used for type 'SUBSCRIPTION'.

Session change

Subscribe to changes to the session of the current user in the drop-in interface.

vendorId	Required String Unique ID that identifies you as a vendor.
callback	Required (checkoutSession: CheckoutSession \| null) => void Function that is called whenever the checkout session of the user changes. The parameter for the callback has the type CheckoutSession.

CheckoutSession object

The current web session object in the callback defined in the drop-in interface if the user is signed in.

Note: When the CheckoutSession object is null, the user is not signed in.

accountId

String

The account ID is unique for your vendor namespace (explicitly set through Link account, otherwise set to an auto-generated UUID) and can be used in conjunction with your API Key to get license information for the current user through the REST API.

sessionToken

String

A signed JWT token, identifying the user in the drop-in session. Before using it, please verify it using the provided JSON Web Key Set. Alternatively you can defer the verification to the licensing server by passing the sessionToken parameter.
The token contains the following fields:

aud – vendor id (see above)
sub – account id
iss – issuer, yatta.de
email – user email
name – user name
exp – token expiration date

Allows the user to sign in, then closes without additional actions.

vendorId	Required String Unique ID that identifies you as a vendor.
forceSignIn	Optional Boolean False by default. Set to true if the user should be signed out and required to sign in again.
locale	Optional String with value 'en' or 'de' Set to your vendor's global default or to the user's browser language by default. To override these defaults, set the locale using the values 'en' or 'de'.
metadataId / metadata	Optional String containing ID or (not recommended) metadata object The metadataId can be set to an ID retrieved via the metadata backend API. This can be called by your backend via yatta.startCheckout(...) in your frontend. The ID refers to a metadata object as explained below. Alternatively, you can pass the metadata object directly to yatta.startCheckout(...) using the metadata key. metadataId overrules metadata.

Sign out

Signs the user out.

Link account

Links a non-Yatta account to the Checkout to ensure access to licenses for products that require a link to this account. This is only necessary if you want to use your own IAM.

accountId

Required String

A new ID for the account in your IAM to map the user to the Yatta account. With this ID, you can use our REST API to check if the user has an active license.

If you do not provide us with a linked account, we will generate an ID for you so you can use the Yatta IAM without calling this method.

Optional String

Email address used to auto-start the Yatta sign-in and to pre-fill Yatta authentication forms, when the checkout is started.

Note: Remember to update your Privacy Policy to reflect the fact you will be passing your user's email address to us for authentication.

Note: If a product that requires a linked account is sold using the Checkout, this API must be called every time the user signs in or out, and upon page load.

Implementation example

Here is a basic example of a Yatta Checkout website implementation showing how to initialize and open the Checkout on a website.

Note: The JavaScript library will embed Yatta Checkout on your website in an iframe. The content of this iframe is hosted on a Yatta domain. Modern browsers do not allow JavaScript to communicate between your website and the iframe due to cross-origin resource policy (CORP), so all communication is handled via window.postMessage (postMessage() is a global method that safely enables cross-origin communication).

Apple Safari reports the existence of an iframe with a different domain as an error in the JavaScript console: "Blocked a frame with origin...". This has no impact on the functionality of Yatta Checkout and this message may be ignored.