Payment lifecycle
From the e-shop payer's point of view, the payment takes place in the standard way that the payer is used to with similar solutions used by banks in the Czech Republic. After completing the purchase, a redirection will take place from the e-shop to the payment gateway. Here the payer will fill in the card details and confirm the payment. Subsequently, payment authentication and payment authorisation take place. The payer is informed of the result of the payment and redirected back to the e-shop.
Under the hat, much more events take place that the payer cannot see. The operations happening in the background are shown in the figure below. We will describe the steps of the payment process, data transferred between the systems and the events taking place inside.
The diagram shows that the payer has made the payment. It is assumed that the purchase will be successful and the items will be shipped by the e-shop. In case of any complications, changes or cancellations by the payer or the merchant, there is an interface available in the next process which enables payment management and additional payment cancellation. This will be described in more detail in the section Payment lifecycle.
Payment transactions are done in several steps influenced by the merchant, payer and the payment card status. The whole life cycle, starting from the payment initiation to the payment completion, including any further statuses initiated by the merchant, is shown in the next diagram. We will describe them in detail:
1) Payment initiated – this is the initial status after the payment/init method is called. If the initiation is successful, the payer is waiting until he/she is redirected from the e-shop to the payment gateway website. If it is not possible to initiate the transaction, e.g. due to an error in entry data or because the merchant is not authorised to do such operation, the request transitions into the 6) Payment denied status.
2) Payment is in progress after the payer is redirected to the payment gateway page. Many card payment steps take place in the background. These steps are hidden from the merchant behind the payment process, they are only interested in the result itself. The result can be:
- 3) Payment cancelled – the payment was cancelled by the payer on the payment gateway;
- 6) Payment denied – denied by the bank due to the lack of funds, non-confirmation of 3D secure verification by the payer or for another reason, or the process was interrupted, e.g. the payer closed the browser;
- 4) Payment confirmed – the payment was confirmed and it is waiting until the merchant adds it to settlement. Successful payments get into this status if the automatic inclusion in the settlement is inactive;
- 7) Waiting for settlement – the payment was made and automatically put in the queue for settlement.
3) Payment cancelled – This status happens when the payer clicks on the Cancel button on the payment gateway page. The payer returns automatically to the e-shop (the payment gateway redirects him/her). In terms of the transaction life cycle, the status is final. If the payer wishes to pay by card for the identical order from the e-shop, the e-shop must generate a new payment request.
4) Payment confirmed – This status happens after the transaction has been made successfully, if the automatic inclusion in settlement is inactive. As early as the payment initiation step, we choose whether we want to send the transaction for settlement and transfer the money to the merchant’s account after it is confirmed or whether the authorised transaction should wait, e.g. until we prepare the goods, and the transaction is not put in the queue for settlement until the goods have been shipped.
The payment cannot have such status for more than seven days. During this period, the payment is guaranteed by the bank and the funds are blocked on the payer’s card. CAUTION! After the period mentioned above expires, the transaction may not be put on the settlement queue! (The funds on the payer’s card are automatically unblocked by the system and the bank no longer guarantees the payment.)
5) Payment reversed – Until the confirmed payment is settled, it can be reversed. This means that the cardholder will not be debited, the blocked funds on the card will be released and no fee will be paid. This status is final and it cannot be unreversed. The number of payments reversed by the merchant is monitored by the bank.
You can count on the option of payment reversal until the transaction is sent for settlement, i.e. it's possible for transactions in the “Payment confirmed" state. For transactions in "Waiting for settlement" state payment reversal is possible till midnight of the given day, after this moment transactions are sent into the settlement process. Only refund operation is possible for settled payments.
6) Payment denied – This status was already discussed above. There are many reasons for payment denial, they are differentiated in detail in the Operation Return Code. Basically, they can be divided into several groups:
- Payment initiation contained erroneous data;
- Merchant is not authorised to perform the payment operation;
- 3D secure verification was not correctly performed by the payer;
- Payer’s bank (card issuer) did not approve card payment;
- Payer closed the browser and the transaction expired.
Payment denial by the bank is a specific status. Only the return code indicates for which reason the issuing bank denied the transaction. From the merchant’s point of view, this is an unsuccessful payment and this detail is only for the merchant’s information.
If the card payment is unsuccessful, the payer’s card payments are not doomed to failure. The payment gateway offers the payer to pay with another card. The reason is that return to the e-shop and payment failure should not discourage the payers from buying. From the merchant’s point of view, this “transaction for the second time” is all the time in the Payment in progress status, the payment does not change its status until the final success or failure is known.
7) Waiting for settlement is a status when transactions are already put in a queue and processed depending on the bank’s settlement rules. Until the transaction is settled, it can be reversed, as described earlier.
8) Payment settled is the desired final status for the merchant. Everything was done, the transaction was put in the queue for settlement, the settlement was done and the money is on the way. This status if final, but the merchant can choose to cancel the transaction (e.g. the customer cancels the order, or the goods are returned within statutory time-limits), the refund operation may be triggered.
ATTENTION When paying with the ČSOB payment button, the authorised transaction will go from status 2 directly to status 8. It is, therefore, necessary for the e-shop to evaluate status 8 as “paid”.
9) Refund processing – If the merchant requests refund processing, the existing transaction gets into this status and the operation is in progress. Refund processing is approved by the bank on the basis of information provided by the merchant, this status may last for several days.
10) Payment returned – This phase is reached by the transaction life cycle after the refund was approved and after the transaction was made in reverse order to the payer.
Payment initiation payment/init
As soon as the final phase of purchase is initiated in the e-shop, the payer proceeds to payment and chooses to pay by a card, the e-shop initiates a payment on the payment gateway. Besides the standard information, such as merchant identification, amount and order reference number, the e-shop can forward purchase details, incl. one or two cart items according to the payment/init specification, to the payment gateway to make the payment process clearer and more transparent and to increase the customer confidence in the correct process of operations in the e-shop and payment gateway.
Order reference number is assigned by the merchant’s e-shop. Finally, the order reference number will appear on the bank statement of transactions. The number is thus used in the merchant’s system (accounting) for the pairing of payments with orders. Therefore, the symbol is mandatory (numeric value with maximum 10 digits). The order reference number is displayed as Variable symbol in ČSOB POS Merchant application.
After payment initiation, the payment gateway assigns payID, a unique payment ID, to each transaction. This identifier returns in the response to payment/init and it accompanies the payment transaction in all its statuses.
Order number, which the merchant forwards to the payment gateway upon the payment initiation, must be unique in the merchant’s e-shop. If the merchant initiates two transactions with the identical order number on the payment gateway, the transactions will have different payID’s, but they will appear as two payments with the identical variable symbol on the bank statement.
If the customer has logged in to the e-shop and his/her identity is known, it is possible to forward the customer’s unique identifier. This will enable the customer to have the gateway remember his/her payment card securely on the gateway and to use it again without having to enter the card’s long number.
Redirecting to gateway payment/process
If the payment was successfully initiated on the gateway, the e-shop may redirect the payer to the gateway in the following steps. The e-shop forwards only the payment’s unique identifier in the link, all the other details about the payment operation, as well as the content of the cart and the merchant’s identity, have been ready on the gateway since the payment initiation step.
The Redirecting to the gateway operation must be used if the customer moves repeatedly between the e-shop and the payment gateway (e.g. using the navigation in the browser). The payment initiation operation with the identical order number may not be called for the initiated payment with a set-up order number, where a unique
payIDwas assigned to such payment by the gateway, new payment with a duplicate order number would be created.
Payment status detection payment/status
The e-shop system may at any time detect the status of any of its payments on the gateway. Calling this method, the merchant will get information on whether the payment is in progress, which step is taking place, and after the payment is completed, the merchant will also get information about the result of the payment.
This call is optional; it may not be used for simple e-shop implementations. In this case, the e-shop waits until the payer is redirected back to the e-shop’s return URL.
As described earlier, the e-shop may verify the transaction status after its completion. The transaction is kept in the active section of the gateway 48 hours following the transaction completion. If the payer, e.g. by mistake, calls the payment gateway from the browser’s history, there will be no complications. The payer will see the payment gateway’s confirmation page with information about the payment result.
After the transaction has been successfully completed, there are still a few steps in which the merchant can manage its status:
Transaction reversal payment/reverse
This method will reverse the successfully completed transaction and will exclude it from the system; the transaction will not be carried out and the funds on the card will be unblocked. The method may be used for unsettled transactions only. It is necessary to be aware that if the method is called in the 7) Waiting for settlement status, the transaction settlement processing may be done, the method will return an error and the transaction will be settled.
Putting transaction in the queue for settlement payment/close
This operation is called only if the transaction is not put in the queue for settlement automatically (this option is inactive during the payment initiation step). Calling this function will put the transaction in the queue for settlement; it can, for instance, be linked to the shipment of the goods in the e-shop.
Refund request payment/refund
This operation is called if money is to be refunded to the payer. A typical example is a complaint, order cancellation or a withdrawal from the purchase in the e-shop within statutory time limits. eAPI v1.5 and higher allows you to send a partial refund, which is lower than the original transaction. This feature is best used when returning money to the customer for only one item, while the customer keeps the rest of his/her purchase.
Transaction detailed statuses provide the e-shop with more detailed information on the progress or status of transaction processing. The use of detailed statuses is optional, it is additional functionality. It is not necessary to work with detailed statuses for handling transactions at the payment gateway. (As a basis) it is enough to work with the basic states of the transaction life cycle. The payment gateway provides the detailed status in e-shop responses that contain the status of the transaction processing (i.e., in response to a payment/status).
Detailed statuses can be used in the e-shop to get a better overview of the progress or status of the transaction processing. The business value of the importance of a micro-state depends on the main state in which the transaction is located.
Detailed statuses in state 2 (payment in progress) carry information about what the customer is doing at the payment gateway, or rather in what step of the payment process the customer is in the middle of. For payment methods integrated directly into the e-shop (Apple Pay, Google Pay, OneClick payment), this is information about the customer's interaction with the external provider of payment methods - this information is usually very limited. More valuable information is available for the payment by card that is processed by the payment gateway itself.
Detailed statuses in state 3 (payment cancelled) contain information on the method of payment cancellation or (if possible) they also give the e-shop information on whether the customer has made an attempt to pay.
Detailed statuses in state 6 (payment declined) contain information about the reason for payment denial or expiration.
Detailed statuses in state 10 (payment returned) allow distinguishing between full return (further returns for such a transaction can no longer be entered) and partial return (additional returns can be made up to the amount of the originally authorised amount).
Detailed statuses for individual payment methods differ depending on the course of the payment process, the logic of the payment method and the situations in which the customer may find themselves. Detailed status always carries information about the payment method that is currently in progress or with which the transaction has been completed. If possible, the detailed statuses also provide the e-shop with information on whether the customer has made an attempt to pay.