Payer 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é.
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.
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
}
]
}
}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).
- le 1 er Avril pour un montant de 50,00 EUR .
- 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)
- le 1er Avril pour un montant de 50,00 EUR .
- le 1er Mai pour un montant de 30,00 EUR .
- 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)
- le 1er Avril pour un montant de 50,00 EUR .
- le 1er Mai pour un montant de 30,00 EUR .
- le 1er Juin pour un montant de 20,00 EUR .
- 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.
Paiement en 2 et 3 fois
Champs obligatoires :
Montant : 100,00 EUR.
Pour le paiement en 2 fois :
- le 1er Avril pour un montant de 50,00 EUR .
- le 1er Mai pour un montant de 50,00 EUR .
- Pour le paiement en 3 fois :
- le 1er Avril pour un montant de 50,00 EUR .
- le 1er Mai pour un montant de 30,00 EUR .
- 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
}
]
}
]
}
}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 :
falsepour masquer le paiement comptant.truepour 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.
Pour les autres échéances
- 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é.
- 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
sequenceTypevalorisé àMULTI_PAYMENTpour du paiement en plusieurs fois, - le champ
occurrenceTypepour identifier si la transaction fait partie d'une série de paiements (abonnement ou paiement en N fois).