Fidel.ukFidel - Home

Transactions

The Fidel API Transaction object is the central piece of data in your card-linked application. When a customer makes a purchase with a linked card in any of the program's participating locations, Fidel tracks the transaction in the payment card networks. The Fidel API sends the data to your server in JSON format through webhooks.

Transaction Object

API version from 2019-03-05

transaction.json

{
  "id": "7fdfd5d8-9589-402f-8477-4a727ad138a2",
  "accountId": "4ed4b72b-aa4c-43a1-8054-da6d1368e17a",
  "amount": 100,
  "auth": true,
  "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": "apple-pay",
  "brand": {
    "id": "9d136f2e-df99-4a08-a0a5-3bc1534b7db8",
    "logoURL": "https://example.com/logo.png",
    "name": "Coffee Brand",
    "metadata": null
  },
  "card": {
    "id": "bc538b71-31c5-4699-820a-6d4a08693314",
    "firstNumbers": "555500",
    "lastNumbers": "5001",
    "scheme": "visa",
    "metadata": {
      "id": "00012345",
      "name": "Joseph Cooper"
    }
  },
  "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 wallet property could be one of: "apple-pay" | "google-pay" | "samsung-pay".

JSON Response on API versions to 2018-08-16
transaction.json
{
  "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 he 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 \
  https://api.fidel.uk/v1/transactions/a375e18f-0678-40fa-aa8b-4875e2146437 \
  -H 'Content-Type: application/json' \
  -H 'Fidel-Key: sk_test_50ea90b6-2a3b-4a56-814d-1bc592ba4d63'

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.

Note
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.

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 \
  https://api.fidel.uk/v1/transactions/test \
  -H 'content-type: application/json' \
  -H 'fidel-key: sk_test_50ea90b6-2a3b-4a56-814d-1bc592ba4d63' \
  -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 Create transaction link, located on the left side, in the ENDPOINTS 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 Send 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 transaction' 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.