Paiement effectué
Une fois que le paiement a eu lieu, vous pouvez récupérer les informations sur la transaction nouvellement créée de deux façons différentes.
Si vous définissez une URL de retour à l'aide du paramètre kr-post-url-success, le client JavaScript va poster le résultat sur la page indiquée. Voir la section suivante: retour à la boutique.
Par exemple,
si vous utilisez la carte de TEST : VISA avec ce pan(numéro de la carte) : "4970 1000 0000 0014", vous aurez dans l'objet : paymentMethodDetails
ce résultat :
"transactions":[ { (...) "transactionDetails":{ (...) "paymentMethodDetails":{ "id":"497010XXXXXX0014", (...) }, }, }, ],
retour à la boutique
Lorsque le paiement a été réalisé, le client JavaScript transmet le résultat du paiement à l'URL définie par le paramètre kr-post-url-success via un formulaire en mode POST. Le formulaire posté contient les données suivantes:
Paramètre | Valeur |
---|---|
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", (...) |
Ces paramètres correspondent à:
Paramètre | Description |
---|---|
kr-hash | Hash de l'objet JSON stocké dans kr-answer. Il permet de vérifier l'authenticité de la réponse. |
kr-hash-algorithm | Algorithme utilisé pour calculer le hash. Sa valeur est sha256_hmac. |
kr-answer-type | Type de l'objet JSON contenu dans kr-answer. |
kr-hash-key | Type de clé utilisée pour signer kr-answer. Peut valoir sha256_hmac (retour à la boutique) ou password (cas IPN). |
kr-answer | Objet contenant le résultat du paiement, encodé en JSON. |
Le paramètre kr-answer contient les informations sur l'état de la session de paiement :
{ "shopId": "69876357", "orderCycle": "CLOSED", "orderStatus": "PAID", "serverDate": "2022-01-21T09:28:17+00:00", "orderDetails": { "orderTotalAmount": 990, "orderEffectiveAmount": 990, "orderCurrency": "EUR", "mode": "TEST", "orderId": "myOrderId-475882", "metadata": null, "_type": "V4/OrderDetails" }, "customer": { "billingDetails": { "address": null, "category": null, "cellPhoneNumber": null, "city": null, "country": null, "district": null, "firstName": null, "identityCode": null, "language": "FR", "lastName": null, "phoneNumber": null, "state": null, "streetNumber": null, "title": null, "zipCode": null, "legalName": 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": "185.244.73.2", "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.71 Safari/537.36", "_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": "1c8356b0e24442b2acc579cf1ae4d814", "amount": 990, "currency": "EUR", "paymentMethodType": "CARD", "paymentMethodToken": null, "status": "PAID", "detailedStatus": "AUTHORISED", "operationType": "DEBIT", "effectiveStrongAuthentication": "ENABLED", "creationDate": "2022-01-21T09:28:16+00:00", "errorCode": null, "errorMessage": null, "detailedErrorCode": null, "detailedErrorMessage": null, "metadata": null, "transactionDetails": { "liabilityShift": "YES", "effectiveAmount": 990, "effectiveCurrency": "EUR", "creationContext": "CHARGE", "cardDetails": { "paymentSource": "EC", "manualValidation": "NO", "expectedCaptureDate": "2022-01-27T09:38:10+00:00", "effectiveBrand": "VISA", "pan": "497011XXXXXX1003", "expiryMonth": 12, "expiryYear": 2025, "country": "FR", "issuerCode": 17807, "issuerName": "Banque Populaire Occitane", "effectiveProductCode": null, "legacyTransId": "929936", "legacyTransDate": "2022-01-21T09:28:16+00:00", "paymentMethodSource": "NEW", "authorizationResponse": { "amount": 990, "currency": "EUR", "authorizationDate": "2022-01-21T09:28:16+00:00", "authorizationNumber": "3fe205", "authorizationResult": "0", "authorizationMode": "FULL", "_type": "V4/PaymentMethod/Details/Cards/CardAuthorizationResponse" }, "captureResponse": { "refundAmount": null, "refundCurrency": null, "captureDate": null, "captureFileNumber": null, "effectiveRefundAmount": null, "effectiveRefundCurrency": null, "_type": "V4/PaymentMethod/Details/Cards/CardCaptureResponse" }, "threeDSResponse": { "authenticationResultData": { "transactionCondition": null, "enrolled": null, "status": null, "eci": null, "xid": null, "cavvAlgorithm": null, "cavv": null, "signValid": null, "brand": null, "_type": "V4/PaymentMethod/Details/Cards/CardAuthenticationResponse" }, "_type": "V4/PaymentMethod/Details/Cards/ThreeDSResponse" }, "authenticationResponse": { "id": "30eaa40d-dd76-4617-b527-4bed6240b81c", "operationSessionId": "ae6f2ad3ffea41bb8faf1aefabad87b9", "protocol": { "name": "THREEDS", "version": "2.1.0", "network": "VISA", "challengePreference": "NO_PREFERENCE", "simulation": true, "_type": "V4/Charge/Authenticate/Protocol" }, "value": { "authenticationType": "CHALLENGE", "authenticationId": { "authenticationIdType": "dsTransId", "value": "bafdb21f-e3d6-4d1c-b4f6-d1668b7f7f21", "_type": "V4/Charge/Authenticate/AuthenticationId" }, "authenticationValue": { "authenticationValueType": "CAVV", "value": "BqLgDBHYRaCBpip3Fn3+erKT9vg=", "_type": "V4/Charge/Authenticate/AuthenticationValue" }, "status": "SUCCESS", "commerceIndicator": "05", "extension": { "authenticationType": "THREEDS_V2", "threeDSServerTransID": "30eaa40d-dd76-4617-b527-4bed6240b81c", "dsTransID": "bafdb21f-e3d6-4d1c-b4f6-d1668b7f7f21", "acsTransID": "bd6e58b4-6f37-4993-b428-9096766d83a6", "_type": "V4/Charge/Authenticate/AuthenticationResultExtensionThreedsV2" }, "reason": { "_type": "V4/Charge/Authenticate/AuthenticationResultReason" }, "_type": "V4/Charge/Authenticate/AuthenticationResult" }, "_type": "V4/AuthenticationResponseData" }, "installmentNumber": null, "installmentCode": null, "markAuthorizationResponse": { "amount": null, "currency": null, "authorizationDate": null, "authorizationNumber": null, "authorizationResult": null, "_type": "V4/PaymentMethod/Details/Cards/MarkAuthorizationResponse" }, "cardHolderName": null, "identityDocumentNumber": null, "identityDocumentType": null, "_type": "V4/PaymentMethod/Details/CardDetails" }, "fraudManagement": { "_type": "V4/PaymentMethod/Details/FraudManagement" }, "subscriptionDetails": { "subscriptionId": null, "_type": "V4/PaymentMethod/Details/SubscriptionDetails" }, "parentTransactionUuid": null, "mid": "9999999", "sequenceNumber": 1, "taxAmount": null, "preTaxAmount": null, "taxRate": null, "externalTransactionId": null, "nsu": null, "tid": "001", "acquirerNetwork": "CB", "taxRefundAmount": null, "userInfo": "JS Client", "paymentMethodTokenPreviouslyRegistered": null, "occurrenceType": "UNITAIRE", "_type": "V4/TransactionDetails" }, "_type": "V4/PaymentTransaction" } ], "subMerchantDetails": null, "_type": "V4/Payment" }
Comment récupérer la réponse?
Les SDKs mis à disposition vous permettent d'extraire facilement les données POST :
/* Use client SDK helper to retrieve POST parameters */ $formAnswer = $client->getParsedFormAnswer();
En PHP, si vous n'utilisez pas notre SDK, il vous suffit de récupérer le contenu de la Superglobale $_POST.
Vérifier la signature navigateur (hash)
Afin de détecter les fraudes potentielles, vous devez vérifier l'authenticité du champ kr-answer.
Le champ kr-hash contient le hash de kr-answer généré avec la clé HMAC-SHA-256.
Cette clé est disponible dans votre Back Office (menu Paramétrage > Boutique, onglet Clés d'API REST, section API REST : clés utilisées pour calculer / vérifier le champ kr-hash).
Pour vérifier la validité de la signature avec nos 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"); }
Exemple d'implémentation de la vérification du hash en 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']); } }
Vérifier la transaction
Il suffit de vérifier le paramètre orderStatus contenu dans kr-answer. Si la valeur du champ est PAID, la transaction a été payée. Voir références de status pour plus de détails.
Gérer la notification à la fin du paiement (IPN)
En cas de coupure réseau ou si l'acheteur ferme son navigateur, il est possible que vous ne receviez jamais les paramètres du formulaire.
Utiliser l’IPN vous garantit de recevoir des données dans tous les cas.
Les données de l'IPN sont plus sûres que celles qui ont transité par un navigateur de l'acheteur. Elles sont envoyées directement sur vos serveurs. En conséquence elles ne peuvent pas être altérées par un plugin corrompu ou un spyware installé sur le navigateur de l'acheteur.
Pour comprendre comment implémenter les IPN, rendez-vous ici : Utilisation de l'IPN