Transaction

Data Model

FieldTypeDescription
transactionIduuid An identifier for the transaction, unique for the platform
organizationIduuidAn identifier for the organization to which the cardholder that created the transaction with his/her card belongs to.
cardholderIduuidAn identifier for the cardholder to whom the card that created the transaction belongs to
cardIduuidAn identifier for the card to which the transaction belongs to
statusstringThe current state of the transaction, either:
DECLINED
PENDING
REVERSED
CONFIRMED
BOOKED
typestringType of the transaction, can either be
PURCHASE
CASH_WITHDRAWAL
REFUND
CHARGEBACK
RECHARGE
STATUS_INQUIRY
For more details see below.
partnerSubmissionStatusstringSynchronisation status of the transaction
NOT_SYNCED
SYNCED
TEMP_LOCKED
LOCKED
Also see two-way-sync here: Synced and the details here.
partnerSyncedAtdate-timeDate the transaction has been synced to the partner (initiated by Pliant)
partnerTempLockedAtdate-timeDate the transaction has been marked as temporarily locked (initiated by partner)
partnerLockedAtdate-timeDate the transaction has been locked in Pliant irreversibly (initiated by partner)
categorystringThe category that has been either assigned by Pliant automatically (based on the merchant) or modified by the cardholder within the Pliant apps
ADVERTISING_AND_MARKETING,
COMPUTING_AND_SOFTWARE,
EDUCATION_AND_TRAINING,
ELECTRONICS_AND_IT_EQUIPMENT,
ENTERTAINMENT_AND_WELLNESS,
FOOD_AND_DRINKS,
GIFTS_AND_VOUCHERS,
MATERIALS_AND_PACKAGING,
OFFICE_SUPPLIES_AND_EQUIPMENT,
SERVICES,
TRAVEL_AND_ACCOMMODATION,
OTHER
billingAmountobjectAn array in regard to the actual transaction amount of the transaction
value (integer)
currency (string)
Important: For transactions processed in a foreign currency this parameter includes the corresponding EUR amount.
transactionAmountobjectAn array in regard to the actual transaction amount for the transaction. For transactions in a foreign currency, this property includes the amount in the given currency
value (integer)
currency (string)
Important: For transactions processed in EUR this parameter includes the corresponding EUR amount.
transactionCountryobjectThis is the country of the location where the transaction was executed
transactionLocalTimedate-timeThis is the time at the location where the transaction was executed
createdAtdate-timeUsually the authorisation time stamp, but for transactions that reach us in CONFIRMED state this matches the confirmedAt timestamp
authorizedAtdate-timeThis is the time when the transaction was authorized (for PoS usually just 1-2 seconds after it has been created; can be a long time for online transactions with 2FA in place)
confirmedAtdate-timeThis is the time when the transaction is confirmed which means it cannot be reversed and is ready to be exported (usually one working day after the transaction has been authorized)
bookedAtdate-timeThis is the time when the transaction is settled and the money flows between the involved parties. This date determines to which statement month the transaction is assigned.
reversedAtdate-timeFor transactions that are being reversed, this is the time when the transaction is being reversed
declineReasonobjecttype
title
description

Currently the following decline reasons are exposed via the API:

CARD_ACCEPTANCE_NOT_ALLOWED, CARD_CONTROLS_DATETIME_LOCKED, CREDIT_ORG_LIMIT_EXCEEDED, DECLINE_REASON_NOT_DETECTED, DISALLOWED_MCC, DO_NOT_HONOUR, EXCEED_AMOUNT_VELOCITY_LIMIT, EXCEED_FREQUENCY_VELOCITY_LIMIT, EXPIRED_CARD, INCORRECT_CVV2, INCORRECT_EXPIRY_DATE, INCORRECT_PIN, INSUFFICIENT_FUNDS, INSUFFICIENT_FUNDS_GPS, INVALID_AMOUNT, INVALID_CARD_NUMBER, ISSUER_INOPERATIVE, LOCKED_CARD, LOST_CARD, MONTHLY_CARD_LIMIT_EXCEEDED, PENDING_CARD, PIN_TRIES_EXCEEDED, PIN_VALIDATION_FAILURE, POSTAL_CODE_NOT_ALLOWED PREFUND_ORG_LIMIT_EXCEEDED, SCA_REQUIRED_PHYSICAL, SCA_REQUIRED_PHYSICAL_OFFLINE, SCA_REQUIRED_PHYSICAL_ONLINE, SCA_REQUIRED_VIRTUAL, SINGLE_USE_CARD, STOLEN_CARD, TERMINATED_CARD, TRANSACTION_LIMIT_EXCEEDED, TRANSACTION_TYPE_NOT_ALLOWED, TRANSACTION_CATEGORY_NOT_ALLOWED, TRANSACTION_MERCH_STRING_NOT_ALLOWED, TRANSACTION_MERCHIDDE42_NOT_ALLOWED, TRANSACTION_MCC_NOT_ALLOWED

The decline reasons starting with SCA describe a scenario where Strong Customer Authentication (SCA) is required by VISA, but the merchant did not initiate this process.
linkedTransactionIdstringTransaction id of related transactions for refunds, chargebacks, and recharges
receiptCountintegerNumber of uploaded receipts (0 - 10)
receiptIdstringAn array of receiptIds that are attached to the transaction either via Pliant apps, email receipt inbox feature or API
receiptUploadEnabledbooleanThe flag that indicates whether receipt upload is enabled for the transaction or not
commentstringText that has been assigned by the user either via our apps
mccstringMerchant category code provided by the credit card scheme (find more details on visa.com
mccDescstringMerchant category code description
merchantIdstringIf available unique identifier code for each merchant
merchantStreetstringStreet of merchants' location (could be the address of a branch or the headquarter)
merchantCitystringCity of merchants' location
merchantRegionstringRegion of merchants' location
merchantPostcodestringPostcode of merchants location
merchantCountrystringCountry of merchants' location
merchantPhonestringPhone number of merchant
merchantUrlstringWebsite URL of the merchant
merchantNamestringName of merchant (as shown in the Pliant apps)
merchantNameOtherstringOptional other name of the merchant
merchantLegalNamestringThe legal name of the merchant
merchantTaxIdstringTax ID of the merchant
merchantContactstringAdditional contact details about the merchant
merchantTerminalIdstringInternal ID for the terminal that has been used by the cardholder
cardPresentbooleanFor point-of-sale purchases, this is set to true
platformFeeCardbooleanFor Pliants subscription fees we are using platform fee cards. This flag is set to true once the transaction is actually a Pliant fee.

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

Refund of the purchase; each refund should have a corresponding purchase. For example, when you return order back to the merchant.

The amount is 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%.

TypePossible StatusCommonness
PURCHASECONFIRMED,DECLINED,PENDING,REVERSED> 92%
STATUS_INQUIRYCONFIRMED,DECLINED,REVERSED> 8%
REFUNDCONFIRMED,DECLINED,PENDING,REVERSED> 2%
CASH_WITHDRAWALCONFIRMED,DECLINED> 1%
CHARGEBACKCONFIRMED> 1%
RECHARGECONFIRMED> 1%

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