Yatta Checkout User Guide
Purchase callback
Setup
To enable a callback for every purchase of your product, drop us a short email with a URL for testing 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 callback cannot be executed for one month, 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://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.
Callback format
The actual body is split into the following objects:
Account
|
Email address of the purchasing Yatta Account. |
|
|
linkedAccount 🠊 accountId |
Can be your linked Account ID (if specified) or a generated one. |
Keys
A list of keys in JWT format, size is equal to the number of licenses, see below.
Price
| 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. |
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
| 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
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.