Liaisons et types de transactions

Cette section décrit les types de transactions supportés par liaisons.

Types de liaisons

La passerelle de paiement permet de créer et d'utiliser trois types de liaisons :

Ordinaire – pour les paiements non liés à aucun plan ou calendrier. 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écurrente – pour les paiements qui se produisent selon un calendrier fixe. Par exemple, les paiements mensuels pour les services publics.
Échelonnement – lors du paiement en échelonnement, lorsque le client paie la facture en petites parties sur une période de temps fixe selon un plan de paiements.

Une carte peut avoir des liaisons de différents types. De plus, une carte peut avoir plusieurs liaisons pour différents échelonnements.

Type de transactions

Les transactions par liaisons 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 carte participe au paiement. Ce groupe inclut 4 types de transactions :
- C/CI – transaction initiatrice avec sauvegarde de liaison ordinaire pour de futurs paiements.
- RI – transaction initiatrice avec sauvegarde de liaison pour les paiements récurrents.
- II – transaction initiatrice avec sauvegarde de liaison pour les paiements en échelonnement.
- F – transaction hors plan, effectuée par le porteur de carte en utilisant une liaison 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 hors plan utilisant une liaison 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 ultérieure utilisant une liaison récurrente.
- I – transaction ultérieure en échelonnement utilisant une liaison pour échelonnement.

Le type de transaction doit être transmis dans le paramètre tii des requêtes API de paiement. Pour plus de détails sur les valeurs du paramètre tii, lisez ici.

Gestion des liens via API

Ci-dessous sont présentés des exemples de création et d'utilisation de différents types de liens via API :

Liens ordinaires
Liens récurrents
Liens pour le paiement échelonné

Liens ordinaires

Création d'un lien ordinaire

Pour créer un lien ordinaire, effectuez la séquence de requêtes suivante :

Effectuez une requête register.do avec le paramètre clientId, obtenez en réponse orderId et formUrl.
Transmettez la valeur obtenue orderId dans le paramètre MDORDER de la requête paymentorder.do.

En résultat, un lien sera créé pour le client avec le clientId initialement spécifié. Vous pouvez effectuer une requête getBindings.do pour vous assurer que le lien est créé.

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=59e00106-1f69-76a7-b893-b27c00b4f820 \
  --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
}

Paiement avec un lien ordinaire

Pour le paiement d'une commande avec un lien ordinaire, utilisez la séquence de requêtes suivante :

Effectuez une requête register.do avec le paramètre clientId → obtenez en réponse orderId.
Obtenez la liste des liens avec la requête getBindings.do avec la même valeur clientId et avec bindingType=C → obtenez en réponse bindingId.
Effectuez une 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.

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

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=24c3d392-4c60-7f0b-9ff5-b00100b4f820 \
  --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
}

Liens récurrents

Création d'un lien récurrent

Pour créer un lien récurrent, effectuez la séquence de requêtes suivante :

Effectuez une requête register.do avec le paramètre clientId, obtenez en réponse orderId et formUrl
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 émettrice de la carte).

En résultat, une liaison sera créée pour le client avec le clientId initialement spécifié. Vous pouvez exécuter la requête getBindings.do pour vous assurer que la liaison est créée.

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=59e00106-1f69-76a7-b893-b27c00b4f820 \
  --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"
}

Paiement par liaison récurrente

Pour le paiement de commande par liaison récurrente, utilisez la séquence de requêtes suivante :

Obtenez la liste des liaisons en utilisant la requête getBindings.do avec bindingType=R → obtenez en réponse bindingId.
Exécutez la requête recurrentPayment.do avec le bindingId obtenu.

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

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": "3080a436-02a0-75c2-a2ce-41be00b40dc0",
  "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"
      }
    ]
  }
}

Liaisons pour échelonnement

Création de liaison pour paiement échelonné

Pour créer une liaison pour échelonnement, exécutez la séquence de requêtes suivante :

Exécutez la requête register.do avec le paramètre clientId → obtenez en réponse orderId.
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.

En résultat, une liaison sera créée pour le client avec le clientId initialement spécifié. Vous pouvez exécuter la requête getBindings.do pour vous assurer que la liaison est créée.

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=bd30b67f-f8c7-7c9c-a4ac-66b300b40dc0 \
  --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"
}

Paiement par liaison pour échelonnement

Pour le paiement de commande par liaison pour échelonnement, utilisez la séquence de requêtes suivante :

Obtenez la liste des liaisons en utilisant la requête getBindings.do avec bindingType=I → obtenez en réponse bindingId.
Exécutez la requête installmentPayment.do avec le bindingId obtenu.

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

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": "8aa4fa8b-4d8a-76ca-b314-7bcc00b4f820",
  "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
}

Catégories:

eCommerce API V1

Liaisons et types de transactions

Types de liaisons

Type de transactions

Gestion des liens via API

Liens ordinaires

Liens récurrents

Liaisons pour échelonnement

Contactez-nous

Merci !