Identifiants stockés et types de transactions

Cette section décrit les types de transactions pris en charge pour les identifiants stockés.

Types d'identifiants stockés

La passerelle de paiement permet de créer et d'utiliser trois types d'identifiants stockés :

• Ordinaire – pour les paiements non liés à un plan ou calendrier quelconque. Par exemple, lorsqu'un acheteur passe une nouvelle commande et la paie en utilisant des données de carte précédemment sauvegardées.
• Récurrent – pour les paiements effectués selon un calendrier fixe. Par exemple, les paiements mensuels pour les services publics.
• Paiement échelonné – lors du paiement échelonné, lorsque le client paie la facture en petites parties sur une période fixe selon un plan de paiements.

Une carte peut avoir des identifiants stockés de différents types. De plus, une carte peut avoir plusieurs identifiants stockés pour différents paiements échelonnés.

Type de transactions

Les transactions par identifiants stockés 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 carte utilisant un identifiant stocké ordinaire.
• MIT (Merchant-initiated Transactions) – transactions de commerce électronique effectuées par le vendeur sans participation du porteur de carte. Ce groupe comprend 3 types de transactions :
  • U – transaction non planifiée utilisant un identifiant stocké ordinaire. Par exemple, application 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 subséquente utilisant un identifiant stocké récurrent.
  • 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 d'initiateur de transaction) des demandes API de paiement. Valeurs possibles du paramètre tii :

Valeur tii	Description	Type de transaction	Initiateur de transaction	Données de carte pour transaction	Sauvegarde des données de carte après transaction	Remarque
Vide		Ordinaire	Acheteur	Saisies par l'acheteur	Non	Transaction de commerce électronique sans sauvegarde d'identifiant stocké.
II	Initiateur - paiement échelonné (CIT)	Initiatrice	Acheteur	Saisies par l'acheteur	Oui	Transaction de commerce électronique avec sauvegarde d'identifiant stocké.
F	paiement non planifié (CIT)	Subséquente	Acheteur	Le client sélectionne la carte au lieu de la saisie manuelle	Non	Transaction de commerce électronique utilisant un identifiant stocké ordinaire précédemment sauvegardé.
U	paiement non planifié (MIT)	Subséquente	Vendeur	Pas de saisie manuelle, le vendeur transmet les données	Non	Transaction de commerce électronique utilisant un identifiant stocké ordinaire précédemment sauvegardé. Utilisé uniquement pour les paiements en une phase.
RI	Initiateur - Récurrents (CIT)	Initiatrice	Acheteur	Saisi par l'acheteur	Oui	Transaction de commerce électronique avec sauvegarde des données de paiement sauvegardées.
R	paiement récurrent (MIT)	Subséquente	Vendeur	Pas de saisie manuelle, le vendeur transmet les données	Non	Opération récurrente utilisant un identifiant stocké sauvegardé. Utilisé uniquement pour les paiements en une phase.
II	Initiateur - Paiement échelonné (CIT)	Initiatrice	Acheteur	Saisi par l'acheteur	Oui	Transaction de commerce électronique avec sauvegarde des données de paiement sauvegardées.
I	paiement échelonné (MIT)	Subséquente	Vendeur	Pas de saisie manuelle, le vendeur transmet les données	Non	Opération de paiement échelonné utilisant un identifiant stocké sauvegardé. Utilisé uniquement pour les paiements en une phase.

Gestion des identifiants stockés via API

Voici des exemples de création et d'utilisation de différents types d'identifiants stockés via API en utilisant la page de paiement propre du commerçant :

• Identifiants stockés ordinaires
• Identifiants stockés récurrents
• Identifiants stockés pour paiement échelonné

Identifiants stockés ordinaires

Création d'un identifiant stocké ordinaire

Pour créer un identifiant stocké ordinaire, effectuez les étapes suivantes :

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

   Exemple de demande register.do pour créer un identifiant stocké ordinaire :

   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 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, un identifiant stocké sera créé pour le client avec le clientId initialement spécifié. En résultat, la commande sera payée à l'aide de l'identifiant stocké avec le bindingId spécifié.

paiement par identifiant stocké ordinaire

Pour payer une commande avec l'identifiant stocké ordinaire créé (voir le processus de création ci-dessus), effectuez les étapes suivantes :

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

2. Obtenez la liste des identifiants stockés à l'aide de la requête getBindings.do avec la même valeur clientId et avec bindingType=C → obtenez bindingId dans la réponse.

   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 le bindingId obtenu. Valeurs disponibles pour 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 l'identifiant stocké avec le bindingId spécifié.

Identifiants stockés récurrents

Création d'un identifiant stocké récurrent

Pour créer un identifiant stocké récurrent, effectuez les étapes suivantes :

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

   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 orderId obtenue 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, un identifiant stocké sera créé pour le client avec le clientId initialement spécifié.

Paiement avec un identifiant stocké récurrent

Pour le paiement d'une commande avec l'identifiant stocké récurrent créé (voir le processus de création ci-dessus), utilisez la séquence de requêtes suivante :

1. Obtenez la liste des identifiants stockés en utilisant la requête getBindings.do avec le même paramètre clientId et avec bindingType=R → obtenez bindingId dans la réponse.

   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 l'identifiant stocké avec le bindingId spécifié.

Identifiants stockés pour le paiement échelonné

Création d'un identifiant stocké pour le paiement en paiement échelonné

Pour créer un identifiant stocké pour le paiement échelonné, effectuez les étapes suivantes :

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

   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 orderId obtenue 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, un identifiant stocké sera créé pour le client avec le clientId initialement spécifié.

Paiement avec un identifiant stocké pour le paiement échelonné

Pour le paiement d'une commande avec l'identifiant stocké pour le paiement échelonné créé (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 orderId en réponse.

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

   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 l'identifiant stocké avec le bindingId spécifié.