Descripción general

Puede utilizar nuestro API de vendedor para crear el escenario de pago que necesite. Por ejemplo, puede crear su propia página de pago completamente configurada y conectarla a nuestra pasarela de pago.

Puede descargar la colección de solicitudes API para Postman para probar las funcionalidades básicas del API. Asegúrese de enviar las solicitudes como POST con atributos en el cuerpo de la solicitud.

Descargar colección Postman

Obligatoriedad de parámetros

La obligatoriedad de presencia del parámetro en la solicitud/respuesta puede tomar los siguientes valores:

• Obligatorio - el parámetro debe estar presente siempre. En caso de ausencia del valor se requiere transmitir un valor vacío dependiendo del formato;
• No obligatorio - el parámetro puede tanto estar presente como ausente, mientras que su presencia redundante no llevará a un error del sistema;
• Condición - el parámetro puede tanto estar presente (ser obligatorio) como ausente dependiendo de una o varias condiciones.

La obligatoriedad de transmisión del parámetro en la descripción de solicitud/respuesta se indica en la columna del mismo nombre "Obligatoriedad".

Autenticación

Para la autenticación del comerciante en la pasarela de pagos se pueden utilizar dos métodos.

• Utilizando el login y contraseña del usuario API del comerciante (cuenta con sufijo -api), obtenido durante el registro. Estos valores se transmiten en los parámetros userName y password respectivamente (ver tabla a continuación).

• Con ayuda de un token especial - su valor puede solicitarlo en el servicio de soporte técnico. En las solicitudes su valor se transmite en el parámetro token (ver tabla a continuación).

URL para llamadas API

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

Errores

Códigos de estado HTTP:

• 200 - en caso de llamadas API del gateway de pago es necesario analizar JSON de la respuesta para determinar si el procesamiento de la transacción fue exitoso o no. El éxito se indica por:
  - valor del parámetro success igual a true
  - valor del parámetro errorCode igual a 0
  Si están presentes ambos parámetros, success tiene prioridad sobre errorCode.

• 400 - ocurrió un error interno en el sistema.

• 404 - error en la llamada API - URL incorrecta (no existe).

• 429 - este código significa que el sistema está sobrecargado. Muy frecuentemente la razón principal es que se alcanzó el límite de solicitudes por segundo o el límite de solicitudes simultáneas. Pero también puede estar relacionado con que el sistema en general está sobrecargado (independientemente de sus solicitudes).

• 500 o 502 - este código significa que algo salió mal de nuestro lado.

Si la solicitud relacionada con el pago del pedido se procesó exitosamente, esto aún no significa que el pago mismo fue exitoso.

Para determinar si el pago fue exitoso o no, puede referirse a la descripción de la solicitud utilizada. También para determinar el estado del pago siempre se puede usar el algoritmo descrito a continuación

1. Hacer una llamada getOrderStatusExtended.do;
2. Verificar el campo orderStatus en la respuesta: el pedido se considera pagado solo si el valor orderStatus es igual a 1 o 2.

Firma de solicitud API

En algunos casos para garantizar el intercambio seguro de datos puede ser necesario implementar una firma asimétrica de solicitud. Generalmente este requisito se aplica solo si está ejecutando solicitudes P2P/AFT/OCT.

Para tener la posibilidad de firmar solicitudes, necesita ejecutar los siguientes pasos:

1. Cree y cargue un certificado.
2. Calcule hash y firma, usando su clave privada, y transmita el hash generado (X-Hash) y valor de firma (X-Signature) en el encabezado de la solicitud.

Estos pasos están descritos detalladamente abajo.

Creación y carga de certificado

1. Cree una clave privada RSA de 2048 bits. El método de generación depende de la política de confidencialidad en su empresa. Por ejemplo, puede hacer esto con ayuda de OpenSSL:

   openssl genrsa -des3 -out private.key 2048

2. Cree un CSR público (solicitud de firma de certificado), usando la clave privada generada:

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

3. Cree un certificado, usando la clave privada generada y CSR. Ejemplo de formación de certificado por 5 años:

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

4. Cargue el certificado generado en el Gabinete Personal. Para esto vaya a Certificados de billeteras > Merchant API, presione Agregar certificado y cargue el certificado público generado.
   

Cálculo de hash y firma

1. Calcule el hash SHA256 del cuerpo de la solicitud de la siguiente manera:

   1. Use el cuerpo de la solicitud en forma de cadena (en nuestro ejemplo esto es amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api).
   2. Calcule el hash SHA256 de esta cadena en bytes sin procesar.
   3. Convierta los bytes sin procesar a codificación base64.

2. Genere una firma para el hash SHA256 calculado con ayuda del algoritmo RSA, usando la clave privada.

En nuestro ejemplo usamos la siguiente clave privada con contraseña 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-----

Obtenemos la firma: pJ/gM4PR1/mKGuIxMvTl5pYDDjJslb0BcXFnIxijFn5qKdPd7W+2ueoctziU7omnkYp01/BlracukH1GOPWMSO+9zKuTDdFueFm1utsS0zaPFU+dmc1niGDRWE0CbCXcti/rGSTDPsnR58mwqgVkbCWxKyCDtuo5LxiKPK9mzgWTUuJ8LX6f6u42MURi5tRG6a9dc8l/+J94g0YOk911R6Lqv2jcluEvZ9ZeMMt8hyxowb0eDaCHlussu2CAyqpE9V+EUAc81Jkwv96MMSsA6UnFwEaCV/k+kwYd0jHCx94m2yWX734p9cWsBW7Fr5F0zox9Yck4GOjqe9nJMMB9jQ== 3. Ahora debe pasar el hash generado (X-Hash) y el valor de la firma (X-Signature) en el encabezado de la solicitud. La solicitud se verá así:

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 solicitud debe cumplir con los siguientes requisitos:

• Todos los parámetros de la solicitud se incluyen en el cuerpo de la solicitud (no en la URL)

• Si los parámetros de la solicitud se pasan en formato JSON, debe usarse el siguiente encabezado:

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

• Si los parámetros de la solicitud se pasan en formato Query (por ejemplo, parameterA=valueA&parameterB=valueB), debe usarse el siguiente encabezado:

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

• La solicitud contiene el usuario y contraseña correctos del usuario API.

• El encabezado X-Hash contiene el hash SHA256 del cuerpo de la solicitud (se calcula en el Paso 1).

• El encabezado X-Signature contiene la firma para el hash SHA256, calculada usando el algoritmo RSA con la clave privada (se genera en el Paso 2).

Ejemplo de código Java

A continuación se muestra un ejemplo de código Java que carga la clave privada, calcula el hash SHA256, lo firma con la clave privada con contraseña 12345, y luego envía la solicitud register.do correcta:

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 {

    // Este ejemplo no está listo para producción. Solo muestra cómo usar firmas en API.
    public static void main(String[] args) throws Exception {
        // cargar clave privada desde 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);

        // Firmar
        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();

        // Enviar
        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);
        }
    }
}

Ejemplo de código Python

A continuación se muestra un ejemplo de código Python que genera la firma:

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)

El archivo de clave privada para el ejemplo de Python debe tener el formato:

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

Registro de pedido

Registro de pedido

Para el registro de pedido se utiliza la solicitud https://dev.bpcbt.com/payment/rest/register.do.

Al ejecutar la solicitud es necesario utilizar el encabezado: Content-Type: application/x-www-form-urlencoded

Parámetros de solicitud

A continuación se muestran los parámetros del bloque billingPayerData (datos sobre la dirección de registro del cliente).

Descripción de los parámetros del objeto shippingPayerData:

Descripción de los parámetros del objeto preOrderPayerData:

Descripción de los parámetros del objeto orderPayerData.

Descripción de parámetros en el objeto orderBundle:

Descripción de parámetros en el objeto customerDetails:

Descripción de los parámetros en el objeto deliveryInfo:

Descripción de parámetros en el objeto cartItems:

Descripción de parámetros en el objeto items:

Descripción de los parámetros en el objeto quantity:

Descripción de parámetros en el objeto itemDetails:

Descripción de parámetros en el objeto itemDetailsParams:

Descripción de los parámetros del objeto paymentFacilitator:

Parámetros del elemento de la matriz subMerchants:

Parámetros del objeto address:

Ejemplo del objeto 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"
      }
    }
  ]
}

Parámetros de respuesta

Ejemplos

Ejemplo de solicitud

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"}'

Ejemplo de respuesta - éxito

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

Ejemplo de respuesta - error

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

Registro de pedido con preautorización

Para la solicitud de registro de pedido con preautorización se utiliza el método https://dev.bpcbt.com/payment/rest/registerPreAuth.do.

Al ejecutar la solicitud es necesario utilizar el encabezado: Content-Type: application/x-www-form-urlencoded

Parámetros de solicitud

A continuación se muestran los parámetros del bloque billingPayerData (datos sobre la dirección de registro del cliente).

Descripción de los parámetros del objeto shippingPayerData:

Descripción de los parámetros del objeto preOrderPayerData:

Descripción de los parámetros del objeto orderPayerData.

Descripción de parámetros en el objeto orderBundle:

Descripción de parámetros en el objeto customerDetails:

Descripción de los parámetros en el objeto deliveryInfo:

Descripción de parámetros en el objeto cartItems:

Descripción de parámetros en el objeto items:

Descripción de los parámetros en el objeto quantity:

Descripción de parámetros en el objeto itemDetails:

Descripción de parámetros en el objeto itemDetailsParams:

Descripción de los parámetros del objeto paymentFacilitator:

Parámetros del elemento de la matriz subMerchants:

Parámetros del objeto address:

Ejemplo del objeto 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"
      }
    }
  ]
}

Parámetros de respuesta

Ejemplos

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Pagos directos

Pago del pedido

Para el pago de un pedido previamente registrado se utiliza la solicitud https://dev.bpcbt.com/payment/rest/paymentorder.do.
La solicitud se utiliza en modo MPI/3DS Server interno, para esto no se requiere la presencia de permisos adicionales y/o certificaciones.
La solicitud se utiliza en modo MPI/3DS Server externo si tiene un contrato con un sistema de pago internacional o un certificado que permite realizar autenticación 3DS de forma independiente. Esto significa que puede utilizar su propio MPI/3DS Server para la autenticación del cliente utilizando la tecnología 3D Secure. Información adicional sobre el pago con MPI/3DS Server propio está disponible aquí.

Al ejecutar la solicitud es necesario utilizar el encabezado: Content-Type: application/x-www-form-urlencoded

Pago del pedido (MPI/3DS Server interno)

El pago del pedido ocurre con la transmisión de datos de pago de tarjeta, así como con el uso de la tecnología de autenticación 3DS (la aplicación de autenticación se regula por configuraciones reguladas por el servicio de soporte).

Parámetros de solicitud

A continuación se muestran los parámetros del bloque billingPayerData (datos sobre la dirección de registro del cliente).

Descripción de los parámetros del objeto shippingPayerData:

Descripción de los parámetros del objeto preOrderPayerData:

Descripción de los parámetros del objeto orderPayerData.

Valores posibles de tii (Lea más sobre los tipos de datos de pago guardados soportados por la pasarela de pagos aquí).

A continuación se presentan los parámetros del bloque clientBrowserInfo (datos sobre el navegador del cliente).

Ejemplo del bloque 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"
    }

Descripción de los parámetros del objeto paymentFacilitator:

Parámetros del elemento de la matriz subMerchants:

Parámetros del objeto address:

Ejemplo del objeto 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"
      }
    }
  ]
}

En la autenticación por protocolo 3DS2 también se transmiten los siguientes parámetros:

Parámetros de respuesta

El elemento payerData contiene los siguientes parámetros.

En la autenticación por protocolo 3DS2 en respuesta a la primera solicitud llegan los siguientes parámetros:

A continuación se muestran los parámetros que deben estar presentes en la respuesta, después de la solicitud repetida de pago y la necesidad de redirigir al cliente al ACS en la autenticación por protocolo 3DS2:

Ejemplos

Ejemplo de solicitud

Ejemplo de primera solicitud:

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"}'

Ejemplo de segunda solicitud:

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

Ejemplos de respuesta

Ejemplo de respuesta a la primera solicitud:

{
  "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="
}

Ejemplo de respuesta a la segunda solicitud:

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

Pago de pedido (en modo MPI/3DS Server externo)

Para usar la solicitud paymenOrder.do en modo MPI/3DS Server externo necesita realizar la autenticación 3DS usando su propio servidor MPI/3DS.
También necesita un permiso adicional, asignado por el servicio de soporte.

Parámetros de solicitud

A continuación se muestran los parámetros del bloque billingPayerData (datos sobre la dirección de registro del cliente).

Descripción de los parámetros del objeto shippingPayerData:

Descripción de los parámetros del objeto orderPayerData.

Descripción de los parámetros del objeto preOrderPayerData:

Descripción de los parámetros del objeto orderPayerData.

Valores posibles de tii (Lea más sobre los tipos de datos de pago guardados soportados por la pasarela de pagos aquí).

A continuación se presentan los parámetros del bloque clientBrowserInfo (datos sobre el navegador del cliente).

Ejemplo del bloque 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"
    }

Descripción de los parámetros del objeto paymentFacilitator:

Parámetros del elemento de la matriz subMerchants:

Parámetros del objeto address:

Ejemplo del objeto 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"
      }
    }
  ]
}

Parámetros de respuesta

Ejemplos

Ejemplo de solicitud

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"}'

Ejemplo de respuesta

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

Pago del pedido con características de transacción Industry Practice

Para el pago del pedido con características de transacción Industry Practice se utiliza la solicitud https://dev.bpcbt.com/payment/industryPractice/paymentOrder.do.

Al ejecutar la solicitud es necesario utilizar la cabecera: Content-Type: application/x-www-form-urlencoded

Parámetros de solicitud

Valores posibles de tii.

El bloque jsonParams contiene campos de información adicional para almacenamiento posterior. Para transmitir N parámetros, en la solicitud deben encontrarse N etiquetas jsonParams, donde el atributo name contiene el nombre, y el atributo value contiene el valor (ver tabla a continuación).

Parámetros de respuesta

Ejemplos

Ejemplo de solicitud

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"
}'

Ejemplo de respuesta - Pago exitoso del pedido con características de transacción Industry Practice

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

Ejemplo de respuesta - Pago no exitoso del pedido con características de transacción Industry Practice (el procesamiento devolvió error)

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

Pago no exitoso del pedido con características de transacción Industry Practice (por ejemplo, error de validación)

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

Pago instantáneo

Solicitud utilizada para registrar un pedido y realizar el pago simultáneamente – https://dev.bpcbt.com/payment/rest/instantPayment.do.

Al ejecutar la solicitud es necesario usar el encabezado: Content-Type: application/x-www-form-urlencoded

Parámetros de solicitud

Descripción de parámetros en el objeto orderBundle:

Descripción de parámetros en el objeto customerDetails:

Descripción de los parámetros en el objeto deliveryInfo:

Descripción de parámetros en el objeto cartItems:

Descripción de parámetros en el objeto items:

Descripción de parámetros en el objeto itemDetails:

Descripción de parámetros en el objeto itemDetailsParams:

Descripción de los parámetros en el objeto quantity:

Valores posibles de tii (Lea más sobre los tipos de datos de pago guardados soportados por la pasarela de pagos aquí).

A continuación se muestran los parámetros del bloque billingPayerData (datos sobre la dirección de registro del cliente).

Descripción de los parámetros del objeto shippingPayerData:

Descripción de los parámetros del objeto preOrderPayerData: