Description générale

Vous pouvez utiliser notre API commerçant pour créer le scénario de paiement dont vous avez besoin. Par exemple, vous pouvez créer votre propre page de paiement entièrement personnalisée et la connecter à notre passerelle de paiement.

Vous pouvez télécharger la collection de demandes API pour Postman afin de tester les fonctionnalités principales de l'API. Envoyez obligatoirement les demandes comme POST avec les attributs dans le corps de la demande.

Caractère obligatoire des paramètres

Le caractère obligatoire de la présence d'un paramètre dans la requête/réponse peut prendre les valeurs suivantes :

• Obligatoire - le paramètre doit toujours être présent. En cas d'absence de valeur, il est nécessaire de transmettre une valeur vide selon le format ;
• Facultatif - le paramètre peut être présent ou absent, sa présence excessive n'entraînera pas d'erreur du système ;
• Condition - le paramètre peut être présent (être obligatoire) ou absent selon une ou plusieurs conditions.

Le caractère obligatoire de la transmission du paramètre dans la description de la requête/réponse est indiqué dans la colonne du même nom "Caractère obligatoire".

Authentification

Pour l'authentification du marchand dans la passerelle de paiement, deux méthodes peuvent être utilisées.

• En utilisant le login et le mot de passe de l'utilisateur API du marchand (compte avec le suffixe -api), obtenu lors de l'inscription. Ces valeurs sont transmises dans les paramètres userName et password respectivement (voir le tableau ci-dessous).

• À l'aide d'un token spécial - sa valeur peut être demandée auprès du service de support technique. Dans les requêtes, sa valeur est transmise dans le paramètre token (voir le tableau ci-dessous).

URL pour les appels API

TEST: https://dev.bpcbt.com/payment/rest/
PROD: https://dev.bpcbt.com/payment/rest/

Erreurs

Codes de statut HTTP :

• 200 - en cas d'appels API de la passerelle de paiement, il est nécessaire d'analyser le JSON de la réponse pour déterminer si le traitement de la transaction a été réussi ou non. Le succès est indiqué soit par :
  - la valeur du paramètre success égale à true
  - la valeur du paramètre errorCode égale à 0
  Si les deux paramètres sont présents, success a la priorité sur errorCode.

• 400 – une erreur interne s'est produite dans le système.

• 404 – erreur lors de l'appel API – URL incorrect (n'existe pas).

• 429 – ce code signifie que le système est surchargé. Le plus souvent, la raison principale est que la limite de requêtes par seconde ou la limite de requêtes simultanées est atteinte. Mais cela peut aussi être lié au fait que le système dans son ensemble est surchargé (indépendamment de vos requêtes).

• 500 ou 502 – ce code signifie que quelque chose s'est mal passé de notre côté.

Si une requête liée au paiement d'une commande est traitée avec succès, cela ne signifie pas encore que le paiement lui-même a réussi.

Pour déterminer si le paiement a été réussi ou non, vous pouvez vous référer à la description de la requête utilisée. Aussi, pour connaître le statut du paiement, vous pouvez toujours utiliser l'algorithme décrit ci-dessous

1. Appeler getOrderStatusExtended.do;
2. Vérifier le champ orderStatus dans la réponse : la commande est considérée comme payée seulement si la valeur orderStatus est égale à 1 ou 2.

Signature de requête API

Dans certains cas, pour assurer un échange de données sécurisé, il peut être nécessaire d'implémenter une signature asymétrique de requête. Habituellement, cette exigence s'applique seulement si vous effectuez des requêtes P2P/AFT/OCT.

Pour pouvoir signer les requêtes, vous devez effectuer les étapes suivantes :

1. Créez et téléchargez un certificat.
2. Calculez le hash et la signature, en utilisant votre clé privée, et transmettez le hash généré (X-Hash) et la valeur de signature (X-Signature) dans l'en-tête de la requête.

Ces étapes sont décrites en détail ci-dessous.

Création et téléchargement d'un certificat

1. Créez une clé privée RSA de 2048 bits. La méthode de génération dépend de la politique de confidentialité de votre entreprise. Par exemple, vous pouvez le faire avec OpenSSL :

   openssl genrsa -des3 -out private.key 2048

2. Créez un CSR public (demande de signature de certificat), en utilisant la clé privée générée :

   openssl req -key private.key -new -out public.csr

3. Créez un certificat en utilisant la clé privée générée et le CSR. Exemple de formation d'un certificat pour 5 ans :

   openssl x509 -signkey private.key -in public.csr -req -days 1825 -out public.cer

4. Téléchargez le certificat généré dans l'Espace personnel. Pour cela, allez dans Certificats de portefeuilles > Merchant API, cliquez sur Ajouter un certificat et téléchargez le certificat public généré.

Calcul du hash et de la signature

1. Calculez le hash SHA256 du corps de la requête de la manière suivante :

2. Utilisez le corps de la requête sous forme de chaîne (dans notre exemple c'est amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api).

3. Calculez le hash SHA256 de cette chaîne en octets bruts.

4. Convertissez les octets bruts en encodage base64.

5. Générez une signature pour le hash SHA256 calculé à l'aide de l'algorithme RSA, en utilisant la clé privée.

Dans notre exemple, nous utilisons la clé privée suivante avec le mot de passe 12345 :

Nous obtenons la signature : pJ/gM4PR1/mKGuIxMvTl5pYDDjJslb0BcXFnIxijFn5qKdPd7W+2ueoctziU7omnkYp01/BlracukH1GOPWMSO+9zKuTDdFueFm1utsS0zaPFU+dmc1niGDRWE0CbCXcti/rGSTDPsnR58mwqgVkbCWxKyCDtuo5LxiKPK9mzgWTUuJ8LX6f6u42MURi5tRG6a9dc8l/+J94g0YOk911R6Lqv2jcluEvZ9ZeMMt8hyxowb0eDaCHlussu2CAyqpE9V+EUAc81Jkwv96MMSsA6UnFwEaCV/k+kwYd0jHCx94m2yWX734p9cWsBW7Fr5F0zox9Yck4GOjqe9nJMMB9jQ== 3. Vous devez maintenant transmettre le hachage généré (X-Hash) et la valeur de la signature (X-Signature) dans l'en-tête de la requête. La requête ressemblera à ceci :

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/register.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'X-Hash: eYkMUF+xaYJhsETTIGsctl6DBNZha1ITN8muCcWQtZk=' \
  --header 'X-Signature: pJ/gM4PR1/mKGuIxMvTl5pYDDjJslb0BcXFnIxijFn5qKdPd7W+2ueoctziU7omnkYp01/BlracukH1GOPWMSO+9zKuTDdFueFm1utsS0zaPFU+dmc1niGDRWE0CbCXcti/rGSTDPsnR58mwqgVkbCWxKyCDtuo5LxiKPK9mzgWTUuJ8LX6f6u42MURi5tRG6a9dc8l/+J94g0YOk911R6Lqv2jcluEvZ9ZeMMt8hyxowb0eDaCHlussu2CAyqpE9V+EUAc81Jkwv96MMSsA6UnFwEaCV/k+kwYd0jHCx94m2yWX734p9cWsBW7Fr5F0zox9Yck4GOjqe9nJMMB9jQ==' \
  --data 'amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api'

La requête doit répondre aux exigences suivantes :

• Tous les paramètres de requête sont inclus dans le corps de la requête (pas dans l'URL)

• Si les paramètres de requête sont transmis au format JSON, l'en-tête suivant doit être utilisé :

  --header 'content-type: application/json'

• Si les paramètres de requête sont transmis au format Query (par exemple, parameterA=valueA&parameterB=valueB), l'en-tête suivant doit être utilisé :

  --header 'content-type: application/x-www-form-urlencoded'

• La requête contient le login et le mot de passe corrects de l'utilisateur API.

• L'en-tête X-Hash contient le hachage SHA256 du corps de la requête (calculé à l'Étape 1).

• L'en-tête X-Signature contient la signature pour le hachage SHA256, calculée à l'aide de l'algorithme RSA en utilisant la clé privée (générée à l'Étape 2).

Exemple de code Java

Ci-dessous un exemple de code Java qui charge la clé privée, calcule le hachage SHA256, le signe à l'aide de la clé privée avec le mot de passe 12345, puis envoie la requête correcte register.do :

import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.KeyStore;
import java.security.MessageDigest;
import java.security.PrivateKey;
import java.security.Signature;
import java.util.Base64;

import static java.net.HttpURLConnection.HTTP_OK;

public class SimpleSignatureExample {

    // Cet exemple n'est pas prêt pour la production. Il montre simplement comment utiliser les signatures dans l'API.
    public static void main(String[] args) throws Exception {
        // charger la clé privée depuis jks
        KeyStore ks = KeyStore.getInstance("JKS");
        char[] pwd = "123456".toCharArray();
        ks.load(Files.newInputStream(Paths.get("/path/to/certificates.jks")), pwd);
        PrivateKey privateKey = (PrivateKey) ks.getKey("111111", pwd);

        // Signer
        String httpBody = "amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api";

        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        Signature signature = Signature.getInstance("SHA256withRSA");
        signature.initSign(privateKey);

        byte[] sha256 = digest.digest(httpBody.getBytes());
        signature.update(sha256);
        byte[] sign = signature.sign();

        // Envoyer
        Base64.Encoder encoder = Base64.getEncoder();
        HttpsURLConnection connection = (HttpsURLConnection) new URL("https://<YOUR_DOMAIN>/payment/rest/register.do").openConnection();
        connection.setDoOutput(true);
        connection.setDoInput(true);
        connection.setRequestMethod("POST");
        connection.addRequestProperty("content-type", "application/x-www-form-urlencoded");
        connection.addRequestProperty("X-Hash", encoder.encodeToString(sha256));
        connection.addRequestProperty("X-Signature", encoder.encodeToString(sign));
        connection.addRequestProperty("Content-Length", String.valueOf(httpBody.getBytes().length));
        try (final DataOutputStream outputStream = new DataOutputStream(connection.getOutputStream())) {
            outputStream.write(httpBody.getBytes());
            outputStream.flush();
        }
        connection.connect();

        InputStream inputStream = connection.getResponseCode() == HTTP_OK ? connection.getInputStream() : connection.getErrorStream();
        BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
        String line;
        while ((line = reader.readLine()) != null) {
            System.out.println(line);
        }
    }
}

Exemple de code Python

Ci-dessous un exemple de code Python qui génère la signature :

import OpenSSL
from OpenSSL import crypto
import base64
from hashlib import sha256
key_file = open("./priv.pem", "r")
key = key_file.read()
key_file.close()

if key.startswith('-----BEGIN '):
    pkey = crypto.load_privatekey(crypto.FILETYPE_PEM, key)
else:
    pkey = crypto.load_pkcs12(key, password).get_privatekey()

data = "amount=2000&currency=978&userName=test_user&password=test_user_password&returnUrl=https%3A%2F%2Fmybestmerchantreturnurl.com&description=my_first_order&language=en"

sha256_hash = sha256(data.encode()).digest()
base64_hash = base64.b64encode(sha256_hash)
print(base64_hash)

sign = OpenSSL.crypto.sign(pkey, sha256_hash, "sha256")

signed_base64 = base64.b64encode(sign)
print(signed_base64)

Le fichier de clé privée pour l'exemple Python doit avoir le format :

Enregistrement de commande

Enregistrement de commande

Pour l'enregistrement de commande, utilisez la requête https://dev.bpcbt.com/payment/rest/register.do.

Lors de l'exécution de la requête, il est nécessaire d'utiliser l'en-tête : Content-Type: application/x-www-form-urlencoded

Paramètres de requête

Ci-dessous sont présentés les paramètres du bloc billingPayerData (données sur l'adresse d'enregistrement du client).

Description des paramètres de l'objet shippingPayerData :

Description des paramètres de l'objet preOrderPayerData :

Description des paramètres de l'objet orderPayerData.

Description des paramètres dans l'objet orderBundle :

Description des paramètres dans l'objet customerDetails :

Description des paramètres dans l'objet deliveryInfo :

Description des paramètres dans l'objet cartItems :

Description des paramètres dans l'objet items :

Description des paramètres dans l'objet quantity :

Description des paramètres dans l'objet itemDetails :

Description des paramètres dans l'objet itemDetailsParams :

Description des paramètres de l'objet marketplace :

Description des paramètres de l'objet qui est un élément du tableau retailers.

Exemple d'objet marketplace :

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

Description des paramètres de l'objet paymentFacilitator :

Paramètres de l'élément du tableau subMerchants :

Paramètres de l'objet address :

Exemple d'objet paymentFacilitator :

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Paramètres de réponse

Exemples

Exemple de requête

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_SSL \
  --data language=en \
  --data 'jsonParams={"param_1_name":"param_1_value","param_2_name":"param_2_value"}'

Exemple de réponse - succès

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

Exemple de réponse - erreur

{
  "errorCode": "1",
  "errorMessage": "Order number is duplicated, order with given order number is processed already"
}

Enregistrement de commande avec pré-autorisation

Pour la demande d'enregistrement de commande avec pré-autorisation, la méthode https://dev.bpcbt.com/payment/rest/registerPreAuth.do est utilisée.

Lors de l'exécution de la demande, il est nécessaire d'utiliser l'en-tête : Content-Type: application/x-www-form-urlencoded

Paramètres de demande

Ci-dessous sont présentés les paramètres du bloc billingPayerData (données sur l'adresse d'enregistrement du client).

Description des paramètres de l'objet shippingPayerData :

Description des paramètres de l'objet preOrderPayerData :

Description des paramètres de l'objet orderPayerData.

Description des paramètres dans l'objet orderBundle :

Description des paramètres dans l'objet customerDetails :

Description des paramètres dans l'objet deliveryInfo :

Description des paramètres dans l'objet cartItems :

Description des paramètres dans l'objet items :

Description des paramètres dans l'objet quantity :

Description des paramètres dans l'objet itemDetails :

Description des paramètres dans l'objet itemDetailsParams :

Description des paramètres de l'objet marketplace :

Description des paramètres de l'objet qui est un élément du tableau retailers.

Exemple d'objet marketplace :

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

Description des paramètres de l'objet paymentFacilitator :

Paramètres de l'élément du tableau subMerchants :

Paramètres de l'objet address :

Exemple d'objet paymentFacilitator :

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Paramètres de réponse

Exemples

Exemple de demande

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/registerPreAuth.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data amount=2000 \
  --data userName=test_user \
  --data password=test_user_password \
  --data returnUrl=https://mybestmerchantreturnurl.com \
  --data orderNumber=1255555555555 \
  --data clientId=259753456 \
  --data language=en

Exemple de réponse

{
  "orderId": "01492437-d2fb-77fa-8db7-9e2900a7d8c0",
  "formUrl": "https://dev.bpcbt.com/payment/merchants/pay/payment_en.html?mdOrder=01492437-d2fb-77fa-8db7-9e2900a7d8c0"
}

Paiements directs

Paiement de commande

Pour le paiement d'une commande précédemment enregistrée, la requête https://dev.bpcbt.com/payment/rest/paymentorder.do est utilisée.
La requête est utilisée en mode MPI/3DS Server interne, cela ne nécessite pas d'autorisations supplémentaires et/ou de certifications.
La requête est utilisée en mode MPI/3DS Server externe si vous avez un contrat avec un système de paiement international ou un certificat qui permet de réaliser de manière autonome l'authentification 3DS. Cela signifie que vous pouvez utiliser votre propre MPI/3DS Server pour l'authentification du client en utilisant la technologie 3D Secure. Des informations supplémentaires sur le paiement avec votre propre MPI/3DS Server sont disponibles ici.

Lors de l'exécution de la requête, il est nécessaire d'utiliser l'en-tête : Content-Type: application/x-www-form-urlencoded

Paiement de commande (MPI/3DS Server interne)

Le paiement de commande s'effectue avec la transmission des données de paiement par carte, ainsi qu'avec l'utilisation de la technologie d'authentification 3DS (l'application de l'authentification est réglementée par les paramètres contrôlés par le service support).

Paramètres de requête

Ci-dessous sont présentés les paramètres du bloc billingPayerData (données sur l'adresse d'enregistrement du client).

Description des paramètres de l'objet shippingPayerData :

Description des paramètres de l'objet preOrderPayerData :

Description des paramètres de l'objet orderPayerData.

Valeurs possibles de tii (Pour en savoir plus sur les types de données de paiement sauvegardées pris en charge par la passerelle de paiement, lisez ici).

Ci-dessous sont présentés les paramètres du bloc clientBrowserInfo (données sur le navigateur du client).

Exemple du bloc clientBrowserInfo :

"clientBrowserInfo":
    {
		"userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
		"fingerprint":850891523,
		"OS":"Windows",
		"OSVersion":"10",
		"isMobile":false,
		"screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
		"colorDepth":24,
		"screenHeight":"864",
		"screenWidth":"1536",
		"plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
		"javaEnabled":false,
		"javascriptEnabled":true,
		"browserLanguage":"it-IT",
		"browserTimeZone":"Europe/Rome",
		"browserTimeZoneOffset":-120,
		"browserAcceptHeader":"gzip",
        "browserIpAddress":"x.x.x.x"
	}

Description des paramètres de l'objet paymentFacilitator :

Paramètres de l'élément du tableau subMerchants :

Paramètres de l'objet address :

Exemple d'objet paymentFacilitator :

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Description des paramètres de l'objet marketplace :

Description des paramètres de l'objet qui est un élément du tableau retailers.

Exemple d'objet marketplace :

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

Lors de l'authentification par le protocole 3DS2, les paramètres suivants sont également transmis :

Paramètres de réponse

L'élément payerData contient les paramètres suivants.

Lors de l'authentification par protocole 3DS2, en réponse à la première requête, arrivent les paramètres suivants :

Ci-dessous sont présentés les paramètres qui doivent être présents dans la réponse, après la requête répétée de paiement et la nécessité de rediriger le client vers ACS lors de l'authentification par protocole 3DS2 :

Exemples

Exemple de requête

Exemple de première requête :

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/paymentorder.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data MDORDER=64d3b8c2-5d87-7d92-bd20-d8db011b4f5b \
  --data '$PAN=4000001111111118' \
  --data '$CVC=123' \
  --data YYYY=2030 \
  --data MM=12 \
  --data 'TEXT=TEST CARDHOLDER' \
  --data language=en \
  --data 'jsonParams={"param_1_name":"param_1_value","param_2_name":"param_2_value"}'

Exemple de seconde requête :

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/paymentorder.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data MDORDER=64d3b8c2-5d87-7d92-bd20-d8db011b4f5b \
  --data '$PAN=4000001111111118' \
  --data '$CVC=123' \
  --data YYYY=2030 \
  --data MM=12 \
  --data 'TEXT=TEST CARDHOLDER' \
  --data language=en \
  --data threeDSServerTransID=5802746e-3393-40c3-929a-dc966ebf08c6

Exemples de réponse

Exemple de réponse à la première requête :

{
  "errorCode": 0,
  "is3DSVer2": true,
  "threeDSServerTransId": "5802746e-3393-40c3-929a-dc966ebf08c6",
  "threeDSMethodURL": "https://example.com/acs2/acs/3dsMethod",
  "threeDSMethodURLServer": "example.com/3dsserver/api/v1/client/gather?threeDSServerTransID=5802746e-3393-40c3-929a-dc966ebf08c6",
  "threeDSMethodDataPacked": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9hY3F1aXJlci5jb20vM2Rzc2VydmVyL2FwaS92MS9hY3Mvbm90aWZpY2F0aW9uP3RocmVlRFNTZXJ2ZXJUcmFuc0lEPTNhZmMxNjhhLTk0YjQtNGViMy04ZTJlLTgwZjZjMTg2NjY5ZCIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiM2FmYzE2OGEtOTRiNC00ZWIzLThlMmUtODBmNmMxODY2NjlkIn0="
}

Exemple de réponse à la seconde requête :

{
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0,
  "acsUrl": "https://example.com/acs2/acs/creq",
  "is3DSVer2": true,
  "packedCReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjU4MDI3NDZlLTMzOTMtNDBjMy05MjlhLWRjOTY2ZWJmMDhjNiIsIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsIm1lc3NhZ2VWZXJzaW9uIjoiMi4xLjAiLCJhY3NUcmFuc0lEIjoiODFmZTU1ODUtZmZhOS00Y2NkLTljMjAtY2QzYWFiZDQwNTllIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0"
}

Paiement de commande (en mode MPI/3DS Server externe)

Pour utiliser la requête paymenOrder.do en mode MPI/3DS Server externe, vous devez effectuer l'authentification 3DS en utilisant votre propre serveur MPI/3DS.
Vous avez également besoin d'une autorisation supplémentaire assignée par le service support.

Paramètres de la requête

Ci-dessous sont présentés les paramètres du bloc billingPayerData (données sur l'adresse d'enregistrement du client).

Description des paramètres de l'objet shippingPayerData :

Description des paramètres de l'objet orderPayerData.

Description des paramètres de l'objet preOrderPayerData :

Description des paramètres de l'objet orderPayerData.

Valeurs possibles de tii (Pour en savoir plus sur les types de données de paiement sauvegardées pris en charge par la passerelle de paiement, lisez ici).

Ci-dessous sont présentés les paramètres du bloc clientBrowserInfo (données sur le navigateur du client).

Exemple du bloc clientBrowserInfo :

"clientBrowserInfo":
    {
		"userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
		"fingerprint":850891523,
		"OS":"Windows",
		"OSVersion":"10",
		"isMobile":false,
		"screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
		"colorDepth":24,
		"screenHeight":"864",
		"screenWidth":"1536",
		"plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
		"javaEnabled":false,
		"javascriptEnabled":true,
		"browserLanguage":"it-IT",
		"browserTimeZone":"Europe/Rome",
		"browserTimeZoneOffset":-120,
		"browserAcceptHeader":"gzip",
        "browserIpAddress":"x.x.x.x"
	}

Description des paramètres de l'objet paymentFacilitator :

Paramètres de l'élément du tableau subMerchants :

Paramètres de l'objet address :

Exemple d'objet paymentFacilitator :

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Description des paramètres de l'objet marketplace :

Description des paramètres de l'objet qui est un élément du tableau retailers.

Exemple d'objet marketplace :

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

Paramètres de réponse

Exemples

Exemple de requête

curl --request POST \\
  --url https://dev.bpcbt.com/payment/rest/paymentorder.do \\
  --header 'content-type: application/x-www-form-urlencoded' \\
  --data userName=test_user \\
  --data password=test_user_password \\
  --data MDORDER=0140dda0-71ed-7706-a61f-36bd00a7d8c0 \\
  --data '$PAN=4000001111111118' \\
  --data '$CVC=123' \\
  --data YYYY=2030 \\
  --data MM=12 \\
  --data 'TEXT=TEST CARDHOLDER' \\
  --data language=en \\
  --data 'jsonParams={
  "eci": "02",
  "cavv": "AkZO5XQAA0rhBxoaufa+MAABAAA=",
  "xid": "5010857f-8d3f-74e1-9c5a-54a000cc4110",
  "threeDSProtocolVersion": "2.2.0",
  "threeDsType": "5"
}'

Exemple de réponse

{
  "redirect": "https://dev.bpcbt.com/payment/merchants/temp/finish.html?orderId=01493844-d4d3-703f-9f7e-a73900a7d8c0",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}

Paiement de commande avec caractéristiques de transaction Industry Practice

Pour le paiement de commande avec caractéristiques de transaction Industry Practice, la requête https://dev.bpcbt.com/payment/industryPractice/paymentOrder.do est utilisée.

Lors de l'exécution de la requête, il est nécessaire d'utiliser l'en-tête : Content-Type: application/x-www-form-urlencoded

Paramètres de requête

Valeurs possibles de tii.

Le bloc jsonParams contient les champs d'informations supplémentaires pour le stockage ultérieur. Pour transmettre N paramètres, la requête doit contenir N balises jsonParams, où l'attribut name contient le nom, et l'attribut value contient la valeur (voir le tableau ci-dessous).

Paramètres de réponse

Exemples

Exemple de requête

curl --request POST \\
  --url https://dev.bpcbt.com/payment/industryPractice/paymentOrder.do \\
  --header 'content-type: application/x-www-form-urlencoded' \\
  --data '{
    "originalMdOrder":"f252eee4-5598-728a-a023-af6e09078dd0",
    "orderNumber":"testOrderNumber1",
    "tii":"IPI",
    "amount":"10",
    "username":"test_user",
    "password":"test_user_password"
}'

Exemple de réponse - Paiement réussi de commande avec caractéristiques de transaction Industry Practice

{
  "errorCode": "0",
  "errorMessage": "Successful",
  "mdOrder": "d88680c4-54e9-7115-80ae-3cc709017350",
  "actionCode": "0",
  "approvalCode": "000000",
  "rrn": "111111111113"
}

Exemple de réponse - Paiement non réussi de commande avec caractéristiques de transaction Industry Practice (le processeur a retourné une erreur)

{
  "errorCode": "5",
  "errorMessage": "Unsuccessful",
  "mdOrder": "d88680c4-54e9-7115-80ae-3cc709017350",
  "actionCode": "116",
  "approvalCode": "000000",
  "rrn": "111111111113"
}

Paiement non réussi de commande avec caractéristiques de transaction Industry Practice (par exemple, erreur de validation)

{
  "errorCode": "5",
  "errorMessage": "Operation is not allowed for original order"
}

Paiement instantané

Requête utilisée pour l'enregistrement de commande et le paiement simultané pour celle-ci – https://dev.bpcbt.com/payment/rest/instantPayment.do.

Lors de l'exécution de la requête, il est nécessaire d'utiliser l'en-tête : Content-Type: application/x-www-form-urlencoded

Paramètres de requête

Description des paramètres dans l'objet orderBundle :

Description des paramètres dans l'objet customerDetails :

Description des paramètres dans l'objet deliveryInfo :

Description des paramètres dans l'objet cartItems :

Description des paramètres dans l'objet items :

Description des paramètres dans l'objet itemDetails :

Description des paramètres dans l'objet itemDetailsParams :

Description des paramètres dans l'objet quantity :

Valeurs possibles de tii (Pour en savoir plus sur les types de données de paiement sauvegardées pris en charge par la passerelle de paiement, lisez ici).

Ci-dessous sont présentés les paramètres du bloc billingPayerData (données sur l'adresse d'enregistrement du client).

Description des paramètres de l'objet shippingPayerData :

Description des paramètres de l'objet preOrderPayerData :

Description des paramètres de l'objet orderPayerData.

Ci-dessous sont présentés les paramètres du bloc clientBrowserInfo (données sur le navigateur du client).

Exemple du bloc clientBrowserInfo :

"clientBrowserInfo":
    {
		"userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
		"fingerprint":850891523,
		"OS":"Windows",
		"OSVersion":"10",
		"isMobile":false,
		"screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
		"colorDepth":24,
		"screenHeight":"864",
		"screenWidth":"1536",
		"plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
		"javaEnabled":false,
		"javascriptEnabled":true,
		"browserLanguage":"it-IT",
		"browserTimeZone":"Europe/Rome",
		"browserTimeZoneOffset":-120,
		"browserAcceptHeader":"gzip",
        "browserIpAddress":"x.x.x.x"
	}

Description des paramètres de l'objet paymentFacilitator :

Paramètres de l'élément du tableau subMerchants :

Paramètres de l'objet address :

Exemple d'objet paymentFacilitator :

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Description des paramètres de l'objet marketplace :

Description des paramètres de l'objet qui est un élément du tableau retailers.

Exemple d'objet marketplace :

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

Paramètres de réponse

Quand l'authentification utilisant le protocole 3DS v2.0 est nécessaire, les paramètres suivants seront obtenus en réponse à la requête :

L'élément payerData contient les paramètres suivants.

Le bloc orderStatus contient les éléments suivants.

Les paramètres du bloc tokenizationInfo (données sur la tokenisation de carte) sont énumérés ci-dessous.

Exemple du bloc tokenizationInfo :

"tokenizationInfo": {
	  "tokenId": "8d577a01-55f7-45d4-add5-bfe0e8e6c571",
	  "tokenizationProvider": "vts",
	  "panReference": "f441492a-5b0a-453d-af97-e897e1148dc5",
	  "dpan": "5435982500356335",
	  "tokenExpiry": "202912"
	}

• Si errorCode <> 0, la transaction doit être rejetée.
• Si errorCode = 0 et OrderStatus n'est pas (1,2), la transaction doit être rejetée.
• Si errorCode = 0 et OrderStatus = 1 ou 2 et acsUrl a une valeur null, la transaction est confirmée.
• Si errorCode = 0 et OrderStatus = 0, et acsUrl n'est pas null, la transaction doit être rejetée.
• Si errorCode = 0 et OrderStatus = 0 et acsUrl n'est pas null, un scénario 3DS doit être initié.

Exemples

Exemple de requête

curl --request POST \
--url  https://dev.bpcbt.com/payment/rest/instantPayment.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data amount=100 \
--data currency=978 \
--data description=my_first_order \
--data orderNumber=1218637308 \
--data pan=4000001111111118  \
--data cvc=123 \
--data expiry=203012 \
--data cardHolderName="TEST CARDHOLDER" \
--data email="demo@example.com" \
--data phone="+449998887766" \
--data language=en \
--data returnUrl=https://mybestmerchantreturnurl.com \
--data failUrl=https://mybestmerchantreturnurl.com

Exemple de réponse

{
    "errorCode": "0",
    "orderId": "eee72f6e-b980-79c5-92e8-6f4200b1eae0",
    "info": "Your order is proceeded, redirecting...",
    "redirect": "https://www.test.com/payment/merchants/gateway/finish.html?orderId=eee72f6e-b980-79c5-92e8-6f4200b1eae0&lang=en",
    "orderStatus": {
        "expiration": "202412",
        "cardholderName": "TEST CARDHOLDER",
        "depositAmount": 100,
        "currency": "978",
        "approvalCode": "123456",
        "authCode": 2,
        "originalActionCode": "S1",
        "rrn": "311489272111",
        "ErrorCode": "0",
        "ErrorMessage": "Success",
        "OrderStatus": 2,
        "OrderNumber": "2011",
        "Pan": "500000**1115",
        "Amount": 100,
        "Ip": "x.x.x.x"
    }
}

Paiement MOTO

Pour effectuer des paiements MOTO, utilisez la méthode https://dev.bpcbt.com/payment/rest/motoPayment.do.

Lors de l'exécution de la requête, il est nécessaire d'utiliser l'en-tête : Content-Type: application/x-www-form-urlencoded

Paramètres de requête

Ci-dessous sont présentés les paramètres du bloc billingPayerData (données sur l'adresse d'enregistrement du client).

Description des paramètres de l'objet shippingPayerData :

Description des paramètres de l'objet preOrderPayerData :

Description des paramètres de l'objet orderPayerData.

Paramètres de réponse

L'élément payerData contient les paramètres suivants.

Exemples

Exemple de requête

curl --request POST \
--url https://dev.bpcbt.com/payment/rest/motoPayment.do \
--header 'content-type: application/x-www-form-urlencoded' \
  --data amount=2000 \
  --data currency=978 \
  --data userName=test_user \
  --data password=test_user_password \
  --data returnUrl=https://mybestmerchantreturnurl.com \
  --data description=my_first_order \
  --data pan=4000001111111118 \
  --data expiry=203012 \
  --data cvc=123 \
  --data cardholder="TEST CARDHOLDER" \
  --data language=en

Exemple de réponse - paiement réussi

{
   "errorCode":"0",
   "success":true,
   "mdOrder":"088433e9-e34d-769e-9366-696200a7d8c0",
   "orderNumber":"62001"
}

Redirection vers ACS (simplifiée)

Si 3-D Secure est requis, alors après avoir reçu la réponse à la demande de paiement, le client doit être redirigé vers ACS. Dans ce cas, la réponse à la demande de paiement contient le paramètre acsUrl, qui sera utilisé pour la redirection.

La requête https://dev.bpcbt.com/payment/acsRedirect.do?orderId={orderId} permet de rediriger le client vers la page d'authentification ACS de manière simplifiée - en utilisant simplement le paramètre orderId, obtenu après l'enregistrement de la commande.

Il est également possible de rediriger le client vers ACS à l'aide d'une requête POST (redirection habituelle). La description de cette méthode est disponible ici.

Sans aucune autre action requise de la part du client, la passerelle de paiement le redirige vers la page ACS, où le client s'authentifie.

Ensuite, selon le résultat de l'authentification, le client est redirigé vers l'URL suivante :

• si l'authentification s'est déroulée avec succès - returnUrl avec le paramètre orderId ajouté ;
• si l'authentification a échoué - failUrl (ou returnUrl, si failUrl n'a pas été transmis) avec le paramètre orderID ajouté.

Pour rediriger le client vers ACS, utilisez l'URL suivante :

https://dev.bpcbt.com/payment/acsRedirect.do?orderId={Numéro de commande dans la passerelle de paiement}

Paramètres de requête

Paramètres de réponse

Exemple

Exemple de requête

curl -X GET https://dev.bpcbt.com/payment/acsRedirect.do?orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1

Exemple d'URL de redirection

https://mybestmerchantreturnurl.com/?orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1

Portefeuilles

Enregistrement de commande Apple Pay

Pour l'enregistrement et le paiement de commande, la méthode https://dev.bpcbt.com/payment/applepay/payment.do est utilisée.

Lors de l'exécution de la requête, il est nécessaire d'utiliser l'en-tête : Content-Type: application/json

Paramètres de requête

Paramètres supplémentaires définissant le type de liaison créée et transmis dans additionalParameters :

Valeurs possibles tii (Pour en savoir plus sur les types de liaisons pris en charge par la passerelle de paiement, lisez ici).

Description des paramètres de l'objet paymentFacilitator :

Paramètres de l'élément du tableau subMerchants :

Paramètres de l'objet address :