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 Cryptopay account.
It is also important to note that you should use only https
URL. Cryptopay 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 Cryptopay, and then passes them to various backend applications for processing.
If your callbacks script performs complex logic, or makes network calls, it’s possible that the script would time out before Cryptopay 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.
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.
Cryptopay 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
0d 00h 00m 30s0d 00h 00m 32s0d 00h 00m 48s0d 00h 01m 54s0d 00h 04m 50s0d 00h 11m 00s0d 00h 22m 12s0d 00h 40m 38s0d 01h 08m 54s0d 01h 50m 00s0d 02h 47m 20s0d 04h 04m 42s0d 05h 46m 18s0d 07h 56m 44s0d 10h 41m 00s0d 14h 04m 30s0d 18h 13m 02s0d 23h 12m 48s1d 05h 10m 24s1d 12h 12m 50s
Every callback request contains a X-Cryptopay-Signature
header:
"X-Cryptopay-Signature": "7c021857107203da4af1d24007bb0f752e2f04478e5e5bff83719101f2349b54"
This header contains the hex encoded SHA256 HMAC signature of the callback request body string, computed using your callback Secret as the key.
You receive a callback
You use SHA256 for hashing its body string with a callback secret
You compare X-Cryptopay-Signature
value to the hash you've got after hashing the callback body string + callback secret
class CryptopayCallbackVerifierdef initialize(secret)@secret = secretenddef verify(body, signature)expected_signature = OpenSSL::HMAC.hexdigest('SHA256', @secret, body)secure_compare(signature, expected_signature)endprivate# Constant-time comparison algorithm to prevent timing attacksdef secure_compare(str1, str2)return false if str1.empty? || str2.empty? || str1.bytesize != str2.bytesizel = str1.unpack("C#{str1.bytesize}")res = 0str2.each_byte { |byte| res |= byte ^ l.shift }res.zero?endendsecret = 'hzeRDX54BYleXGwGm2YEWR4Ony1_ZU2lSTpAuxhW1gQ'verifier = CryptopayCallbackVerifier.new(secret)# Raw callback bodybody = '{"type":"Invoice","event":"status_changed","data":{"id":"ff48eeba-ab18-4088-96bc-4be10a82b994","status":"completed","status_context":null,"address":"rs9pE6CnNLE8YiTgTwbAk1AkFyS3opsm7K?dt=701","price_amount":"1.0","price_currency":"EUR","pay_amount":"3.113326","pay_currency":"XRP","paid_amount":"3.113326","exchange":{"pair":"XRPEUR","rate":"0.3212"},"transactions":[{"txid":"3EA591FED2F1F61263CB66AAC6BCF520B0714A08F2481D56DE267F31E0C782B9","risk":null}],"name":null,"description":null,"metadata":null,"custom_id":null,"success_redirect_url":null,"created_at":"2019-04-09T15:22:09+00:00","expires_at":"2019-04-09T15:32:09+00:00"}}'# Value of X-Cryptopay-Signature headersignature = '7c021857107203da4af1d24007bb0f752e2f04478e5e5bff83719101f2349b54'verifier.verify(body, signature) # => true
Every new callback request will have a new value of the X-Cryptopay-Signature
header. Make sure you are comparing the hash to the right header.
A callback secret is available in the "Settings → API" section in your Cryptopay account.