Webhooks

This document serves as a guide for integrating Guardarian's webhooks functionality with partner applications. It covers the technical details of how webhooks work, the process for setting up and configuring webhooks in partner applications, and the various events and data that can be received via webhooks. The document also provides examples of how partner applications can use webhooks to receive real-time updates and notifications from Guardarian's system.

Integration process

To enable webhooks, contact your Business Development manager.

If the request is approved, you must

• Provide an endpoint where Guardarian will send webhook payloads.
• Get confirmation that Guardarian has added the settings.

note

If the partner uses an IP allowlist, the Business Development manager can provide the Guardarian IP addresses.

How it works

Partners are notified when the status of one of their customers' transactions changes. When the transaction status changes to one of the specified statuses, Guardarian notifies the partner through a webhook to the configured endpoint.

Status list:

• new;
• failed;
• refunded;
• finished;
• expired;
• cancelled;

Webhook payload

Field	Event type	New	Expired	Cancelled	Failed	Refunded	Finished
id		✓	✓	✓	✓	✓	✓
email		✓	✓	✓	✓	✓	✓
errors		✓	✓	✓	✓	✓	✓
status		✓	✓	✓	✓	✓	✓
location		✓	✓	✓	✓	✓	✓
to_amount		✓	✓	✓	✓	✓	✓
created_at		✓	✓	✓	✓	✓	✓
partner_id		✓	✓	✓	✓	✓	✓
to_network		✓	✓	✓	✓	✓	✓
updated_at		✓	✓	✓	✓	✓	✓
from_amount		✓	✓	✓	✓	✓	✓
output_hash		✓	✓	✓	✓	✓	✓
payout_type		✓	✓	✓	✓	✓	✓
to_currency		✓	✓	✓	✓	✓	✓
deposit_type		✓	✓	✓	✓	✓	✓
from_network		✓	✓	✓	✓	✓	✓
from_currency		✓	✓	✓	✓	✓	✓
refund_reason		✓	✓	✓	✓	✓	✓
status_reason		✓	✓	✓	✓	✓	✓
payout_address		x	x	✓	✓	✓	✓
status_details		✓	✓	✓	✓	✓	✓
expected_to_amount		✓	✓	✓	✓	✓	✓
from_amount_in_eur		✓	✓	✓	✓	✓	✓
expected_from_amount		✓	✓	✓	✓	✓	✓
initial_from_currency		✓	✓	✓	✓	✓	✓
payout_payment_category		✓	✓	✓	✓	✓	✓
deposit_payment_category		✓	✓	✓	✓	✓	✓
external_partner_link_id		✓	✓	✓	✓	✓	✓
to_currency_with_network		✓	✓	✓	✓	✓	✓
from_currency_with_network		✓	✓	✓	✓	✓	✓
initial_expected_from_amount		✓	✓	✓	✓	✓	✓
version		✓	✓	✓	✓	✓	✓
requesterType		✓	✓	✓	✓	✓	✓

Guardarian does not provide the reason for refunded or failed transactions in callbacks for security reasons. To enable webhooks, contact your Business Development manager.

New

Occurs when the system creates a transaction after the partner submits a create transaction request.

{
  "payload" : {
    "id": "5211023988",
    "email": null,
    "errors": [],
    "status": "new",
    "location": "DE",
    "to_amount": null,
    "created_at": "2025-11-07T11:57:34.880Z",
    "partner_id": "6269619154",
    "to_network": "BSC",
    "updated_at": "2025-11-07T11:57:34.902Z",
    "from_amount": "0",
    "output_hash": null,
    "payout_type": "CN_CUSTODY",
    "to_currency": "USDT",
    "deposit_type": "VISA_MC6",
    "from_network": "EUR",
    "from_currency": "EUR",
    "refund_reason": "",
    "status_reason": "",
    "status_details": null,
    "estimate_breakdown": {
      "toAmount": "221.77521931793637",
      "fromAmount": 200,
      "networkFee": {
        "amount": "0.05825908",
        "currency": "USDT"
      },
      "partnerFee": {
        "amount": "3.4",
        "currency": "EUR",
        "percentage": "1.7%"
      },
      "serviceFees": [
        {
          "name": "Service fee",
          "amount": "1",
          "currency": "EUR",
          "percentage": "0.5%"
        }
      ],
      "convertedAmount": {
        "amount": "199",
        "currency": "EUR"
      },
      "estimatedExchangeRate": "1.10887610"
    },
    "expected_to_amount": "221.77521931793638",
    "from_amount_in_eur": "200",
    "expected_from_amount": "200",
    "initial_from_currency": "EUR",
    "payout_payment_category": "CRYPTO",
    "deposit_payment_category": "VISA_MC",
    "external_partner_link_id": "01K9F2VP40115MYTXTAF814ES0",
    "to_currency_with_network": "Tether (Binance Smart Chain)",
    "from_currency_with_network": "Euro",
    "initial_expected_from_amount": "200",
  },
  "version": "1.0",
  "requesterType": "EXCHANGE"
}

Expired

Occurs when a customer doesn't complete all the necessary steps on time.

{
  "payload": {
    "id": "4432487061",
    "email": null,
    "errors": [],
    "status": "expired",
    "location": null,
    "to_amount": null,
    "created_at": "2025-10-31T09:54:13.254Z",
    "partner_id": " ",
    "to_network": "EUR",
    "updated_at": "2025-10-31T11:16:01.517Z",
    "from_amount": "0",
    "output_hash": null,
    "payout_type": "IVY",
    "to_currency": "EUR",
    "deposit_type": "CN_CUSTODY",
    "from_network": "TRX",
    "from_currency": "TRX",
    "refund_reason": "",
    "status_reason": "",
    "status_details": null,
    "expected_to_amount": "16.3453019301",
    "from_amount_in_eur": "16.858899840662236",
    "expected_from_amount": "66",
    "initial_from_currency": "TRX",
    "payout_payment_category": "SEPA",
    "deposit_payment_category": "CRYPTO",
    "external_partner_link_id": " ",
    "to_currency_with_network": "Euro",
    "from_currency_with_network": "TRON",
    "initial_expected_from_amount": "66"
  },
  "version": "1.0",
  "requesterType": "EXCHANGE"
}

Failed

Occurs when the system cannot complete the transaction.

{
  "payload": {
    "id": "6207518277",
    "email": null,
    "errors": [],
    "status": "failed",
    "location": "UA",
    "to_amount": null,
    "created_at": "2025-03-12T09:32:42.714Z",
    "partner_id": " ",
    "to_network": "BASE",
    "updated_at": "2025-03-12T09:33:39.676Z",
    "from_amount": "0",
    "output_hash": null,
    "payout_type": "CRYPTO_THROUGH_CN",
    "to_currency": "USDC",
    "deposit_type": "REVOLUT",
    "from_network": "USD",
    "from_currency": "USD",
    "refund_reason": "",
    "status_reason": "",
    "payout_address": "  ",
    "status_details": null,
    "expected_to_amount": "25.304816",
    "from_amount_in_eur": "24.74755713",
    "expected_from_amount": "27",
    "initial_from_currency": "USD",
    "payout_payment_category": "CRYPTO",
    "deposit_payment_category": "VISA_MC",
    "external_partner_link_id": "  ",
    "to_currency_with_network": "USD Coin (Base)",
    "from_currency_with_network": "United States dollar",
    "initial_expected_from_amount": "27"
  },
  "version": "1.0",
  "requesterType": "EXCHANGE"
}

Refunded

Occurs when the system returns the customer's funds.

{
  "payload": {
    "id": "5925744208",
    "email": null,
    "errors": [],
    "status": "refunded",
    "location": "HR",
    "to_amount": null,
    "created_at": "2025-04-01T10:51:03.547Z",
    "partner_id": " ",
    "to_network": "ETH",
    "updated_at": "2025-04-01T12:05:11.447Z",
    "from_amount": "285",
    "output_hash": null,
    "payout_type": "CRYPTO_THROUGH_CN",
    "to_currency": "USDC",
    "deposit_type": "REVOLUT",
    "from_network": "EUR",
    "from_currency": "EUR",
    "refund_reason": "",
    "status_reason": "",
    "payout_address": " ",
    "status_details": null,
    "expected_to_amount": "292.969604",
    "from_amount_in_eur": "285",
    "expected_from_amount": "285",
    "initial_from_currency": "EUR",
    "payout_payment_category": "CRYPTO",
    "deposit_payment_category": "REVOLUT_PAY",
    "external_partner_link_id": " ",
    "to_currency_with_network": "USD Coin",
    "from_currency_with_network": "Euro",
    "initial_expected_from_amount": "285"
  },
  "version": "1.0",
  "requesterType": "EXCHANGE"
}

Cancelled

Occurs when a customer cancels a transaction.

{
  "payload": {
    "id": "5794497998",
    "email": null,
    "errors": [],
    "status": "cancelled",
    "location": "DE",
    "to_amount": null,
    "created_at": "2025-10-31T12:45:05.066Z",
    "partner_id": " ",
    "to_network": "MATIC",
    "updated_at": "2025-10-31T12:57:04.270Z",
    "from_amount": "0",
    "output_hash": null,
    "payout_type": "CN_CUSTODY",
    "to_currency": "USDT",
    "deposit_type": "IVY",
    "from_network": "EUR",
    "from_currency": "EUR",
    "refund_reason": "transaction_was_cancelled_by_the_customer",
    "status_reason": "",
    "payout_address": " ",
    "status_details": null,
    "expected_to_amount": "36.3404199908473",
    "from_amount_in_eur": "32.52",
    "expected_from_amount": "32.52",
    "initial_from_currency": "EUR",
    "payout_payment_category": "CRYPTO",
    "deposit_payment_category": "SEPA",
    "external_partner_link_id": " ",
    "to_currency_with_network": "Tether (Polygon)",
    "from_currency_with_network": "Euro",
    "initial_expected_from_amount": "32.52"
  },
  "version": "1.0",
  "requesterType": "EXCHANGE"
}

Finished

Occurs when the system completes the exchange and sends the payout to the customer.

{
  "payload": {
    "id": "6093711135",
    "email": null,
    "errors": [],
    "status": "finished",
    "location": "PE",
    "to_amount": "0.75408722",
    "created_at": "2025-03-07T02:04:08.439Z",
    "partner_id": " ",
    "to_network": "SOL",
    "updated_at": "2025-03-07T02:11:51.251Z",
    "from_amount": "419.24",
    "output_hash": " ",
    "payout_type": "CRYPTO_THROUGH_CN",
    "to_currency": "SOL",
    "deposit_type": "VISA_MC5",
    "from_network": "PEN",
    "from_currency": "PEN",
    "refund_reason": "",
    "status_reason": "",
    "payout_address": " ",
    "status_details": null,
    "expected_to_amount": "0.7607362049013585",
    "from_amount_in_eur": "106.35651492776119838",
    "expected_from_amount": "419.24",
    "initial_from_currency": "PEN",
    "payout_payment_category": "CRYPTO",
    "deposit_payment_category": "APPLE_PAY",
    "external_partner_link_id": " ",
    "to_currency_with_network": "Solana",
    "from_currency_with_network": "Sol",
    "initial_expected_from_amount": "419.24"
  },
  "version": "1.0",
  "requesterType": "EXCHANGE"
}

Webhooks for KYC and deposit statuses

Additional webhook statuses are available upon request. To enable them, contact your Business Development manager and explain why they are required for the integration.

Guardarian can send additional webhooks for KYC and deposit statuses.

In KYC status webhooks, the status field can contain these values:

• "kycStarted" — when the customer starts the KYC process.
• "kycFailed" — when the KYC process fails for any reason.
• "kycFinished" — when the KYC process finishes successfully.

For kycFailed, Guardarian passes the reason in status_reason.

In deposit status webhooks, the status field can contain these values:

• "waitingForDeposit" — when Guardarian waits for a deposit from the customer.
• "depositReceived" — when the funds are received or pre-authorized (for the payment methods that support pre-authorization).
• "depositCaptured" — when the funds are captured after pre-authorization (for the payment methods that support pre-authorization).
• "depositFailed" — when a deposit fails for any reason.

For depositFailed, Guardarian passes the reason in status_reason.

Guardarian can also enable these events for specific partners:

• cryptoSent – when the transaction status is sending
• paymentSubmitted – when the transaction status is paid
• sharedTokenImported – emitted by Guardarian API when the customer is successfully created using a shared token (only if a shared token is passed during transaction creation)
• userRegistered – emitted by Guardarian API when the customer confirms their email