Documentation

API Status: Affected

Introduction

Fidel API provides a developer-friendly, secure and reliable API to link payment cards to mobile and web applications. Through a single API, developers can securely access real-time data from the card networks and build applications on top of a powerful financial infrastructure platform.

Once a card is enrolled and verified, every payment event (i.e. authorization, clearing, refund) from that card will be sent to your server in real time. The transaction data you receive is of high quality, accuracy and consistency. This allows you to build a rich experience for cardholders at the moment the transaction is made, while they are still at the terminal or checkout page.

Card Coverage

The Transaction Stream API is available for the following card networks and countries:

Stream Card Coverage

Transaction Life Cycle

To understand how the Transaction Stream API works and the data it provides to you, it’s important to understand the authorization processes and fund movements that happen when a cardholder makes a purchase.

Authorization, clearing

When a cardholder uses a credit or debit card to make a purchase, the funds are not immediately transferred to the merchant’s account. There are two important events that need to happen for the funds to be transferred: authorization and clearing. Here’s how these events occur:

  1. When the cardholder initiates the transaction, their bank (issuing bank, issuer) needs to authorize it. For this, the authorization request must travel from the merchant through the merchant’s bank (acquirer) and through the card network to the issuing bank.
  2. If the cardholder has the necessary funds, the issuing bank sends back on the same path the authorization response containing the authorization code (auth code), which means that the cardholder can make the purchase.
    At this point, the payment amount is still on the cardholder’s account. However, the merchant can safely provide the purchased goods or services, as the transaction was authorized. Usually, the merchant places an authorization hold on the cardholder’s account for the authorized amount of the sale.
  3. The next step is the clearing request, which initiates the administrative process of the payment.
    Typically, clearing occurs at the end of the day, when the acquirer bank collects all the transaction information (amounts, auth codes, etc.) from all payment endpoints of the merchant. Then, on its own processing schedule, the acquirer starts processing the payments with the respective issuing banks.
  4. The issuing bank sends back the clearing response, and the funds are moved to the merchant’s account.

Note that at Fidel API both cleared and settled transactions are referred to as cleared transactions.

Where does Fidel API enter the picture?

As we saw, all the transaction events go through the card networks. This is where Fidel API comes into play.

When a cardholder links a card to a Fidel API program, Fidel API verifies the card with the associated card network and creates a token to represent that card, thereby not storing sensitive information about the cardholder or card itself. Using this token-based identification, after you verify that the user has access to the card, the card network starts sending the transactions made on that card to Fidel API.

You can then retrieve the collected data using the Transaction Stream API. You can also register webhooks to be notified about the card’s transaction events (new authorization, clearing, etc.).

Collected Data

The Transaction Stream API collects the following data for the supported transactions made with linked cards:

Field nameDescriptionType
accountIdThe unique identifier of the user account at Fidel API.string
amountThe amount of the transaction in the currency it was charged in. In the case of international transactions, the transaction has both amount and billingAmount fields filled in and their value may differ due to the conversion.number
authIndicates whether the transaction was authorized by the issuing bank.boolean
authCodeUnique code that authorizes a transaction, sent by the issuer/the PCN on the issuer's behalf when approving a transaction. It mirrors the identifiers.visaAuthCode property. You can use the authorization code in combination with the card number to match an authorization event and a clearing event when the transaction ID is different.string (or null)
billingAmountThe amount in the currency of the country of issuance, converted from the original purchase currency. In the case of international transactions, the transaction has both amount and billingAmount fields filled in and their value may differ due to the conversion.number (or null)
billingCurrencyThe currency of the country of issuance.string in ISO 4217 format (or null)
brand.nameThe name of the merchant where the purchase was made.string
card.firstNumbersThe first numbers of the card, used for helping users identify their cards.string
card.idThe tokenized card identifier used by Fidel API.string
card.lastNumbersThe last numbers of the card, used for helping users identify their cards.string
card.schemeThe payment network (Visa).string
cardPresentNot in usenull
clearedIndicates whether the transaction was cleared.boolean
createdThe timestamp in UTC format when the transaction object was created in the Fidel API database.string, timestamp in UTC format
currencyThe original currency of the purchase.string in ISO 4217 format
datetimeThe timestamp (in the local timezone of the merchant/acquirer) of the transaction.string, timestamp in UTC format
idThe unique identifier of the transaction.string
identifiers.amexApprovalCodeNot in use in Transaction Stream programs.null
identifiers.mastercardAuthCodeNot in use in Transaction Stream programs.null
identifiers.mastercardRefNumberNot in use in Transaction Stream programs.null
identifiers.mastercardTransactionSequenceNumberNot in use in Transaction Stream programs.null
identifiers.visaAuthCodeUnique code that is sent along with the authorization of the transaction by Visa. It mirrors the authCode property.string (or null)
locationDetails of the merchant where the purchase was made:
location.city, location.countryCode, location.postcode, location.state.string (city, postcode, and state can be null)
merchantCategoryCodeThe merchant category code (MCC) provided by the card network. It is used to classify businesses by the types of goods provided or services rendered.string
programIdThe identifier of the Fidel API program that this transaction is linked to.string
programTypeThe type of the Fidel API program that this transaction is linked to (transaction-stream).string
updatedThe date and time when this transaction was last time updated (authorized/cleared/reimbursed).string, timestamp in UTC format
walletNot in use.null

You can see the JSON format of an example transaction object in the Transactions page.

Learn More

Start your Fidel API journey by creating an account. Read the Getting Started page to learn how.

You can see an example implementation for integrating the Fidel APIs and Web SDK in our sample application on GitHub.

Check out the API Reference to see all available requests, code examples and response payloads.