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)

Fiat withdrawal