Terminal Virtual
Introducción
Este servicio tiene el propósito de ofrecer la misma funcionalidad que tiene los comercios actualmente con Bancomer ecommerce.
Hay dos opciones para el envio de la peticion de compra:
- Se envian los datos de la transaccion sin tajeta y Openpay muestra la pantalla de captura: El comercio envía datos básicos de la compra como el monto y la descripción del producto y se presenta un formulario donde se capturan los datos de la tarjeta.
- Los datos de tarjeta son capturados en el sitio del comercio: Para los comercios que tienen permitido la captura de los datos de tarjeta en sus pantallas, el POST enviado ya contiene los datos de tarjeta.
DATO/ Campo del formulario |
Obligatorio/ opcional |
Long./Tipo | COMENTARIOS |
---|---|---|---|
Importe/ Ds_Merchant_Amount |
Obligatorio | 12 / Núm |
El monto será con punto decimal. Ejemplo:
|
Moneda/ Ds_Merchant_Currency |
Obligatorio | 3 / Núm |
Valores permitidos: 484 Pesos, 840 US dólares Cualquier otro valor se debe rechazar. El código de moneda debe corresponder al especificado en la afiliación del comercio |
Número de Pedido/ Ds_Merchant_Order |
Obligatorio | 12 / A-N |
Solo se deben admitir caracteres alfanuméricos en este rango:
Este campo no puede estar vacío. Su longitud máxima es 12. |
Descripción del producto/ Ds_Merchant_Product |
Obligatorio | 250 / A-N |
250 caracteres como longitud máxima. Este campo se mostrará al titular en la pantalla de captura y confirmación de la compra. |
Número de afiliación/ Ds_Merchant_MerchantCode |
Obligatorio | 7 / N | Código asignado al comercio por parte del Banco (número de afiliación). |
URL del comercio para la notificación on-line/ Ds_Merchant_MerchantURL |
Obligatorio | 1000/ A-N |
1000 caracteres máximo: URL del comercio donde se notificará en tiempo real a través de un mensaje POST la información de la transacción. Esta liga debe ser HTTPS con un certificado SSL válido. |
Número de terminal/ Ds_Merchant_Terminal |
Obligatorio | 3 / Núm. | 0 - Valor fijo |
Tipo de transacción/ Ds_Merchant_TransactionType |
Obligatorio | 1 / Num |
Valor fijo.
|
Firma SHA del comercio/ Ds_Merchant_MerchantSignature |
Obligatorio | 64 / A-N |
Ver Firma del comercio |
URL OK/ Ds_Merchant_UrlOK |
Opcional | 1500 / A-N |
Si la transacción es aceptada, en el botón “continuar” del recibo de compra se incluirá esta URL para redirigir el browser del cliente. |
URL Cancel/ Ds_Merchant_UrlKO |
Opcional | 1500 / A-N |
Si la transacción es denegada, en el botón “continuar” del recibo de compra se incluirá esta URL para redirigir el browser del cliente. |
Nombre del comercio/ Ds_Merchant_MerchantName |
Opcional | 250 / A-N | Nombre del comercio que aparecerá en la pantalla de captura. |
Datos del comercio/ Ds_Merchant_MerchantData |
Opcional | 500 /A-N |
Campo de formato libre que será devuelto íntegro en la notificación POST online. |
Nombre y apellidos del titular/ Ds_Merchant_Titular |
Opcional | 60 / A-N | Informativo. |
Idioma del titular/ Ds_Merchant_ConsumerLanguage |
Opcional | 2 / A-N |
Idioma a usarse en el recibo y la pantalla de compra, actualmente se aceptan dos valores:
|
Promociones: Diferimiento/ Ds_Promo_Diferimiento |
Opcional | 2 / Num |
Campo de promociones: Número de meses en que el pago no se hará exigible (Compre hoy y pague después). |
Promociones: Parcialización/ Ds_Promo_Parcializacion |
Opcional | 2 / Num |
Campo de promociones: Número de meses en que se van a dividir los pagos (con o sin intereses) |
Promociones: Tipo de Plan/ Ds_Promo_TipoPlan |
Opcional | 2 / A-N |
Campo de promociones: Tipo de plan que se usa en la promoción. Valores permitidos.
|
(1) Nota sobre Promociones Interbancarias:
Con la aprobación y previo contrato con Bancomer, se podrán incluir los tres campos de promoción para aquellas compras que se realicen bajo el esquema de Promociones Interbancarias.
Los valores a incluir en estos tres campos dependen del tipo de promoción contratado con el emisor correspondiente.
Para los comercios que tienen permitida la captura de datos bancarios en sus páginas, se agregan los 4 campos siguientes a la tabla anterior, que contienen los datos de la tarjeta capturada.
DATO/ Campo del formulario |
Obligatorio/ opcional |
Long./Tipo | COMENTARIOS |
---|---|---|---|
Número de Tarjeta/ Ds_Merchant_Pan |
Obligatorio | 16 / N |
Número de tarjeta capturado en el portal del comercio.
|
Caducidad/ Ds_Merchant_ExpiryDate |
Obligatorio | 4 / N |
Formato yyMM capturado en el portal del comercio. |
Código de seguridad/ Ds_Merchant_SecurityCode |
Obligatorio | 3 / N |
CVC2 o CVV2 capturado en el portal del comercio |
Pago con puntos/ Ds_CompraConPuntos |
Opcional | 1 / A-N |
Bandera para realizar la venta con puntos Bancomer, valores permitidos: 0 – Compra sin puntos 1 – Compra con puntos |
Captura de datos y culminación de la compra
Una vez que el comercio envía este formulario con los datos respectivos, el browser del cliente es redireccionado a un formulario en el que captura sus datos bancarios:
Posteriormente, para tarjetas participantes en los programas Verified by Visa y MasterCard Securecode, se presentarán las pantallas de autenticación del banco emisor correspondiente.
Por último, se lleva a cabo la autorización con el banco emisor correspondiente. En este punto se realizan dos acciones:
- Se envía la notificación POST online al comercio a la URL que indicó en el parámetro Ds_Merchant_MerchantURL
- Al término de esta notificación, se presenta al cliente un recibo de la compra con un botón ‘continuar’ que redirecciona el browser del cliente a una de las rutas UrlOK y UrlKO para transacciones aprobadas y rechazadas, respectivamente y que corresponden a las indicadas por el comercio en los campos Ds_Merchant_UrlOK y Ds_Merchant_UrlKO del formulario de entrada
Notas sobre notificación POST online:
- El recibo de compra se muestra al cliente despues que se envia el POST online al comercio.
- Se espera la respuesta del POST online hasta 25 segundos.
- Se debe manejar correctamente los formatos de los campos del POST online de acuerdo a su definición.
- Considerar que se pueden agregar más campos en el futuro.
Ejemplo de recibo de compra:
Firma del comercio
Se asignará al comercio una clave que se utilizará para firmar los datos enviados por el mismo, que permiten verificar la identidad del comercio y que los datos no han sido alterados en ningún momento. Se utilizará como algoritmo de digestión un código Hash SHA-1 o SHA-256, La clave secreta se proporcionará como parte del trámite de inscripción a la plataforma.
La firma electrónica del comercio se deberá calcular de la forma siguiente:
IMPORTE=1235
NÚMERO DE PEDIDO=29292929
CODIGO COMERCIO=1920191
MONEDA=484
TIPO DE OPERACIÓN = 0
CLAVE SECRETA=h2u282kMks01923kmqpo
Cadena datos: 12352929292919201914840h2u282kMks01923kmqpo
Resultado SHA-1: 332de724dde0ed9e71d2d07cc5aaf3c49a526b58
Notar que el algoritmo SHA-1 genera un valor binario de 160 bits (20 bytes), la cual se debe convertir a su representación hexadecimal con 40 caracteres ASCII (2 por cada byte, del 00 al ff). Si se usa el algoritmo SHA-256, la cadena resultante es de 64 caracteres.
El cálculo de la firma del comercio NO debe hacerse en el browser del tarjetahabiente, de lo contrario, la clave secreta estaría comprometida.
Respuesta POST TPV
Los parámetros que se enviarán el la peticion POST serán:
DATO/ Campo del formulario |
Long./Tipo | COMENTARIOS |
---|---|---|
Fecha/ Ds_Date |
dd/mm/yyyy | Fecha de la transacción |
Hora/ Ds_Hour |
HH:mm | Hora de la transacción formato de 24 horas |
Importe/ Ds_Amount |
12 / Núm. | Mismo valor que en la petición, |
Moneda/ Ds_Currency |
3 / Núm. | Mismo valor que en la petición |
Número de pedido/ Ds_Order |
12 / A-N. | Mismo valor que en la petición. |
Identificación de comercio/ Ds_MerchantCode |
7 / N. | Mismo valor que en la petición |
Terminal/ Ds_Terminal |
3 / Núm. | Mismo valor que en la petición. |
Firma para el comercio/ Ds_Signature |
64 / A-N | Ver sección siguiente para las instrucciones de su cálculo. |
Código de autorización/ Ds_AuthorisationCode |
6 /A-N | Número de autorización recibido del emisor. Si es un rechazo, enviar el campo vacío. |
Valor ECI (E-commerce Indicator)/ Ds_AuthenticationECI |
2 /A-N | Resultado de la autenticación 3d secure |
Código de respuesta/ Ds_Response |
3 /A-N |
Código simplificado del resultado de la transacción: 000 – Aprobada 001 – Rechazada 00 – aprobada, cualquier otro valor: rechazada |
Datos del comercio/ Ds_MerchantData |
500 / A-N | Misma información de la petición. |
Pago Seguro/ Ds_SecurePayment |
1 / Núm. | Si se el tarjeta habiente se autenticó con 3d secure. |
Tipo de operación/ Ds_TransactionType |
1 / A-N | Mismo valor que en la petición. |
Idioma del titular/ Ds_ConsumerLanguage |
2 / A | Usar el valor registrado en la petición, una vez que se aplicó la regla de entrada, es decir, solo se envían valores SP o EN |
Código de error/ Ds_ErrorCode |
7 / A-N |
Vacío si la transaccion fua probada |
Mensaje de error/ Ds_ErrorMessage |
40 / A-N |
Descripción del código de error o aprobación. Para una transacción aprobada, enviar la siguiente cadena: Successful approval/completion |
PAN enmascarada/ Ds_MaskedPAN |
16 /A-N |
Si el perfil del comercio indica que se le envíe el número de cuenta enmascarado, enviar el número de cuenta con los primeros 6 y los últimos 4 dígitos en claro de la forma: |
Saldo Anterior en Puntos/ Ds_Merchant_PreviousBalancep |
10/ Núm. |
Incluir el campo únicamente si el comercio tiene habilitada esta funcionalidad en su perfil. Si la transacción no fue realizada con puntos y el comercio tiene activada esta función, enviar el campo vacío |
Saldo Disponible en Puntos/ Ds_Merchant_AvailableBalancep |
10/ Núm. |
Incluir el campo únicamente si el comercio tiene habilitada esta funcionalidad en su perfil. Si la transacción no fue realizada con puntos y el comercio tiene activada esta función, enviar el campo vacío. |
Redimido en Pesos/ Ds_Merchant_RedeemedBalancew |
12/ Núm |
Incluir el campo únicamente si el comercio tiene habilitada esta funcionalidad en su perfil. Si la transacción no fue realizada con puntos y el comercio tiene activada esta función, enviar el campo vacío. |
Redimido en Puntos/ Ds_Merchant_RedeemedBalancep |
10/ Núm |
Incluir el campo únicamente si el comercio tiene habilitada esta funcionalidad en su perfil. Si la transacción no fue realizada con puntos y el comercio tiene activada esta función, enviar el campo vacío. |
Tipo de Pago/ Ds_PaymentType |
10/ A-N |
Incluir el campo únicamente si el comercio tiene habilitada esta funcionalidad en su perfil. |
Metodo de Pago Qropay/ Ds_QroPayPaymentMethod |
12/ A-N |
Incluir el campo únicamente si el comercio tiene habilitada esta funcionalidad en su perfil. |
Cuenta de Pago Qropay/ Ds_QroPayPayingAccount |
16/ Núm |
Incluir el campo únicamente si el comercio tiene habilitada esta funcionalidad en su perfil. |
La firma para el comercio es calculada de acuerdo al algoritmo y operativa descrita en Firma del comercio, pero utilizando la siguiente fórmula.
De acuerdo al perfil del comercio, la función puede ser sha-1 o sha-256.
Código ISO | Mensaje a incluir en campo Ds_ErrorMessage |
---|---|
01 | Refer to card issuer |
03 | Invalid merchant/service provider |
04 | Pickup card |
05 | Do not honor |
13 | Invalid amount |
14 | Invalid account number (no such number) |
41 | Pickup card (lost card) |
43 | Pickup card (stolen card) |
51 | Not sufficient funds |
54 | Expired card |
55 | Incorrect PIN |
75 | Allowable number of PIN-entry tries exceeded |
82 | Incorrect CVV |
83 | Unable to verify PIN |
96 | System malfunction/System malfunction or certain field error conditions |