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.
- field
amount
with the amount of the order. - field
currency
with the payment currency, according to the ISO 4217 alpha-3 standard. - field
useCase
with 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.
- field
uuid
: unique reference of the initial transaction. - field
amount
: 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
- Use case:SHIPMENT_MULTIPLE_AUTHORISATIONto request multiple authorizations.
. Recommended fields:
- Référence de la commande : "myOrder-1234-initial".
- E-mail de l'acheteur : "sample@example.com".
{ "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">
{
 "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"]; ?>
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 valeurf183418d08df49f3900bbd74ef837816
. 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: unique reference of the initial transaction:f183418d08df49f3900bbd74ef837816
. Recommended fields:
- E-mail de l'acheteur : "sample@example.com"
{ "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:
- E-mail de l'acheteur : "sample@example.com"
{ "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:
- E-mail de l'acheteur : "sample@example.com"
{ "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.
2. Pour les transactions d'expédition
The Web Service returns an object of type Debit transaction.