Documento de especificación técnica IPN DineroMail

Documento de especificación
técnica IPN DineroMail
1
..::: Contenido
1. Introducción…………………………………………... 2
2. Descripción general
de IPN versión 2……………………………………… 2
3. Requisitos previos a
la implementación del sistema……………………… 2
4. Modificaciones al formulario
de CARRITO/BOTON……………………………….. 3
5. Especificación de la
interfaz de notificación……………………………….. 4
6. Especificación de la
interfaz de consulta…………………………………... 6
7. Especificación de la
interfaz de reporte de operaciones…………………. 8
2
1
..::: 1. Introducción
Para aquellos casos en que los usuarios deseen recibir notificaciones
de sus operaciones de manera automática, DineroMail ha desarrollado
IPN.
..::: 2. Descripción general de IPN
IPN v2 es una herramienta que permite a los usuarios vendedores de
DineroMail recibir notificaciones de los últimos movimientos de su
cuenta y de ese modo informarse acerca del estado de cada uno de
ellos. IPN permite asimismo que los usuarios vendedores puedan
realizar consultas sobre los detalles de dichos movimientos.
Los movimientos que se notificarán son los siguientes:
- Operación de Venta
- Acreditación de dinero
- Cancelación de una operación de venta
..::: 3. Requisitos previos a la implementación del sistema.
Para poder implementar el IPN v2, es necesario que tu como usuario
vendedor te identifiques mediante un código alfanumérico de hasta
veinte (20) caracteres para verificar cada operación de intento de
pago.
Para ello, deberás ingresar a la sección “Datos de usuario” en tu
cuenta de DineroMail, y dirigirte a ‘Configurar IPN’. A continuación,
ingresa la URL y una contraseña que sólo tú conozcas. De esta
manera, sólo tú como usuario vendedor tendrás acceso al IPN
3
exclusivo que identifica a tu comercio.
2
..::: 4. Modificaciones al formulario de CARRITO/BOTON
Debe incluirse un parámetro (INPUT) del tipo oculto (HIDDEN) que
contenga el identificador del intento de pago. El mismo será llamado
“TRX_ID”. Se adjunta un ejemplo de un botón a continuación:
<form action='https://www.dineromail.com/mx/Shop/Shop_Ingreso.asp' method='post'>
<input type='hidden' name='NombreItem' value='Windows XP SP2'>
<input type='hidden' name='TipoMoneda' value='1'>
<input type='hidden' name='PrecioItem' value='650.00'>
<input type='hidden' name='E_Comercio' value='31009'>
<input type='hidden' name='NroItem' value='GC09821'>
<input type='hidden' name='image_url' value='http://'>
<input type='hidden' name='DireccionExito' value='http://'>
<input type='hidden' name='DireccionFracaso' value='http://'>
<input type='hidden' name='DireccionEnvio' value='1'>
<input type='hidden' name='Mensaje' value='1'>
<input type='hidden' name='MediosPago' value='4,5,6,14,15,16,17,2,7,13'>
<input type='hidden' name='TRX_ID' value='13461'>
<input type='image' src='https://www.dineromail.com/mx/imagenes/post-login/botoncomprar-01.gif' border='0' name='submit' alt='Pagar con DineroMail'>
</form>
4
3
..::: 5. Especificación de la interfaz de notificación.
En caso de crearse nuevas operaciones o de modificarse el estado de
estas, DineroMail enviará por “POST” un parámetro “NOTIFICACION”
que contiene un XML el cual contendrá los identificadores de las
operaciones que han sido modificadas. La estructura del XML se
detalla a continuación:
<NOTIFICACION>
<TIPONOTIFICACION>1</TIPONOTIFICACION>
<OPERACIONES>
<OPERACION>
<TIPO>1</TIPO>
<ID>31548</ID>
</OPERACION>
<OPERACION>
<TIPO>1</TIPO>
<ID>XA5547</ID>
</OPERACION>
</OPERACIONES>
</NOTIFICACION>
5
4
Descripción de los elementos del documento XML de Notificación
Elemento
Descripción
NOTIFICACION
Elemento base del documento XML, dentro de este se
encuentran todos los elementos de la notificación.
TIPONOTIFICACION
Indica el tipo de notificación que se esta enviando.
OPERACIONES
Contiene la colección de operaciones.
OPERACIÓN
Contiene el detalle de cada operación, pueden ser una o
más operaciones.
TIPO
Tipo de notificación que se envía.
ID
Este valor es el que proporciona el usuario como
identificador único de la operación de pago.
Valores posibles del elemento TipoNotificacion
1
Notificación de cambio de estado de operaciones
Valores posibles del elemento Tipo
1
Notificación de cambio de estado de una venta de Carrito o
Botón de Compras.
6
5
..::: 6. Especificación de la interfaz de consulta
Se enviará a una URL de Dineromail por “POST” un parámetro
llamado “DATA” que contenga un XML de consulta, el cual contendrá
el número de cuenta del usuario y el detalle de las operaciones a
consultar. Entre los datos que se deben enviar se encuentra el número
de cuenta del usuario y la clave (a revisar en nombre del campo)
ingresada en el sitio de Dineromail para la verificación del usuario. La
estructura del XML se detalla a continuación:
<REPORTE>
<NROCTA>31009</NROCTA>
<DETALLE>
<CONSULTA>
<CLAVE>MIPASSWORD001</CLAVE>
<TIPO>1</TIPO>
<OPERACIONES>
<ID>31548</ID>
<ID>XA5547</ID>
</OPERACIONES>
</CONSULTA>
<DETALLE>
</REPORTE>
URL de consulta:
https://mexico.dineromail.com/Vender/Consulta_IPN.asp
7
6
Descripción de los elementos del documento XML de Consulta.
Elemento
Descripción
REPORTE
Elemento base del documento XML, dentro de este se
encuentran todos los elementos de la consulta.
NROCTA
Número cuenta del usuario de Dineromail
DETALLE
Elemento que contiene todos los elementos correspondientes a
la consulta.
CONSULTA
Contiene los elementos correspondientes a la consulta en si.
CLAVE
Clave ingresada por el usuario en “Mi Cuenta” para autenticar
La identificación del mismo.
TIPO
Tipo de consulta solicitada. Los valores posibles se detallan en
La siguiente tabla.
OPERACIONES
Elemento que agrupa todas las operaciones que se solicitan en
la consulta.
ID
Este valor es el que proporciona el usuario como identificador
único de la operación de pago. Es el valor ingresado en el
punto 2.
Valores posibles del elemento Tipo
1
Consulta de estado de ventas de Carrito o Botón de Compras.
8
7
..::: 7. Especificación de la interfaz de reporte de operaciones.
La consulta realizada en el punto 4 por el negocio será respondida
mediante un XML de consulta, el cual contendrá los detalles de las
operaciones consultadas. La estructura del XML se detalla a
continuación:
<REPORTE>
<ESTADOREPORTE></ ESTADOREPORTE >
<DETALLE>
<OPERACIONES>
<OPERACIÓN>
<ID></ID>
<FECHA></FECHA>
<ESTADO></ESTADO>
<COMPRADOR>
<EMAIL></EMAIL>
<DIRECCION></DIRECCION>
<COMENTARIO></COMENTARIO>
</COMPRADOR>
<MONTO></MONTO>
<MONTONETO></MONTONETO>
<METODOPAGO></METODOPAGO>
<ITEMS>
<ITEM>
<DESCRIPCION></DESCRIPCION>
<MONEDA></MONEDA>
<PRECIOUNITARIO></PRECIOUNITARIO>
<CANTIDAD></CANTIDAD>
</ITEM>
</ITEMS>
</OPERACIÓN>
</OPERACIONES>
</DETALLE>
</REPORTE>
9
8
Descripción de los elementos del documento XML de Reporte.
Elemento
Descripción
REPORTE
Elemento base del documento XML, dentro de este se encuentran todos
los elementos de la consulta.
ESTADOREPORTE
Este elemento devuelve el estado de la operación de consulta. Los
valores que puede devolver se especifican en la tabla siguiente.
DETALLE
Elemento que contiene todos los elementos correspondientes al reporte.
OPERACIONES
Contiene los elementos correspondientes a la consulta en si. Contiene
la cantidad solicitada de operaciones que se requieren en la consulta
del punto 4.
OPERACIÓN
Detalle de la operación solicitada.
ID
Identificador único ingresado en el punto 2.
FECHA
Fecha
ESTADO
Estado actual de la operación. Se describen los valores
correspondientes en la tabla siguiente.
COMPRADOR
Contiene los elementos correspondientes a los datos del comprador.
EMAIL
Dirección de mail del comprador.
DIRECCION
Dirección que ingresa el comprador como destino de la compra. Es
opcional durante el pago de la operación de compra.
COMENTARIO
Comentario que ingresa el comprador durante la compra. Es opcional.
MONTO
Monto total de la compra en pesos. Se utiliza punto (.) como separador
de decimales.
MONTONETO
Monto neto de la operación en pesos. Es el valor informado en MONTO
con las comisiones aplicadas.
METODOPAGO
Método de pago seleccionado para el pago de la operación. Se
describen los valores correspondientes en la tabla siguiente.
ITEMS
Contiene la colección de ítems de la operación.
ITEM
Elemento que contiene los elementos correspondientes a los datos de
cada ítem.
DESCRIPCION
Descripción del ítem.
MONEDA
Tipo de moneda utilizada en el ítem. Se describen los valores
correspondientes en la tabla siguiente.
PRECIOUNITARIO
Precio unitario del ítem.
CANTIDAD
Cantidad del ítem.
10
9
Valores posibles del elemento EstadoReporte
1
CORRECTO
2
XML MAL FORMADO
3
NUMERO DE CUENTA INVALIDO (validación de sintaxis)
4
CLAVE INVALIDA (validación de sintaxis)
5
TIPO DE CONSULTA INVALIDO (validación de sintaxis)
6
ID OPERACIÓN INVALIDO (validación de sintaxis)
7
NUMERO DE CUENTA O CLAVE INVALIDO
8
NO SE ENCONTRARON OPERACIONES A REPORTAR
Valores posibles del elemento Estado
1
PENDIENTE DE PAGO
2
ACREDITADO
3
CANCELADO
Valores posibles del elemento MetodoPago
1
FONDOS DINEROMAIL
2
EFECTIVO EN BANCOMER, BANAMEX, SANTANDER,
BANCO DEL BAJIO, IXE BANCO, SCOTIABANK/INVERLAT
3
TARJETA DE CREDITO
4
TRANSFERENCIA BANCARIA
5
EFECTIVO EN TIENDAS OXXO Y 7ELEVEN
Valores posibles del elemento Moneda
1
PESO
2
DÓLAR
11
10