Transaction

Data Model

Partner Submission Status

Pliant aims to indicate which transactions have been synced to the partner app and which ones have not, as well as the possibility to freeze transaction data that is marked by the partner app as locked.

Each transaction has a so-called partner submission status (partnerSubmissionStatus). It allows the partner to reflect its own transaction status into Pliant. The possible values for this field are:

• NOT_SYNCED: the transaction was not stored on the partner's system yet.
• SYNCED: the transaction was synced to the partner's system and stored there.
• TEMP_LOCKED: the transaction is locked and cannot be changed (similar to LOCKED), but the partner can still go back to the SYNCED status.
• LOCKED: the transaction is immutable now in both systems (Pliant and partner) and thus no receipt can be uploaded or any field changed of this specific transaction. The status cannot be changed back to SYNCED or any other status. This is a final status.

Transaction Status

Pending

The transaction occurred on the merchant side. In this case, VISA sends us an authorization for the transactions with the transactions data such as date time, amount, local currency, transactions amount and card number. As soon as this authorization message arrives, we create the transactions in our system and show them in this pending status.

Confirmed

The previously pending transaction is now confirmed by VISA and the merchant.

Booked

Each authorized transaction is confirmed by VISA and Pliants banking partner separately. After we receive these confirmations from both, we update the status of the transactions to be booked. The transaction is now relevant for accounting purposes.

Declined

When a transaction is not authorized because of an error (e.g. wrong PIN, or CVV), or limitation (e.g. organization limit, card limit). The transaction declined.

Additionally, certain transactions may be declined, because the merchant did not initiated the transaction with the properer Strong Customer Authentication (SCA) method. Pliant declines the transaction then and the merchant normally initiates the same transaction again, this time with SCA enabled. Meaning the customer receives a one-time password via SMS and confirms the transaction. It then is processed correctly. You can identify those transactions by the decline reason SCA_REQUIRED*.

Reversed

This is more of an edge cases. Sometimes authorised transactions are reversed because the amount of the service or product changes, or the refund is done before the service or product is created or dispatched. For example, a user calls a ride on Uber for 10.00 EUR and pays the bill immediately after confirming the ride. If the user gives a tip to the driver, e.g. 2.00 EUR, at the end of the ride, the payment is firstly reversed and then another payment with an updated price (12.00 EUR) is created.

Transaction Types

The following transaction types are used in the Pliant platform and API.

Purchase

Purchase activity is when a user purchases something from a merchant. This is the most common type you will see, above 90% of transactions carry this type.

The amount is negative for this transaction type.

Refund

Normally a refund of a purchase. In seldom edge cases Visa might directly create a REFUND transaction.
Each refund transaction should have a corresponding purchase (if a purchase happened prior). For example, when you return an order back to the merchant.

The amount is normally positive for this transaction type.

Card Check (Status Inquiry)

In some cases, some merchants do card checks to see if the card is active or not. Example: When a user gives her card for a SaaS subscription. The merchant firstly checks if the card is valid and active and then charges.
There are two types of card checks. This is the second most common type, around 8% of transactions carry this type.

The amount is negative or zero for this transaction type.

0 amount card checks

There is a transactions but doesn’t include any amounts. Purely a card check.

Reversed card checks

Some cards checks with 1.00 USD, 1.00 EUR, ... (or any other currency) amounts and then reverse the transaction immediately. This is the old way of card checks. This type of transaction has always REVERSED status.

Chargeback

This type is similar to a refund, but the cause and reason are different. The user should initiate a chargeback by contacting her bank or credit card provider and claiming that the transaction doesn’t belong to her. The bank will refund the amount on the credit card the user. Each chargeback must have a corresponding purchase. Otherwise it cannot be initiated.

The amount is positive for this transaction type.

Recharge

Recharges can occur only after a chargeback. If the chargeback of the customer is objected to by the merchant, then it is investigated by authorities. If the authorities find the cardholder is right, then chargeback stays as it is. If the authorities find the merchant is right, the merchant will recharge the customer again. For a transaction with RECHARGE status, there must always be a PURCHASE and CHARGEBACK before.

The amount is negative or positive for this transaction type.

Cash Withdrawal

The cardholder withdrew cash at an ATM or similar.

The amount is negative for this transaction type.

Possible Combinations of Type and Status

To give you an idea of how often which type/status combinations occur, you can find here a rough overview of what to expect. Since the values below are rounded and also estimations, they do not add up to 100%.

Example Data

[
  {
    "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "cardholderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "cardId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "DECLINED",
    "type": "PURCHASE",
    "partnerSubmissionStatus": "LOCKED",
    "partnerSycnedAt": "2022-04-01T07:21:13.780Z",
    "partnerTempLockedAt": "2022-04-01T07:21:13.780Z",
    "partnerLockedAt": "2022-04-01T07:21:13.780Z",
    "category": "ADVERTISING_AND_MARKETING,",
    "billingAmount": {
      "value": 0,
      "currency": "string"
    },
    "transactionAmount": {
      "value": 0,
      "currency": "string"
    },
    "transactionCountry": "string",
    "transactionLocalTime": "2022-04-01T07:21:13.780Z",
    "createdAt": "2022-04-01T07:21:13.780Z",
    "authorizedAt": "2022-04-01T07:21:13.780Z",
    "confirmedAt": "2022-04-01T07:21:13.780Z",
    "reversedAt": "2022-04-01T07:21:13.780Z",
    "declineReason": {
      "type": "LOCKED_CARD",
      "title": {
          "en": "Card locked",
          "de": "Karte ist gesperrt"
      },
      "description": {
          "en": "The card is locked. You can unlock the card in the Wallet section of the cardholder app.",
          "de": "Die Karte ist gesperrt. Bitte überprüfen Sie den Kartenstatus im Web oder in der mobilen App. Für weitere Informationen wenden Sie sich bitte an den Administrator der Organisation."
      }
  	},
    "linkedTransactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "receiptIds": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "receiptUploadEnabled": true,
    "comment": "string",
    "mcc": "string",
    "mccDesc": "string",
    "merchantId": "string",
    "merchantStreet": "string",
    "merchantCity": "string",
    "merchantRegion": "string",
    "merchantPostcode": "string",
    "merchantCountry": "string",
    "merchantPhone": "string",
    "merchantUrl": "string",
    "merchantName": "string",
    "merchantNameOther": "string",
    "merchantTaxId": "string",
    "merchantContact": "string",
    "merchantTerminalId": "string",
    "cardPresent": true,
  	"platformFeeCard": true
  }
]

State Machine