Part 6: Realtime Authorisations

Introduction

This section explains how a Blockchain Network receives booking events in real time and executes custom business logic—typically booking—based on the received data.

Fiat24 sends events using webhook-based communication, where the Blockchain Network hosts an HTTP server and Fiat24 acts as the client. The reason we need such a webhook is to compensate for the fact that blockchains like Mantle cannot confirm transactions within one second, while real-time decisions are required to fulfill transactions such as card spending.

Each Blockchain Network must provide a webhook and register it with the Fiat24 backend. The webhook must strictly adhere to the following specifications. Fiat24 sends HTTP POST requests in JSON format.

Communication Format

To use the Fiat24 notification system, Blockchain Network must share the following information:

1. Basic authentication credentials (username & password)

2. HTTP server URL

We strongly recommend whitelisting our IP 111.222.333.444 only.

Card Transactions

To ensure real-time processing within 1 second for critical operations like:

• Swiping a card to make an authorisation, or

• Increase the amount to a previous authorisation

• Reversing a booking

The webhook will send the following request and expect the response within 1 second.

Request Body of Authorisation transaction

{
    "authorize"  : {
       "authorizationToken"    : "edb0737f-06f3-4e3a-ab21-80dfd0ffb0de",
       "cardId"                : "MQ-100000010365-CARD-1745238070",
       "tokenId"               : "100000010365",
       "cardCurrency"          : "0xbE00f3db78688d9704BCb4e0a827aea3a9Cc0D62",
       "transactionCurrency"   : "HKD",
       "settlementCurrency"    : "0x2c5d06f591D0d8cd43Ac232c2B654475a142c7DA",
       "transactionAmount"     : "100050",
       "settlementAmount"      : "15036"
    },
    "trxInfo" : {
       "merchantId"            : "000001060020179",
       "merchant"              : "McDonalds Singapore",
       "mcc"                   : 4722,
       "city"                  : "Singapore",
       "country"               : "SGP"
    }
}

Request Body of Increment transaction

{
    "increment"  : {
       "authorizationToken"    : "edb0737f-06f3-4e3a-ab21-80dfd0ffb0de",
       "cardId"                : "MQ-100000010365-CARD-1745238070",
       "tokenId"               : "100000010365",
       "cardCurrency"          : "0xbE00f3db78688d9704BCb4e0a827aea3a9Cc0D62",
       "transactionCurrency"   : "HKD",
       "settlementCurrency"    : "0x2c5d06f591D0d8cd43Ac232c2B654475a142c7DA",
       "transactionAmount"     : "100050",
       "settlementAmount"      : "15036"
    },
    "trxInfo" : {
       "merchantId"            : "000001060020179",
       "merchant"              : "McDonalds Singapore",
       "mcc"                   : 4722,
       "city"                  : "Singapore",
       "country"               : "SGP"
    }
}

Request Body of Reverse transaction

{
    "reverse"  : {
       "authorizationToken"         : "edb0737f-06f3-4e3a-ab21-80dfd0ffb0de",
       "originalAuthorizationToken" : "556sfouf-5566-124h-558s-56332sk99l82",
       "cardId"                     : "MQ-100000010365-CARD-1745238070",
       "tokenId"                    : "100000010365",
       "transactionCurrency"        : "HKD",
       "settlementCurrency"         : "0x2c5d06f591D0d8cd43Ac232c2B654475a142c7DA",
       "transactionAmount"          : "100050",
       "settlementAmount"           : "15036",
       "originalPaidCurrency"       : "0xbE00f3db78688d9704BCb4e0a827aea3a9Cc0D62"
    }
}

Processing

• the field tokenId_ need to be transformed

  • For Mantle network, tokenId_ = tokenId_ - 100000000000

  • For BNB Chain network, tokenId_ = tokenId_ - 200000000000

• the fields cardCurrency_, settlementCurrency_, originalPaidCurrency_ need to be replaced by currency contracts deployed on the blockchain network.

  • Replace 0xbE00f3db78688d9704BCb4e0a827aea3a9Cc0D62 to your USD24 address

  • Replace 0xd41F1f0cf89fD239ca4c1F8E8ADA46345c86b0a4 to your CHF24 address

  • Replace 0x2c5d06f591D0d8cd43Ac232c2B654475a142c7DA to your EUR24 address

  • Replace 0x7288Ac74d211735374A23707D1518DCbbc0144fd to your CNH24 address

Response

200 OK

Response code 200 indicates the debit request is approved.

Response with Approved status

{
    "statusCode" : 200,
    
    "chainId"    : 5000,
    "tx" : "0xe674031db70f6fa4cfc9976107129324da4ffc504053b180299deeb37bfd1ce7"
}

401 NOK

Response code 401 indicates the debit request is NOT approved, and the transaction on MasterCard network will be declined.

Response with Rejected status

{
    "statusCode" : 401
}

403 Not Sufficient Fund

Response code 403 indicates either user's account has insufficient balance, or the balance is not authorised.

Response Body:

{
    "statusCode" : 403
}

500 Error

Response code 500 indicates the debit request has unexpected error from server side, and the transaction on MasterCard network will be declined.

Response of a Error status

{
    "statusCode" : 500
}