Purchase callback

Setup

To enable a callback for every purchase of your product, drop us a short email, ideally with a URL for testing and a URL for your live system. In the future, it will also be possible to set these URLs directly in the portal.

Please note that the content of each callback is packaged in a JSON web token (JWT), to ease the verification of incoming requests. These tokens will be signed with an RSA key and the selected key is available on https://yatta.de/checkout/v1/jwks. Make sure to verify the token's signature and only acknowledge the request with a 200 return code if verification is successful.

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.

Callback format

On every purchase, you will receive a request on the specified URL with a JWT which looks similar to the following snippet.

By using a JWT library, the extraction of the payload and its validation may be automated. Otherwise, it can be decoded by dividing it into three parts around the dots:

HEADER.PAYLOAD.SIGNATURE

The header is a base64 encoded json, which describes how this JWT is signed. Together with the signature, the integrity of the whole message can be verified. The payload is also a base64-encoded json and decodes as follows:

The payload contains information about the successful purchase of a product with its productId (and if set, also specifies the selected limited term defining a start and expiryDate). A purchasing customer is identified by their accountId and email.

In case you offer variable quantities for your product, the keys attribute will contain a list of keys differentiating multiple sub keys, which are themselves valid JWT (shortened in this example to jwt-key-*). They can be handed out to customers to identify their unique license key.

Keys are similar in content to the overall message, notable difference is a sequence number (seq):