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 |
| txId (transaction ID) |
UUID of the payment transaction. |
| iat (issued at) |
Unix timestamp of the payment transaction. |
| 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:
Account
|
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.
Price
Similar to Transaction object, Price object is common in events where a payment is executed or expected.
For additional fields specific to each event type, see the Event Types section below.
Event types
Purchase
The event payload contains following fields in addition to common fields:
Transaction
| txId |
A unique identifier for the purchase transaction. |
| purchaseDate |
The purchase's timestamp. |
| customerInvoiceNo |
A continuous prefixed number of the issued invoice |
| customMetadata |
The full object given via the startCheckout() call. |
|
groupContext 🠊 id 🠊 name |
ID and name of the group context given via the startCheckout() call. |
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:
Reactivation
Renewal
The event payload contains following fields in addition to common fields:
Transaction
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.
Booking Created
Booking Canceled
The event payload contains following fields in addition to common fields: