Vinculaciones y tipos de transacciones

En esta sección se describen los tipos de transacciones soportados por vinculaciones.

Tipos de vinculaciones

La pasarela de pagos permite crear y utilizar tres tipos de vinculaciones:

Común – para pagos no relacionados con ningún plan o cronograma. Por ejemplo, cuando el comprador hace un nuevo pedido y lo paga utilizando datos de tarjeta guardados anteriormente.
Recurrente – para pagos que ocurren según un cronograma fijo. Por ejemplo, pagos mensuales por servicios públicos.
Cuotas – al pagar en cuotas, cuando el cliente paga la factura en pequeñas partes durante un período de tiempo fijo de acuerdo con un plan de pagos.

Una tarjeta puede tener vinculaciones de diferentes tipos. Además, la tarjeta puede tener varias vinculaciones para diferentes planes de cuotas.

Tipo de transacciones

Las transacciones por vinculaciones pertenecen a uno de dos grupos dependiendo del iniciador de la transacción:

CIT (cardholder-initiated transactions) – transacciones de comercio electrónico en las que el titular de la tarjeta participa en el pago. Este grupo incluye 4 tipos de transacciones:
- C/CI – transacción iniciadora con guardado de vinculación común para pagos futuros.
- RI – transacción iniciadora con guardado de vinculación para pagos recurrentes.
- II – transacción iniciadora con guardado de vinculación para pagos en cuotas.
- F – transacción no programada, realizada por el titular de la tarjeta utilizando vinculación común.
MIT (Merchant-initiated Transactions) – transacciones de comercio electrónico realizadas por el vendedor sin participación del titular de la tarjeta. En este grupo entran 3 tipos de transacciones:
- U – transacción no programada utilizando vinculación común. Por ejemplo, aplicación de multas. Tenga en cuenta que para tal operación no hay verificación CVC o 3DS, ya que el titular de la tarjeta no participa en ella y no puede introducir ningún dato.
- R – transacción recurrente subsiguiente utilizando vinculación recurrente.
- I – transacción subsiguiente en cuotas utilizando vinculación para cuotas.

El tipo de transacción debe pasarse en el parámetro tii de las solicitudes API de pagos. Más detalles sobre los valores del parámetro tii lea aquí.

Gestión de vinculaciones a través de API

A continuación se presentan ejemplos de creación y uso de diferentes tipos de vinculaciones a través de API:

Vinculaciones ordinarias
Vinculaciones recurrentes
Vinculaciones para financiamiento

Vinculaciones ordinarias

Creación de vinculación ordinaria

Para crear una vinculación ordinaria, ejecute la siguiente secuencia de solicitudes:

Ejecute la solicitud register.do con el parámetro clientId, obtenga en respuesta orderId y formUrl.
Transfiera el valor obtenido orderId en el parámetro MDORDER de la solicitud paymentorder.do.

Como resultado se creará una vinculación para el cliente con el clientId inicialmente indicado. Puede ejecutar la solicitud getBindings.do para asegurarse de que la vinculación se haya creado.

Ejemplo de solicitud paymentorder.do:

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/paymentorder.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '$CVC=123' \
  --data '$EXPIRY=203012' \
  --data '$PAN=4000001111111118' \
  --data 'TEXT=TEST CARDHOLDER' \
  --data MDORDER=59e00106-1f69-76a7-b893-b27c00b4f820 \
  --data userName=test_user \
  --data password=test_user_password

{
  "redirect": "https://dev.bpcbt.com/payment/merchants/pay/finish.html?orderId=59e00106-1f69-76a7-b893-b27c00b4f820&lang=en",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}

Pago con vinculación ordinaria

Para el pago del pedido con vinculación ordinaria utilice la siguiente secuencia de solicitudes:

Ejecute la solicitud register.do con el parámetro clientId → obtenga en respuesta orderId.
Obtenga la lista de vinculaciones mediante la solicitud getBindings.do con el mismo valor clientId y con bindingType=C → obtenga en la respuesta bindingId.
Ejecute la solicitud paymentOrderBinding.do. Transfiera el valor orderId (obtenido en el Paso 1) en el parámetro mdOrder, así como transfiera el bindingId obtenido. Valores disponibles de tii: F, U.

Como resultado el pedido será pagado mediante la vinculación con el bindingId indicado.

Ejemplo de solicitud paymentOrderBinding.do:

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/paymentOrderBinding.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data mdOrder=24c3d392-4c60-7f0b-9ff5-b00100b4f820 \
  --data ip=127.0.0.1 \
  --data cvc=123 \
  --data bindingId=b83317e0-1679-7d85-b375-a63200b4f820 \
  --data userName=test_user \
  --data password=test_user_password \
  --data language=en \
  --data tii=F

{
  "redirect": "https://dev.bpcbt.com/payment/merchants/pay/finish.html?orderId=24c3d392-4c60-7f0b-9ff5-b00100b4f820&lang=en",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}

Vinculaciones recurrentes

Creación de vinculación recurrente

Para crear una vinculación recurrente, ejecute la siguiente secuencia de solicitudes:

Ejecute la solicitud register.do con el parámetro clientId, obtenga en respuesta orderId y formUrl
Transfiera el valor obtenido orderId en el parámetro MDORDER de la solicitud paymentorder.do. Es necesario transferir parámetros adicionales recurringFrequency y recurringExpiry (la verificación no se realiza, pero esta información es utilizada por el banco emisor de la tarjeta).

Como resultado se creará una vinculación para el cliente con el clientId originalmente especificado. Puede ejecutar la solicitud getBindings.do para asegurarse de que la vinculación ha sido creada.

Ejemplo de solicitud paymentorder.do:

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/paymentorder.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '$CVC=123' \
  --data '$EXPIRY=203012' \
  --data '$PAN=4000001111111118' \
  --data 'TEXT=TEST CARDHOLDER' \
  --data MDORDER=59e00106-1f69-76a7-b893-b27c00b4f820 \
  --data userName=test_user \
  --data password=test_user_password \
  --data language=en \
  --data 'jsonParams={"recurringFrequency": "1", "recurringExpiry":"20261231"}'

{
  "errorCode": 0,
  "is3DSVer2": true,
  "threeDSServerTransId": "efa8e3ce-a4a6-49f8-b422-df781de18119",
  "threeDSMethodURLServer": "https://dev.bpcbt.com/payment/client/gather?threeDSServerTransID=efa8e3ce-a4a6-49f8-b422-df781de18119"
}

Pago con vinculación recurrente

Para el pago de pedido con vinculación recurrente utilice la siguiente secuencia de solicitudes:

Obtenga la lista de vinculaciones utilizando la solicitud getBindings.do con bindingType=R → obtenga en la respuesta bindingId.
Ejecute la solicitud recurrentPayment.do con el bindingId obtenido.

Como resultado el pedido será pagado con ayuda de la vinculación con el bindingId especificado.

Ejemplo de solicitud recurrentPayment.do:

curl --request POST \
  --url https://dev.bpcbt.com/payment/recurrentPayment.do \
  --header 'Content-Type: application/json' \
  --data '{
  "userName": "test_user",
  "password": "test_user_password",
  "orderNumber": "UAF-203974-DE-12",
  "language": "EN",
  "bindingId": "3080a436-02a0-75c2-a2ce-41be00b40dc0",
  "amount": 12300,
  "currency": "978",
  "description" : "Test description",
  "additionalParameters": {
    "firstParamName": "firstParamValue",
    "secondParamName": "secondParamValue"
  }
 }'

{
  "success": true,
  "data": {
    "orderId": "9adaa8f0-3b5a-742f-80b4-172200b40dc0"
  },
  "orderStatus": {
    "errorCode": "0",
    "orderNumber": "9003",
    "orderStatus": 2,
    "actionCode": 0,
    "actionCodeDescription": "",
    "amount": 12300,
    "currency": "978",
    "date": 1618338779501,
    "orderDescription": "Test description",
    "merchantOrderParams": [
      {
        "name": "firstParamName",
        "value": "firstParamValue"
      },
      {
        "name": "secondParamName",
        "value": "secondParamValue"
      }
    ],
    "transactionAttributes": [],
    "attributes": [
      {
        "name": "mdOrder",
        "value": "9adaa8f0-3b5a-742f-80b4-172200b40dc0"
      }
    ],
    "cardAuthInfo": {
      "maskedPan": "400000**1118",
      "expiration": "202612",
      "cardholderName": "TEST CARDHOLDER",
      "approvalCode": "123456",
      "paymentSystem": "VISA",
      "product": "visa-product",
      "secureAuthInfo": {
        "eci": 7
      },
      "pan": "400000**1118"
    },
    "bindingInfo": {
      "clientId": "test-client",
      "bindingId": "3080a436-02a0-75c2-a2ce-41be00b40dc0"
    },
    "authDateTime": 1618338779790,
    "authRefNum": "111111111111",
    "paymentAmountInfo": {
      "paymentState": "DEPOSITED",
      "approvedAmount": 12300,
      "depositedAmount": 12300,
      "refundedAmount": 0,
      "totalAmount": 12300
    },
    "bankInfo": {
      "bankName": "ES TEST BANK",
      "bankCountryCode": "ES",
      "bankCountryName": "Spain"
    },
    "chargeback": false,
    "operations": [
      {
        "amount": 12300,
        "cardHolder": "TEST CARDHOLDER",
        "authCode": "123456"
      }
    ]
  }
}

Vinculaciones para pagos a plazos

Creación de vinculación para pago a plazos

Para crear una vinculación para pagos a plazos, ejecute la siguiente secuencia de solicitudes:

Ejecute la solicitud register.do con el parámetro clientId → obtenga en la respuesta orderId.
Transfiera el valor obtenido orderId en el parámetro MDORDER de la solicitud paymentorder.do. Es necesario transferir parámetros adicionales installments, totalInstallmentAmount, recurringFrequency y recurringExpiry.

Ejemplo de solicitud paymentorder.do:

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/paymentorder.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data '$CVC=123' \
  --data '$EXPIRY=203012' \
  --data '$PAN=4000001111111118' \
  --data 'TEXT=TEST CARDHOLDER' \
  --data MDORDER=bd30b67f-f8c7-7c9c-a4ac-66b300b40dc0 \
  --data userName=test_user \
  --data password=test_user_password \
  --data language=en \
  --data 'jsonParams={"installments": "3", "totalInstallmentAmount": "900000", "recurringFrequency": "3", "recurringExpiry":"20261231"}'

{
    "errorCode": 0,
    "is3DSVer2": true,
    "threeDSServerTransId": "3e07d895-8cac-460c-81f3-da6f6389dc11",
    "threeDSMethodURLServer": "https://dev.bpcbt.com/payment/client/gather?threeDSServerTransID=3e07d895-8cac-460c-81f3-da6f6389dc11",
    "threeDSMethodURLServerDirect": "https://dev.bpcbt.com/payment/rest/3dsmethod.do"
}

Pago con vinculación para pagos a plazos

Para el pago de pedido con vinculación para pagos a plazos utilice la siguiente secuencia de solicitudes:

Obtenga la lista de vinculaciones utilizando la solicitud getBindings.do con bindingType=I → obtenga en la respuesta bindingId.
Ejecute la solicitud installmentPayment.do con el bindingId obtenido.

Como resultado el pedido será pagado con ayuda de la vinculación con el bindingId especificado.

Ejemplo de solicitud installmentPayment.do:

curl --request POST \
  --url https://dev.bpcbt.com/payment/installmentPayment.do \
  --header 'Content-Type: application/json' \
  --data '{
  "userName": "test_user",
  "password": "test_user_password",
  "orderNumber": "UAF-203974-DE-12",
  "language": "EN",
  "bindingId": "8aa4fa8b-4d8a-76ca-b314-7bcc00b4f820",
  "amount": 12300,
  "currency": "978",
  "description" : "Test description",
  "additionalParameters": {
    "firstParamName": "firstParamValue",
    "secondParamName": "secondParamValue"
  }
 }'

{
  "errorCode": 0,
  "errorMessage": "Success",
  "orderId": "0e441115-f3bc-711c-8827-2fdc00b4f820",
  "orderStatus": {
    "errorCode": "0",
    "orderNumber": "7033",
    "orderStatus": 2,
    "actionCode": 0,
    "actionCodeDescription": "",
    "amount": 12300,
    "currency": "978",
    "date": 1618340470944,
    "orderDescription": "Test description",
    "merchantOrderParams": [
      {
        "name": "firstParamName",
        "value": "firstParamValue"
      },
      {
        "name": "secondParamName",
        "value": "secondParamValue"
      }
    ],
    "transactionAttributes": [],
    "attributes": [
      {
        "name": "mdOrder",
        "value": "0e441115-f3bc-711c-8827-2fdc00b4f820"
      }
    ],
    "cardAuthInfo": {
      "maskedPan": "400000**1118",
      "expiration": "203012",
      "cardholderName": "TEST CARDHOLDER",
      "approvalCode": "123456",
      "paymentSystem": "VISA",
      "product": "visa-product",
      "secureAuthInfo": {
        "eci": 7
      },
      "pan": "400000**1118"
    },
    "bindingInfo": {
      "clientId": "test-client",
      "bindingId": "8aa4fa8b-4d8a-76ca-b314-7bcc00b4f820"
    },
    "authDateTime": 1618340471076,
    "authRefNum": "111111111111",
    "paymentAmountInfo": {
      "paymentState": "DEPOSITED",
      "approvedAmount": 12300,
      "depositedAmount": 12300,
      "refundedAmount": 0,
      "totalAmount": 12300
    },
    "bankInfo": {
      "bankName": "ES TEST BANK",
      "bankCountryCode": "ES",
      "bankCountryName": "Spain"
    },
    "chargeback": false,
    "operations": [
      {
        "amount": 12300,
        "cardHolder": "TEST CARDHOLDER",
        "authCode": "123456"
      }
    ]
  },
  "error": false
}

Categorías:

eCommerce API V1

Vinculaciones y tipos de transacciones

Tipos de vinculaciones

Tipo de transacciones

Gestión de vinculaciones a través de API

Vinculaciones ordinarias

Vinculaciones recurrentes

Vinculaciones para pagos a plazos

Contáctanos

¡Gracias!