Yatta Checkout User Guide

Webhooks

Setup

To enable webhooks for your product, drop us a short email containing a list of event types you want to receive and a URL for your live system. In the future, you'll be able to set these URLs directly in the portal.

If the specified endpoint cannot be reached or the request is not acknowledged with a 200 code, the request will be retried hourly for 24h and afterwards once per day. If the webhook cannot be executed for 30 days, it will be dropped.

Verification

To verify that the message was actually sent by Yatta, every request uses the Bearer authentication scheme with a JWT token. These tokens will be signed with an RSA key, and the selected key is available on https://api.yatta.de/checkout/v1/jwks.

After decoding the JWT token into its parts—header, payload and signature—the payload will contain the following example data:

sub (subject)	YattaCheckoutCallback
aud (audience)	Unique for each Vendor.
iss (issuer)	yatta.de
iat (issued at)	Unix timestamp at which the JWT was issued.
hash-alg	Currently only SHA3-256 is supported as algorithm for the hash.
hash	Hash sum over the request body.

Make sure to verify the token's signature (for fast and safe results, use a library of your choice) and also check that the audience field equals your known Vendor ID. Last but not least, you can verify the hash of the full body to ensure the data you received has not been tampered with.

Only acknowledge the request with a 200 return code if verification is successful.

Structure

Each webhook event payload contains the following common fields:

event	The type of event.
eventVersion	The version of the event.
bookingId	A unique identifier for user purchase.

Account

email	Email address of the purchasing Yatta Account.
linkedAccount 🠊 accountId	Can be your linked Account ID (if specified) or a generated one.

Product

productIdentifier	Contains the ID and environment of your product.
productName	Added for readability of this message.
licenseTypeId	A unique identifier of the purchased license type.
kind 🠊 type	Can be ONE_TIME_PURCHASE or SUBSCRIPTION.
🠊 term	Runtime constraint for one-time purchases, if defined for this license type.

Transaction

For event types where a payment is executed or expected (e.g. PURCHASE, RENEWAL and BOOKING_CREATED), the event payload contains following common fields in addition to event specific fields in transaction object.

txId	A unique identifier for the transaction.
customMetadata	Key-value pair passed through metadata REST API during purchase process.
groupContext 🠊 id 🠊 name	The group context passed through IAM context through metadata REST API during purchase process.
additions	Array of objects Additional data required for purchase of a particular product.

Price

Similar to Transaction object, Price object is common in events where a payment is executed or expected.

currency	Selected currency for this transaction.
netValue	Amount without VAT (if applicable).
total	Gross value of the transaction.
quantity	Amount of licenses for the selected product.
userCountryISO2Lookup	Selected country for the VAT calculation.
vatReversed	True if reversed VAT is active for this transaction.
vatPercentage	Applied VAT rate.
vatValue	Added VAT amount.

For additional fields specific to each event type, see the Event Types section below.

Event types

PURCHASE	Triggered when a user completes a purchase — either a one-time product or a subscription.
CANCELLATION	Triggered when a user cancels an active subscription.
REACTIVATION	Triggered when a user re-subscribes to a previously canceled but still active subscription.
RENEWAL	Triggered when a subscription is extended for the next billing period.
BOOKING_CREATED	Triggered when a user books a subscription for a future date.
BOOKING_CANCELED	Triggered when a user cancels a subscription scheduled to start in the future.

Purchase

The event payload contains following fields in addition to common fields:

Transaction

purchaseDate	The purchase's timestamp.
customerInvoiceNo	A continuous prefixed number of the issued invoice

Keys

A list of keys in JWT format, size is equal to the number of licenses. In case you offer variable quantities for your product, the keys attribute will contain a list of keys differentiating multiple sub-keys, which are valid JWT. They can be handed out to customers to identify their unique license key and contain the timespan in which they are valid.

Keys are similar in content to the overall message, notable differences are:

Subject of the token is the accountId.
Additional sequence number (seq).
Detail objects (account, transaction and product) are stringified.

Cancellation

The event payload contains following fields in addition to common fields:

terminationDate

Date in ISO 8601 format when the license will be terminated.

reason

Reason of cancellation.

It will be CUSTOMER_REQUEST if user requested to cancel the subscription.

Reactivation

Renewal

The event payload contains following fields in addition to common fields:

Transaction

renewalDate	The renewal's timestamp.
customerInvoiceNo	A continuous prefixed number of the issued invoice

Keys

Keys are similar in content to the overall message, notable differences are:

Subject of the token is the accountId.
Additional sequence number (seq).
Detail objects (account, transaction and product) are stringified.

Booking Created

Booking Canceled

The event payload contains following fields in addition to common fields:

cancellationDate

Date in ISO 8601 format when the user canceled the booked subscription.

reason

Reason of cancellation.

It will be CUSTOMER_REQUEST if user requested to cancel the subscription.