Browser return

Values posted by the browser

Once the payment has been made, the following values are sent to the merchant server by the browser using the POST method:

Parameter Value
kr-hash c3c0323c748fdb7c2d24bd39ada99663526236828efa795193bebfdea022fe58
kr-hash-algorithm sha256_hmac
kr-hash-key sha256_hmac
kr-answer-type V4/Payment
kr-answer {“shopId”:”33148340”,”orderCycle”:”CLOSED”,”orderStatus”:”PAID”, (…)

These 4 parameters correspond to:

Parameter Description
kr-hash Hash of the JSON object stored in kr-answer. It allows to verify the authenticity of the response.
kr-hash-algorithm Algorithm used to calculate the hash. Its value is sha256_hmac.
kr-answer-type Type the JSON object stored in kr-answer.
kr-hash-key Type of key used to sign kr-answer. Can be set to sha256_hmac (browser return) or password (IPN).
kr-answer Object containing the payment result, encoded in JSON.

The kr-answer parameter contains information on the status of the payment session:

{
    "shopId": "69876357",
    "orderCycle": "CLOSED",
    "orderStatus": "PAID",
    "serverDate": "2018-09-27T14:02:17+00:00",
    "orderDetails": {
        "orderTotalAmount": 990,
        "orderCurrency": "EUR",
        "mode": "TEST",
        "orderId": null,
        "_type": "V4/OrderDetails"
    },
    "customer": {
        "billingDetails": {
            "address": null,
            "category": null,
            "cellPhoneNumber": null,
            "city": null,
            "country": null,
            "district": null,
            "firstName": null,
            "identityCode": null,
            "language": "EN",
            "lastName": null,
            "phoneNumber": null,
            "state": null,
            "streetNumber": null,
            "title": null,
            "zipCode": null,
            "_type": "V4/Customer/BillingDetails"
        },
        "email": "sample@example.com",
        "reference": null,
        "shippingDetails": {
            "address": null,
            "address2": null,
            "category": null,
            "city": null,
            "country": null,
            "deliveryCompanyName": null,
            "district": null,
            "firstName": null,
            "identityCode": null,
            "lastName": null,
            "legalName": null,
            "phoneNumber": null,
            "shippingMethod": null,
            "shippingSpeed": null,
            "state": null,
            "streetNumber": null,
            "zipCode": null,
            "_type": "V4/Customer/ShippingDetails"
        },
        "extraDetails": {
            "browserAccept": null,
            "fingerPrintId": null,
            "ipAddress": "90.71.64.161",
            "browserUserAgent": "Mozilla/5.0",
            "_type": "V4/Customer/ExtraDetails"
        },
        "shoppingCart": {
            "insuranceAmount": null,
            "shippingAmount": null,
            "taxAmount": null,
            "cartItemInfo": null,
            "_type": "V4/Customer/ShoppingCart"
        },
        "_type": "V4/Customer/Customer"
    },
    "transactions": [{
        "shopId": "69876357",
        "uuid": "5b158f084502428499b2d34ad074df05",
        "amount": 990,
        "currency": "EUR",
        "paymentMethodType": "CARD",
        "paymentMethodToken": null,
        "status": "PAID",
        "detailedStatus": "AUTHORISED",
        "operationType": "DEBIT",
        "effectiveStrongAuthentication": "DISABLED",
        "creationDate": "2018-09-27T14:02:16+00:00",
        "errorCode": null,
        "errorMessage": null,
        "detailedErrorCode": null,
        "detailedErrorMessage": null,
        "metadata": null,
        "transactionDetails": {
            "liabilityShift": "NO",
            "effectiveAmount": 990,
            "effectiveCurrency": "EUR",
            "creationContext": "CHARGE",
            "cardDetails": {
                "paymentSource": "EC",
                "manualValidation": "NO",
                "expectedCaptureDate": "2018-09-27T14:02:16+00:00",
                "effectiveBrand": "CB",
                "pan": "497010XXXXXX0055",
                "expiryMonth": 11,
                "expiryYear": 2021,
                "country": "FR",
                "emisorCode": null,
                "effectiveProductCode": "F",
                "legacyTransId": "927516",
                "legacyTransDate": "2018-09-27T14:02:05+00:00",
                "paymentMethodSource": "NEW",
                "authorizationResponse": {
                    "amount": 990,
                    "currency": "EUR",
                    "authorizationDate": "2018-09-27T14:02:16+00:00",
                    "authorizationNumber": "3fe7a1",
                    "authorizationResult": "0",
                    "authorizationMode": "FULL",
                    "_type": "V4/PaymentMethod/Details/Cards/CardAuthorizationResponse"
                },
                "captureResponse": {
                    "refundAmount": null,
                    "captureDate": null,
                    "captureFileNumber": null,
                    "refundCurrency": null,
                    "_type": "V4/PaymentMethod/Details/Cards/CardCaptureResponse"
                },
                "threeDSResponse": {
                    "authenticationResultData": {
                        "transactionCondition": "COND_3D_ERROR",
                        "enrolled": "UNKNOWN",
                        "status": "UNKNOWN",
                        "eci": null,
                        "xid": null,
                        "cavvAlgorithm": null,
                        "cavv": null,
                        "signValid": null,
                        "brand": "VISA",
                        "_type": "V4/PaymentMethod/Details/Cards/CardAuthenticationResponse"
                    },
                    "_type": "V4/PaymentMethod/Details/Cards/ThreeDSResponse"
                },
                "installmentNumber": null,
                "markAuthorizationResponse": {
                    "amount": null,
                    "currency": null,
                    "authorizationDate": null,
                    "authorizationNumber": null,
                    "authorizationResult": null,
                    "_type": "V4/PaymentMethod/Details/Cards/MarkAuthorizationResponse"
                },
                "_type": "V4/PaymentMethod/Details/CardDetails"
            },
            "parentTransactionUuid": null,
            "mid": "6969696",
            "sequenceNumber": 1,
            "_type": "V4/TransactionDetails"
        },
        "_type": "V4/PaymentTransaction"
    }],
    "_type": "V4/Payment"
}

The provided SDKs allow you to easily extract POST data:

/* Use client SDK helper to retrieve POST parameters */
$formAnswer = $client->getParsedFormAnswer();

Verify the browser signature (hash)

In order to detect potential fraud, you must verify the authenticity of the kr-answer field.

The kr-hash field contains the hash of kr-answer generated with the HMAC-SHA256 key.

To verify the validity of the signature with our SDKs:

>
if (!$client->checkHash()) {
    //something wrong, probably a fraud ....
    signature_error($formAnswer['kr-answer']['transactions'][0]['uuid'], $hashKey, 
                    $client->getLastCalculatedHash(), $_POST['kr-hash']);
    throw new Exception("invalid signature");
}

Example of implementing hash verification in PHP:

    /**
     * check kr-answer object signature
     */
    public function checkHash($key=NULL)
    {
        $supportedHashAlgorithm = array('sha256_hmac');

        /* check if the hash algorithm is supported */
        if (!in_array($_POST['kr-hash-algorithm'],  $supportedHashAlgorithm)) {
            throw new LyraException("hash algorithm not supported:" . $_POST['kr-hash-algorithm'] .". Update your SDK");
        }

        /* on some servers, / can be escaped */
        $krAnswer = str_replace('\/', '/', $_POST['kr-answer']);

        /* if key is not defined, we use kr-hash-key POST parameter to choose it */
        if (is_null($key)) {
            if ($_POST['kr-hash-key'] == "sha256_hmac") {
                $key = $this->_hashKey;
            } elseif ($_POST['kr-hash-key'] == "password") {
                $key = $this->_password;
            } else {
                throw new LyraException("invalid kr-hash-key POST parameter");
            }
        }
    
        $calculatedHash = hash_hmac('sha256', $krAnswer, $key);
        $this->_lastCalculatedHash = $calculatedHash;

        /* return true if calculated hash and sent hash are the same */
        return ($calculatedHash == $_POST['kr-hash']);
    }
}

Go to the following page to find your $hash_key: Prerequisites (Keys)

Verify the transaction

All you need to do is verify the orderStatus parameter in kr-answer. If the field value is PAID, the transaction has been paid. See the status reference for more information.

Handling limiting cases

In case of a network failure or if the buyer closes their browser, you might never receive the form parameters.

Using the IPN guarantees that you will receive data in any case.

The IPN data will be more secure than the data passed by the buyer’s browser. It is sent directly to your servers. Therefore, it cannot be altered by a corrupted plug-in or spyware installed on the buyer’s browser.

To understand how to implement IPNs, go to: Using IPNs