python-est

python-est is a set of example code I prepared for adding the virtual POS service of Turkish banks that use the EST platform to web projects written in Python. It shows, step by step, how to prepare the payment form, how to generate the transaction's security hash and how to interpret the result returned by 3D Secure verification. I wrote the code with the Django framework in January 2014 and updated the repository in the years that followed.

Purpose

A virtual POS is the service a bank provides so that a website can take credit card payments. EST was a shared virtual POS platform used by many banks in Turkey at the time. A developer wanting to integrate with it faced a large number of parameters and long technical documents. After finishing the integration in my own project, I wanted to share code that could be dropped into a project and tested right away, without confusing detail. My aim was to help other developers doing the same work reach their first working payment sooner.

How it works

The flow consists of two Django views. The first view takes the price of the product being bought from the database. It then generates a random order number and a random value for each transaction. The merchant ID, the addresses to return to on success and failure, the transaction type and the store key are read from the settings file. These values are joined in a specific order together with the amount and the number of installments, hashed with SHA-1 and encoded with Base64. The resulting hash is the value the bank uses to verify that the request has not been altered.

This information is passed to an HTML template. The form in the template asks the user for the card number, security code, expiry date and card type, and carries every other value in hidden fields. The form is sent straight to the bank's 3D payment address. The currency is set to Turkish lira and the payment model to 3D Pay.

When the cardholder completes verification on the bank's 3D Secure page, the bank sends the result to the return address set by the merchant. The second view reads the mdStatus value in this response and turns each status code from 0 to 9 into a Turkish description. If the transaction was not successful, the error message returned by the bank is added to the description, and the result is shown to the user along with the amount and installment details.

Key features

• It shows clearly how the security hash sent to the bank is calculated.
• It explains in Turkish what each of the ten status codes returned by 3D Secure means, so cases such as not approved, successful, card not enrolled in 3D Secure, invalid card and system error can be shown to users with the right message.
• It handles installment and single payments in the same template.
• Because it is set up for the bank's test environment, it can be tried without a real card.

Technical stack

The examples are written in Python 2 with Django. The random and string modules are used for random values, and hashlib and base64 for the hash. Pages are built with Django templates and routes are defined with Django's URL configuration. The merchant details provided by the bank go into the settings file rather than into the code.

Status

The code was written in 2014 and the repository was last updated in 2019. Because it targets Python 2 and the Django versions of that time, it is better used today as a reference for understanding the flow than run as it is. The SHA-1 hash used in the example has also since given way to stronger algorithms.

Use cases

• It can help developers starting an EST-based virtual POS integration see the payment flow from start to finish.
• It can serve as a reference in any payment project that wants to show 3D Secure return codes to users as meaningful messages.
• It is useful for checking the correct order of parameters and the hash calculation when writing the same integration in another language or framework.