Callbacks

When creating a payment or payout, you can specify a callback_url. As soon as the payment reaches new status you will receive a notification at the specified url with the following content:

{
  "status": "complete",
  "transaction_id": "703ea600-f5bc-4ef0-b9b6-7af6000abf7e",
  "amount": {
    "currency": "USD",
    "value": "1.0"
  },
  "redirect_url": "https://pay.paylander.com/703ea600-f5bc-4ef0-b9b6-7af6000abf7e/",
  "channel": "2bad7e2d-15b1-4078-b5ee-01ff2e4491b3",
  "payment_method": {
    "type": "card"
  },
  "create_date": "2025-11-24T20:10:58.065252+00:00",
  "external_id": "external-id"
}

The request will also contain the following headers, which you can use to make sure that the callback is genuine:

{
  "Content-Type": "application/json",
  "X-API-KEY": "key",
  "X-TIMESTAMP": "1764015058.078768",
  "X-SIGNATURE": "ac22c7d3ea3bb8d304167cacc8d2b7486803242c8c5a35904a632e939496eb79"
}

An example of a authenticity check function in Python:

import hmac
import hashlib
import json

def verify_signature(
  secret_key: str,
  raw_body: str,
  timestamp: str,  # X-TIMESTAMP
  received_signature: str  # X-SIGNATURE
) -> bool:
    message = f"{timestamp}{raw_body}"

    expected_signature = hmac.new(
        secret_key.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected_signature, received_signature)

Note: For verification, use the secret key corresponding to the public key from the X-API-KEY header. The secret key is known only to you and our system.

If the verification is successful, send the 200 code in response to confirm receipt of the callback.