Voltar navegador

Valores postados pelo navegador

Depois que o pagamento é realizado, os seguintes valores são enviados para o servidor do vendedor por meio do navegador no modo POST:

Configuração Valor
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”, (…)

Essas quatro configurações correspondem a:

Configuração Descrição
kr-hash Hash do objeto JSON armazenado no kr-answer. Permite verificar a autenticidade da resposta.
kr-hash-algorithm Algoritmo utilizado para calcular o hash. Seu valor é sha256_hmac.
kr-answer-type Tipo do objeto JSON contido no kr-answer.
kr-hash-key Tipo de chave utilizada para assinar o kr-answer. Pode corresponder a sha256_hmac (retorno do navegador) ou a password (IPN).
kr-answer Objeto que contém o resultado do pagamento, codificado em JSON.

A configuração kr-answer contém as informações sobre o estado da sessão de pagamento:

{
    "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"
}

Os SDKs disponibilizados permitem extrair facilmente os dados de POST:

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

Verificar a assinatura do navegador (hash)

Para detectar possíveis fraudes, verifique a autenticidade do campo kr-answer.

O campo kr-hash contém o hash de kr-answer gerado com a chave HMAC SHA256.

Para verificar a validade da assinatura com nossos 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");
}

Exemplo de implementação da verificação do hash em 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']);
    }
}

Consulte a página seguinte para encontrar seu $hash_key: Pré-requisitos (Chaves)

Verificar a transação

Basta verificar o parâmetro orderStatus contido no kr-answer. Se o valor do campo for PAID, a transação foi paga. Ver referências de status para maiores detalhes.

Gerenciar os casos-limites

Se a rede falhar ou se o comprador fechar seu navegador, pode-se que você nunca receberá os parâmetros do formulário.

Usar a IPN garante a recepção de dados em todos os casos.

Os dados da IPN são mais seguros que os que transitaram pelo navegador de um comprador. São enviados diretamente para seus servidores. Conseqüentemente, não podem ser alterados por um plug-in corrompido ou um spyware instalado no navegador do comprador.

Para saber como implementar a IPN, consulte: Uso da IPN