Online authorizator
In SPEI transfers we have the option that you auhorize the payments with your own custom rules, You can authorize the request by a service in your application.
Workflow steps
In authorization process follows the following steps:
- Your Customer sends SPEI request with the merchant CLABE account or with their CLABE account generated in Openpay.
- Bank network sends the SPEI transaction to "Openpay" to validate if will be authorized or rejected and transaction be processed as required.
- Openpay verify that your merchant type requires online validation, therefore Openpay invokes the Authorizer Service exposed in your server to validate the SPEI request.
- Your web service validates SPEI request and notify to Openpay if was accepted or rejected.
- Openpay use the response to notify to the Bank network if SPEI was accepted or rejected.
To validate SPEI request you must implement a Web service in your application, which will be called by Openpay via HTTPS.
SPEI authorization service
The SPEI authorization service will be called by Openpay when a customer tries to order a SPEI (Step 3), your response must contain a code indicating the authorization result with an authorization number in case of successful or an optional error description in case of failure (Step 4).
Note: If a customer tries to send a SPEI with an invalid format this will be rejected without call to the SPEI authorization service.
Request sends by Openpay
Openpay will call this service via HTTP POST method, using HTTP Basic authentication. The content type of request will be application/json, UTF-8 encoding
The request body will contains a JSON object with following properties:
Name | Type | Length | Description |
---|---|---|---|
cuenta_beneficiario | Numeric | 20 | Beneficiary CLABE account |
clave_rastreo | Alfanumeric | 25 | Standard identification code recognized by Banco de México. |
monto | Numeric | 1 - 15 | SPEI amount. |
concepto_pago | Numeric | 1 - 210 | Description associated with payment |
referencia_numerica | Numeric | 1 - 5 | Numeric Reference associated with payment. |
fecha_operacion | Date | 25 | Date and time of payment, with ISO 8601 format. (ej. "2015-10-01T13:00:00-05:00") |
institucion_ordenante | Numeric | 5 | The key of the institution to which the payment is directed according to the SPEI catalog. |
cuenta_emisor | Numeric | 20 | Account of who makes the SPEI |
nombre_ordenante | Alfanumeric | 1 - 40 | The name of the payer associated with the SPEI. |
rfc_curp_ordenante | Alfanumeric | 1 - 12 | El rfc o curp del payer associated with the SPEI. |
HTTP Request example:
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" }
Test your SPEI validation service using the following curl:
curl https://my-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
Service response
The service expects an answer HTTP 200 OK, with request body type application/json that contains the following fields:
Name | Type | Length | Description |
---|---|---|---|
response_code | Numeric | 4 | The response code indicating the authorization result. |
authorization_number | Numeric | 6 | Number that identify the SPEI in case of successful authorization. |
error_description | Alfanumeric | 255 | Description of error, in case of failed authorization. This is only for Openpay to review posible errors. |
Example of successful response:
{
"response_code" : 2000,
"authorization_number" : 123456
}
Example of rejected response:
{
"response_code" : 4040,
"error_description" : "Beneficiary account doesn't exist."
}
Response codes
The authorization service must returns a code indicating the authorization result:
Code | Description | Cause |
---|---|---|
2000 | Successful operation | Authorized transaction. SPEI will be accepted. |
4040 | Invalid account | Beneficiary account doesn't exist. |
4120 | SPEI not reconized | System doesn't recognize SPEI. |
4121 | Invalid reference | Reference not found or is invalid. |
5050 | System error | System error, response was not generated. |
Considerations
Comunication time between Openpay and Authorization service
Openpay will wait for a response of Authorization service approximately 5 seconds, once after that time is posible that Openpay cancel the connection and consider the transaction as rejected
HTTPS Comunication
Although in the Sandbox environment is allowed that the service was HTTP, don't forget that in production environment is required that the service be enable via HTTPS
Errors in Authorization service
If the services fail, either the server does not respond for the unanswered service an HTTP 2xx response, Openpay will get the following actions:
- Is considered the transaction as rejected
- The SPEI will not be accepted.