Description générale

Vous pouvez utiliser notre API marchand 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. Assurez-vous d'envoyer les demandes comme POST avec les attributs dans le corps de la demande.

Télécharger la collection Postman

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 s'est déroulé avec succès.

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 déterminer le statut du paiement, il est toujours possible d'utiliser l'algorithme décrit ci-dessous

1. Faire un appel 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 :

   1. 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).
   2. Calculez le hash SHA256 de cette chaîne en octets bruts.
   3. Convertissez les octets bruts en encodage base64.

2. 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 :

-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,C502560EDE8F82B7
O4+bY1Q1ZcXFLDGVE8s9G2iVISHR/c/IMZKZEjkBED/TbuOCUGVjcav2ZaZO2dO0 lm771N6JNB01uhJbTHScVQ6R0UnGezHFTcsJlAlBa9RQyOwujs4Pk6riOGnLliIs urnTXD0oskBR1wLRA2kp8+V0UPOAMXQaoLxFGE/o8taDGSrkyIcYTBoh9o7ZBxvO SqUWAt2vPbGVyc6XspyuVtgHgEctaJO+E26QTweqdpN5JITF+fDFPNwUrFHoho4N pxpKRWbiCJSpbvbsvhdizkmfgvRw+qYJvTirF3JTfGr14DttudFwjm7sNrr0JILR XPKDUhRyWjkthZM+oDjF2HwISAGkbxcpn4PU7Tywq0uax+5KCQQn2uz4jLM2P6+9 000cvVLwhMnoUdOxuISRXeOcOWVyTO1mPfKiWnHaoO4yS3Y36OCIOe9RHGP8TTmq acb3LUIF30eQyk3KxH/tUB0ScPDKEKMiww13/Kcfr0JkdIe/BWCvV+hSQm38TLQe bTFy+wnD9kHACCwTSVVSOO+rHgJGVIyLgnpClZKWQyyJ4clH7/cORA7mTmp85Ckx IjV5Egu0bPPUMudOB5BnQ4u85RnqXavasgrLRA3JZM4+Jzl8MNy/fsFXnVBQLJJC Wlz/B7S7W8sabRogFuiqkkPmXE/QcpdKQoY3yh748QqMSl8vkA6WgndyYv1EnDDl jA5j7vSf0wKI8BHgdHBEWuEjn3X/s0S/BiPPI6puboYY90tYVJTWSQCR83QrMF3N BIcMu4+RIYu6GWnPx9npZpt0858c670ZII56np24iMse3qgHCOZxsGOenK2x7ta6 163gvaD8bu8xoeQcGVfd6IMbXWVb0+z1hvWR5HWHSalof4lMzZrDsQDKc2UA0ygh hA1+VAl1MAEHVLNCCmyG1SwRwg1PI7FfftW7YARngCZRWkJ1haj1fgy7rtYolrdv lEz/vjFD6diABx67omGgfiJhWdiKIlzsYlX1SW7yaik/Uxf1j8gTFwY34y8ekVd9 6pQTzV2V/4a48ELZl4LvelLWyt1AB3AR+/fM7YG6LYIqlo+qnLtro7Bqu8RNTNRP wcWCd04r/20ulFWMIH8pVa60C98pSdOXriWEI1KDLc0E/fCdhjW2kL+FTPLC7ORe cuzmfI27+06P/BvLZq/FAVBrDAmkioKwe6XYzTjpK1p5jZ3IrNwjAiasY1MNxCRy 5ufhQwkW//d+VUdU5m8Sm30/kXe9UkxMaetXgzPxbB7+5QFFr0bi7D1MjIrJNtTx 5g5E+UfOhqrp8ztBht9csQeFYSYabyyGX4Lh7ymVWrKCVdHlJib3M36nvOjpV/lA zf35sxFz9kaQqNK7xJdQ9Bx6TBUzLjpYhNry37vKk+SIB6Weo+LJ99mALMeX79CB osRqZqX5yrZhaQ8bbpo981nvLy5xFnpRqCuSWVZrVMBq3LQLaOvaCeyGC0V+ZN0C CU6lHlR6XQqd/IjoEN8+8aiVp6Ubw8FuD28TDaEvCltrX3ARL0xFpABsa42LgV1F 09Vi+ju7SSNDvbezN8q0EILq9xp/zNCVhMpyRCIXBq9fzHkyCZ5qMw==
-----END RSA PRIVATE KEY-----

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 :

-----BEGIN PRIVATE KEY-----
MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDdpOwhY/p9x0WmBd3HaDfCD+KYung3M8Cxrw0ozF+h//GltRdnkJD7ejsBDB6/YeIVXZeU3AyqWvsi/IfeHwnokGxVg2IMw8OPacY6o1x7W0EQtfRoZa2Cn2PMCpZhEHlIVraXZDDeg4HY26YP0FZxRbpNnpXhGbiop+Bq0wHeE3JIk53cRmwYhxdxMmvFpgNd6C3dYhmnQqLv6WSpVNDFbQxBVU+JDNyR9FQwB1dU2MadgYwFJnEssbhUkM+sXAC4Wv3qhcZek6MWeWsbFIIlyTPa1T3yrWSXIb4qFJEro4pRMmwQ72qG02p8EPx1tlveQo22TojV9WbTPtaVwQtxAgMBAAECggEBANheTGkYOYsZwgMdzPAB7BSU/0bLGdoBuoV6dqUyRdVWjqaOTwe519625uzR0R5RRqxGzlfyLKcM5Aa2cUhEEp8mhatA87G0Va8lue66VOjTH4RZq/tR7v0J7hlc6Ipe05brl5nYo+BEjriNS+I6Jnizcfid7IBvZJW4NFr0G+mWTxl2BhUK/Mk895n8hg9QtgSRoMNO4jK2f0vJrH4hBHehTYpjHx+QhbUyIvsp60bEnNOXzl054TuWBVCYAQHcHTTZowWMY0s1Z0kGNxwsqQm4amW/v+1EqCF4fjRDrU6v/kjDKxGFx9GJUktKZAe2T8e2LySjgGpJO5g4AdxIVpUCgYEA8x9te+i2ijxoS3kIUSwXaPq5EdKGWGl5mW8KZHzmt9LB/CqTKvSOiDkMGoAx/76t5QmKOYojP+Vsc2XdfQfhT6d00MGTdiPBd+8//MmQQ07/D1/PV58Jd1O8bQFU4fZCMpQl/8Azp9ix/NEx0sHDv2KigLfFMBVGeJxwSoU2JzMCgYEA6WJC0BDTA9vx+i+p9i/41f7ozpQuYey5sxdZa2emOSYen6ptxUFLAYXMxVDaBJ89PMUa8GzWoXHhgXzbuRJk74IzUhWgPpneS4HTr5KDStJh2TqWWVLwEIgLwxvtuw0i9uSEU64D/Czzm801lrOhVgmZsWwNpFtP8ujz0v84MssCgYEA1P4YhbB3kx2e5VfwgGSXUcIttr5wMi6deF0+hpCh9DNw/QEzkzNTV2ZbAzCCHSKo5/n2nbg2b3kIDQUWCL6JlqYHAghErwBeMztoHIddmoovjAGM/Z93xJGYhwremWOL1RHTRH7XAlomfG2tL43PdvDrmsbkut44sdujyLVxnt8CgYBirK3tBMADKLJVgmOM+FlwORe7iAFYW9tj8iJXe/pWvVxDS66fsOyCl0ytvHKBc8ZTdE7gilPw7JJYyi6oQDO25EjIkuYusaXALQMQf5TNRMgkLVY2LA/eHXdDpgJMjNBUrOeZ7cA3ldXl8MyQjCBRnTuDPVlDPWw/GulEM65SIwKBgQDIEv8XK2YBkZrr+0fZSFTQAeK4R7Ve3z4hbpHhJi41YanCNaEWoeYAuQd6/b/QLwABllvfJBDYCNnF8heUxqISpyWd+FZ8nhZtxBoKj5l80czTcutIz/M+ETcvl8FqnMBsoCdp1wodqaLkOx6DIldgKLze6AqKXl5lHUsU4mvVqg==
-----END PRIVATE KEY-----

Enregistrement de commande

Enregistrement de commande

Pour l'enregistrement de commande, la requête https://dev.bpcbt.com/payment/rest/register.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

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 :

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 features=FORCE_TDS \
  --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 la 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 :

Paramètres de la réponse

Exemples

Exemple de requête

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 la commande

Pour le paiement d'une commande préalablement 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 mener 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 la commande (MPI/3DS Server interne)

Le paiement de la commande se fait 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égulée par les paramètres, régulés par le service de 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 preOrderPayerData :

Description des paramètres de l'objet orderPayerData.

Valeurs possibles de tii (Pour plus de détails sur les types de liaisons supportés 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 de 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"
    }

Lors de l'authentification par 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, les paramètres suivants arrivent :

Ci-dessous sont présentés les paramètres qui doivent être présents dans la réponse, après une 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 deuxième 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 deuxième 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, attribuée par le service de 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 orderPayerData.

Description des paramètres de l'objet preOrderPayerData :

Description des paramètres de l'objet orderPayerData.

Valeurs possibles de tii (Pour plus de détails sur les types de liaisons supportés 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 de 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"
    }

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", "authenticationTypeIndicator": "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 enregistrer une commande et effectuer simultanément le paiement – 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 plus de détails sur les types de liaisons supportés 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 de 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"
    }

Paramètres de réponse

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

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

Le bloc orderStatus contient les éléments suivants.