Si deseamos utilizar reglas más complicadas para validar nuestros pagos, podemos solicitar que las referencias sean autorizadas por un servicio en nuestra aplicación, previo a ser aceptadas por la tienda. Esta funcionalidad te permite conectar a tu aplicación directamente con las tiendas de conveniencia de nuestro red Paynet.
Pasos de flujo
El proceso de autorización de una referencia sigue los siguientes pasos:
- El cliente acude a realizar un pago en cualquier cadena soportada por la plataforma.
- La cadena envía la transacción de pago a ”Openpay” para que valide si se autoriza o no la transacción y se procese la transacción según sea requerido.
- Openpay verifica que el tipo de comercio SI requiere de una validación online, por lo tanto Openpay invoca al Servicio autorizador expuesto por el comercio para realizar la validación correspondiente de la referencia.
- El comercio efectúa la validación de la referencia correspondiente e informa a Openpay si se autoriza o no.
- Openpay utiliza la respuesta para indicar a la tienda si acepta o no el pago.
En caso de que la tienda tenga un problema al registrar un pago autorizado, ocurre un proceso de cancelación:
- Openpay detectará este evento y verificará que la transacción requirió una validación online.
- Openpay invoca al servicio de cancelación expuesto por el comercio para notificar la cancelación.
- El comercio efectúa la cancelación de la transacción correspondiente.
Para esto requerimos implementar dos servicios web en nuestra aplicación, los cuales serán llamados por Openpay mediante HTTPS:
- Servicio de autorización de pago
- Servicio de cancelación de pago
Servicio de autorización de pago
El servicio de autorización será llamado por Openpay cuando un cliente intente pagar una referencia válida del comercio, y en su respuesta deberá contener un código indicando el resultado de la autorización, junto con un número de autorización en caso de una autorización exitosa, o una descripción de error opcional en caso de ser fallida.
Si un cliente intenta pagar una referencia con un formato inválido ésta será rechazada sin llamar al servicio autorizador.
Petición enviada por Openpay
Openpay llamará a este servicio mediante un método HTTP POST, utilizando autenticación HTTP Basic para identificarse. El contenido de la petición será de tipo application/json, codificado en UTF-8.
El cuerpo de la petición contendrá un objeto JSON con las siguientes propiedades:
Nombre
Tipo
Longitud
Descripción
folio
Alfanumérico
8 - 35
La referencia que se esta autorizando. Esta referencia siempre se encuentra en mayúsculas.
local_date
Fecha
25
La fecha y hora del pago efectuado, en formato ISO 8601. (ej. "2015-10-01T13:00:00-05:00")
amount
Numérico
1 - 15
El monto por el que se esta efectuando el pago.
trx_no
Numérico
1 - 12
Id de la transacción en el punto de venta.
Ejemplo de la petición HTTP:
POST /openpay/authorizer HTTP/1.1
Host: example.com
Authorization: Basic VEVTVDp0ZXN0
Content-Type: application/json
Cache-Control: no-cache
{
"folio" : "TESTSTABC123456782",
"local_date" : "2015-08-07T10:00:00-05:00",
"amount" : 100.00,
"trx_no" : 1234567890,
}Ejemplo usando curl:
curl https://example.com/openpay/authorizer \
-H "Content-type: application/json" \
-d '{
"folio" : "TESTSTABC123456782",
"local_date" :"2015-08-07T10:00:00-05:00",
"amount" : 100.00,
"trx_no" : 1234567890
}' \
-u TEST:test \
-X POST En el ambiente de producción es requerido que la URL del servicio pueda ser accesada mediante HTTPS.
Respuesta del servicio
El servicio espera una respuesta HTTP 200 OK, con un cuerpo de tipo application/json con los siguientes campos:
Nombre
Tipo
Longitud
Descripción
response_code
Numérico
1-2
El código de respuesta indicando el resultado de la autorización
authorization_number
Numérico
6
Un número que identifique el pago, en caso de una autorización exitosa.
error_description
Alfanumérico
1-2
Una descripción del error, en caso de una autorización fallida. Esto solo es usado por Openpay para revisión de posibles errores.
Ejemplo de respuesta exitosa:
{
"response_code" : 0,
"authorization_number" : 123456
}Ejemplo de respuesta fallida:
{
"response_code" : 12,
"error_description" : "Agotadas existencias"
}Códigos de respuesta
El servicio autorizador debe de regresar un código indicando el resultado de la autorización:
Código
Descripción
Causa
0
Operación exitosa
Transacción autorizada. El pago en la tienda será aceptado.
12
Transacción inválida
Transacción rechazada.
30
Error de formato
El formato de la referencia es incorrecto.
88
Monto inválido
El monto de la transacción es inválido.
93
Adquiriente inválido
El sistema no reconoce la referencia.
96
Error de sistema
Ocurrió un error en el servicio
Servicio de cancelación de pago
El servicio de cancelación será llamado por Openpay cuando la tienda requiera cancelar un pago, usualmente en caso de que tuviera un error al momento de registrar su transacción. Este servicio se llamará a lo más 15 minutos después de la respuesta de autorización.
El método de cancelación solo debe deshacer un único pago de la referencia. Una vez cancelado el pago se debe tomar en cuenta que el cliente puede volver a intentar pagar la referencia de nuevo.
Petición enviada por Openpay
La petición enviada por Openpay será de tipo HTTP DELETE, sin un contenido y con los valores de la transacción a cancelar en la URL del servicio. Los parametros enviados en la URL serán:
Nombre
Tipo
Longitud
Descripción
folio
Alfanumérico
8 - 35
La referencia que se esta autorizando. Esta referencia siempre se encuentra en mayúsculas.
local_date
Fecha
25
La fecha y hora del pago efectuado, en formato ISO 8601. (ej. "2015-10-01T13:00:00-05:00")
amount
Numérico
1 - 15
El monto por el que se esta efectuando el pago.
trx_no
Numérico
1 - 12
Id de la transacción en el punto de venta.
authorization_number
Numérico
1 - 6
El valor regresado por el servicio de autorización.
El servicio de cancelación debe poder identificar un único pago realizado utilizando estos datos, y cancelarlo en su sistema.
Ejemplo de la petición HTTP:
DELETE /openpay/authorizer?folio=TESTSTABC123456782&local_date=2015-08-07T10%3A00%3A00-05%3A00&amount=100.00&trx_no=1234567890 HTTP/1.1
Host: example.com
Authorization: Basic VEVTVDp0ZXN0
Content-Type: application/json
Cache-Control: no-cacheEjemplo usando curl:
curl https://example.com/openpay/authorizer \
-G \
-d folio=TESTSTABC123456782 \
-d authorization_number=123456 \
-d amount=100.00 \
-d trx_no=1234567890 \
--data-urlencode local_date=2015-08-07T10:00:00-05:00 \
-u TEST:test \
-X DELETE Respuesta del servicio
En este caso Openpay espera una respuesta HTTP vacía, con un estado HTTP 2xx, de preferencia 200 OK o 204 No Content.
Consideraciones
Tiempo de comunicación entre Openpay y el Servicio
Openpay esperará aproximadamente 5 segundos por una respuesta del servicio autorizador, y una vez pasado ese tiempo es posible que Openpay cancele la conexión y considere la transacción como rechazada.
Comunicación HTTPS
Aunque en el ambiente de Sandbox se permite que el servicio sea HTTP, no olvides que en el ambiente de producción se requiere que el servicio se encuentre disponible mediante HTTPS
Errores en el servicio autorizador
Si los servicios llegaran a fallar, ya sea por que el servidor no responde o por que el servicio no regresó una respuesta HTTP 2xx, Openpay tomará las siguientes acciones:
- En el caso del servicio de autorización, se considerará la transacción como rechazada y no se aceptará el pago.
- En el caso de cancelación, Openpay solo registrará el evento y continuará con la operación de cancelación.
Envío de Webhooks
En caso de implementar el modelo de validador Paynet, las transacciones de tienda que sean validadas mediante este servicio no generarán Webhooks, por lo que el sistema debe tomar esto en cuenta y utilizar estas llamadas para validar cualquier proceso de compra.
Tiempo de cancelación
Una vez autorizada una transacción, ésta podría ser cancelada durante los siguientes 15 minutos, por lo que tu aplicación debe tomar esto en cuenta y estar lista para esa posibilidad.
