Autorizador en línea
En las transferencias SPEI contamos con la opción de que definas tus propias reglas para validar los pagos, podemos solicitar que las peticiones sean autorizadas por un servicio en tu aplicación, previo a ser aceptadas.
Pasos de flujo
El proceso de autorización de un SPEI sigue los siguientes pasos:
- El cliente realiza el SPEI con la cuenta CLABE del comercio ó a su cuenta CLABE generada en openpay.
- La red bancaria envía la transacción de pago a ”Openpay”, para que valide si se autoriza o no la transacción.
- Openpay verifica que si tu comercio requiere una autorización online, por lo tanto Openpay invocará al Servicio autorizador expuesto en tu servidor para realizar la autorización correspondiente.
- Tu servidor ejecuta la validación del SPEI correspondiente e informa a Openpay si es autorizado o no.
- Openpay utiliza la respuesta para indicar al Red bancaria si acepta o no el pago.
Para esto Openpay requiere que implementes un servicio web en en tu aplicación.
Servicio de Autorización de SPEI
Cuando un cliente intente ordenar un SPEI entonces Openpay invocará el servicio de autorización de SPEI (Paso 3) 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 (Paso 4).
Nota: Si un cliente intenta ordenar un SPEI 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 | Descripcion |
---|---|---|---|
cuenta_beneficiario | Numérico | 20 | Cuenta CLABE del Beneficiario |
clave_rastreo | Alfanumérico | 25 | Clave de identificación estándar reconocida por Banco de México. |
monto | Numérico | 1 - 15 | El monto por el que se esta efectuando. |
concepto_pago | Numérico | 1 - 210 | Descripción asociada al SPEI. |
referencia_numerica | Numérico | 1 - 5 | Una referencia numérica asociada al SPEI. |
fecha_operacion | Fecha | 25 | La fecha y hora del SPEI efectuado, en formato ISO 8601. (ej. "2015-10-01T13:00:00-05:00") |
institucion_ordenante | Numérico | 5 | La clave de la institución a la que va dirigida el pago según el catálogo de SPEI. |
cuenta_emisor | Numérico | 20 | Cuenta de quien realiza el SPEI para realizar el pago |
nombre_ordenante | Alfanumérico | 1 - 40 | El nombre del ordenante asociado al SPEI realizado. |
rfc_curp_ordenante | Alfanumérico | 1 - 12 | El rfc o curp del ordenante asociado al SPEI realizado. |
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
{ "cuenta_beneficiario": "646180109490476827", "monto": 20.50, "clave_rastreo": "2341341", "concepto_pago": "Auto", "referencia_numerica": "122311", "fecha_operacion": "2020-10-25T18:48:00-06:00", "institucion_ordenante": 33453, "cuenta_emisor": "646180109490000112", "nombre_ordenante": "NIKOLA ASIMOV", "rfc_ordenante": "asdf881212hdf" }
Prueba tu servicio de validacion de SPEI usando el siguiente curl:
curl https://mi-website.com/openpay/authorizer \
-H "Content-type: application/json" \
-d '{
"cuenta_beneficiario": "646180109490476827",
"monto": 20.50,
"clave_rastreo": "2341341",
"concepto_pago": "Auto",
"referencia_numerica": "122311",
"fecha_operacion": "2020-10-25T18:48:00-06:00",
"institucion_ordenante": 33453,
"cuenta_emisor": "646180109490000112",
"nombre_ordenante": "NIKOLA ASIMOV",
"rfc_ordenante": "asdf881212hdf"
}' \
-u TEST:test \
-X POST
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 | Descripcion |
---|---|---|---|
response_code | Numérico | 4 | El código de respuesta indicando el resultado de la autorización |
authorization_number | Numérico | 6 | Un número que identifique el SPEI, en caso de una autorización exitosa. |
error_description | Alfanumérico | 255 | 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" : 2000,
"authorization_number" : 123456
}
Ejemplo de respuesta fallida:
{
"response_code" : 4040,
"error_description" : "La cuenta del beneficiario no existe."
}
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 |
---|---|---|
2000 | Operación exitosa | Transacción autorizada. El SPEI será aceptado. |
4040 | Cuenta invalida | La cuenta del beneficiario no existe. |
4120 | SPEI no reconocido | Pago no reconocido. |
4121 | Referencia invalida | Referencia invalida o no encontrada. |
5050 | Error del sistema | Error en el sistema no se puede generar una respuesta. |
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 de SPEI
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:
- Se considerará la transacción como rechazada
- No se aceptará el pago.