Réaliser un paiement à l'expédition

Cas d'utilisation

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

Lors de la prise de la commande, créez une transaction initiale avec le Web Service Charge/CreatePayment.

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 valeur SHIPMENT_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

Pour chaque déclenchement d'expédition, créez une transaction d'expédition associée à la transaction initiale avec le Web Service Charge/CreateShipmentTransaction.

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é pour 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">&#010;{&#010;    &quot;amount&quot;: 200050,&#010;    &quot;currency&quot;: &quot;PEN&quot;,&#010;    &quot;orderId&quot;: &quot;myOrderId-999999&quot;,    &#010;    &quot;channelOptions&quot;: {&#010;      &quot;channelType&quot;: &quot;MAIL&quot;,&#010;      &quot;mailOptions&quot;: {&#010;        &quot;recipient&quot;: &quot;sample@example.com&quot;&#010;      }&#010;    },&#010;    &quot;paymentReceiptEmail&quot;: &quot;sample@example.com&quot;,&#010;    &quot;expirationDate&quot;: &quot;2020-04-20T20:13:26+02:00&quot;,&#010;    &quot;locale&quot;: &quot;es_PE&quot;,&#010;    &quot;dataCollectionForm&quot;: &quot;false&quot;&#010;}&#010;</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

<p>Récupérez le <no-translate><code>formToken</code></no-translate> pour afficher le formulaire de paiement.</p>
<p>(Plus d'infos : <a href="/doc/fr-FR/rest/V4.0/javascript/guide/display/presentation.html">Etape 4 : Afficher le formulaire de paiement</a>)</p>

<p>L'acheteur s'authentifie pour le montant total de la commande mais la carte ne sera pas débitée immédiatement.</p>
<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"
/doc/fr-FR/rest/V4.0/api/kb/authentication.html

https://api.scelliuspaiement.labanquepostale.fr/api-payment/V4/Charge/CreateShipmentTransaction

      {
        "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"
/doc/fr-FR/rest/V4.0/api/kb/authentication.html

https://api.scelliuspaiement.labanquepostale.fr/api-payment/V4/Charge/CreateShipmentTransaction

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

/doc/fr-FR/rest/V4.0/api/kb/authentication.html

https://api.scelliuspaiement.labanquepostale.fr/api-payment/V4/Charge/CreateShipmentTransaction

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

Catégories

Tags

Réaliser un paiement à l'expédition

Cas d'utilisation

Schéma

Exemple

Requête

Requête

Réponse de la requête

Requête

Réponse de la requête

Requête

Réponse de la requête

Gestion des erreurs

Analyse du résultat du paiement