Skip to main content

Overview

Kraken Pay will notify your system via webhook when the payment status changes. You’ll receive POST notifications for the following statuses:
The payload is encoded and signed using JWT with the ES256 algorithm (ECDSA using P-256 and SHA-256) and the specified kid. The kid is used to verify the signature by looking up the correct public key in the JWKS available at https://www.kraken.com/.well-known/pay-callback-keys.json.
A given kid will always point to the same key, so you can cache it forever. You will only need to fetch the remote JWKS and update your local set if the JWT is signed with a new kid.
JWT expiration is set to 24 hours. If you have to process the message past the expiry you can simply ignore it.

Claims

JWT claims have the following schema:
FieldTypeDescription
issstringIssuer. Should always be kraken-pay
audstring or nullRecipients that the JWT is intented for (unused)
expnumberExpiration time. Unix timestamp in seconds
payload.external_idstringYour unique ID for tracking the payment
payload.statusstringPayment status. success, failed, cancelled, expired, declined
payload.customer_kraktagstring or nullIn the case of a pay request, Kraktag of the payer. In the case of a transfer or paylink, Kraktag of the recipient. If the notification is triggered by a cancelled or an expired paylink or pay request, this will be null.
Because new fields could be added to the payload in the future, your deserialization implementation should handle unknown fields. Example: Decoded JWT claims

Webhook response

On successful validation of the payload your endpoint must return a 200 code with the following JSON payload:
Anything else will be treated as an error.

Examples

Decode and validate JWT

The following are Rust and PHP examples of how to decode the JWT and validate its signature.
TypeValue
Private key
-----BEGIN PRIVATE KEY----- 
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgCfJ5HUY3VRpKR7rb
f60ba2BMvRSoZCyqnscwBvf+HlGhRANCAARtlMp6bYdgBIuEn3b/tmIRnJ6O6+Zf
9NhKpuKPe7Vj76Vv5mohvNczcM0sWjo6OEQ6jngzD5wMTWIhXvRcyRtO
-----END PRIVATE KEY-----
AlgorithmES256
kidtest-pay-callback-1
JWTeyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6InRlc3QtcGF5LWNhbGxiYWNrLTEifQ.eyJpc3MiOiJrcmFrZW4tcGF5IiwiYXVkIjpudWxsLCJleHAiOjE3NDk1NDc4NjksInBheWxvYWQiOnsiZXh0ZXJuYWxfaWQiOiJHU29BQUFBQUFBQSIsInN0YXR1cyI6InN1Y2Nlc3MiLCJjdXN0b21lcl9rcmFrdGFnIjoiYm9iIn19.dmlaZ0sdPVodkytuv8IFUj4Sbn0wpywzW51itWCh7dHX-bELdhkwE8pVpIyRYGP42TtyBChbVKwXEfd2-uxTHQ