Yatta Checkout User Guide
REST API Endpoints
Check licenses
This endpoint can be used to check if a specific account has purchased a license for a given product, including its expiry date.
Request
Headers
| Content-Type |
Currently only application/json messages are accepted. |
| Authorization |
Use basic authentication with your vendor ID as username and your vendor API key as password. Both can be found in the company information. |
Parameters
| environment |
Set to PREVIEW for your test systems (no real payments or licenses are processed). Set to LIVE for production systems that only allow real licenses. |
| accountId |
The account ID your IAM uses to identify Yatta Checkout accounts. Note: The account ID can be any unique string, UUID or hash. We recommend generating a new UUID for each account. |
| sessionToken |
A token received from the Web API onSessionChange callback. It can be optionally added here to verify the frontend session. Note: When the token is invalid, an INVALID_TOKEN error is returned. |
| productId |
The product ID can be found in product details in the Vendor Portal. |
| durationMinutes |
Interval after which the license validity must be re-checked. Should be roughly the length of a typical user session, but can also be a timestamp in the far future. It must be rechecked at least once for each payment period (e.g., monthly). |
Response
Parameters
| environment |
Will respond with the same environment as requested. |
| validity |
Describes the current license state for the requested account. LICENSED The requested account owns an active license. EXPIRED The account used to have a license but it has expired. UNLICENSED The account does not have a license for this product. INVALID_API_USAGE The call to the API was invalid. (e.g., too many API calls in a short period or invalid parameters). |
| accountId |
Requested account ID. |
| licenseType |
PERSONAL Other license types are in development: FLOATING, TRIAL. |
| productId |
Requested product ID. |
| checkedOutAt |
The timestamp for when the license check was executed. |
| checkedOutUntil |
The checkedOut timestamp offset by the duration set in the request. If the license is not valid for the whole duration, this will be limited to the current license validity. |
| validFrom |
The date and time when the account purchased their current license. |
| validUntil |
Date and time at which the current license will expire (unless it is renewed). |
Errors
400 —
401 —
404 —
Parameters
| errorType |
Describes the error type: ACCOUNT_NOT_FOUND: Account ID is wrong or could not be found. PRODUCT_NOT_FOUND: Product ID is wrong or could not be found. INVALID_TOKEN: Provided session token is invalid (e.g., it has expired). |
Check SaaS API key
This endpoint can be used by your SaaS API service to check whether a request is from a user with a valid API key for your product. To speed up consecutive requests, the response can be cached in your API service.
Request
Headers
| Content-Type |
Currently only application/json messages are accepted. |
| Authorization |
Use basic authentication with your vendor ID as username and your vendor API key as password. Both can be found in the company information. |
Parameters
| environment |
Set to PREVIEW for your test systems (no real payments or licenses are processed). Set to LIVE for production systems that only allow real licenses. |
| productId |
The product ID can be found in product details in the Vendor Portal. |
| apiKey |
Given API key received as part of a user request. |
Response
Parameters
| environment |
Will respond with the same environment as requested. |
| productId |
Requested product ID. |
| accountId |
Requested account ID. |
| validity |
Describes the current license state for the requested account. LICENSED The requested account owns an active license. EXPIRED The account used to have a license but it has expired INVALID_API_USAGE The call to the API was invalid. (E.g., too many API calls in a short period or invalid parameters.) |
| validFrom |
The date and time when the selected key was activated. |
| validUntil |
Date and time at which the current key will expire (unless the user renews their license). For one-time purchases this field is not set. |
Errors
401 —
404 —
Parameters
| errorType |
Describes the error type: KEY_NOT_FOUND: Specified SaaS API key could not be found and is not valid. |
Price API
Prices both define and show users a range of attributes related to the costs of a single unit of a particular product. These include:
Unit cost
Currency
Subscription intervals (optional)
These parameters apply to both subscriptions and one-time purchases.
Request
The Price API request has the following general format:
This request generates a response that shows all price options for a particular product. With a specified type, you will receive a filtered list of license types and their prices.
URL parameters
| env |
Case insensitive
Set to PREVIEW for your test systems to list unpublished prices. Set to LIVE to list the currently active prices. Once your product has been published, this shows you the prices users currently see when they select your product in Yatta Checkout. If invalid, this defaults to LIVE. |
| productId |
The product ID can be found in product details in the Vendor Portal. |
| type |
Optional
Case insensitive
This parameter defines a given product's payment scheme. Set to SUBSCRIPTION to filter prices for subscription licenses. Set to ONE_TIME_PURCHASE to filter prices for one-time purchase licenses. |
Response
Requesting a specific one-time purchase license type
In addition to the above, the one-time-purchase-specific license type needs the following parameters:
| runtime |
Specify the length of the selected runtime. |
| unit |
Case insensitive
Select a unit from DAY, MONTH or YEAR. |
Request example
Response example
Requesting a specific subscription license type
In addition to the above parameters, the subscription-specific license type needs the following parameter:
| interval |
Case insensitive
Select an interval: DAILY, MONTHLY or YEARLY. |
Request example
Response example
Metadata
For each checkout call, you can attach custom metadata as well as information about the user to the Checkout session. The resulting has to be added to the startCheckout parameters (see startCheckout()). The will also be returned to your backend service via the purchase callback.
Request
Headers
| Content-Type |
Currently only application/json messages are accepted. |
| Authorization |
Use basic authentication with your vendor ID as username and your vendor API key as password. Both can be found in the company information. |
Parameters
| 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. |
Contexts
For each object you can add several . Those are as follows:
Purchase context
| type |
Required
String with value 'PURCHASE'
The type of the context. |
| billingInformation |
Optional
Object with optional string keys
The billing information object contains only optional string keys. Those are: firstName for the first name of the issued person, lastName for the last name of the issued person, organizationName for the name of the issued company, address for street and house number, address2 for additional address data, postalCode for the zip code of the city, city for the name of the city, country for the country of the billing address (ISO code), province for the province of the billing address, email for the billing email the invoice will be sent to, and vatId for the VAT number of the company or person (if located inside the European Union). |
IAM context
| type |
Required
String with value 'IAM'
The type of the context. |
| groupContext |
Optional
Object with ID and name
If the user buys within a certain group context, e.g., on behalf of a company, an object can be passed through the purchase process and will be returned to you after a successful purchase via callback. The object contains an ID, i.e., a string identifying the group, and a name string for the name of the group. |
| accountMigration |
Optional
Object with optional email and optional launchDate
If you reach out to a user who was registered with an account in your existing IAM and who should now re-register with a Yatta account, accountMigration can be set. You can pass a launchDate after which Yatta accounts can be used within your ecosystem and the user's email, if you are allowed by your privacy policy to pass it to Yatta. |
Mobile context
| type |
Required
String with value 'MOBILE'
The type of the context. |
| redirectUrl |
Optional
String
The deep-link URL to open the app from checkout email links. |
| appName |
String
The name of the mobile app. |
Travel ticket context
| type |
Required
String with value 'TRAVEL_TICKET'
The type of the context. |
| route |
Optional
Object with from and to strings
The route the travel ticket is bought for. |
Shopping cart context
Request
| type |
Required
String with value 'SHOPPING_CART'
The type of the context. |
| environment |
Required
String
Set to PREVIEW for your test systems (no real payments or licenses are processed). Set to LIVE for production systems that only allow real licenses. |
| products |
Required
Array of objects with productId and quantity
productId identifier of the product added to the shopping cart. quantity number of units of the product to be added to the shopping cart. |
Response
Errors
401 —