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 product ID (found in the integration details of your product) as user name and the vendor API key (found in the company information) as password. |
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. If set, sessionToken can be skipped. Note: The account ID can be any unique string, UUID or hash. We recommend generating a new UUID for each account. |
| sessionToken |
For every user session you receive a token from the License session change callback of the web api. If set, accountId can be skipped. |
| 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
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. |
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 product ID (found in the integration details of your product) as user name and the vendor API key (found in the company information) as password. |
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 |