# Transactions

A Card Transaction is an operation associated to an issued Card. All Card Transactions are mapped to CardTransaction objects.

Card payments almost always go through many steps. There is one CardTransaction per step but not all CardTransactions affect the Balances of the associated Wallet.

# Key attributes

Attribute Type Description
cardtransactionId string The unique identifier of the card transaction.
cardId string The unique identifier of the card used for the transaction.
walletId string The unique identifier of the Wallet the card is attached to.
walletCurrency string The currency of the Wallet.
merchantId string The MID
merchantName string The name of the merchant.
merchantAddress string The address of the merchant.
merchantCity string The city of the merchant.
merchantCountry string The country of the merchant. ISO 3166 3-letter code (except of the US which is a two-letter code)
publicToken string The token of the card (a way to identify a card without knowing or communicating its PAN)
paymentAmount string The amount of the transaction, always expressed in Euros.
paymentCurrency string The local currency in which the transaction was made, ISO 4217 3-letter code.
paymentLocalAmount string The amount of the transaction in the local currency.
paymentLocalDate string The local date on which the transaction occurred.
paymentLocalTime string The local time at which the transaction occurred.
fees string ATM usage or foreign payments fees as defined by Treezor, always set to 0
paymentCountry string Country in which the transaction occurred, ISO 3166 3-letter code.
paymentStatus string The general status of the transaction. See table below
posCardholderPresence string Describes more precisely how the card was used. See list below
posPostcode string Postcode of the transaction location.
posCountry string Country of the point of sale, ISO 3166 3-letter code.
posTerminalId string The id of the terminal used for the transaction.
posCardPresence string Indicates whether or not the card was physically present during the transaction:
  • 0 – The card was present
  • 1 – The card was absent
  • 9 – The card presence cannot be determined
panEntryMethod string How the PAN was captured by the merchant. See list below
authorizationNote string Contains detailed information regarding a declined transaction. See table below
authorizationResponseCode string The precise status of the transaction. See table below
authorizationIssuerId string The transaction identifier as generated by the payment processor.
authorizationIssuerTime string The time of the transaction, in the timezone of the payment processor.
authorizationMti string The message type indicator. See list below
authorizedBalance string The Authorized Balance of the wallet after the transaction
mcc string The Merchant Category Code (MCC). A MCC valued to 6011 indicates a withdrawal.
acquirerId string The acquirer's ID (the merchant's bank in the form of 5 to 6 digits)
is3DS string Indicates whether or not 3DSecure was used for authentication:
  • 1 – 3DS was used
  • 0 – 3DS was not used
totalLimitPaymentYear string The related Card's yearly spent amount. This is used with Cards Limits
totalLimitPaymentMonth string The related Card's monthly spent amount. This is used with Cards Limits
totalLimitPaymentWeek string The related Card's weekly spent amount. This is used with Cards Limits
totalLimitPaymentDay string The related Card's daily spent amount. This is used with Cards Limits
totalLimitPaymentAll string The related Card's lifetime spent amount. This is used with Cards Limits
totalLimitAtmWeek string The related Card's weekly ATM withdrawal amount. This is used with Cards Limits
totalLimitAtmDay string The related Card's daily ATM withdrawal amount. This is used with Cards Limits
totalLimitAtmAll string The related Card's lifetime ATM withdrawal amount. This is used with Cards Limits
cardDigitalizationExternalId string The digital payment token identifier (only present if payment was made with a digital token such as ApplePay or GooglePay for example)

💡 When a CardTransaction produces a Transaction object, the CardTransaction.id is reflected in the Transaction.foreignId attribute.

red warning icon

Caution – Data formats may differ

The date, time, and country formats are different from Treezor usual API format because Treezor displays the information as provided by the Card processor.

# Statuses (paymentStatus)

This attribute allows you to identify the type of transaction, as Card payments almost always go through many steps.

Status Description Impacts
Current Balance
Impacts
Authorized Balance
Note
A Authorization accepted no cross yes checkmark Authorization request accepted by Treezor
R Refund no cross no cross Refunded authorization
S Settled yes checkmark Generally no Can be:
  • Refund is successful and the buyer has been refunded
  • Payment is successful and the merchant has been paid
  • MoneySend is successful and the cardholder's bank account has been credited
M MoneySend no cross no cross MoneySend authorization
C Cleared no cross no cross Settlement is received without a previous matching authorization request
I Declined no cross no cross Authorization refused
V Reversed no cross yes checkmark Authorization reversed

C (Cleared) may happen when a payment was approved offline by the payment terminal.

V (Reversed) may happen when an automated gas station authorized an amount greater than the actual amount of fuel pumped.

💡 Negative amounts and Non-Euro Settlement (S) can affect the Authorized Balance. See Non-Euro example and Negative amount settlement example.

# MTI (authorizationMti)

The Message Type Identifier (MTI) indicates the type of transaction message.

Type Description
100 Authorisation Request
120 Advice This message is generated by the card processor, when a prior authorization request has been declined by the processor for example. It is also used for a reversal advice when the final amount spent at an AFD is known.
400 Reversal Request
420 Reversal Advice This message is sent to Treezor by the card processor when a prior reversal request was not delivered due to a network issue, for example.
1240 Settlement

# PAN Entry Method (panEntryMethod)

This attribute informs you of how the PAN was provided to or accessed by a merchant for a transaction.

Description
0 Unknown or no terminal
1 Manual Key Entry
2 Partial Magnetic Stripe Read
3 Barcode
4 OCR
5 Chip (contact interface)
7 Chip (contactless interface)
10 Credential-on-file (e.g. one-click purchase)
79 PAN & Expiration date entered by acquirer
80 Magnetic Stripe fallback (The terminal was not able to read the chip)
81 e-commerce
91 Contactless magstripe mod

# Cardholder Presence (posCardholderPresence)

This attribute indicates whether the cardholder was present at the point of sale and provides details if they were not present.

Cardholder Presence Description
0 yes checkmark Present Cardholder present
1 no cross Not-present Unspecified
2 no cross Not-present Mail/facsimile order
3 no cross Not-present Phone/ARU order
4 no cross Not-present Standing order/recurring transactions
5 no cross Not-present Electronic order (home computer, internet, mobile phone, PDA)
6 no cross Not-present Installment transaction (similar to recurring but fixed number of installments)
9 Unknown Unknown

# Authorization Note (authorizationNote)

This attribute allows your Support Users to inform the cardholder of the cause of a payment incident and/or status.

You should always use the authorizationNote together with the authorizationResponseCode to provide accurate informations to the cardholder.

The authorizationResponseCode will tell you if the transaction was Declined or Approved, while the authorizationNote will provide more details as to why.

Bulb icon

Tip – Multiple messages may be contained in the authorizationNote

In which case they are concatenated with the \n character to separate them.

Authorization Note Description Source
; DE095={amount}; DE095={amount} ℹ️ Informative message, {amount} is the remaining authorized amount after a partial reversal Card Processor
ASI.... AVS check ℹ️ Informative message, the address of the cardholder has been checked Card Processor
ASI.... CVC check ℹ️ Informative message, the CVC has been checked Card Processor
ATM MONTHLY LEGAL LIMIT OF WALLET EXCEEDED The legal ATM withdrawal limit has been reached Treezor
AUTOMATIC AUTHORISATION REMOVAL BillAmt - {amount} Location - {business} {country} An authorization from 7 days ago has been cancelled and reversed, as no settlement occured (these are generally used to ensure a Card is valid by authorizing a small amount that is never actually debited) Card Processor
Banknet advice: APS error; unable to deliver response 🔄 Temporary internal error, the Cardholder should retry their payment Card Processor
BlockedCard The Card is blocked. Card Processor
Card CVV2 not matching with cvv2 in auth request The cardholder entered an erroneous CVV2 (or CVC) Card Processor
ChargeBack - Credit to Card ℹ️ Informative message, the cardholder has just been refunded following a chargeback Card Processor
Connection Timeout 🔄 Temporary internal error, the Cardholder should retry their payment Card Processor
COUNTRY CODE NOT ALLOWED The merchant's country is not allowed by the Card or Card Program Card Processor
CountryNotPermittedToCardHolder The payment country is not allowed by the Card or Card Program Card Processor
DECLINED BY GPS The card processor declined the transaction (this is always accompanied by a more detailed message) Treezor
DECLINED BY NETWORK The card processor declined the transaction Scheme
DR: AF:Mag ATM attempt An ATM withdrawal was attempted using the magstripe, which is forbidden for security reason. The cardholder should retry uing the Card's Chip&PIN method. Card Processor
DR: ARQC not matching 🔄 There was a malfunction with the Card and/or the payment terminal, the cardholder may retry their payment once Card Processor
DR: Card expiry check failed with Emboss Expiry date (DE014) The cardholder entered a wrong expiration date Card Processor
DR: Card not found UnKnownCard The Card's PAN is unknown or invalid but does match Treezor's range of Card numbers Card Processor
DR: CVC2 tries exceeded The cardholder entered erronerous CVC too many times. A ticket must be open with Treezor to unlock it. Card Processor
DR: Declined due to Card Status: Card Destroyed (Original status 83, changed to 05) The Card has been destroyed Card Processor
DR: Declined due to Card Status: Expired card The Card has expired (expiration date is in the past) Card Processor
DR: Declined due to Card Status: Lost card (Capture)(Issuer will be charged if card is picked up) The Card has been lost and the merchant is allowed to keep the Card and send it to their bank for restitution to Treezor Card Processor
DR: Declined due to Card Status: Restricted card (Card is not active) The Card is inactive Card Processor
DR: Declined due to Card Status: Short-term Debit The Card is locked Card Processor
DR: Declined due to Card Status: Stolen card (Capture)(Issuer will be charged if card is picked up) The Card has been stolen and the merchant is allowed to keep the Card and send it to their bank for restitution to Treezor Card Processor
DR: Declined due to CardUsageGroupCheck GroupUsageID-{groupId} [Card Acceptance Method (A) - Card Not Present - E-Commerce - Failed] The Card is used to make an internet purchase but this feature is not enabled on the Card or Card Program Card Processor
DR: Declined due to CardUsageGroupCheck GroupUsageID-{groupId} [Card Acceptance Method (A) - Contactless EMV - Failed] The contactless/NFC feature is not enabled on the Card or Card Program Card Processor
DR: Declined due to CardUsageGroupCheck GroupUsageID-{groupId} [Card Acceptance Method (A) - Card not present - Credential on File - Failed] The Card is used to make an internet purchase but this feature is not enabled on the Card or Card Program Card Processor
DR: Declined due to CardUsageGroupCheck GroupUsageID-{groupId} [Card Acceptance Method (A) - Card Not Present - E-Commerce - Failed] The Card is used to make an internet purchase but this feature is not enabled on the Card or Card Program Card Processor
DR: Declined due to CardUsageGroupCheck GroupUsageID-{groupId} [Card Acceptance Method (A) - POS usage outside country of Issue of a card - Failed] The Card is used to make a purchase outside of the cardholder's country, but this feature is not enabled on the Card or Card Program Card Processor
DR: Declined due to CardUsageGroupCheck GroupUsageID-{groupId} [Card Acceptance Method (A) - Mag Stripe PAN Entry - Chip Capable Terminal - Failed] The Card's magstripe was used when the Chip was supported and should have been used instead Card Processor
DR: Declined due to CardUsageGroupCheck GroupUsageID-{groupId} Transaction is refused due to configuration restrictions on the Card or on the Card Program. The message provides additional information regarding the applicable restriction Card Processor
DR: Declined due to Lost Card (Capture)(Original auth resp status 41, changed to 05) The Card has been declared as lost Card Processor
DR: Declined due to Restricted card (Card is not active) The Card is not activated or is disabled Card Processor
DR: Declined due to Stolen Card (Capture)(Original auth resp status 43, changed to 05) The Card has been declared as stolen Card Processor
DR: Decline existing tokens(10) > Min_Tokens_To_Decline(10) DR: MDES/VDEP validation failed MDES check failed from Tokenisation Processing There are already 10 Cards tokenized with an X-Pay provider (Google Pay, Apple Pay, Samsung Pay...), no more tokenization are allowed
DR: Decline as wallet_device_score (1) <= wallet_device_max_score_decline (1) Card tokenization has been denied by the X-Pay provider (Apple Pay, Google Pay, Samsung Pay...) due to poor End User's device scoring
DR: Expiry Date missing. The expiration date of the Card has not been provided Card Processor
DR: IAV:V (checked by MC-PREVAL) Monetary Currency mismatch between authorization and authentication Card Processor
DR: iCVV does not match on EMV Track 2 Either an issue with the merchant's terminal, or the chip of the card. Contact Support if the issue occurs with multiple merchants. Card Processor
DR: Incorrect PIN The PIN code entered was incorrect Card Processor
DR: MDES Invalid Card Number - payment_token not found The Card was properly digitized for X-Pay but an incident occured when payin with X-Pay. The cardholder should digitize their card again. Card Processor
DR: Offline PIN incorrect The cardholder entered an erroneous PIN Card Processor
DR: Offline PIN try limit exceeded The maximum number of erroneous PIN has been reached, the PIN must be unlocked Card Processor
DR: Requires SCA The transaction requires a Strong Customer Authentication such as 3D Secure or Chip & Pin. Card Processor
EH Timeout - An error occurred while sending the request. 🔄 Temporary internal error, the Cardholder should retry their payment Card Processor
EH Timeout - Response status code does not indicate success: 429 (Too Many Requests). 🔄 Temporary internal error, the Cardholder should retry their payment Card Processor
EH Timeout - Response status code does not indicate success: 502 (Bad Gateway). 🔄 Temporary internal error, the Cardholder should retry their payment Card Processor
EH Timeout - The operation was canceled. 🔄 Temporary internal error, the Cardholder should retry their payment Card Processor
EH Timeout - Unable to connect to the remote server 🔄 Temporary internal error, the Cardholder should retry their payment Card Processor
EH Timeout 🔄 Temporary internal error, the Cardholder should retry their payment Card Processor
ELECTRONIC MONEY LIMIT EXCEEDED The electronic money limit has been reached. This only occurs with ME projects Treezor
ELECTRONIC MONEY MCC NOT PERMITED The law doesn't allow this MCC (type of business). This only occurs with ME projects Treezor
Electronic Money: transaction not permitted to cardholder The cardholder doesn't exist or is frozen. This only occurs with ME projects Treezor
Electronic Money: cumulative amount authorized exceeded The electronic money limit on sliding period has been reached. This only occurs with ME projects Treezor
Electronic Money: amount exceeds the authorized amount The transaction amount exceeds the authorized amount. This only occurs with ME projects Treezor
Electronic Money: payment is not permitted in this country The country of the wallet and the country in which the payment is done don't match. This only occurs with ME projects Treezor
ErrorInternal 🔄 Temporary internal error, the Cardholder should retry their payment Treezor
EXTERNAL AUTHORIZATION - APPROVED The Transaction was approved by you, using the External Authorization feature Treezor
EXTERNAL AUTHORIZATION - DO NOT HONOR The transaction has been refused by you and the refusal code is unspecified, using the External Authorization feature Agent
EXTERNAL AUTHORIZATION - INSUFFICIENT_FUNDS The transaction has been refused by you because there are insufficient funds, using the External Authorization feature Agent
EXTERNAL AUTHORIZATION - TRANSACTION_NOT_PERMITTED_TO_CARDHOLDER The transaction has been refused by you because the conditions of use of the card are not respected by the cardholder, using the External Authorization feature Agent
EXTERNAL AUTHORIZATION - INVALID_CARD_NUMBER The transaction has been refused by you because the card is unknown, using the External Authorization feature Agent
EXTERNAL AUTHORIZATION - INVALID_MERCHANT The transaction has been refused by you because the merchant or type of merchant is not allowed, using the External Authorization feature Agent
EXTERNAL AUTHORIZATION - EXCEEDS_WITHDRAWAL_AMOUNT_LIMIT The transaction has been refused by you because the withdrawal limits or ceilings are insufficient, using the External Authorization feature Agent
Gen: Pre-Authorization Request ℹ️ Informative message, indicates a pre-authorization request (such as a deposit) which can be canceled later Card Processor
Incoming transaction concern an unactive wallet The transaction is associated to an inactive Wallet Treezor
Incoming transaction concern an unactive user The transaction is associated to an inactive User Treezor
Incoming transaction concern an unactive card The transaction is associated to an inactive Card Treezor
Incoming transaction concern an unknown PAN The transaction is associated to an unknown PAN (absent from our system) Treezor
Insufficient funds The Wallet has insufficient funds Treezor
Invalid card number (no such token) The Card's PAN is invalid or unknown Treezor
Issuer Time-out 🔄 Temporary internal error, the Cardholder should retry their payment Card Processor
LIMIT ATM EXCEEDED ALL The lifetime ATM withdrawal limit has been reached Treezor
LIMIT ATM EXCEEDED DAY The daily ATM withdrawal limit has been reached Treezor
LIMIT ATM EXCEEDED MONTH The monthly ATM withdrawal limit has been reached Treezor
LIMIT ATM EXCEEDED WEEK The weekly ATM withdrawal limit has been reached Treezor
LIMIT ATM EXCEEDED YEAR The yearly ATM withdrawal limit has been reached Treezor
LIMIT CONTACTLESS APPLE PAY EXCEEDED The Apple Pay contactless limit has been reached Treezor
LIMIT CONTACTLESS EXCEEDED The contactless limit has been reached Treezor
LIMIT PAYMENT EXCEEDED ALL The lifetime payment limit has been reached Treezor
LIMIT PAYMENT EXCEEDED DAY The daily payment limit has been reached Treezor
LIMIT PAYMENT EXCEEDED MONTH The monthly payment limit has been reached Treezor
LIMIT PAYMENT EXCEEDED WEEK The weekly payment limit has been reached Treezor
LIMIT PAYMENT EXCEEDED YEAR The yearly payment limit has been reached Treezor
MCC NOT ALLOWED The Merchant Category Code (category of business) is not allowed by the Card or Card Program Treezor
MccNotPermittedToCardHolder The Merchant Category Code (category of business) is not allowed by the Card or Card Program Treezor
MDES FPAN Status:41 ℹ️ Informative message, a payment was made with Apple Pay/Google Pay/Samsung Pay and the actual Card is lost Card Processor
MDES FPAN Status:62 ℹ️ Informative message, a payment was made with Apple Pay/Google Pay/Samsung Pay and the actual Card is stolen or disabled Card Processor
MERCHANT ID NOT ALLOWED The merchant's ID (one specific business) is not allowed Treezor
MerchantIdNotPermittedToCardHolder The merchant's ID (one specific business) is not allowed Treezor
Null or Empty Response received from client 🔄 Temporary internal error, the Cardholder should retry their payment Card Processor
POSDailyLimitExceeded The daily payment limit has been reached Treezor
Presentment for Partial Reversal ℹ️ Informative message, following a Gas station transaction Card Processor
PSD2 Counter Reset ℹ️ Informative message, the contactless counter or e-commerce counter has been reset to zero Card Processor
Refund ℹ️ Informative message, refund authorization Treezor
REVERSAL ℹ️ Informative message, the reversal cancels a previous authorization at the merchant's request. It frees up the Authorized Balance of the Wallet. Treezor
Reversal due to AFD Advice with different amount. (AFD Amount=30.0000) ℹ️ Informative message, the reversal cancels a previous authorization at the merchant's request. It frees up the Authorized Balance of the Wallet. Card processor
SIMULTANEOUS OPERATIONS ON THE SAME WALLET 🔄 Multiple operations occured at the very same time on the Wallet, the Cardholder should retry their payment Treezor
System Error. 🔄 Temporary internal error, the Cardholder should retry their payment Treezor
User's assets are freezed The Wallet or payment account of the User is frozen by an AML-CFT sanction Treezor
Specific to AFD: fixed amount authorization The fixed amount of €160 has been applied for a automated fuel dispenser (AFD) transaction. Learn more about this specific case in the corresponding example. Treezor
Fixed amount adjustment The difference between the pre-authorized amount for the AFD transaction and the actually charged amount has been reversed. Learn more about this specific case in the corresponding example. Treezor
MDC DECLINED - did not match: {rulesetIds} The transaction was refused by the Treezor transaction rules engine. Treezor
{rulesetIds} The transaction was accepted by the Treezor transaction rules engine. Treezor

The DR: prefix means Decline Reason.

🚧 Despite our best efforts to keep this list up-to-date, some messages or combinations of messages may be missing.

# Codes (authorizationResponseCode)

This information is provided in the authorizationResponseCode attribute.

It provides clues as to why the transaction was accepted or refused, and pointers regarding what to do next. This information comes in addition to the status of a transaction.

Code Description Action
00 APPROVED yes checkmark Approve
08 HONOR_WITH_ID yes checkmark Approve
10 PARTIAL_APPROVAL yes checkmark Approve
87 PURCHASE_AMOUNT_ONLY_NO_CASH_BACK_ALLOWED yes checkmark Approve
98 REFUND_GIVEN_TO_CUSTOMER yes checkmark Approve
85 NOT_DECLINED_VALID_FOR_ALL_ZERO_AMOUNT_TRANSACTIONS yes checkmark Approve
01 REFER_TO_CARD_ISSUER phone Call-Issuer
70 CONTACT_CARD_ISSUER phone Call-issuer
41 LOST_CARD lock Capture
43 STOLEN_CARD lock Capture
02 CARD_NOT_YET_ACTIVATED no cross Decline
03 INVALID_MERCHANT no cross Decline
04 CAPTURE_CARD_CAPTURE no cross Decline
05 DO_NOT_HONOR no cross Decline
06 ERROR (REVERSAL ONLY) no cross Decline
12 INVALID_TRANSACTION no cross Decline
13 INVALID_AMOUNT no cross Decline
14 INVALID_CARD_NUMBER no cross Decline
15 INVALID_ISSUER no cross Decline
30 FORMAT_ERROR no cross Decline
51 INSUFFICIENT_FUNDS no cross Decline
54 EXPIRED_CARD no cross Decline
55 INVALID_PIN no cross Decline
57 TRANSACTION_NOT_PERMITTED_TO_CARDHOLDER no cross Decline
58 TRANSACTION_NOT_PERMITTED_TO_ACQUIRER_TERMINAL no cross Decline
61 EXCEEDS_WITHDRAWAL_AMOUNT_LIMIT no cross Decline
62 RESTRICTED_CARD no cross Decline
63 SECURITY_VIOLATION no cross Decline
65 EXCEEDS_WITHDRAWAL_COUNT_LIMIT no cross Decline
71 PIN_NOT_CHANGED no cross Decline
75 ALLOWABLE_NUMBER_OF_PIN_TRIES_EXCEEDED no cross Decline
76 INVALID_TO_ACCOUNT_SPECIFIED no cross Decline
77 INVALID_FROM_ACCOUNT_SPECIFIED no cross Decline
78 INVALID_ACCOUNT_SPECIFIED_GENERAL no cross Decline
81 DOMESTIC_DEBIT_TRANSACTION_NOT_ALLOWED_REGIONAL_USE_ONLY no cross Decline
83 CARD_DESTROYED no cross Decline
84 INVALID_AUTHORIZATION_LIFE_CYCLE no cross Decline
86 PIN_VALIDATION_NOT_POSSIBLE no cross Decline
88 CRYPTOGRAPHIC_FAILURE no cross Decline
89 UNACCEPTABLE_PIN__TRANSACTION_DECLINED__RETRY no cross Decline
91 AUTHORIZATION_PLATFORM_OR_ISSUER_SYSTEM_INOPERATIVE no cross Decline
92 UNABLE_TO_ROUTE_TRANSACTION no cross Decline
94 DUPLICATE_TRANSMISSION_DETECTED no cross Decline
96 SYSTEM_ERROR no cross Decline
99 CARD_VOIDED no cross Decline

# Structure of a Transaction

# Endpoints

Endpoint Description Scope
/v1/cardtransactions Search Card transactions read_only
/v1/cardtransactions/{cardTransactionId} Retrieve a specific transaction, using its id read_only
/v1/auth-requests/{authenticationRequestID}/result Answer to a Strong Customer Authentication request read_write
books icon

Reading – Find out more about Transactions

Updated on: 5/7/2024, 1:35:14 PM