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 bePURCHASE CASH_WITHDRAWAL REFUND CHARGEBACK RECHARGE STATUS_INQUIRY For more details see below. |
partnerSubmissionStatus | string | Synchronisation status of the transactionNOT_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 appsADVERTISING_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 transactionvalue (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 currencyvalue (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 toLOCKED
), but the partner can still go back to theSYNCED
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 toSYNCED
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%.
Type | Possible Status | Commonness |
---|---|---|
PURCHASE | CONFIRMED,DECLINED,PENDING,REVERSED | > 92% |
STATUS_INQUIRY | CONFIRMED,DECLINED,REVERSED | > 8% |
REFUND | CONFIRMED,DECLINED,PENDING,REVERSED | > 2% |
CASH_WITHDRAWAL | CONFIRMED,DECLINED | > 1% |
CHARGEBACK | CONFIRMED | > 1% |
RECHARGE | CONFIRMED | > 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
Updated 4 months ago