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

The identifiers object includes the following properties, all of them being of string type or null:

• identifiers.amexApprovalCode: Unique code that is sent along with the authorization of the transaction by Amex. It mirrors the approvalCode property.
• identifiers.mastercardAuthCode: Unique code that is sent along with the authorization of the transaction by Mastercard. It mirrors the authCode property.
• identifiers.mastercardRefNumber: Unique identifier of the transaction provided by Mastercard. It is generated by Mastercard when the authorization request is received from the issuer. This is used by Fidel API to try to match a given clearing transaction with the corresponding authorization transaction.
• identifiers.mastercardTransactionSequenceNumber: Transaction sequence number provided by Mastercard. This is generated by Mastercard to identify the sequence of the transaction for a given PAN in a calendar day. Available only in clearing transactions.
• identifiers.MID: Card terminal identifier in a brand's location that may or may not be unique. MIDs can be different between auth and clearing.
• identifiers.visaAuthCode: Unique code that is sent along with the authorization of the transaction by Visa. It mirrors the authCode property.

Example of a transaction in JSON format (API version is 2022-07-13)
transaction.json
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465
{
  "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": "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"
    }
  },
  "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
  },
}

Transaction Event Types

In the life cycle of a transaction, there are multiple transaction events. One transaction event occurs at authorization time. Another transaction event occurs when the transaction has cleared, meaning the funds were successfully moved. If a payment gets reimbursed, that results in a third event. These are distinct events, and Fidel API processes all of them, even if you're not registering webhooks to listen for all event types.

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

Authorization

Authorization transactions are processed when a purchase is made on a linked card at a location (either in-store or online). For example, when a customer makes a purchase at a location with their linked card, the transaction.auth webhook will be triggered and the transaction object will be sent to your specified URL in real time.

Clearing

Clearing transactions - also known as settled transactions - are processed when a payment transaction settles. This usually happens 48 to 72 hours after a payment is made. Clearing transactions trigger the transaction.clearing webhook event.

Refund

Refund transactions are processed when a payment is refunded, i.e., 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. 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 refundTransactionId property set to the transactionId of the refunded transaction. Updates on the original transaction will not trigger a webhook event.

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

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

12345678910
curl -X POST \
  https://api.fidel.uk/v1/transactions/test \
  -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.

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.