Données de paiement sauvegardées et types de transactions

Cette section décrit les types de transactions supportés pour les données de paiement sauvegardées.

Types de données de paiement sauvegardées

La passerelle de paiement permet de créer et d'utiliser trois types de données de paiement sauvegardées :

• Normale – pour les paiements non liés à aucun plan ou calendrier. Par exemple, lorsque l'acheteur fait une nouvelle commande et la paie en utilisant des données de carte précédemment sauvegardées.

• Récurrente – pour les paiements effectués selon un calendrier fixe. Par exemple, les paiements mensuels pour les services publics.

• Échelonnement – lors du paiement échelonné, lorsque le client paie la facture par petites parties sur une période fixe selon un plan de paiements.

Une seule carte peut avoir des données de paiement sauvegardées de différents types. De plus, la carte peut avoir plusieurs données de paiement sauvegardées pour différents échelonnements.

Type de transactions

Les transactions avec données de paiement sauvegardées appartiennent à l'un des deux groupes selon l'initiateur de la transaction :

• CIT (cardholder-initiated transactions) – transactions de commerce électronique dans lesquelles le porteur de la carte participe au paiement. Ce groupe comprend 4 types de transactions :
  • C/CI – transaction initiatrice avec sauvegarde de données de paiement sauvegardées normales pour les paiements futurs.
  • RI – transaction initiatrice avec sauvegarde de données de paiement sauvegardées pour les paiements récurrents.
  • II – transaction initiatrice avec sauvegarde de données de paiement sauvegardées pour les paiements échelonnés.
  • F – transaction non planifiée effectuée par le porteur de la carte en utilisant des données de paiement sauvegardées normales.

• MIT (Merchant-initiated Transactions) – transactions de commerce électronique effectuées par le vendeur sans participation du porteur de la carte. Ce groupe comprend 3 types de transactions :

  • U – transaction non planifiée utilisant des données de paiement sauvegardées normales. Par exemple, imputation de pénalités. Notez que pour une telle opération il n'y a pas de vérification CVC ou 3DS, car le propriétaire de la carte n'y participe pas et ne peut saisir aucune donnée.
  • R – transaction récurrente ultérieure utilisant des données de paiement sauvegardées récurrentes.
  • I – transaction ultérieure échelonnée utilisant des données de paiement sauvegardées pour l'échelonnement.

Le type de transaction doit être transmis dans le paramètre tii (Transaction Intitiator Indicator, Identifiant de l'initiateur de transaction) des requêtes API de paiement. Valeurs possibles du paramètre tii :

Gestion des données de paiement sauvegardées via API

Ci-dessous sont présentés des exemples de création et d'utilisation de différents types de données de paiement sauvegardées via API en utilisant la page de paiement propre du marchand :

• Données de paiement sauvegardées ordinaires
• Données de paiement sauvegardées récurrentes
• Données de paiement sauvegardées pour paiement échelonné

Données de paiement sauvegardées ordinaires

Création de données de paiement sauvegardées ordinaires

Pour créer des données de paiement sauvegardées ordinaires, exécutez les étapes suivantes :

1. Exécutez la demande register.do avec le paramètre clientId, obtenez en réponse orderId et formUrl.

   Exemple de demande register.do pour créer des données de paiement sauvegardées ordinaires :

   curl --request POST \
     --url https://dev.bpcbt.com/payment/rest/register.do \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data amount=123456 \
     --data userName=test_user \
     --data password=test_user_password \
     --data orderNumber=1234567890ABCDEF \
     --data returnUrl=https://mybestmerchantreturnurl.com \
     --data failUrl=https://mybestmerchantfailurl.com \
     --data email=test@test.com \
     --data clientId=259753456 \
     --data features=FORCE_CREATE_BINDING \
     --data language=en

   {
     "orderId": "01491d0b-c848-7dd6-a20d-e96900a7d8c0",
     "formUrl": "https://dev.bpcbt.com/payment/payment/merchants/ecom/payment_en.html?mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0"
   }

2. Transmettez la valeur orderId obtenue dans le paramètre MDORDER de la demande paymentorder.do.

   Exemple de demande paymentorder.do :

   curl --request POST \
     --url https://dev.bpcbt.com/payment/rest/paymentorder.do \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data '$CVC=123' \
     --data '$EXPIRY=203012' \
     --data '$PAN=4000001111111118' \
     --data 'TEXT=TEST CARDHOLDER' \
     --data MDORDER=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
     --data userName=test_user \
     --data password=test_user_password

   {
     "redirect": "https://dev.bpcbt.com/payment/merchants/pay/finish.html?orderId=59e00106-1f69-76a7-b893-b27c00b4f820&lang=en",
     "info": "Your order is proceeded, redirecting...",
     "errorCode": 0
   }

En résultat, des données de paiement sauvegardées seront créées pour le client avec le clientId initialement spécifié. En résultat, la commande sera payée à l'aide de données de paiement sauvegardées avec le bindingId spécifié.

Paiement par données de paiement sauvegardées ordinaires

Pour payer une commande avec des données de paiement sauvegardées ordinaires créées (voir le processus de création ci-dessus), exécutez les étapes suivantes :

1. Enregistrez une nouvelle commande à l'aide de la demande register.do avec le même paramètre clientId, obtenez en réponse orderId.

2. Obtenez la liste des liaisons de données de paiement sauvegardées à l'aide de la requête getBindings.do avec la même valeur clientId et avec bindingType=C → obtenez en réponse bindingId.

   Exemple de requête getBindings.do:

   curl --request POST \
   --url https://dev.bpcbt.com/payment/rest/getBindings.do \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data userName=test_user \
   --data password=test_user_password \
   --data clientId=259753456 \
   --data bindingType=C

   {
       "errorCode":"0",
       "errorMessage":"Success",
       "bindings": [
           {
                   "bindingId": "b83317e0-1679-7d85-b375-a63200b4f820",
                   "maskedPan": "411111**1111",
                   "expiryDate": "203412",
                   "paymentWay": "TOKEN_PAY",
                   "paymentSystem": "CARD",
                   "displayLabel": "XXXXXXXXXXXX1111",
                   "bindingCategory": "COMMON"
               }
           ]
        }

3. Exécutez la requête paymentOrderBinding.do. Transmettez la valeur orderId (obtenue à l'Étape 1) dans le paramètre mdOrder, ainsi que transmettez le bindingId obtenu. Valeurs disponibles tii: F, U.

   Exemple de requête paymentOrderBinding.do:

   curl --request POST \
     --url https://dev.bpcbt.com/payment/rest/paymentOrderBinding.do \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
     --data ip=127.0.0.1 \
     --data cvc=123 \
     --data bindingId=b83317e0-1679-7d85-b375-a63200b4f820 \
     --data userName=test_user \
     --data password=test_user_password \
     --data language=en \
     --data tii=F

   {
     "redirect": "https://dev.bpcbt.com/payment/merchants/pay/finish.html?orderId=24c3d392-4c60-7f0b-9ff5-b00100b4f820&lang=en",
     "info": "Your order is proceeded, redirecting...",
     "errorCode": 0
   }

En résultat, la commande sera payée à l'aide de la liaison de données de paiement sauvegardées avec le bindingId spécifié.

Liaisons de données de paiement sauvegardées récurrentes

Création d'une liaison de données de paiement sauvegardées récurrente

Pour créer une liaison de données de paiement sauvegardées récurrente, exécutez les étapes suivantes:

1. Exécutez la requête register.do avec le paramètre clientId, obtenez en réponse orderId et formUrl

   Exemple de requête register.do:

   curl --request POST \
     --url https://dev.bpcbt.com/payment/rest/register.do \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data amount=123456 \
     --data userName=test_user \
     --data password=test_user_password \
     --data orderNumber=1234567890ABCDEF \
     --data returnUrl=https://mybestmerchantreturnurl.com \
     --data failUrl=https://mybestmerchantfailurl.com \
     --data email=test@test.com \
     --data clientId=259753456 \
     --data features=FORCE_CREATE_BINDING \
     --data language=en \'

   {
     "orderId": "01491d0b-c848-7dd6-a20d-e96900a7d8c0",
     "formUrl": "https://dev.bpcbt.com/payment/payment/merchants/ecom/payment_en.html?mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0"
   }

2. Transmettez la valeur obtenue orderId dans le paramètre MDORDER de la requête paymentorder.do. Il est nécessaire de transmettre les paramètres supplémentaires recurringFrequency et recurringExpiry (la vérification n'est pas effectuée, mais cette information est utilisée par la banque qui a émis la carte).

   Exemple de requête paymentorder.do:

   curl --request POST \
     --url https://dev.bpcbt.com/payment/rest/paymentorder.do \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data '$CVC=123' \
     --data '$EXPIRY=203012' \
     --data '$PAN=4000001111111118' \
     --data 'TEXT=TEST CARDHOLDER' \
     --data MDORDER=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
     --data userName=test_user \
     --data password=test_user_password \
     --data language=en \
     --data 'jsonParams={"recurringFrequency": "1", "recurringExpiry":"20261231"}'

   {
     "errorCode": 0,
     "is3DSVer2": true,
     "threeDSServerTransId": "efa8e3ce-a4a6-49f8-b422-df781de18119",
     "threeDSMethodURLServer": "https://dev.bpcbt.com/payment/client/gather?threeDSServerTransID=efa8e3ce-a4a6-49f8-b422-df781de18119"
   }

En résultat, une liaison de données de paiement sauvegardées sera créée pour le client avec le clientId initialement spécifié.

Paiement par liaison de données de paiement sauvegardées récurrente

Pour le paiement de commande par liaison de données de paiement sauvegardées récurrente créée (voir le processus de création ci-dessus) utilisez la séquence de requêtes suivante:

1. Obtenez la liste des liaisons de données de paiement sauvegardées, en utilisant la requête getBindings.do avec le même paramètre clientId et avec bindingType=R → obtenez en réponsebindingId.

   Exemple de requête getBindings.do:

   curl --request POST \
   --url https://dev.bpcbt.com/payment/rest/getBindings.do \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data userName=test_user \
   --data password=test_user_password \
   --data clientId=259753456 \
   --data bindingType=R

   {
   "errorCode":"0",
   "errorMessage":"Success",
   "bindings": [
       {
               "bindingId": "44779116-41a5-7798-b072-c0a30760e2b0",
               "maskedPan": "411111**1111",
               "expiryDate": "203412",
               "paymentWay": "TOKEN_PAY",
               "paymentSystem": "CARD",
               "displayLabel": "XXXXXXXXXXXX1111",
               "bindingCategory": "RECURRENT"
           }
       ]
    }

2. Exécutez la requête recurrentPayment.do avec le bindingId obtenu, pour enregistrer et payer la commande.

   Exemple de requête recurrentPayment.do:

   curl --request POST \
     --url https://dev.bpcbt.com/payment/recurrentPayment.do \
     --header 'Content-Type: application/json' \
     --data '{
     "userName": "test_user",
     "password": "test_user_password",
     "orderNumber": "UAF-203974-DE-12
     "language": "EN",
     "bindingId": "44779116-41a5-7798-b072-c0a30760e2b0",
     "amount": 12300,
     "currency": "978",
     "description" : "Test description",
     "additionalParameters": {
       "firstParamName": "firstParamValue",
       "secondParamName": "secondParamValue"
     }
    }'

   {
     "success": true,
     "data": {
       "orderId": "9adaa8f0-3b5a-742f-80b4-172200b40dc0"
     },
     "orderStatus": {
       "errorCode": "0",
       "orderNumber": "9003",
       "orderStatus": 2,
       "actionCode": 0,
       "actionCodeDescription": "",
       "amount": 12300,
       "currency": "978",
       "date": 1618338779501,
       "orderDescription": "Test description",
       "merchantOrderParams": [
         {
           "name": "firstParamName",
           "value": "firstParamValue"
         },
         {
           "name": "secondParamName",
           "value": "secondParamValue"
         }
       ],
       "transactionAttributes": [],
       "attributes": [
         {
           "name": "mdOrder",
           "value": "9adaa8f0-3b5a-742f-80b4-172200b40dc0"
         }
       ],
       "cardAuthInfo": {
         "maskedPan": "400000**1118",
         "expiration": "202612",
         "cardholderName": "TEST CARDHOLDER",
         "approvalCode": "123456",
         "paymentSystem": "VISA",
         "product": "visa-product",
         "secureAuthInfo": {
           "eci": 7
         },
         "pan": "400000**1118"
       },
       "bindingInfo": {
         "clientId": "test-client",
         "bindingId": "3080a436-02a0-75c2-a2ce-41be00b40dc0"
       },
       "authDateTime": 1618338779790,
       "authRefNum": "111111111111",
       "paymentAmountInfo": {
         "paymentState": "DEPOSITED",
         "approvedAmount": 12300,
         "depositedAmount": 12300,
         "refundedAmount": 0,
         "totalAmount": 12300
       },
       "bankInfo": {
         "bankName": "ES TEST BANK",
         "bankCountryCode": "ES",
         "bankCountryName": "Spain"
       },
       "chargeback": false,
       "operations": [
         {
           "amount": 12300,
           "cardHolder": "TEST CARDHOLDER",
           "authCode": "123456"
         }
       ]
     }
   }

   En résultat, la commande sera payée à l'aide de la liaison de données de paiement sauvegardées avec le bindingId spécifié.

Liaisons de données de paiement sauvegardées pour paiement échelonné

Création d'une liaison de données de paiement sauvegardées pour le paiement en paiement échelonné

Pour créer une liaison de données de paiement sauvegardées pour paiement échelonné, exécutez les étapes suivantes:

1. Exécutez la requête register.do avec le paramètre clientId → obtenez en réponse orderId.

   Exemple de requête register.do:

   curl --request POST \
     --url https://dev.bpcbt.com/payment/rest/register.do \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data amount=123456 \
     --data userName=test_user \
     --data password=test_user_password \
     --data orderNumber=1234567890ABCDEF \
     --data returnUrl=https://mybestmerchantreturnurl.com \
     --data failUrl=https://mybestmerchantfailurl.com \
     --data email=test@test.com \
     --data clientId=259753456 \
     --data features=FORCE_CREATE_BINDING \
     --data language=en \'

   {
     "orderId": "01491d0b-c848-7dd6-a20d-e96900a7d8c0",
     "formUrl": "https://dev.bpcbt.com/payment/payment/merchants/ecom/payment_en.html?mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0"
   }

2. Transmettez la valeur obtenue orderId dans le paramètre MDORDER de la requête paymentorder.do. Il est nécessaire de transmettre les paramètres supplémentaires installments, totalInstallmentAmount, recurringFrequency et recurringExpiry.

   Exemple de requête paymentorder.do:

   curl --request POST \
     --url https://dev.bpcbt.com/payment/rest/paymentorder.do \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data '$CVC=123' \
     --data '$EXPIRY=203012' \
     --data '$PAN=4000001111111118' \
     --data 'TEXT=TEST CARDHOLDER' \
     --data MDORDER=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
     --data userName=test_user \
     --data password=test_user_password \
     --data language=en \
     --data 'jsonParams={"installments": "3", "totalInstallmentAmount": "900000", "recurringFrequency": "3", "recurringExpiry":"20261231"}'

   {
       "errorCode": 0,
       "is3DSVer2": true,
       "threeDSServerTransId": "3e07d895-8cac-460c-81f3-da6f6389dc11",
       "threeDSMethodURLServer": "https://dev.bpcbt.com/payment/client/gather?threeDSServerTransID=3e07d895-8cac-460c-81f3-da6f6389dc11",
       "threeDSMethodURLServerDirect": "https://dev.bpcbt.com/payment/rest/3dsmethod.do"
   }

En résultat, une liaison sera créée pour le client avec le clientId initialement spécifié.

Paiement par liaison pour l'échelonnement

Pour payer une commande avec une liaison créée pour l'échelonnement (voir le processus de création ci-dessus), utilisez la séquence de requêtes suivante :

1. Enregistrez une nouvelle commande à l'aide de la requête register.do avec le même paramètre clientId, obtenez en réponse orderId.

2. Obtenez la liste des liaisons en utilisant la requête getBindings.do avec le même paramètre clientId et avec bindingType=I → obtenez en réponse bindingId.

   Exemple de requête getBindings.do :

   curl --request POST \
       --url https://dev.bpcbt.com/payment/rest/getBindings.do \
       --header 'Content-Type: application/x-www-form-urlencoded' \
       --data userName=test_user \
       --data password=test_user_password \
       --data clientId=259753456 \
       --data bindingType=I

   {
       "errorCode":"0",
       "errorMessage":"Success",
       "bindings": [
           {
                   "bindingId": "44779116-41a5-7798-b072-c0a30760e2b0",
                   "maskedPan": "411111**1111",
                   "expiryDate": "203412",
                   "paymentWay": "TOKEN_PAY",
                   "paymentSystem": "CARD",
                   "displayLabel": "XXXXXXXXXXXX1111",
                   "bindingCategory": "INSTALLMENT"
               }
           ]
        }

3. Exécutez la requête installmentPayment.do avec le bindingId obtenu.

   Exemple de requête installmentPayment.do :

   curl --request POST \
     --url https://dev.bpcbt.com/payment/installmentPayment.do \
     --header 'Content-Type: application/json' \
     --data '{
     "userName": "test_user",
     "password": "test_user_password",
     "orderNumber": "UAF-203974-DE-12",
     "language": "EN",
     "bindingId": "44779116-41a5-7798-b072-c0a30760e2b0",
     "amount": 12300,
     "currency": "978",
     "description" : "Test description",
     "additionalParameters": {
       "firstParamName": "firstParamValue",
       "secondParamName": "secondParamValue"
     }
    }'

   {
     "errorCode": 0,
     "errorMessage": "Success",
     "orderId": "0e441115-f3bc-711c-8827-2fdc00b4f820",
     "orderStatus": {
       "errorCode": "0",
       "orderNumber": "7033",
       "orderStatus": 2,
       "actionCode": 0,
       "actionCodeDescription": "",
       "amount": 12300,
       "currency": "978",
       "date": 1618340470944,
       "orderDescription": "Test description",
       "merchantOrderParams": [
         {
           "name": "firstParamName",
           "value": "firstParamValue"
         },
         {
           "name": "secondParamName",
           "value": "secondParamValue"
         }
       ],
       "transactionAttributes": [],
       "attributes": [
         {
           "name": "mdOrder",
           "value": "0e441115-f3bc-711c-8827-2fdc00b4f820"
         }
       ],
       "cardAuthInfo": {
         "maskedPan": "400000**1118",
         "expiration": "203012",
         "cardholderName": "TEST CARDHOLDER",
         "approvalCode": "123456",
         "paymentSystem": "VISA",
         "product": "visa-product",
         "secureAuthInfo": {
           "eci": 7
         },
         "pan": "400000**1118"
       },
       "bindingInfo": {
         "clientId": "test-client",
         "bindingId": "8aa4fa8b-4d8a-76ca-b314-7bcc00b4f820"
       },
       "authDateTime": 1618340471076,
       "authRefNum": "111111111111",
       "paymentAmountInfo": {
         "paymentState": "DEPOSITED",
         "approvedAmount": 12300,
         "depositedAmount": 12300,
         "refundedAmount": 0,
         "totalAmount": 12300
       },
       "bankInfo": {
         "bankName": "ES TEST BANK",
         "bankCountryCode": "ES",
         "bankCountryName": "Spain"
       },
       "chargeback": false,
       "operations": [
         {
           "amount": 12300,
           "cardHolder": "TEST CARDHOLDER",
           "authCode": "123456"
         }
       ]
     },
     "error": false
   }

   En résultat, la commande sera payée à l'aide de la liaison avec le bindingId spécifié.