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

When taking the order, create an initial transaction with the Charge/CreatePayment Web Service.

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

For each shipment trigger, create a shipment transaction with the Web Service Charge/CreateShipmentTransaction associated with the initial transaction.

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.

You will then use the initial transaction (the payment made by the buyer) to create a new transaction each time the shipment is triggered. For example:
- 3 days after ordering, you trigger the shipment of product No. 1. You then create a shipping transaction for 35 EUR. And the buyer will be charged 35 EUR.
- 10 days after ordering, you trigger the shipment of product No. 2. You create a new shipping transaction for 25 EUR. And the buyer will be charged another 25 EUR.
- 20 days after ordering, you trigger the shipment of product No. 3. You then create a shipping transaction for EUR 14.12. And the buyer will be debited with the remaining EUR 14.12.
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
Use cases:SHIPMENT_MULTIPLE_AUTHORISATION to request multiple authorizations.

. Recommended fields:

Order reference: "myOrder-1234-initial".
Buyer's email: " 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

Retrieve the formToken to display the payment form (More info: Step 4: Display the payment form )

The buyer authenticates the total amount of the order, but the card will not be debited immediately. The payment platform creates a verification transaction, valid for 180 days.

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 ).
Keep the uuid of the original transaction. In the example, [transactions][0].[uuid] has the value f183418d08df49f3900bbd74ef837816 . This data is required to create shipping transactions.

Example of shipping transaction 1

Request

Required fields:

Amount: €35,00
UUID : unique reference of the initial transaction:f183418d08df49f3900bbd74ef837816

. Recommended fields:

Buyer's email: " 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 : unique reference of the initial transaction:f183418d08df49f3900bbd74ef837816

. Recommended fields:

Buyer's email: " 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 : unique reference of the initial transaction:f183418d08df49f3900bbd74ef837816

. Recommended fields:

Buyer's email: " 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. For the initial transaction

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. For shipping transactions

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