Callbacks

Callbacks are used for retrieving state changes of initiated processes on specific URLs.

Types and statuses in callbacks

Transaction types: deposit / withdrawal / incoming / outgoing

Transaction statuses: new / processing / executed* / cancelled*

Operation types: deposit / withdrawal / exchange

Operation statuses: new / processing / executed* / cancelled*

*final statuses

Callback authorization

As an additional security layer, a Callback token can be generated, and received callbacks will have a X_SIGNATURE in the header.

The value of X_SIGNATURE is a callback body (JSON string), signed by the Callback token HMAC-SHA256.

The callback token is displayed only once, when you generate/re-generate it in the Settings->Integration->Callback token for Tunell Gateway section (Business Dashboard).

You can validate the X_SIGNATURE generation logic by comparing the result with the provided example.

Example:

Callback token: db80953ab79860450a75c35c56cc79bf
Callback body: {"id":"31d236fc-a1fe-4288-8896-ea385659b40c","referenceId":"Outgoing_Ref_102","type":"outgoing","amount":100,"amountType":"purchase","status":"processing","statusNote":null,"timestampCreated":"2022-01-01 00:00:00.000001 +03:00","timestampUpdated":"2022-01-01 00:00:00.000001 +03:00","operations":[{"id":1003,"type":"exchange","status":"processing","currency":"USDT_ERC20","exchangeFrom":"EUR","amount":97.713505,"rate":1.0234,"amountFinal":100}],"callbackId":13}

X_SIGNATURE: a2cc5fe1841f1f6a0a32ff0779cb6939dea6f5ac9f656b938c54a187bb4a1105

Callback examples

Incoming (deposit with autoconvert)

Note: the second callback will have the "executed" operation depending on what was executed first - exchange or deposit

{
        "id":"65757b70-ef85-4c63-bebb-4eb75a5f8832",
        "referenceId":"Address_Ref_2345",
        "type":"incoming",
        "amount": 100,
        "status":"processing",
        "statusNote":null,
        "timestampCreated":"2022-01-01 00:00:00.000001 +03:00",
        "timestampUpdated":"2022-01-01 00:00:00.000001 +03:00",
        "operations": [
                {
                                "id":1005,
                                "type":"deposit",
                                "status":"processing",
                                "addressSource":"0x621D1d...bd0dc2",
                                "addressDestination":"0xe0a113...c913F6",
                                "currency":"USDT_ERC20",
                                "amount":100,
                                "serviceFee":2,
                                "networkFee": 0.0001,
                                "amountFinal":97.9999,
                                "txHash":"0x17gh3f4e70...2edfb4c11b"
                },
                {
                                "id":1006,
                                "type":"exchange",
                                "status":"processing",
                                "currency":"USDT_ERC20",
                                "exchangeTo":"EUR",
                                "amount":97.9999,
                                "rate":0,
                                "amountFinal": null
                }
        ],
        "callbackId":13
}

{
        "id":"65757b70-ef85-4c63-bebb-4eb75a5f8832",
        "referenceId":"Address_Ref_2345",
        "type":"incoming",
        "status":"processing",
        "statusNote":null,
        "timestampCreated":"2022-01-01 00:00:00.000001 +03:00",
        "timestampUpdated":"2022-01-01 00:02:15.123123 +03:00",
        "operations": [
                {
                                "id":1005,
                                "type":"deposit",
                                "status":"processing",
                                "addressSource":"0x621D1d...bd0dc2",
                                "addressDestination":"0xe0a113...c913F6",
                                "currency":"USDT_ERC20",
                                "amount":100,
                                "serviceFee":2,
                                "networkFee":0.0001,
                                "amountFinal":97.9999,
                                "txHash":"0x17gh3f4e70...2edfb4c11b"
                },
                {
                                "id":1006,
                                "type":"exchange",
                                "status":"executed",
                                "currency":"USDT_ERC20",
                                "exchangeTo":"EUR",
                                "amount":97.9999,
                                "rate":1,
                                "amountFinal":97.99
                }
        ],
        "callbackId":13
}

{
        "id":"65757b70-ef85-4c63-bebb-4eb75a5f8832",
        "referenceId":"Address_Ref_2345",
        "type":"incoming",
        "status":"executed",
        "statusNote":"Incoming successfully executed",
        "timestampCreated":"2022-01-01 00:00:00.000001 +03:00",
        "timestampUpdated":"2022-01-01 00:02:42.123123 +03:00",
        "operations": [
                {
                                "id":1005,
                                "type":"deposit",
                                "status":"executed",
                                "addressSource":"0x621D1d...bd0dc2",
                                "addressDestination":"0xe0a113...c913F6",
                                "currency":"USDT_ERC20",
                                "amount":100,
                                "serviceFee":2,
                                "networkFee":0.0001,
                                "amountFinal":97.9999,
                                "txHash":"0x17gh3f4e70...2edfb4c11b"
                },
                {
                                "id":1006,
                                "type":"exchange",
                                "status":"executed",
                                "currency":"USDT_ERC20",
                                "exchangeTo":"EUR",
                                "amount":97.9999,
                                "rate":1,
                                "amountFinal":97.99
                }
        ],
        "callbackId":13
}

Outgoing (withdrawal with autoconvert)

{
        "id":"31d236fc-a1fe-4288-8896-ea385659b40c",
        "referenceId":"Outgoing_Ref_102",
        "type":"outgoing",
        "amount":100,
        "status":"processing",
        "statusNote":null,
        "timestampCreated":"2022-01-01 00:00:00.000001 +03:00",
        "timestampUpdated":"2022-01-01 00:00:00.000001 +03:00",
        "operations": [
                {
                                "id":1003,
                                "type":"exchange",
                                "status":"processing",
                                "currency":"USDT_ERC20",
                                "exchangeFrom":"EUR",
                                "amount":97.713505,
                                "rate":0,
                                "amountFinal":null
                }
        ],
        "amountType":"purchase",
        "callbackId":13
}

{
        "id":"31d236fc-a1fe-4288-8896-ea385659b40c",
        "referenceId":"Outgoing_Ref_102",
        "type":"outgoing",
        "amount":100,
        "status":"processing",
        "statusNote":null,
        "timestampCreated":"2022-01-01 00:00:00.000001 +03:00",
        "timestampUpdated":"2022-01-01 00:00:15.123123 +03:00",
        "operations": [
                {
                                "id":1003,
                                "type":"exchange",
                                "status":"executed",
                                "currency":"USDT_ERC20",
                                "exchangeFrom":"EUR",
                                "amount":97.713505,
                                "rate":1.0234,
                                "amountFinal":100
                },
                {
                                "id":1004,
                                "type":"withdrawal",
                                "status":"processing",
                                "address":"0xe0a113...c913F6",
                                "currency":"USDT_ERC20",
                                "amount":100,
                                "serviceFee":2.5,
                                "networkFee":0.25,
                                "currencyNetworkFee":"USDT_ERC20",
                                "networkFeeType":1,
                                "amountFinal":97.25,
                                "txHash":null
                }
        ],
        "amountType":"purchase",
        "callbackId":13
}

{
        "id":"31d236fc-a1fe-4288-8896-ea385659b40c",
        "referenceId":"Outgoing_Ref_102",
        "type":"outgoing",
        "amount":100,
        "status":"executed",
        "statusNote":"Outgoing successfully executed",
        "timestampCreated":"2022-01-01 00:00:00.000001 +03:00",
        "timestampUpdated":"2022-01-01 00:03:21.123123 +03:00",
        "operations": [
                {
                                "id":1003,
                                "type":"exchange",
                                "status":"executed",
                                "currency":"USDT_ERC20",
                                "exchangeFrom":"EUR",
                                "amount":97.713505,
                                "rate":1.0234,
                                "amountFinal":100
                },
                {
                                "id":1004,
                                "type":"withdrawal",
                                "status":"processing",
                                "address":"0xe0a113...c913F6",
                                "currency":"USDT_ERC20",
                                "amount":100,
                                "serviceFee":2.5,
                                "networkFee":0.25,
                                "currencyNetworkFee":"USDT_ERC20",
                                "networkFeeType":1,
                                "amountFinal":97.25,
                                "txHash":"0x17gh3f4e70...2edfb4c11b"
                }
        ],
        "amountType":"purchase",
        "callbackId":13
}

Fiat withdrawal

{
  "id": "1a740268-75a4-47ad-9306-dbb9cdcfba8e",
  "referenceId": null,
  "type": "fiat_manual_withdrawal",
  "amount": 1,
  "status": "new",
  "statusNote": null,
  "timestampCreated": "2022-01-01 00:00:00.000001 +03:00",
  "timestampUpdated": "2022-01-01 00:00:00.000001 +03:00",
  "operations": [
    {
      "id": 1007,
      "type": "fiat_manual_withdrawal",
      "status": "processing",
      "currency": "EUR",
      "amount": 1,
      "ibanTo": "EU123IBANTEST12312345",
      "ibanFrom": null
    }
  ],
  "callbackId": 15
}

{
  "id": "1a740268-75a4-47ad-9306-dbb9cdcfba8e",
  "referenceId": null,
  "type": "fiat_manual_withdrawal",
  "amount": 1,
  "status": "processing",
  "statusNote": null,
  "timestampCreated": "2022-01-01 00:00:00.000001 +03:00",
  "timestampUpdated": "2022-01-01 00:12:42.123123 +03:00",
  "operations": [
    {
      "id": 1007,
      "type": "fiat_manual_withdrawal",
      "status": "processing",
      "currency": "EUR",
      "amount": 1,
      "ibanTo": "EU123IBANTEST12312345",
      "ibanFrom": null
    }
  ],
  "callbackId": 15
}

{
  "id": "1a740268-75a4-47ad-9306-dbb9cdcfba8e",
  "referenceId": null,
  "type": "fiat_manual_withdrawal",
  "amount": 1,
  "status": "executed",
  "statusNote": "Executed by ECNG Digital",
  "timestampCreated": "2022-01-01 00:00:00.000001 +03:00",
  "timestampUpdated": "2022-01-01 00:32:42.123123 +03:00",
  "operations": [
    {
      "id": 1007,
      "type": "fiat_manual_withdrawal",
      "status": "executed",
      "currency": "EUR",
      "amount": 1,
      "ibanTo": "EU123IBANTEST12312345",
      "ibanFrom": "EU987IBANTEST98798765"
    }
  ],
  "callbackId": 15
}