TransactionsImprove this page

The Fidel API Transaction object is the central piece of data in your card-linked application. When a user makes a purchase with a linked card in a program participating brand location, Fidel captures the transaction event in real-time. The Fidel API then sends the data to your server in JSON format through webhooks.

One transaction event occurs at authorisation time. The other transaction event occurs when the transaction has cleared. These are two distinct events, and Fidel processes both of them, even if you're not registering webhooks to listen for both event types. Because we bill based on transaction events, and we process both of them, you'll get charged for both of them, regardless of the number or type of webhooks you have registered with Fidel.

Transaction Object

API version from 2022-07-13


  "id": "7fdfd5d8-9589-402f-8477-4a727ad138a2",
  "accountId": "4ed4b72b-aa4c-43a1-8054-da6d1368e17a",
  "amount": 100,
  "approvalCode": "AA00BB",
  "auth": true,
  "authCode": "A73H890",
  "cardPresent": false,
  "cleared": false,
  "created": "2019-04-09T16:00:00.644Z",
  "currency": "GBP",
  "datetime": "2019-04-10T15:59:30",
  "programId": "6e38aa0c-b7ef-46bd-b1bd-c07c647d9cba",
  "refundTransactionId": null,
  "updated": "2019-04-09T16:00:00.644Z",
  "wallet": null,
  "brand": {
    "id": "9d136f2e-df99-4a08-a0a5-3bc1534b7db8",
    "logoURL": "",
    "name": "Coffee Brand",
    "metadata": null
  "card": {
    "id": "bc538b71-31c5-4699-820a-6d4a08693314",
    "firstNumbers": "555500",
    "lastNumbers": "5001",
    "scheme": "visa",
    "metadata": {
      "id": "00012345"
  "identifiers": {
    "amexApprovalCode": "AA00BB",
    "mastercardAuthCode": null,
    "mastercardRefNumber": "AABBCCDDE",
    "mastercardTransactionSequenceNumber": "0000001234567",
    "MID": "8552067328",
    "visaAuthCode": "A73H890"
  "location": {
    "id": "7a916fbd-70a0-462f-8dbc-bd7dbfbea140",
    "address": "53 Frith Street",
    "city": "London",
    "countryCode": "GBR",
    "postcode": "W1D 4SN",
    "timezone": "Europe/London",
    "geolocation": {
      "latitude": 51.513716,
      "longitude": -0.13202
    "metadata": {
      "id": "0001234567",
      "name": "Coffee Brand HQ"
  "offer": {
    "qualified": true,
    "id": "eeefb94b-d11c-44db-81d7-d86a9fcc4069",
    "message": [],
    "qualificationDate": null,
    "cashback": 2.5,
    "performanceFee": 0.3

The authCode property is present only for Mastercard and Visa transactions, and will mirror the identifiers.mastercardAuthCode or identifiers.visaAuthCode properties, depending on the issuing card for the transaction. The approvalCode property is present only for Amex transactions and will mirror the identifier.amexApprovalCode property.

The wallet property has been deprecated since August 2019 because of privacy concerns, and will always return null on transactions created after that date. If you're retrieving a transaction that was created before August 2019, the property could be one of: "apple-pay" | "google-pay" | "samsung-pay".

JSON Response on API versions to 2018-08-16


  "id": "7fdfd5d8-9589-402f-8477-4a727ad239a2",
  "accountId": "4ed4b62b-aa4c-43a1-8064-da6d1368e17a",
  "programId": "6e38aa0c-b7ef-46bd-b1bd-c07c648d9cba",
  "brandId": "9d136f2e-df99-4a08-a0a5-3bc1534b7db9",
  "locationId": "7a916fbd-70a0-462f-8dbc-bd7dbfbea160",
  "cardId": "bc538b71-31c5-4699-840a-6d4a08693314",
  "amount": 100,
  "currency": "GBP",
  "countryCode": "GBR",
  "scheme": "visa",
  "firstNumbers": "555500",
  "lastNumbers": "5001",
  "address": "2 Soho Square",
  "postcode": "W1D3PX",
  "city": "London",
  "merchantId": "12345",
  "live": false,
  "auth": true,
  "cleared": true,
  "time": "2017-03-02T19:12:01.743Z",
  "date": "2017-03-02T19:12:01.743Z",
  "created": "2017-03-02T19:12:01.744Z",
  "updated": "2017-03-02T19:12:01.744Z",
  "offer": null,
  "medatada": {
    "id": "your-unique-id",
    "property": "value"

The Fidel API currently supports three types of transactions: authorisation transactions, clearing transactions and refund transactions.

Authorisation transactions are processed when a purchase registers on a linked card. For example, when a customer makes a payment in-store or online in real time. When a customer makes a payment with a linked debit/credit card in an auth-enabled location, the transaction.auth webhook is also triggered and the transaction object sent to your specified URL in real time.

Clearing transactions, also known as “settled transaction”, are processed when a payment transaction settles, usually happens 48 to 72 hours after a payment registers. The Fidel processes for clearing transactions are also triggering the transaction.clearing webhook events. The processes run daily at 12:00 UTC for Mastercard and multiple times per day for Visa and American Express. Only one transaction is sent per event.

Refund transactions are processed when a payment is refunded, usually when a purchased item is returned, and the payment reverses. A refunded transaction triggers two webhook events, transaction.clearing and transaction.refund, with the auth property set to false. The amount on both events is negative. The Fidel API tries to identify the initial transaction for which the refund was issued, using cardId, locationId, merchantId, amount and datetime. If an associated initial transaction is identified, the webhook data contains the originalTransactionId. If no initial transaction is identified, the data comes in on both webhooks with a negative amount but no originalTransactionId property.

The original transaction has a new refundTransactionId property, set to the transactionId of the refunded transaction. Updates on the original transaction will not trigger a webhook event.

You will receive both transaction.auth events in real-time and transaction.clearing events (in the next 48 to 72 hours). When clearing transactions are processed, the Fidel API matches the clearing transaction to the corresponding authorisation transaction if it exists by updating the cleared property from false to true.

If you need the updated information about the original transaction, you can retrieve it using our Transactions API, with the originalTransactionId from the refunded Transaction object.

curl -X GET \ \
  -H 'Content-Type: application/json' \
  -H 'Fidel-Key: <KEY>'

We suggest that you use the auth event to notify the user that you registered the transaction and will fulfil the reward when the transaction clears. The clearing event is the confirmation that the transaction has been settled.

Please allow up to 24h after linking a Mastercard card to start receiving real-time authorisation transactions.

Test Transactions

For testing purposes, you can use the API Playground in the Fidel Dashboard test environment to create test transactions and test your application logic. Alternatively, you can use the Create Test Transaction API endpoint to create authorisation test transaction. You can see an example implementation for creating and clearing test transactions via the API in our sample application on GitHub.

To create a test transaction, you will need a Program, a Location and a test Card linked to the program.

Create Test Transactions Using the API
curl -X POST \ \
  -H 'Content-Type: application/json' \
  -H 'Fidel-Key: <KEY>' \
  -d '{
    "amount": 10,
    "cardId": "bc538b71-31c5-4699-820a-6d4a08693314",
    "locationId": "7a916fbd-70a0-462f-8dbc-bd7dbfbea140"
Create Test Transactions Using the API Playground

On the Fidel Dashboard, go to the Playground option in the navigation menu. Click on the transactions /create link, located on the left side, in the Endpoints drawer menu. The method will be set to POST and the endpoint to /transactions/test. An editable sample JSON object like the following one will be used to create the transaction.

Create transaction

To create a test transaction, use the dropdown menus to select the Program, Location and Card for the transaction. These selections will be used to populate the cardId, locationId and the amount in the JSON payload. You can modify any of the properties in the JSON file (including the amount).

Click Run and a test authorisation transaction will be created. If the transaction is created successfully, you will see the transaction object in the Response body box. If you have registered a transaction.auth webhook event for this program, the authorisation transaction object will be sent to your webhook URL as well.

Clear Test Transactions Using the Dashboard

To clear an authorisation test transaction, you can navigate to the Transaction option in the Dashboard navigation menu. You'll see all your transactions listed there. Find the one you want to change the status of, click on the three dots on the right side of it. A popup menu will appear, and you should click on the 'Clear' option. This action will change the status of the transaction from auth to cleared, and trigger the transaction.clearing webhook event.

API Reference

To find out more about our Transactions API and how to use it with your application, please visit the Fidel API Reference.