• France
état des services
démonstrations
assistance
FAQContacter le support
Video tutorials
Rechercher
Catégories
Tags
docs.
France
Espagne
Europe (Anglais)
Inde
Accueil
Cas d'usage
Créer un paiement
Créer un paiement en plusieurs fois
Proposer un paiement complémentaire
Créer un paiement par alias (token)
Créer un lien de paiement
Créer un abonnement
Gérer vos abonnements
Gérer vos transactions (rembourser,...)
Analyser vos journaux
Docs API
Formulaire embarqué
API REST
Formulaire en redirection
SDK Mobile
Échange de fichiers
Mandats SEPA par API REST
Exemples de code
Moyens de paiement
Modules de paiement
Marketplace
Guides
Back Office Marchand
Back Office Expert
Guides fonctionnels

Cas d'utilisation

Voici une liste non exhaustive des cas d'utilisation avec la création du formToken (lors de l'appel au web service Charge/createPayment).

Description
Créer un paiement en plusieurs fois
Transmettre le numéro de commande
Transmettre les données de l'acheteur
Transmettre les données de livraison
Transmettre le contenu du panier
Transmettre les données du sous-marchand
Proposer l'enregistrement du moyen de paiement
Utiliser un moyen de paiement enregistré
Utiliser un moyen de paiement enregistré sans afficher le formulaire embarqué
Transmettre la préférence marchand
Augmenter les chances de frictionless en 3DS2
Surcharger l'URL de notification instantanée
Transmettre des données personnalisées

Créer un paiement en plusieurs fois

Définition

Le paiement en plusieurs fois consiste à échelonner les paiements avec la création d'échéances sur une durée déterminée.

Ce mode de paiement est une facilité de paiement proposée à l’acheteur, connue aussi sous le nom de BNPL (Buy Now Pay Later).

  • La première échéance est réalisée lors de l'achat.
  • Les échéances suivantes sont débitées en différé.

Seule la première échéance est garantie, grâce au 3-D Secure avec transfert de responsabilité. Les échéances suivantes peuvent être refusées. Dans ce cas, contactez votre acheteur pour régulariser la situation.

Le paiement en plusieurs en fois avec un organisme de crédit fonctionne de manière différente. L'organisme de crédit (Alma, Cofidis, ...) vous règle la totalité du montant de la commande et se charge de débiter les futures échéances auprès de l'acheteur.

Disponibilité

Cette fonctionnalité est disponible :

  • Uniquement pour le paiement par cartes pour créer des paiements 2, 3 ou 4 fois.
  • Selon le mode d'affichage du formulaire de paiement.
Mode d'affichage Description Disponibilité
Mode liste (voir : lien) Le formulaire s'affiche directement avec les champs embarqués
Mode pop-in (voir : lien ) Non disponible
Mode liste avec carte embarquée (voir : lien) Le formulaire s'affiche directement avec les champs embarqués

Intégration

1. Créer un échéancier simple (avec montants et dates d'échéances fixes)

Prérequis
- soumis à option et/ou en fonction de votre offre

Exemple de requête

Paiement en 2 fois

Champs obligatoires :

  • Montant : 100,00 EUR.
  • Règle :
    • Nombre d’échéances : 2.
    • Période (en jours) entre chaque échéance : 7 jours.

Champs recommandés :

  • Montant du premier paiement : 50,00 EUR .
  • Référence de la commande : "myOrderId-1234".
/fr-FR/rest/V4.0/api/kb/authentication.html
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44
https://api.lyra.com/api-payment/V4/Charge/CreatePayment
    {
      "amount":10000,
      "currency":"EUR",
      "orderId":"myOrderId-1234",
      "transactionOptions":{
         "installmentOptions":[
            {
               "firstAmount":5000,
               "count":2,
               "period":7
            }
         ]
      }
   }

Le premier paiement de 50,00 EUR est créé à J+0.

Le deuxième paiement de 50,00 EUR est créé à J+7.

La description et l'intégralité de tous les champs sont disponibles (menu à gauche) : Charge/CreatePayment.

Paiement en 3 fois

Champs obligatoires :

  • Montant : 100,00 EUR.
  • Règle :
    • Nombre d’échéances : 3.
    • Période (en jours) entre chaque échéance : 7 jours.

Champs recommandés :

  • Montant du premier paiement : 50,00 EUR .
  • Référence de la commande : "myOrderId-1234".
/fr-FR/rest/V4.0/api/kb/authentication.html
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44
https://api.lyra.com/api-payment/V4/Charge/CreatePayment
{
  "amount":10000,
  "currency":"EUR",
  "orderId":"myOrderId-1234",
  "transactionOptions":{
     "installmentOptions":[
        {
           "firstAmount":5000,
           "count":3,
           "period":7
        }
     ]
  }
}

Le premier paiement de 50,00 EUR est créé à J+0.

Le deuxième paiement de 25,00 EUR est créé à J+7.

Le troisième paiement de 25,00 EUR est créé à J+14.

La description et l'intégralité de tous les champs sont disponibles (menu à gauche) : Charge/CreatePayment.

Paiement en 4 fois

Champs obligatoires :

  • Montant : 200,00 EUR.
  • Règle :
    • Nombre d’échéances : 4.
    • Période (en jours) entre chaque échéance : 7 jours.

Champs recommandés :

  • Montant du premier paiement : 50,00 EUR .
  • Référence de la commande : "myOrderId-1234".
/fr-FR/rest/V4.0/api/kb/authentication.html
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44
https://api.lyra.com/api-payment/V4/Charge/CreatePayment
{
  "amount":20000,
  "currency":"EUR",
  "orderId":"myOrderId-1234",
  "transactionOptions":{
     "installmentOptions":[
        {
           "firstAmount":5000,
           "count":4,
           "period":7
        }
     ]
  }
}

Le premier paiement de 50,00 EUR est créé à J+0.

Le deuxième paiement de 50,00 EUR est créé à J+7.

Le troisième paiement de 50,00 EUR est créé à J+14.

Le quatrième paiement de 50,00 EUR est créé à J+21.

La description et l'intégralité de tous les champs sont disponibles (menu à gauche) : Charge/CreatePayment.

Vous pouvez proposer à l'acheteur plusieurs choix. Par exemple, combinez le paiement en 2 et 3 fois (voir ci-dessous).

Paiement en 2 et 3 fois

Champs obligatoires :

  • Montant : 100,00 EUR.
  • Règle :
    • Nombre d’échéances : 2 et 3.
    • Période (en jours) entre chaque échéance :
      • 7 jours pour le paiement en 2 fois.
      • 10 jours pour le paiement en 3 fois.

Champs recommandés :

  • Montant du premier paiement : 50,00 EUR .
  • Référence de la commande : "myOrderId-1234".
/fr-FR/rest/V4.0/api/kb/authentication.html
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44
https://api.lyra.com/api-payment/V4/Charge/CreatePayment
    {
      "amount":10000,
      "currency":"EUR",
      "orderId":"myOrderId-1234",
      "transactionOptions":{
         "installmentOptions":[
            {
               "firstAmount":5000,
               "count":2,
               "period":7
            },
            {
               "firstAmount":5000,
               "count":3,
               "period":10
            }
         ]
      }
   }

La date de la dernière échéance ne peut être supérieure à 12 mois. Si la date de la dernière échéance est supérieure à la date de validité de la carte, aucune échéance ne sera enregistrée et l'acheteur sera notifié par un message de ce problème.

2. Créer un écheancier avancé (avec montants et dates d'échéances variables)

Prérequis
- soumis à l’option *"Paiement en plusieurs fois avancé"* - non prise en compte de la *valeur du champ Capture Delay* (délai de remise en banque)

Exemple de requête

Paiement en 2 fois

Champs obligatoires :

  • Montant : 100,00 EUR.
  • Règle : Paiement en 2 fois (date au format ISO-8601).
  1. le 1 er Avril pour un montant de 50,00 EUR .
  2. le 1 er Mai pour un montant de 50,00 EUR .

Champs recommandés :

  • Référence de la commande : "myOrderId-1234".
/fr-FR/rest/V4.0/api/kb/authentication.html
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44
https://api.lyra.com/api-payment/V4/Charge/CreatePayment
  {
    "amount":10000,
    "currency":"EUR",
    "orderId":"myOrderId-1234",
    "transactionOptions":{
        "installmentOptions":[
          {
              "schedules":[
                {
                    "date":"2025-04-01T00:00:00+00:00",
                    "amount":5000
                },
                {
                    "date":"2025-05-01T00:00:00+00:00",
                    "amount":5000
                }
              ]
          }
        ]
    }
  }

La description et l'intégralité de tous les champs sont disponibles (menu à gauche) : Charge/CreatePayment.

Paiement en 3 fois

Champs obligatoires :

  • Montant : 100,00 EUR.
  • Règle : Paiement en 3 fois (date au format ISO-8601)
  1. le 1er Avril pour un montant de 50,00 EUR .
  2. le 1er Mai pour un montant de 30,00 EUR .
  3. le 1er Juin pour un montant de 20,00 EUR .

Champs recommandés :

  • Référence de la commande : "myOrderId-1234".
/fr-FR/rest/V4.0/api/kb/authentication.html
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44
https://api.lyra.com/api-payment/V4/Charge/CreatePayment
    {
      "amount":10000,
      "currency":"EUR",
      "orderId":"myOrderId-1234",
      "transactionOptions":{
         "installmentOptions":[
            {
               "schedules":[
                  {
                     "date":"2025-04-16T00:00:00+00:00",
                     "amount":5000
                  },
                  {
                     "date":"2025-05-20T00:00:00+00:00",
                     "amount":3000
                  },
                  {
                     "date":"2025-06-01T00:00:00+00:00",
                     "amount":2000
                  }
               ]
            }
         ]
      }
   }

La description et l'intégralité de tous les champs sont disponibles (menu à gauche) : Charge/CreatePayment.

Paiement en 4 fois

Champs obligatoires :

  • Montant : 120,00 EUR.
  • Règle : Paiement en 4 fois (date au format ISO-8601)
  1. le 1er Avril pour un montant de 50,00 EUR .
  2. le 1er Mai pour un montant de 30,00 EUR .
  3. le 1er Juin pour un montant de 20,00 EUR .
  4. le 1er Juillet pour un montant de 20,00 EUR .

Champs recommandés :

  • Référence de la commande : "myOrderId-1234".
/fr-FR/rest/V4.0/api/kb/authentication.html
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44
https://api.lyra.com/api-payment/V4/Charge/CreatePayment
{
  "amount":12000,
  "currency":"EUR",
  "orderId":"myOrderId-1234",
  "transactionOptions":{
     "installmentOptions":[
        {
           "schedules":[
              {
                 "date":"2025-04-01T00:00:00+00:00",
                 "amount":5000
              },
              {
                 "date":"2025-05-01T00:00:00+00:00",
                 "amount":3000
              },
              {
                 "date":"2025-06-01T00:00:00+00:00",
                 "amount":2000
              },
              {
                "date": "2025-07-01T00:00:00+00:00",
                "amount": 2000
             }
           ]
        }
     ]
  }
}

La description et l'intégralité de tous les champs sont disponibles (menu à gauche) : Charge/CreatePayment.

Vous pouvez proposer à l'acheteur plusieurs choix. Par exemple, combinez le paiement en 2 et 3 fois (voir ci-dessous).

Paiement en 2 et 3 fois

Champs obligatoires :

  • Montant : 100,00 EUR.

  • Pour le paiement en 2 fois :

  1. le 1er Avril pour un montant de 50,00 EUR .
  2. le 1er Mai pour un montant de 50,00 EUR .
  • Pour le paiement en 3 fois :
  1. le 1er Avril pour un montant de 50,00 EUR .
  2. le 1er Mai pour un montant de 30,00 EUR .
  3. le 1er Juin pour un montant de 20,00 EUR .

Champs recommandés :

  • Référence de la commande : "myOrderId-1234".
/fr-FR/rest/V4.0/api/kb/authentication.html
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44
https://api.lyra.com/api-payment/V4/Charge/CreatePayment
    {
      "amount":10000,
      "currency":"EUR",
      "orderId":"myOrderId-1234",
      "transactionOptions": {
         "installmentOptions": [
         {
            "schedules": [
                {
                    "date": "2025-04-01T00:00:00+00:00",
                    "amount": 5000
                },
                {
                    "date": "2025-05-01T00:00:00+00:00",
                    "amount": 5000
                }
            ]
        },
             {
                 "schedules": [
                     {
                         "date": "2025-04-01T00:00:00+00:00",
                         "amount": 5000
                     },
                     {
                         "date": "2025-05-01T00:00:00+00:00",
                         "amount": 2500
                     },
                     {
                         "date": "2025-06-01T00:00:00+00:00",
                         "amount": 2500
                     }
                 ]
             }
         ]
     }
   }

La somme totale des montants doit être égale à la valeur du champ amount.
La date de la dernière échéance ne peut être supérieure à 12 mois.
Si la date de la dernière échéance est supérieure à la date de validité de la carte, aucune échéance ne sera enregistrée et l'acheteur sera notifié par un message de ce problème.

3. Personnaliser

Masquer le paiement comptant

Par défaut, le paiement comptant est toujours proposé quand vous créez un paiement en plusieurs fois.

Pour masquer le paiement comptant, utilisez cette fonction KR.setFormConfig.

Exemple d'intégration :

await KR.setFormConfig({
  smartForm: {
    splitPayment: {
      showPayNowOption: false // to hide, by default: true
    }
  }
});

Valorisez le champ splitPayment.showPayNowOption :

  • false pour masquer le paiement comptant.
  • true pour afficher le paiement comptant, valeur par défaut.

Réponse

Exemple de réponse 
{
    "webService": "Charge/CreatePayment",    
    "version": "V4",
    "applicationVersion": "5.5.0",
    "status": "SUCCESS",
    "answer": {
        {
            "shopId": "12345678",
            "cardOrderCycle": "CLOSED",
            "orderCycle": "CLOSED",
            "orderStatus": "PAID",
            "serverDate": "[DATE ISO-8601]",
            "orderDetails": {
              "orderTotalAmount": 10000,
              "orderEffectiveAmount": 10000,
              "orderPaidAmount": 10000,
              "orderCurrency": "EUR",
              "mode": "TEST",
              "orderId": "myOrderId-1234",
              "metadata": null,
              "updatedDna": null,
              "_type": "V4/OrderDetails"
            },
            "customer": {
              "billingDetails": {
                "address": null,
                "category": null,
                "cellPhoneNumber": null,
                "city": "Lisboa",
                "country": null,
                "district": null,
                "firstName": "John",
                "identityCode": null,
                "identityType": null,
                "language": "FR",
                "lastName": "Doe",
                "phoneNumber": "+351 210312700",
                "state": null,
                "streetNumber": null,
                "title": null,
                "zipCode": "1000-001",
                "legalName": null,
                "_type": "V4/Customer/BillingDetails"
              },
              "email": "main@example.com",
              "reference": null,
              "shippingDetails": {
                "address": null,
                "address2": null,
                "category": null,
                "city": null,
                "country": null,
                "deliveryCompanyName": null,
                "district": null,
                "firstName": null,
                "identityCode": null,
                "lastName": null,
                "legalName": null,
                "phoneNumber": null,
                "shippingMethod": null,
                "shippingSpeed": null,
                "state": null,
                "streetNumber": null,
                "zipCode": null,
                "_type": "V4/Customer/ShippingDetails"
              },
              "extraDetails": {
                "browserAccept": null,
                "fingerPrintId": null,
                "ipAddress": "[IP ADRESS]",
                "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
                "_type": "V4/Customer/ExtraDetails"
              },
              "shoppingCart": {
                "insuranceAmount": null,
                "shippingAmount": null,
                "taxAmount": null,
                "cartItemInfo": null,
                "_type": "V4/Customer/ShoppingCart"
              },
              "_type": "V4/Customer/Customer"
            },
            "transactions": [
              {
                "shopId": "12345678",
                "uuid": "5762bfc8cf1e412ea8e76ad343ec5232",
                "amount": 10000,
                "currency": "EUR",
                "paymentMethodType": "CARD",
                "paymentMethodToken": null,
                "status": "PAID",
                "detailedStatus": "AUTHORISED",
                "operationType": "DEBIT",
                "effectiveStrongAuthentication": "ENABLED",
                "creationDate": "[DATE ISO-8601]",
                "errorCode": null,
                "errorMessage": null,
                "detailedErrorCode": null,
                "detailedErrorMessage": null,
                "metadata": {
                  "orderInfo": "test",
                  "orderInfo2": "test2"
                },
                "transactionDetails": {
                  "liabilityShift": "YES",
                  "effectiveAmount": 5000,
                  "effectiveCurrency": "EUR",
                  "creationContext": "CHARGE",
                  "cardDetails": {
                    "paymentSource": "EC",
                    "manualValidation": "NO",
                    "expectedCaptureDate": "[DATE ISO-8601]",
                    "effectiveBrand": "VISA",
                    "pan": "497011XXXXXX1003",
                    "expiryMonth": 12,
                    "expiryYear": 2025,
                    "country": "FR",
                    "issuerCode": 17807,
                    "issuerName": "BP Occitane",
                    "effectiveProductCode": null,
                    "legacyTransId": "942629",
                    "legacyTransDate": "[DATE ISO-8601]",
                    "paymentMethodSource": "NEW",
                    "authorizationResponse": {
                      "amount": 5000,
                      "currency": "EUR",
                      "authorizationDate": "[DATE ISO-8601]"",
                      "authorizationNumber": "3fc386",
                      "authorizationResult": "0",
                      "authorizationMode": "FULL",
                      "_type": "V4/PaymentMethod/Details/Cards/CardAuthorizationResponse"
                    },
                    "captureResponse": {
                      "refundAmount": null,
                      "refundCurrency": null,
                      "captureDate": null,
                      "captureFileNumber": null,
                      "effectiveRefundAmount": null,
                      "effectiveRefundCurrency": null,
                      "_type": "V4/PaymentMethod/Details/Cards/CardCaptureResponse"
                    },
                    "threeDSResponse": {
                      "authenticationResultData": {
                        "transactionCondition": null,
                        "enrolled": null,
                        "status": null,
                        "eci": null,
                        "xid": null,
                        "cavvAlgorithm": null,
                        "cavv": null,
                        "signValid": null,
                        "brand": null,
                        "_type": "V4/PaymentMethod/Details/Cards/CardAuthenticationResponse"
                      },
                      "_type": "V4/PaymentMethod/Details/Cards/ThreeDSResponse"
                    },
                    "authenticationResponse": {
                      "id": "3aa32136-42d9-49ea-a91b-8dc455a974d6",
                      "operationSessionId": "43b3143dfbf7466cba5b6ec3a17f56fd",
                      "protocol": {
                        "name": "THREEDS",
                        "version": "2.1.0",
                        "network": "VISA",
                        "challengePreference": "CHALLENGE_MANDATED",
                        "simulation": true,
                        "_type": "V4/Charge/Authenticate/Protocol"
                      },
                      "value": {
                        "authenticationType": "CHALLENGE",
                        "authenticationId": {
                          "authenticationIdType": "dsTransId",
                          "value": "aeb8ba19-3a19-4c69-a9f8-9c6d7cb317fb",
                          "_type": "V4/Charge/Authenticate/AuthenticationId"
                        },
                        "authenticationValue": {
                          "authenticationValueType": "CAVV",
                          "value": "q**************************=",
                          "_type": "V4/Charge/Authenticate/AuthenticationValue"
                        },
                        "status": "SUCCESS",
                        "commerceIndicator": "05",
                        "extension": {
                          "authenticationType": "THREEDS_V2",
                          "threeDSServerTransID": "3aa32136-42d9-49ea-a91b-8dc455a974d6",
                          "dsTransID": "aeb8ba19-3a19-4c69-a9f8-9c6d7cb317fb",
                          "acsTransID": "c6dee769-ccdf-4f79-a8b5-5f24aee5841c",
                          "requestorName": "So easy to test",
                          "_type": "V4/Charge/Authenticate/AuthenticationResultExtensionThreedsV2"
                        },
                        "reason": {
                          "_type": "V4/Charge/Authenticate/AuthenticationResultReason"
                        },
                        "_type": "V4/Charge/Authenticate/AuthenticationResult"
                      },
                      "_type": "V4/AuthenticationResponseData"
                    },
                    "installmentNumber": null,
                    "installmentCode": null,
                    "markAuthorizationResponse": {
                      "amount": null,
                      "currency": null,
                      "authorizationDate": null,
                      "authorizationNumber": null,
                      "authorizationResult": null,
                      "_type": "V4/PaymentMethod/Details/Cards/MarkAuthorizationResponse"
                    },
                    "cardHolderName": null,
                    "cardHolderPan": "497011XXXXXX1003",
                    "cardHolderExpiryMonth": 12,
                    "cardHolderExpiryYear": 2025,
                    "identityDocumentNumber": null,
                    "identityDocumentType": null,
                    "initialIssuerTransactionIdentifier": "6790783855558831",
                    "productCategory": "DEBIT",
                    "nature": "CONSUMER_CARD",
                    "sequenceType": "MULTI_PAYMENT",
                    "_type": "V4/PaymentMethod/Details/CardDetails"
                  },
                  "paymentMethodDetails": {
                    "id": "497011XXXXXX1003",
                    "paymentSource": "EC",
                    "manualValidation": "NO",
                    "expectedCaptureDate": "[DATE ISO-8601]",
                    "effectiveBrand": "VISA",
                    "expiryMonth": 12,
                    "expiryYear": 2025,
                    "country": "FR",
                    "issuerCode": 17807,
                    "issuerName": "BP Occitane",
                    "effectiveProductCode": null,
                    "legacyTransId": "942629",
                    "legacyTransDate": "[DATE ISO-8601]",
                    "paymentMethodSource": "NEW",
                    "authorizationResponse": {
                      "amount": 5000,
                      "currency": "EUR",
                      "authorizationDate": "[DATE ISO-8601]",
                      "authorizationNumber": "3fc386",
                      "authorizationResult": "0",
                      "authorizationMode": "FULL",
                      "_type": "V4/PaymentMethod/Details/Cards/CardAuthorizationResponse"
                    },
                    "captureResponse": {
                      "refundAmount": null,
                      "refundCurrency": null,
                      "captureDate": null,
                      "captureFileNumber": null,
                      "effectiveRefundAmount": null,
                      "effectiveRefundCurrency": null,
                      "_type": "V4/PaymentMethod/Details/Cards/CardCaptureResponse"
                    },
                    "authenticationResponse": {
                     (...)
                  "subscriptionDetails": {
                    "subscriptionId": null,
                    "_type": "V4/PaymentMethod/Details/SubscriptionDetails"
                  },
                  "parentTransactionUuid": null,
                  "mid": "1549425",
                  "sequenceNumber": 1,
                  "taxAmount": null,
                  "preTaxAmount": null,
                  "taxRate": null,
                  "externalTransactionId": null,
                  "nsu": null,
                  "tid": "001",
                  "acquirerNetwork": "CB",
                  "taxRefundAmount": null,
                  "userInfo": "JS Client",
                  "paymentMethodTokenPreviouslyRegistered": null,
                  "occurrenceType": "UNITAIRE",
                  "archivalReferenceId": "L01494262901",
                  "useCase": null,
                  "wallet": null,
                  "_type": "V4/TransactionDetails"
                },
                "_type": "V4/PaymentTransaction"
              }
            ],
            "subMerchantDetails": null,
            "_type": "V4/Payment"
          }

}

Retrouvez la description et l'intégralité des champs dans notre playground : Payment

Gestion des erreurs

Tableau des erreurs
Code Description
CLIENT_515 Le nombre maximum de versements autorisé est de 4.
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_928 Le format du champ installmentOptions.firstAmount est invalide ou le champ n'est pas transmis.
INT_929 Le paramètre installmentOptions.count est invalide.
INT_930 Le paramètre installmentOptions.period est invalide.
INT_931 Le paramètre installmentOptions.schedules[] est invalide.
INT_932 Le paramètre installmentOptions.schedules[date] est invalide.
INT_933 Le format du champ installmentOptions.schedules[amount] est invalide ou le champ n'est pas transmis.
INT_945 Problème de combinaison entre les champs d'un écheancier simple et avancé.
PSP_519 Devise inconnue.
PSP_606 Devise non supportée par le contrat.
PSP_610 Aucun des contrats associés à votre boutique ne peut être utilisé. Ex : la date de la dernière échéance est supérieure à 12 mois, lors de la création d'un échéancier avancé.
PSP_1007 La date d'expiration de l'ordre de paiement ne peut etre antérieure à la date courante ni excédée 90 jours.

Analyse du résultat du paiement

Pour la première échéance

Pour connaître le résultat du paiement, implémentez l’URL de notification à la fin du paiement (également appelée IPN).

L'utilisation du champ ipnTargetUrl est déconseillée.

  1. Renseignez uniquement l'URL de notification dans la section API REST (TEST ou PRODUCTION) : Procédure.
  2. Analysez l'IPN : Procédure.
Pour les autres échéances
  1. Configurez la notification sur autorisation par batch.

Voir : Notification sur autorisation par batch.

Cette notification est indispensable pour obtenir le résultat d’un paiement différé :

  • En cas de paiement accepté.
  • En cas de paiement refusé.
  1. Analysez cette notification comme l'IPN : Procédure.

Plus spécifiquement, vérifiez :

  • le statut de la transaction avec le champ orderStatus.

    La valeur PAID signifie que la transaction a été acceptée (voir : Cycle de vie d'une transaction),

  • le champ sequenceType valorisé à MULTI_PAYMENT pour du paiement en plusieurs fois,
  • le champ occurrenceType pour identifier si la transaction fait partie d'une série de paiements (abonnement ou paiement en N fois).

Transmettre le numéro de commande

Pour transmettre le numéro de commande, utilisez le champ orderId :

{
    "orderId" : "CX-1254"
}

Transmettre les données de l'acheteur

Le marchand peut transmettre l'adresse de facturation et les coordonnées de l'acheteur (adresse e-mail, civilité, numéro de téléphone etc.).

Ces données seront:

  • visibles dans le Back Office Expert, dans le détail de la transaction (onglet Acheteur),
  • retournées dans l'IPN, sans modification.

Pour cela, utilisez le champ customer:

Exemple

{
    "customer": {
        "reference":"C2383333540",
        "email" : " <sample@example.net>",
        "billingDetails" : {
            "category" : "PRIVATE",
            "title" : "M",
            "firstName" : "Laurent",
            "lastName" : "DURANT",
            "streetNumber" : "109",
            "address" : "rue de l'innovation",
            "zipCode" : "31670",
            "city" : "LABEGE",
            "country" : "FR",
            "phoneNumber" : "0123456789",
            "cellPhoneNumber" :"0623456789"
        }
    }
}

Transmettre les données de livraison

Le marchand peut transmettre les données de livraison de l'acheteur (adresse, civilité, numéro de téléphone etc.).

Ces données seront:

  • visibles dans le Back Office Expert, dans le détail de la transaction (onglet Livraison),
  • retournées dans l'IPN, sans modification.

Exemple pour une livraison de type "Retrait en magasin"

L'adresse de livraison est celle du magasin.

L'adresse de facturation est différente de l'adresse de livraison.

Le nom du destinataire de la livraison est celui de l'adresse de facturation.

{
    "customer": {
        "shippingDetails": {
            "shippingMethod": "RECLAIM_IN_SHOP",
            "shippingSpeed": "STANDARD",
            "streetNumber": "230",
            "address": "avenue des Champs Elysées",
            "zipCode": "59170",
            "city": "CROIX",
            "country": "FR",
            "firstName": "Marie-Charlotte",
            "lastName": "GRIMALDI",
            "phoneNumber": "0328386789"
        }
    }
}

Exemple pour une livraison de type "point relais"

L'adresse de livraison est celle du point relais.

Le nom du point relais est transmis dans la deuxième ligne d'adresse de livraison.

L'adresse du point relais est transmise dans la première ligne d'adresse de livraison.

Le nom du destinataire est celui de l'adresse de facturation.

L'adresse de facturation est différente de l'adresse de livraison.

{
    "customer": {
        "shippingDetails": {
            "shippingMethod": "RELAY_POINT",
            "shippingSpeed": "STANDARD",
            "streetNumber": "100",
            "address": "avenue du parc Barbieux",
            "zipCode": "59170",
            "city": "CROIX",
            "country": "FR",
            "firstName": "Martine",
            "lastName": "DURAND",
            "phoneNumber": "0328386789",
      "deliveryCompanyName":"Chronospost"
        }
    }
}

Transmettre le contenu du panier

Lors de la création d'un paiement, le marchand peut transmettre le contenu du panier de l'acheteur.

Ces données seront visibles dans le Back Office Expert, dans le détail de la transaction (onglet Panier).

Pour celà, utilisez le champ cartItemInfo (tableau d'objets json) lors de l'appel au Web Service Charge/CreatePayment.

Exemple pour définir 2 articles dans le panier

{
"customer": {

     "shoppingCart": {
       "cartItemInfo": [
       {
        "productRef": "myRef1",
        "productAmount": "1200",
        "productLabel": "myLabel1",
        "productQty" : "1"
       },
       {
        "productRef": "myRef2",
        "productAmount": "2400",
        "productLabel": "myLabel2",
        "productQty" : "1"
       }
       ]
     }
    }

}

Remarques:

  • Le champ cartItemInfo est toujours retourné à vide dans la réponse.
  • Pour que l'onglet Panier s'affiche correctement dans le Back Office Expert, vous devez transmettre au minimum le champ productAmount de chaque produit.

Transmettre les données du sous-marchand

Le facilitateur de paiement peut transmettre les données du sous-marchand concerné par la transaction.

Ces données seront :

  • visibles dans le Back Office Expert, dans le détail de la transaction (onglet Sous-marchand),
  • retournées dans l’IPN, sans modification.

Le tableau décrit les champs communs disponibles avec les informations sur le sous-marchand.

Nom du champ Format Description
subMerchantDetails.address1 ans..255 Adresse du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.address2 ans..255 Complément de l'adresse du sous-marchand.Transmis par le facilitateur de paiement.
subMerchantDetails.city an..128 Ville du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.companyType ans..60 Type de société du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.country a2 Code pays de l'adresse du sous-marchand (norme ISO 3166 alpha-2). Transmis par le facilitateur de paiement.
subMerchantDetails.facilitatorId ans..128 Identifiant du facilitateur de paiement. Transmis par le facilitateur de paiement.
subMerchantDetails.legalNumber ans..24 Numéro légal du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.mcc n4 Code MCC du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.mid n..64 Numéro de contrat (MID) du sous-marchand.Transmis par le facilitateur de paiement.
subMerchantDetails.name ans..255 Raison sociale du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.phoneNumber an..32 Numéro de téléphone du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.softDescriptor ans..255 Libellé (soft descriptor) du sous-marchand qui apparaît sur le relevé d'opérations bancaires de l'acheteur.Transmis par le facilitateur de paiement.
subMerchantDetails.state ans..128 Région de l'adresse du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.url ans..128 URL du sous-marchand. Transmis par le facilitateur de paiement.
subMerchantDetails.zip an..64 Code postal du sous-marchand. Transmis par le facilitateur de paiement.

Proposer l'enregistrement du moyen de paiement

Seules les cartes de paiement sont supportées. Cette méthode ne permet pas de créer un alias à partir d'un IBAN.

Le marchand peut proposer à l'acheteur de faciliter ses achats en demandant l'enregistrement des données bancaires par la plateforme de paiement.

Grâce à cette opération, la plateforme de paiement attribue un jeton unique au moyen de paiement et le retourne au site marchand via le champ paymentMethodToken.

Ainsi lors de futurs achats, l'acheteur n'aura plus à saisir son moyen de paiement.

Cette solution apporte un niveau supplémentaire de sécurité aux paiements puisque seul transite le token utilisable uniquement par la plateforme de paiement.

Pour proposer à l'acheteur d'enregistrer son moyen de paiement au moment du paiement, utilisez le champ formAction avec la valeur ASK_REGISTER_PAY

{
    "formAction" : "ASK_REGISTER_PAY",
    "customer": {
        "email": " <sample@example.net>"
    }
}

Remarque

Le champ email devient obligatoire lors de l'enregistrement du moyen de paiement.

Lors de l'affichage du formulaire, une case à cocher apparaitra.

Par défaut, cette case est décochée.

Si l'acheteur accepte l'enregistrement de son moyen de paiement, il doit cocher la case.

Si le paiement est refusé, le moyen de paiement ne sera pas enregistré.

Forcer l'enregistrement du moyen de paiement

Seules les cartes de paiement sont supportées. Cette méthode ne permet pas de créer un alias à partir d'un IBAN.

Si le marchand a avertit l'acheteur plus tôt dans le process d'achat, il peut "forcer" l'enregistrement du moyen de paiement sans afficher de case supplémentaire.

Pour celà, utilisez le champ formAction avec la valeur REGISTER_PAY:

{
    "formAction" : "REGISTER_PAY",
    "customer": {
  "email": " <sample@example.net>"
    }
}

Utiliser un moyen de paiement enregistré

Seules les cartes de paiement sont supportées. Cette méthode ne permet pas d'utiliser un alias créé à partir d'un IBAN.

Le marchand peut transmettre le token à débiter lors de l'initialisation du paiement.

Lors de l'affichage du formulaire, les champs kr-pan et kr-expiry seront automatiquement renseignés.

L'acheteur n'aura plus qu'à saisir son code de sécurité (CVV) pour finaliser son achat.

Pour celà, il suffit de transmettre le token à débiter dans le champ paymentMethodToken et de valoriser le champ formAction à PAYMENT.

Cette valeur étant la valeur par défaut, le champ formAction n'est plus nécessaire.

{
    "formAction" : "PAYMENT",
    "paymentMethodToken":"d3d9cc0d24a4400e9d123e9e1b8f1793",
}

Utiliser un moyen de paiement enregistré sans afficher le formulaire embarqué

Seules les cartes de paiement sont supportées. Cette méthode ne permet pas d'utiliser un alias créé à partir d'un IBAN.

Ce mode permet de créer une transaction sans affichage du formulaire de paiement et sans authentification (appel de serveur à serveur).

{
    "formAction" : "SILENT",
    "paymentMethodToken":"d3d9cc0d24a4400e9d123e9e1b8f1793",
}

Sans authentification, le marchand n'est pas protégé contre les risques de fraude et plus spécifiquement en cas de contestation du porteur de carte.

Remarque

  • Ce cas d'utilisation n'utilise pas le client JavaScript, mais uniquement un appel serveur à serveur. Il n'y a pas de redirection vers l'url de retour spécifiée dans kr-post-url-success.
  • La réponse ne contient pas de formToken mais directement un objet Transaction.
  • Voir : Paiement 0 clic

Transmettre la préférence 3-D Secure

Utilisez le champ strongAuthentication (lien vers le playground : strongAuthentication).

Ce champ indique la préférence du marchand au sujet de l'authentification de l'acheteur.

  • Sans interaction du porteur (frictionless).
  • Avec interaction du porteur (authentification forte ou challenge).
  • Pas de préférence du marchand.

Dans tous les cas, la banque émettrice décide seule du mode d'authentification de l'acheteur.

Cas d'utilisation Valeurs possibles
Avec interaction du porteur : Challenge
  • ENABLED : Cette valeur est dépréciée.
  • CHALLENGE_REQUESTED : Cette valeur permet de demander une authentification forte pour la transaction.
  • CHALLENGE_MANDATE : Cette valeur permet de demander une authentification forte pour la transaction pour des raisons règlementaires.
Sans interaction du porteur : Frictionless
  • DISABLED : Cette valeur permet de demander une exemption à l'authentification forte.

    Avec l'option Frictionless 3DS2 :

    • Transactions à faible montant
    • Safe'R by CB

    Si la demande de Frictionless est acceptée, la transaction ne bénéficie pas du transfert de responsabilité en cas de contestation du porteur.

    Sans l'option Frictionless 3DS2, le choix de la préférence est délégué à l'émetteur de la carte (No Preference).


  • DATA_SHARE_ONLY : Réservée au Brésil et à l'amérique Latine. Cette valeur permet de demander une transaction sans interaction du porteur (ni authentification) mais pour laquelle le marchand souhaite partager les données via le processus 3DS avec l'émetteur pour réduire le risque de refus lors de l'autorisation.
Pas de préférence du marchand
  • NO_PREFERENCE : Permet d'indiquer au DS que le marchand n'a pas de préférence. Si l'émetteur décide de réaliser une authentification sans interaction (frictionless), le paiement sera garanti.
  • AUTO: Le choix de la préférence est délégué à l'émetteur de la carte (No Preference).

Tableau des exemptions pour le Frictionless (valeur DISABLED)

Exemption Description
Transactions à faible montant Pour les paiements en euro, vous pouvez demander une exemption à l'authentification forte :
  • Si le montant est inférieur à 30 EUR, et dans la limite soit de 5 opérations successives ou d’un montant cumulé inférieur à 100 EUR.
  • Si le montant est supérieur à 30 EUR, la valeur transmise par le marchand est ignorée et le choix de la préférence est délégué à l'émetteur de la carte ( No Preference ).
Pour les paiements réalisés dans une devise différente de l'euro, une demande de frictionless est transmise à l'émetteur. Si la demande de frictionless est acceptée, la transaction ne bénéficie pas du transfert de responsabilité en cas de contestation du porteur.
Safe'R by CB

    Le programme Safe'R by CB a pour objectif de répondre aux attentes des marchands à très faible risque et à la volumétrie importante (120.000 transactions CB / an).

    Vous pouvez demander une exemption à l'authentification forte :

    • Si le montant est inférieur à 100 EUR, l'exemption est systématique pour les marchands éligibles.
    • Si le montant est compris entre 100 EUR et 250 EUR, une expérimentation est en cours. Le marchand doit remplir ces conditions :
      • Avoir un contrat CB.
      • Être éligible à la TRA acquéreur.
      • Transmettre les valeurs requises dans le flux 3-D Secure, selon les règles définies par la plateforme.
    Si la demande de frictionless est acceptée, la transaction ne bénéficie pas du transfert de responsabilité en cas de contestation du porteur.

    Pour bénéficier du programme Safe'R by CB, vous devez contacter l'administration des ventes pour obtenir un accord explicite.

Augmenter les chances de frictionless en 3DS2

Transmettez ces données pour augmenter les chances de frictionless lors du paiement.

L'utilisation de ces champs est optionnelle. Dans tous les cas, c'est la banque émettrice qui décide si une authentification forte doit être réalisée.

Liste des champs à transmettre

Paramètre Description
customer.email Adresse e-mail de l’acheteur
customer.billingDetails.identityCode Identifiant national. Permet d’identifier de façon unique chaque citoyen au sein d’un pays. CPF ou CNPJ au Brésil
customer.billingDetails.streetNumber Numéro de rue de l’adresse de facturation
customer.billingDetails.address Adresse postale
customer.billingDetails.address2 Deuxième ligne d'adresse
customer.billingDetails.zipCode Code postal
customer.billingDetails.city Ville
customer.billingDetails.state Etat / Région
customer.billingDetails.country Code pays suivant la norme ISO 3166 alpha-2
customer.billingDetails.phoneNumber Numéro de téléphone
customer.billingDetails.cellPhoneNumber Numéro de téléphone mobile
customer.shippingDetails.address Adresse postale
customer.shippingDetails.address2 Deuxième ligne d’adresse
customer.shippingDetails.zipCode Code postal
customer.shippingDetails.city Ville
customer.shippingDetails.state Etat / Région
customer.shippingDetails.country Code pays suivant la norme ISO 3166
customer.shippingDetails.shippingMethod Mode de livraison.
customer.shippingDetails.shippingSpeed Délai de livraison.

Transmettre des données personnalisées

Lors de la création d'un paiement, le marchand peut transmettre des informations spécifiques à la plateforme de paiement pour répondre à des besoins métier.

Par exemple, transmettre un numéro de dossier, un numéro de contrat etc...

Ces informations seront :

  • visibles dans le Back Office Expert, dans le détail de la transaction (onglet Extras),
  • visibles dans l'e-mail de confirmation de paiement à destination du marchand,
  • retournées dans l'URL de notification, sans modification.

Pour celà, utilisez les champs metadata (au format json) lors de l'appel au Web Service Charge/CreatePayment:

Exemple pour transmettre une donnée nommée "contract" et sa valeur:

{
"metadata": {
"contract": "1245KL-78/ZE"
}
}

Surcharger l'URL de notification instantanée (déconseillé)

Vous pouvez surcharger l’URL de notification instantanée (également appelée IPN) dans le formulaire dans le cas où vous utilisez une seule boutique pour différents canaux de ventes, différentes typologies de paiement, différentes langues etc…

Cette fonctionnalité est incompatible avec l'exécution, depuis le Back Office Expert, de la requête envoyée à l’URL de notification instantanée.

L’URL appelée sera celle configurée dans la règle de notification (voir chapitre Paramétrer les notifications).

Utilisez le champ ipnTargetUrl lors de l'initialisation du paiement pour surcharger l’URL de la page à notifier.

Si la valeur du champ ipnTargetUrl est erronée, le formulaire ne sera pas rejeté.

{
    "ipnTargetUrl" : "<https://my.site/my-ipn>",
}
Nous recrutons
Mentions légales
Charte de Protection des Données Personnelles
25.18-1.11