Callbacks

It is a good idea to create an IPN listener page on your website and then specify the URL of the listener page in a "Settings → API" section in your Kriptopay account.

It is also important to note that you should use only https URL. Kriptopay then sends a secure POST request containing payment details of all transaction-related events to the URL.

Handling callbacks correctly is crucial to make sure your integration’s business logic works as expected. It is highly recommended to validate payment statuses and callbacks before acting on it inside your system.

The IPN listener page contains a custom script or a program that gets messages, validates them with Kriptopay, and then passes them to various backend applications for processing.

Acknowledge events immediately

If your callbacks script performs complex logic, or makes network calls, it’s possible that the script would time out before Kriptopay sees its complete execution. Ideally, your callback handler code (notification of an event by returning a 200 status code) is separate from any other logic you do for that event.

Handle duplicate events

Callback endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts. One way of doing this is logging the events you’ve processed, and then not processing the logged ones.

Retry logic

Kriptopay IPN server expects to get a 200 status code from you within 10 seconds. If the response code is different from 200 or a deadline is exceeded, we deliver your callbacks for up to one and a half days with an exponential backoff:

30 + num ^ 4 + num seconds where num is 0 to 19 retry

Security

Every callback request contains a HMAC header:

"HMAC": "7c021857107203da4af1d24007bb0f752e2f04478e5e5bff83719101f2349b54"

This header contains the hex encoded SHA512 HMAC signature of the callback request body string, computed using your callback Secret as the key.

1. You receive a callback

2. You use SHA512 for hashing its body string with a callback secret

3. You compare HMAC value to the hash you've got after hashing the callback body string + callback secret

4. When creating HMAC do not include spaces in request body

class KriptopayCallbackVerifier
  def initialize(secret)
    @secret = secret
  end
​
  def verify(body, signature)
    expected_signature = OpenSSL::HMAC.hexdigest('SHA512', @secret, body)
  end  
end
​
secret = 'hzeRDX54BYleXGwGm2YEWR4Ony1_ZU2lSTpAuxhW1gQ'
verifier = KriptopayCallbackVerifier.new(secret)
​
# Raw callback body
raw_data = '{"type": "invoice", "merchant": "LTYM23KU6BX3JQ0C", "data": {"transaction_id": "test", "fiat_currency": "USD", "fiat_amount": "0", "txn_id": "12d4d1f7-fc16-45a6-890c-217db96e615e", "status": "created"}}'
​
# do not include spaces and special characters
body = JSON.generate(raw_data, quirks_mode: true)

# assuming your secret key is "123456"

# Value of HMAC header
signature = '8049a06642b948d8e6b5e259f4a26c2b1b4c64701b58414cf9ac468823a74432fa947e875a1267df13083192743a9641bea46b2f0e413e2f8e7de6cbaa10da84'
​
verifier.verify(body, signature) # => true

Every new callback request will have a new value of the HMAC header. Make sure you are comparing the hash to the right header.

A callback secret is available in the "Site Settings → API" section in your Kriptopay account.

Callback IPs

We send all our callbacks from these IP:

• Production - 134.209.238.254

• Sandbox - 134.209.238.254

You can use these IPs as a whitelist for receiving callbacks.

Callbacks reference can be found in relevant sections of the API reference: