Preliminary Customer Evaluation (optional implementation)

Pre-check Image

This check occurs when payment methods are offered to the customer. It is used to evaluate orders and customer information to determine whether to display the payment method in the checkout process. Due to the nature of anonymous data, this evaluation is only approximate and does not guarantee that our service will be offered to the user. Implementing this check is optional, but it can save the customer trouble because if the customer did not pass the evaluation test until after ordering through Twisto, you can simply disable Twisto as a payment method.

Although the data sent in this step is the same as when downloading historical transactions via webhook, it is necessary to resend this data. The reason is that downloading is done in batches at an unspecified interval. By sending this information at the time of ordering, the freshness of this data is guaranteed for accurate evaluation.

To ensure anonymity, the information is hashed. The data is only sent when the current customer's email is known because it serves as the customer's identification. Please retrieve information about previous orders based on the email.

If the customer passes the preliminary evaluation, they will be allowed to use our payment method (Twisto will be displayed among the payment methods). If the customer selects this method, the entire process continues with final evaluation. Otherwise, the payment method will not be displayed at all. Other payment methods remain unaffected, and payment can be made using one of the alternative methods.

Implementation Method

Preliminary evaluation is performed using the JavaScript method Twisto.precheck(data, success, error).

The data argument of the precheck method is a JSON object that contains encrypted anonymous customer data in the form of a serialized JSON object. Encryption is performed using your secret key, so this process needs to be done on your server. The getPrecheckPayload(customer, orders) method of the library (e.g., PHP library) is used for this purpose, which returns a string that is directly inserted into the precheck JavaScript function call.

Note: The reason for encryption is to prevent user data tampering. If a user looks at the source code, they will only see the encrypted Base64 representation of their data. The only way to decrypt it is using your private key, which is only accessible to you on the server and inaccessible to users.

Usage example

The following code block provides an example of how to use the PHP and JavaScript libraries to perform preliminary customer evaluation:

<?php
    require_once 'twistophp/Twisto.php';

    $twisto = new Twisto\Twisto();
    $twisto->setPublicKey('');
    $twisto->setSecretKey('');

    // zákazník je uložen v session z předchozích kroků nákupního procesu
    $customer_data = $_SESSION['customer_data'];

    // celková cena objednávky
    $total_price_vat = $_SESSION['total_price_vat'];

    // získání předešlých objednávek z databáze
    $customer_orders = $database->table('orders')->where('email', $customer_data['email']);

    $orders = array();
    // vytvoření instance Twisto\BareOrder pro všechny objednávky získané z databáze
    foreach ($customer_orders as $order) {
        $orders[] = new Twisto\BareOrder(array(
                    'order_id' => $order['id'],
                    'created' => $order['date_add'],
                    'total_price_vat' => $order['total_paid_tax_incl'],
                    'billing_address' => new Twisto\BareAddress(array(
                        'street' => $order['street'],
                        'city' => $order['city'],
                        'zipcode' => $order['zipcode'],
                        'phones' => array($order['phone'], $order['mobile_phone'])
                    )),
                    'delivery_address' => new Twisto\BareAddress(array(
                        'street' => $order['delivery_street'],
                        'city' => $order['delivery_city'],
                        'zipcode' => $order['delivery_zipcode'],
                        'phones' => array($order['delivery_phone'])
                    )),
                    'is_paid' => $order['paid'],
                    'is_shipped' => $order['shipped'],
                    'is_delivered' => $order['delivered'],
                    'is_returned' => $order['returned'],
        ));
    }

    $customer = new Twisto\BareCustomer(array(
        'email' => $customer_data['email'],
        'facebook_id' => $customer_data['facebook_id'],
        'customer_id' => $customer_data['id']
    ));

    // vytvoření zašifrovaných dat pro javascript
    $payload = $twisto->getPrecheckPayload($customer, $orders, $total_price_vat);
?>

<script type="text/javascript" src="https://static.twisto.cz/api/v1/twisto.js"></script>
<script type="text/javascript">
    Twisto.setPublicKey('');
    Twisto.precheck("<?php echo $payload; ?>", function(response) {
        if (response.accepted) {
            // zobrazit možnost platby Twisto
        }
    });
</script>

Note: If you have the entire shopping process on one page, the customer data is not yet available at the time of page generation. This problem needs to be solved, for example, by sending an AJAX request with the customer's email to your server before confirming the order, where you will obtain the necessary data.

Data format

Name	Required	Data type	Value
`customer`	✓	BareCustomer	Anonym information about customer
`orders`	✓	Array<BareOrder>	Basic order information
`total_price_vat`	✓	`Number`	Total amount of current order including tax

Testing

In the testing API, you can use the following email to simulate customer rejection: karel.zlodej@example.cz. In the BareCustomer object, you need to set the email field to this value. For all customers with a different email, the testing API method will be allowed (the response will have the accepted field set to true).