Query transaction status
the websevice method you should call to know the state of a transaction is CallReadTrxS2S.
To use this method it is necessary to assign the arguments to securely identify the transaction.
A transaction may be uniquely identified by using the pair shopLogin and bankTransactionId (the ID assigned by Gestpay); It is however possible to also use the transaction code assigned by the merchant (shopLogin and shopTransactionID), taking care to ascertain that it uniquely identifies a transaction.
In case CallReadTrxS2S cannot identify a single transaction based on the input, it will return the Not uniquely identified error.
To get the outcome of CallReadTrxS2S, you must check ErrorCode (and ErrorDescription): any value different from 0 means an error has occurred.
If the transaction was correctly identified, CallReadTrxS2S will return all the informations related to the transaction. Here we will discuss only the most important fields; more informations about other fields are described in CallReadTrxS2S.
| name | description |
|---|---|
TransactionResult |
whether the transaction was authorised: OK, KO |
AuthorizationCode |
to obtain the authorisation code assigned to the transaction by the international credit card network (if the transaction was authorised) |
AlertCode (and the corresponding AlertDescription) |
if the Risk Management criteria were set within the Back Office environment and the transaction violated one of these; if no Risk Management criteria were violated, AlertCode will return the value 0. See Risk Management for further details. |
TransactionState |
The current status of the transaction. Can be one of AUT, MOV, CAN, STO, PRE |
Events |
contains one or more tags event, which corresponds to an event in the transaction history. |
The phases of a transaction
The history of events that occur to a transaction are recorded in Events.event.eventtype.
AUT - Authorized. A transaction always starts with an authorization event AUT, that can have a positive or negative result. If the result is negative, no more events can happen. Converseley if the result is positive, the transaction will have other events.
The transaction has 25 days (configurable) to move to another state otherwise, based on M.O.T.O. configuration, it will be cancelled/settled automatically.
CAN - Cancelled. The cancelled event (CAN) will be added if the transaction is cancelled; no more events can be added after this.
MOV - Amount Transferred. When the system receives a confirmation of the transaction, and the money can be transferred to the seller’s account, the MOV event will be added to the history.
PRE - Amount Reserved for Transfer. If the Transfer request is not processed immediately, the system will add the event PRE (prenotazione in Italian, reservation in English).
Usually MOV requests are processed immediately. However there are some cases where the payment can be delayed, for example with Paga con Bonifico payment method where payments are processed only in some time ranges.
REQ (refund request) and STO (refund event). A transaction can be refunded until six months from its authorization. If the seller asks for a refund, a new STO event can be added. Similarly to the MOV event, if the refund is not synchronous, a REQ event can be added before the STO event.
Refunds can be done on partial amounts, so a transaction can have more than one refund requests and actual refund events, until the transferred amount is positive.
Events & TransactionState
TrasactionState holds the current status of the transaction.
If the transaction is still valid and the corresponding amount is greater than zero, its status will be MOV. When the amount reaches 0, the transaction can be considered STO.
You can have more than one REQ and STO and the transaction can be still MOV, if the remaining amount is positive.
| latest event | TransactionState |
|---|---|
CAN |
CAN |
AUT |
AUT |
PRE |
PRE |
MOV |
MOV |
REQ |
MOV |
STO and the cancellation is total (amount = 0) |
STO |
STO and the cancellation is partial (amount > 0) |
MOV |
