Guardarian exchange webhooks

This document serves as a comprehensive 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

This feature is available by request, please contact [email protected] or your account manager.

if request is approved, then you must

• provide an endpoint where to send information via contact [email protected] or your account manager
• get confirmation that we have added all the settings

note

If you want to add our IP to the whitelist, we will provide them in a reply letter

How does it work?

Our partners require notifications of status changes for their user’s B2C exchanges. When the transaction status changes to one of the specified statuses, we will notify the partner via a webhook to the desired endpoint.

Status list:

• new;
• failed;
• refunded;
• finished;
• expired;
• canceled;

Data format

{
  "requesterType": "EXCHANGE",
  "version": "1.0",
  "payload": {
		"id": 5517577077,
	  "status": "new",
	  "email": "[email protected]",
	  "errors": [
	    {
	      "code": "customer_blocked_by_risk_control",
	      "reason": "Customer 5196934097 was blocked by risk control"
	    }
	  ],
	  "status_details": null,
	  "from_currency": "EUR",
	  "initial_from_currency": "EUR",
	  "from_network": "EUR",
	  "from_currency_with_network": "EUR",
	  "from_amount": 1200.24,
	  "deposit_type": "SEPA_1",
	  "payout_type": "SEPA_1",
	  "expected_from_amount": 1200.24,
	  "initial_expected_from_amount": 1200.24,
	  "to_currency": "BTC",
	  "to_network": "BNB",
	  "to_currency_with_network": "Binance Coin Mainnet",
	  "to_amount": 0.144,
	  "output_hash": "6146ccf6a66d994f7c363db875e31ca35581450a4bf6d3be6cc9ac79233a69d0",
	  "expected_to_amount": 0.144,
	  "location": "Somewhere",
	  "created_at": "2019-04-18T13:39:27.982Z",
	  "updated_at": "2019-04-18T13:39:27.982Z",
	  "partner_id": 2517577071,
	  "external_partner_link_id": "3245324",
	  "from_amount_in_eur": 1200.24,
	  "estimate_breakdown": {
	    "toAmount": 0.036606,
	    "fromAmount": 1000.24,
	    "serviceFees": [
	      {
	        "name": "Service fee",
	        "amount": 2.5,
	        "currency": "EUR"
	      }
	    ],
	    "convertedAmount": {
	      "amount": 997.74,
	      "currency": "EUR"
	    },
	    "estimatedExchangeRate": 0.0000366,
	    "networkFee": {
	      "amount": 0.00000267,
	      "currency": "BTC"
	    }
	  }
	}
}

Callback data examples for each event type:

*We do not provide reason of refunded/failed transaction in callbacks due to security reasons. If you would like to further investigate the reason of such event types — it can be done through our Customer Support team (please contact our Business Development team on this matter).

New: Occurs when a transaction is triggered and started

{
  "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 (transaction is active for 15 minutes to ~1h for instant payment methods and ~24h for Bank transfers)

{
  "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:

{
  "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:

{
  "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:

{
  "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"
}

Difference between event types is displayed below, the only event field that isn’t included in all event types is payout_address (absent in New and Expired transactions).

Fields	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_categpry		✓	✓	✓	✓	✓	✓
deposit_payment_category		✓	✓	✓	✓	✓	✓
external_partner_link_id		✓	✓	✓	✓	✓	✓
to_currency_with_network		✓	✓	✓	✓	✓	✓
from_currency_with_network		✓	✓	✓	✓	✓	✓
initial_expected_from_amount		✓	✓	✓	✓	✓	✓
version		✓	✓	✓	✓	✓	✓
requesterType		✓	✓	✓	✓	✓	✓

Webhooks for KYC and deposit statuses

(Available upon request: if you would like to enable additional webhook statuses, please contact [email protected] or your account manager with reasoning why this is required for your business model)

We have an option to send additional webhooks for KYC and deposit statuses.

In the KYC status webhooks the "status" field can pass the following values:

• "kycStarted" — when the customer starts the KYC process.
• "kycFailed" — when the KYC process is failed for any reason.
• "kycFinished" — when the KYC process is finished successfully.

For the webhooks with the "kycFailed" status, we pass the reason in the "status_reason" field.

In the deposit status webhooks the "status" field can pass the following values:

• "waitingForDeposit" - when we wait for a deposit from the user
• "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 the webhooks with the "depositFailed" status, we pass the reason in the "status_reason" field.

Also we have an option to send webhook for special partners with special status

• 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 user confirms their email