API VERSIÓN 4.0 DOCUMENTACIÓN PARA INTEGRACION DE SITIOS WEB

Transcripción

1 API VERSIÓN 4.0 DOCUMENTACIÓN PARA INTEGRACION DE SITIOS WEB

2 TOKEN, URL PARA NOTIFICACIONES Y LOGO Para poder operar con la API de CobrosYA el comercio deberá obtener el token de su cuenta dentro de CobrosYA en el menú Configuración / Opciones de Configuración. Tanto en ambiente de sandbox (sandbox.cobrosya.com) como de producción ( En ese mismo lugar deberá ingresar la url de su sitio donde desea recibir notificaciones de pago, así como también cargar el logo de su empresa o sitio web. Cabe aclarar que los ambientes de producción y de sandbox son totalmente independientes. DIAGRAMA DE FLUJO DE UNA TRANSACCION

3 PASO 1: USUARIO ELIJE MEDIO DE PAGO EN WEB DEL COMERCIO El usuario completa la orden de compra en la web del comercio y elije el medio de pago que desea, así como también la cantidad de cuotas que desee en caso de haber elegido OCA, Mastercard, Diners, Lider o Discover. PASOS 2, 3 Y 4: CREAR TRANSACCION EN COBROSYA Si la transacción aun no fue creada en CobrosYA, entonces se deberá crear enviando un POST desde el servidor del comercio al a la siguiente URL con los siguientes parámetros. La información debe estar codificada en UTF8. URL Sandbox: sandbox.cobrosya.com/v4/crear URL Producción:

4 Parámetros a enviar en el POST: token Alfanumérico 32 Token de la API asignado a su cuenta id_transaccion Alfanumérico 50 Identificador único de la transacción en su sistema nombre Alfanumérico 50 Nombre de la persona que va a efectuar el pago apellido Alfanumérico 50 Apellido de la persona que va a efectuar el pago Alfanumérico 50 de la persona que va a efectuar el pago. celular Alfanumérico 7 Celular de la persona que va a efectuar el pago. OPCIONAL concepto Alfanumérico 200 Descripción para el talón PDF. OPCIONAL moneda Numérico = pesos, 840 = dólares monto Numérico 10.2 Monto de la transacción fecha_vencimiento Fecha YYYY MM DD Vencimiento del pago en redes de Cobranza. OPCIONAL url_respuesta Alfanumérico 200 Url para redirigir al usuario al finalizar la transacción consumo_final Numérico 1 1 = consumidor final, 0 = venta con rut. Para ley de inclusión factura Alfanumerico 20 Numero de factura de la transacción para ley de inclusión monto_gravado Numérico 10,2 Monto gravado con IVA para la ley de inclusión financiera Datos opcionales para Visa: direccion Alfanumérico 50 Dirección del cliente ciudad Alfanumérico 50 Ciudad del cliente departamento Alfanumérico 15 Departamento del cliente pais Alfanumérico 2 País del cliente (código de 2 caracteres, UY = Uruguay) codigo_postal Alfanumérico 10 Código postal del cliente telefono Alfanumérico 7 El teléfono del cliente El servidor de CobrosYA responde con un XML con este formato: <?xml version='1.0' encoding='utf 8'?> <respuesta> <error>0</error> <nro_talon>1234</nro_talon> <id_secreto> </id_secreto> <url_pdf> <mediosdepago>1,2,3,4,5,...</mediosdepago> </respuesta>

5 Campos de respuesta: error Numérico 2 Código de error de la llamada nro_talon Numérico 20 Identificar único del talón de pago de CobrosYA id_secreto Alfanumérico 32 Identificar secreto único para talón de CobrosYA url_pdf Alfanumérico 200 Url para descargar el talón para redes de Cobranza en PDF mediosdepago Alfanumérico 50 Lista de medios de pago autorizados, separados con coma Posibles valores del campo error: 0. Transacción iniciada correctamente 1. Faltan campos 2. El token no es correcto 3. Error al crear talón 4. La fecha de vencimiento es incorrecta 5. El celular tiene un formato incorrecto ( expresión regular para validar: /^09[0 9]{7}$/ ) 6. El mail tiene un formato incorrecto 7. La moneda no es valida 8. El monto tiene un formato incorrecto 9. La transacción ya fue cobrada *** En caso de que error sea distinto de 0, NO se devuelven el resto de los campos en la respuesta. PASO 5: VALIDAR QUE EL MEDIO DE PAGO ESTA AUTORIZADO El siguiente paso es validar que el medio de pago elegido por el usuario esté dentro de la lista de medios de pago autorizados devuelta en el paso anterior. Los motivos por los que un medio de pago podría no aparecer en esa lista son: el comercio no contrato ese medio de pago, el medio de pago se encuentra temporalmente fuera de servicio por temas ajenos a CobrosYA, alguno de los datos de la transacción no califica para ese medio de pago, etc. PASO 6: OFFLINE U ONLINE Si el medio de pago seleccionado es Offline (Redpagos, Paganza) (Paso 6.1) entonces mostrar en pantalla los datos para que el usuario pueda realizar el pago en la red de cobranza elegida. Los datos a mostrar se obtienen directamente en el paso anterior. Para Redpagos y Paganza deberá indicarse: Servicio: COBROSYA Nro. de Talón: <nro_talon> Link para descargarse talón de pago en formato PDF (OPCIONAL) <url_pdf>

6 En caso de que el medio de pago elegido sea ONLINE (banco o tarjeta de crédito) (Paso 6.2), deberá redireccionarse el navegador del usuario, sin utilizar iframes, haciendo un POST a la siguiente url: URL Sandbox: sandbox.cobrosya.com/v4/cobrar URL Producción: con los siguientes parámetros: nro_talon Numérico 20 El numero de talón de CobrosYA a cobrar id_medio_pago Numérico 2 Identificador del medio de pago seleccionado cuotas Numérico 2 Cantidad de cuotas para OCA/Master/Diners/Discovery/Lider El navegador del usuario será redirigido a la web del banco o de la tarjeta de crédito donde el usuario podrá ingresar sus datos y aceptar el pago. De ocurrir algún error se desplegará en pantalla alguno de los siguientes códigos: 1. Faltan campos 2. Medio de pago incorrecto 3. Talón no existe 4. La transacción ya fue cobrada 5. Medio de pago deshabilitado PASO 7: POST A URL DE NOTIFICACION EN CASO DE PAGO EXITOSO Si el medio de pago fue ONLINE, y el pago fue procesado correctamente, CobrosYA notifica mediante un POST desde su servidor a la URL de Notificaciones del comercio, indicando que el pago ha sido procesado exitosamente. Si el medio de pago había sido OFFLINE, CobrosYA va a notificar exactamente de la misma forma, en el mismo momento que el usuario efectúe el pago en el local de cobranzas. Los datos que enviamos en ese post son los siguientes: accion Alfanumérico Tipo de notificación. Tiene el valor "cobro" para esta notificación id_secreto Alfanumérico 32 Identificador secreto único de la transacción id_medio_pago Numérico 2 Identificador del medio de pago seleccionado. medio_pago Alfanumérico 50 Nombre del medio de pago seleccionado. moneda Numérico = pesos, 840 = dólares monto Numérico 10,2 Monto del pago fecha_hora_pago Fecha Hora YYYY MM DD H:M:S Fecha y hora en la cual se efectuó el pago cuotas_codigo Numérico 2 Cantidad de cuotas elegida por el cliente (solo tarjetas) cuotas_texto Alfanumérico 30 Descripción de la cantidad de cuotas elegida por el cliente (solo tarjetas)

7 autorizacion Alfanumérico 30 Código de autorización del medio de pago (solo tarjetas) *** El servidor del cliente deberá responder al POST de la notificación devolviendo un número 1, una vez procesados los datos para indicarnos que la notificación fue recibida y procesada correctamente. EN CASO DE PAGO RECHAZADO Si el medio de pago fue ONLINE, y el pago fue rechazado, CobrosYA notifica mediante un POST desde su servidor a la URL de Notificaciones del comercio, indicando que el pago ha sido rechazado. Los datos que enviamos en ese post son los siguientes: accion Alfanumérico Tipo de notificación. Tiene el valor "rechazo" para esta notificación id_secreto Alfanumérico 32 Identificador secreto único de la transacción id_medio_pago Numérico 2 Identificador del medio de pago seleccionado. medio_pago Alfanumérico 50 Nombre del medio de pago seleccionado. moneda Numérico = pesos, 840 = dólares monto Numérico 10,2 Monto del pago fecha_hora_pago Fecha Hora YYYY MM DD H:M:S Fecha y hora en la cual se efectuó el pago cuotas_codigo Numérico 2 Cantidad de cuotas elegida por el cliente (solo tarjetas) cuotas_texto Alfanumérico 30 Descripción de la cantidad de cuotas elegida por el cliente (solo tarjetas) autorizacion Alfanumérico 30 Código de autorización del medio de pago (solo tarjetas) *** El servidor del cliente deberá responder al POST de la notificación devolviendo un número 1, una vez procesados los datos para indicarnos que la notificación fue recibida y procesada correctamente. PASO 8: REDIRECCION A LA URL DE RESPUESTA Por último redireccionamos el navegador del usuario a la url_respuesta que nos fuera enviada en el Paso 2. Se sugiere que dicha url contenga un parámetro que sirva para identificar la transacción en el sitio web del comercio. CODIGOS DE MEDIOS DE PAGO La siguiente tabla contiene la lista de posibles valores del campo id_medio_pago: 2 ebrou 3 Santander 4 BBVA 5 Paganza 6 Redpagos 7 Visa 8 Mastercard

8 9 Diners 10 Discovery 11 Lider 12 OCA 13 Banred *** Cabe destacar que la disponibilidad de estos medios de pago en algunos casos requiere un contrato previo entre el comercio y el medio de pago.