Transaction

Data Model

Field	Type	Description
`transactionId`	uuid	An identifier for the transaction, unique for the platform
`organizationId`	uuid	An identifier for the organization to which the cardholder that created the transaction with his/her card belongs to.
`cardholderId`	uuid	An identifier for the cardholder to whom the card that created the transaction belongs to
`cardId`	uuid	An identifier for the card to which the transaction belongs to
`status`	string	The current state of the transaction, either: `DECLINED` `PENDING` `REVERSED` `CONFIRMED` `BOOKED`
`type`	string	Type of the transaction, can either be `PURCHASE` `CASH_WITHDRAWAL` `REFUND` `CHARGEBACK` `RECHARGE` `STATUS_INQUIRY` For more details see below.
`partnerSubmissionStatus`	string	Synchronisation status of the transaction `NOT_SYNCED` `SYNCED` `TEMP_LOCKED` `LOCKED` Also see two-way-sync here: Synced and the details here.
`partnerSyncedAt`	date-time	Date the transaction has been synced to the partner (initiated by Pliant)
`partnerTempLockedAt`	date-time	Date the transaction has been marked as temporarily locked (initiated by partner)
`partnerLockedAt`	date-time	Date the transaction has been locked in Pliant irreversibly (initiated by partner)
`category`	string	The 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`
`billingAmount`	object	An 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.
`transactionAmount`	object	An 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.
`transactionCountry`	object	This is the country of the location where the transaction was executed
`transactionLocalTime`	date-time	This is the time at the location where the transaction was executed
`createdAt`	date-time	Usually the authorisation time stamp, but for transactions that reach us in CONFIRMED state this matches the `confirmedAt` timestamp
`authorizedAt`	date-time	This 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)
`confirmedAt`	date-time	This 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)
`bookedAt`	date-time	This 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.
`reversedAt`	date-time	For transactions that are being reversed, this is the time when the transaction is being reversed
`declineReason`	object	`type` `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.
`linkedTransactionId`	string	Transaction id of related transactions for refunds, chargebacks, and recharges
`receiptCount`	integer	Number of uploaded receipts (0 - 10)
`receiptId`	string	An array of `receiptIds` that are attached to the transaction either via Pliant apps, email receipt inbox feature or API
`receiptUploadEnabled`	boolean	The flag that indicates whether receipt upload is enabled for the transaction or not
`comment`	string	Text that has been assigned by the user either via our apps
`mcc`	string	Merchant category code provided by the credit card scheme (find more details on visa.com
`mccDesc`	string	Merchant category code description
`merchantId`	string	If available unique identifier code for each merchant
`merchantStreet`	string	Street of merchants' location (could be the address of a branch or the headquarter)
`merchantCity`	string	City of merchants' location
`merchantRegion`	string	Region of merchants' location
`merchantPostcode`	string	Postcode of merchants location
`merchantCountry`	string	Country of merchants' location
`merchantPhone`	string	Phone number of merchant
`merchantUrl`	string	Website URL of the merchant
`merchantName`	string	Name of merchant (as shown in the Pliant apps)
`merchantNameOther`	string	Optional other name of the merchant
`merchantLegalName`	string	The legal name of the merchant
`merchantTaxId`	string	Tax ID of the merchant
`merchantContact`	string	Additional contact details about the merchant
`merchantTerminalId`	string	Internal ID for the terminal that has been used by the cardholder
`cardPresent`	boolean	For point-of-sale purchases, this is set to `true`
`platformFeeCard`	boolean	For 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

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.