Réaliser un paiement à l'expédition
Contexte
Le paiement à l’expédition est une nouvelle fonctionnalité, conforme à la réglementation de la `DSP2` (seconde Directive européenne relative aux services de paiement).
Le marchand peut réaliser plusieurs expéditions d’une même commande dans un délai maximum de **180 jours**.
Le paiement à l’expédition fonctionne par étape :
1. Transaction initiale
- Champ
amount
avec le montant de la commande. - Champ
currency
avec la devise du paiement, selon la norme ISO 4217 alpha-3. - Champ
useCase
avec la valeurSHIPMENT_MULTIPLE_AUTHORISATION
.
La plateforme de paiement crée une transaction de vérification, avec une durée de validité de 180 jours. L'acheteur s'authentifie sur le montant total de la commande mais la carte ne sera pas débité immédiatement.
2. Transaction d'expédition
- Champ
uuid
: référence unique de la transaction initiale. - Champ
amount
: montant de la marchandise expédiée.
La plateforme crée une transaction de débit sur le montant de la marchandise expédiée.
Schéma
Cinématique du paiement
Exemple
- Votre acheteur commande 3 produits ( 35,00 EUR , 25,00 EUR , 14,12 EUR ), pour un montant total de 74,12 EUR .
- Si les 3 produits ne sont pas en stock, le marchand décide de faire du paiement à l’expédition avec des autorisations multiples.
L’acheteur est authentifié sur le montant total ( 74,12 EUR ) lors de la création de la transaction initiale mais il ne sera débité qu'à chaque expédition.
Vous vous servirez ensuite de la transaction initiale (le paiement effectué par l’acheteur) pour créer une nouvelle transaction à chaque déclenchement de l'expédition. Par exemple :
- 3 jours après la commande, vous déclenchez l'expédition du produit N°1. Vous créez à ce moment une transaction d’expédition de 35,00 EUR . Et l’acheteur sera débité de ce montant.
- 10 jours après la commande, vous déclenchez l'expédition du produit N°2. Vous créez une nouvelle transaction d’expédition de 25,00 EUR . Et l’acheteur sera débité de ce montant.
- 20 jours après la commande, vous déclenchez l'expédition du produit N°3. Vous créez à ce moment une transaction d’expédition de 14,12 EUR . Et l’acheteur sera débité du dernier montant.
Si la transaction est réalisée sur le réseau CB, les trois transactions bénéficieront d’une garantie de paiement car le déclenchement de l'expédition a eu lieu dans les 30 jours qui suivent la commande.
Requête
Exemple d'une transaction initiale
Champs obligatoires :
- Montant : 74,12 EUR
- Cas d'utilisation : SHIPMENT_MULTIPLE_AUTHORISATION pour demander des autorisations multiples.
<p>Champs recommandés :</p>
* Référence de la commande : "myOrder-1234-initial".
* E-mail de l'acheteur : "sample@example.com".
<div><doc-code-block>
<doc-param name="auth-link">/doc/fr-FR/rest/V4.0/api/kb/authentication.html</doc-param>
<doc-param name="url-target">https://api.scelliuspaiement.labanquepostale.fr/api-payment/V4/Charge/CreatePayment</doc-param>
<doc-param name="data-markets"></doc-param>
{ "amount": 7412, "currency": "EUR", "customer": { "email": "sample@example.com" }, "orderId": "myOrder-1234-initial", "useCase": "SHIPMENT_MULTIPLE_AUTHORISATION" }
<!-- <pre data-language="json" data-market="es-PE">
{
 "amount": 200050,
 "currency": "PEN",
 "orderId": "myOrderId-999999", 
 "channelOptions": {
 "channelType": "MAIL",
 "mailOptions": {
 "recipient": "sample@example.com"
 }
 },
 "paymentReceiptEmail": "sample@example.com",
 "expirationDate": "2020-04-20T20:13:26+02:00",
 "locale": "es_PE",
 "dataCollectionForm": "false"
}
</pre>
{ "amount": 200050, "currency": "ARS", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient": "sample@example.com" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "locale": "es_AR", "dataCollectionForm": "false" }
{ "amount": 200050, "currency": "COP", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient": "sample@example.com" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "locale": "es_CO", "dataCollectionForm": "false" }
{ "amount": 200050, "currency": "BRL", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient": "sample@example.com" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "locale": "pt_BR", "dataCollectionForm": "false" }-->
/** * I initialize the PHP SDK */ require_once __DIR__ . '/vendor/autoload.php'; require_once __DIR__ . '/keys.php'; require_once __DIR__ . '/helpers.php'; /** * Initialize the SDK * see keys.php */ $client = new Lyra\Client(); /** * I create a formToken */ $store = array("amount" => 250, "currency" => "EUR", "orderId" => uniqid("MyOrderId"), "customer" => array( "email" => "sample@example.com" )); $response = $client->post("V4/Charge/CreatePayment", $store); /* I check if there are some errors */ if ($response['status'] != 'SUCCESS') { /* an error occurs, I throw an exception */ display_error($response); $error = $response['answer']; throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage'] ); } /* everything is fine, I extract the formToken */ $formToken = $response["answer"]["formToken"]; ?>
/** * I initialize the PHP SDK */ require_once __DIR__ . '/vendor/autoload.php'; require_once __DIR__ . '/keys.php'; require_once __DIR__ . '/helpers.php'; /** * Initialize the SDK * see keys.php */ $client = new Lyra\Client(); /** * I create a formToken */ $store = array("amount" => 250, "currency" => "EUR", "orderId" => uniqid("MyOrderId"), "customer" => array( "email" => "sample@example.com" )); $response = $client->post("V4/Charge/CreatePayment", $store); /* I check if there are some errors */ if ($response['status'] != 'SUCCESS') { /* an error occurs, I throw an exception */ display_error($response); $error = $response['answer']; throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage'] ); } /* everything is fine, I extract the formToken */ $formToken = $response["answer"]["formToken"]; ?>
Pour connaître l'intégralité et la description des champs, voir le playground : <a href="/doc/fr-FR/rest/V4.0/api/playground/?ws=Charge/CreatePayment">Charge/CreatePayment</a> (menu à gauche).
### Réponse
Récupérez le <no-translate><code>formToken</code></no-translate> pour afficher le formulaire de paiement (Plus d'infos : <a href="/doc/fr-FR/rest/V4.0/javascript/guide/display/presentation.html">Etape 4 : Afficher le formulaire de paiement</a>)
L'acheteur s'authentifie sur le montant total de la commande mais la carte ne sera pas débité immédiatement.
<p>La plateforme de paiement crée une transaction de vérification, avec une durée de validité de 180 jours.</p>
### Exemple de réponse
<div><doc-code-block>
"kr-answer": { "shopId": "12345678", "orderCycle": "CLOSED", "orderStatus": "PAID", "orderDetails": { "orderTotalAmount": 7212, "orderEffectiveAmount": 7212, "orderCurrency": "EUR", "mode": "TEST", "orderId": "myOrder-1234-initial", "metadata": null, "_type": "V4/OrderDetails" }, "transactions": [ { "shopId": "12345678", "uuid": "f183418d08df49f3900bbd74ef837816", "amount": 12500, "currency": "EUR", "paymentMethodType": "CARD", "paymentMethodToken": null, "status": "PAID", "detailedStatus": "ACCEPTED", "operationType": "VERIFICATION", "orderId": "myOrderId-1234", "_type": "V4/Charge/CreateQRCodeResponse" }, (...) "_type": "V4/WebService/Response" } }
* Analysez le résultat du paiement (Plus d'infos : <a href="/doc/fr-FR/rest/V4.0/javascript/guide/analyse/presentation.html">Etape 5 : Analyser le résultat du paiement</a>).
* Conservez l'<no-translate><code>uuid</code></no-translate> de la transaction initiale. Dans l'exemple, <no-translate><code>[transactions][0].[uuid]</code></no-translate> a pour valeur <no-translate><code>f183418d08df49f3900bbd74ef837816</code></no-translate>. Cette donnée est **obligatoire** pour créer les transactions d'expédition.
Exemple de la transaction d'expédition 1
Requête
Champs obligatoires :
- Montant : 35,00 €
- Uuid : référence unique de la transaction initiale : f183418d08df49f3900bbd74ef837816
Champs recommandés :
- E-mail de l'acheteur : "sample@example.com"
{ "amount": 3500, "customer": { "email": "sample@example.com" }, "uuid": "f183418d08df49f3900bbd74ef837816" }
Pour connaître l'intégralité et la description des champs, voir le playground : Charge/CreateShipmentTransaction (menu à gauche).
Réponse de la requête
{ "webService": "Charge/CreateShipmentTransaction", "version": "V4", "applicationVersion": "6.12.0", "status": "SUCCESS", "answer": { "shopId": "12345678", "uuid": "7b8179b7845e4576868d624039b754c5", "paymentMethodType": "CARD", "paymentMethodToken": null, "detailedStatus": "AUTHORISED", "status": "PAID", "amount": 3500, "currency": "EUR", (...) "_type": "V4/WebService/Response" } }
La valeur PAID du champ status signifie que la transaction a été acceptée.
Plus d'infos : références de status
Exemple de la transaction d'expédition 2
Requête
Champs obligatoires :
- Montant : 25,00 €
- Uuid : référence unique de la transaction initiale : f183418d08df49f3900bbd74ef837816
Champs recommandés :
- E-mail de l'acheteur : "sample@example.com"
{ "amount": 2500, "customer": { "email": "sample@example.com" }, "uuid": "f183418d08df49f3900bbd74ef837816" }
Pour connaître l'intégralité et la description des champs, voir le playground : Charge/CreateShipmentTransaction (menu à gauche).
Réponse de la requête
{ "webService": "Charge/CreateShipmentTransaction", "version": "V4", "applicationVersion": "6.12.0", "status": "SUCCESS", "answer": { "shopId": "12345678", "uuid": "7b8179b7845e4576868d624039b754c5", "paymentMethodType": "CARD", "paymentMethodToken": null, "detailedStatus": "AUTHORISED", "status": "PAID", "amount": 2500, "currency": "EUR", (...) "_type": "V4/WebService/Response" } }
La valeur PAID du champ status signifie que la transaction a été acceptée.
Plus d'infos : références de status
Exemple de la transaction d'expédition 3
Requête
Champs obligatoires :
- Montant : 14,12 €
- Uuid : référence unique de la transaction initiale : f183418d08df49f3900bbd74ef837816
Champs recommandés :
- E-mail de l'acheteur : "sample@example.com"
{ "amount": 1412, "customer": { "email": "sample@example.com" }, "uuid": "f183418d08df49f3900bbd74ef837816" }
Pour connaître l'intégralité et la description des champs, voir le playground : Charge/CreateShipmentTransaction (menu à gauche).
Réponse de la requête
{ "webService": "Charge/CreateShipmentTransaction", "version": "V4", "applicationVersion": "6.12.0", "status": "SUCCESS", "answer": { "shopId": "12345678", "uuid": "7b8179b7845e4576868d624039b754c5", "paymentMethodType": "CARD", "paymentMethodToken": null, "detailedStatus": "AUTHORISED", "status": "PAID", "amount": 1412, "currency": "EUR", (...) "_type": "V4/WebService/Response" } }
La valeur PAID du champ status signifie que la transaction a été acceptée.
Plus d'infos : références de status
Gestion des erreurs
Tableau des erreurs
Code | Description |
---|---|
INT_009 | Le format du champ amount est invalide ou le champ n'est pas transmis. |
INT_010 | Le format du champ currency est invalide ou le champ n'est pas transmis. |
INT_050 | Le paramètre strongAuthentication est invalide. |
PSP_519 | Devise inconnue. |
PSP_606 | Devise non supportée par le contrat. |
PSP_227 | Erreur technique inconnue lors de la création d'une transaction d'expédition. |
PSP_228 | Transaction d'expédition créée mais impossible de générer un résultat de réponse. |
PSP_229 | Impossible de créer une transaction d'expédition. |
PSP_231 | Une transaction initiale de paiement d'expédition ne peut pas être modifiée. |
PSP_236 | Une transaction d'expédition ne peut pas être dupliquée. |
Analyse du résultat du paiement
- Pour la transaction initiale
Implémentez l’URL de notification à la fin du paiement (également appelée IPN) pour analyser le résultat et conserver l'
uuid
de la transaction initiale.
- Renseignez uniquement l'URL de notification dans la section API REST (TEST ou PRODUCTION) : Procédure.
- Analysez l'IPN: Procédure.
- Pour les transactions d'expédition Le Web Service retourne un objet de type Transaction de débit.