Making a payment upon shipment

Context

Payment upon shipment is a new feature, in accordance with PSD2 regulation (second European directive relative to payment services). The merchant can perform several shipments of the same order within the maximum delay of 180 days.

Use cases

Payment upon shipment is performed in several steps:

1. Initial transaction

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

fieldamountwith the amount of the order.
fieldcurrencywith the payment currency, according to the ISO 4217 alpha-3 standard.
fielduseCasewith the valueSHIPMENT_MULTIPLE_AUTHORISATION.

The payment gateway creates a verification transaction, with a validity period of 180 days. The buyer authenticates with the total order amount but the card will not be debited immediately.

2. Shipping transaction

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

fielduuid: unique reference of the initial transaction.
fieldamount: amount of the shipped product.

The gateway creates a debit transaction for the amount of the shipped product.

diagram

Payment kinematics

Example

Your buyer orders 3 products (EUR 35, EUR 25 and EUR 14,12), for a total amount of EUR 72,12.

If the 3 products are not in stock, the merchant decides to make a payment upon shipment with multiple authorizations.
The buyer is authenticated for the total amount (EUR 72,12) upon creation of the initial transaction but he or she will only be debited upon each shipment.

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 EUR. Et l'acheteur sera débité de 35 EUR.
- 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 EUR. Et l'acheteur sera encore débité de 25 EUR.
- 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é des 14.12 EUR restant.
If the transaction is carried out on the CB network, all three transactions will benefit from a payment guarantee because the triggering of the shipment took place within 30 days following the order.

Request

Example of an initial transaction

Required fields:

Amount: €72.12
Cas d'utilisation : SHIPMENT_MULTIPLE_AUTHORISATION pour demander des autorisations multiples.

. Recommended fields:

Référence de la commande : "myOrder-1234-initial".
E-mail de l'acheteur : "sample@example.com".

/en/rest/V4.0/api/kb/authentication.html

https://api.lyra.com/api-payment/V4/Charge/CreatePayment

    {
        "amount": 7212,
        "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"];

?>

To view the fields and their description, go to the playground: Charge/CreatePayment (menu on left).

Response

Récupèrez le formToken pour afficher le formulaire de paiement (Plus d'infos : Etape 4 : Afficher le formulaire de paiement)

L'acheteur s'authentifie sur le montant total de la commande mais la carte ne sera pas débité immédiatement. La plateforme de paiement crée une transaction de vérification, avec une durée de validité de 180 jours.

Example of a response

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

}

Analyzing the payment result (more information: Step 5: Analyze the payment result ).
Conservez l'uuid de la transaction initiale. Dans l'exemple, [transactions][0].[uuid] a pour valeur f183418d08df49f3900bbd74ef837816. Cette donnée est obligatoire pour créer les transactions d'expédition.

Example of shipping transaction 1

Request

Required fields:

Amount: €35,00
Uuid : référence unique de la transaction initiale : f183418d08df49f3900bbd74ef837816

. Recommended fields:

E-mail de l'acheteur : "sample@example.com"

/en/rest/V4.0/api/kb/authentication.html

https://api.lyra.com/api-payment/V4/Charge/CreateShipmentTransaction

      {
        "amount": 3500,
        "customer": {
          "email": "sample@example.com"
        },
        "uuid": "f183418d08df49f3900bbd74ef837816"
      }

To view the fields and their description, go to the playground: Charge/CreateShipmentTransaction (menu on the left).

Query response

   
      {
        "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 valeurPAIDdu champstatusmeans that the transaction has been accepted.
More information :status reference

Example of shipping transaction 2

Request

Required fields:

Amount: €25,00
Uuid : référence unique de la transaction initiale : f183418d08df49f3900bbd74ef837816

. Recommended fields:

E-mail de l'acheteur : "sample@example.com"

/en/rest/V4.0/api/kb/authentication.html

https://api.lyra.com/api-payment/V4/Charge/CreateShipmentTransaction

      {
        "amount": 2500,
        "customer": {
          "email": "sample@example.com"
        },
        "uuid": "f183418d08df49f3900bbd74ef837816"
      }

To view the fields and their description, go to the playground: Charge/CreateShipmentTransaction (menu on the left).

Query response

   
      {
        "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 valeurPAIDdu champstatusmeans that the transaction has been accepted.
More information :status reference

Example of shipping transaction 3

Request

Required fields:

Amount: €14,12
Uuid : référence unique de la transaction initiale : f183418d08df49f3900bbd74ef837816

. Recommended fields:

E-mail de l'acheteur : "sample@example.com"

/en/rest/V4.0/api/kb/authentication.html

https://api.lyra.com/api-payment/V4/Charge/CreateShipmentTransaction

      {
        "amount": 1412,
        "customer": {
          "email": "sample@example.com"
        },
        "uuid": "f183418d08df49f3900bbd74ef837816"
      }

To view the fields and their description, go to the playground: Charge/CreateShipmentTransaction (menu on the left).

Query response

   
      {
        "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 valeurPAIDdu champstatusmeans that the transaction has been accepted.
More information :status reference

Error handling

Error table

Code	Description
INT_009	The format of the amount field is invalid or the field is not transmitted.
INT_010	The format of the currency field is invalid or the field is not transmitted.
INT_050	The strongAuthentication parameter is invalid.
PSP_519	Unknown currency.
PSP_606	Currency not supported by the MID.

Analysis of payment results

1. Pour la transaction initiale

Implement the Payment Completion Notification URL (also known as IPN) to parse the result and retain the uuid of the original transaction.

In the REST API section (TEST or PRODUCTION), enter only the notification URL: Procedure.
Analyze the IPN: Procedure.

2. Pour les transactions d'expédition

The Web Service returns an object of type Debit transaction.

Categories

Tags

Making a payment upon shipment

Context

Use cases

diagram

Example

Request

Response

Example of a response

Request

Query response

Request

Query response

Request

Query response

Error handling

Analysis of payment results