Autorizador en línea

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:

  1. El cliente acude a realizar un pago en cualquier cadena soportada por la plataforma.
  2. 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.
  3. 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.
  4. El comercio efectúa la validación de la referencia correspondiente e informa a Openpay si se autoriza o no.
  5. 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:

  1. Openpay detectará este evento y verificará que la transacción requirió una validación online.
  2. Openpay invoca al servicio de cancelación expuesto por el comercio para notificar la cancelación.
  3. 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:

  1. Servicio de autorización de pago
  2. 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-cache

Ejemplo 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.