Online Authorizator
In payments via stores we have the option to define our own references (Offline References), which we can handle the format of references that you want to use. This references allows to validate These references are valid for certain data according to the format that we define.
However, if we want to use more complex rules to validate our payments, we can request that the references be authorized by a service in our application, prior to being accepted by the store
Workflow steps
The authorization process of reference follows the following steps:
- The customer goes to make a payment in any chain supported by the platform.
- The chain sends the payment transaction to "Openpay" to validate whether or not the transaction is authorized and the transaction processed as required.
- Openpay verifies that the type of merchant requires an online validation, therefore Openpay invokes to the authorization Service exposed by the merchant to realize the corresponding validation of the reference.
- The trade performs the validation of the corresponding reference and notify to Openpay if it is authorized or not.
- Openpay uses the response to tell the store whether or not to accept payment.
In case the store has a problem when registering an authorized payment, a cancellation process occurs:
- Openpay will detect this event and verify that the transaction required online validation.
- Openpay invokes the cancellation service exposed by the trade to notify the cancellation.
- The trade cancels the corresponding transaction.
To validate your own references you must implement two Web service in your application, which will be called by Openpay via HTTPS:
- Authorization service
- Payment cancellation service
Authorization service
The authorization service will be called by Openpay when a customer tries to pay a valid reference of merchant, in your response must contain a code identifing the authorization result with the authorization number in case of successful authorization, or an optional description of error in case of failure.
If a customer tries to pay a reference with an invalid format, it will be rejected without calling the authorization service.
Request send by Openpay
Openpay will call this service using an HTTP POST method, using HTTP Basic authentication to identify itself. The content of the request will be type application/json, encoded in UTF-8.
The request body will contain a JSON object with the following properties:
Name | Type | Length | Description |
---|---|---|---|
folio | Alfanumeric | 8 - 35 | The reference that is being authorized. This reference is always in upper case. |
local_date | Date | 25 | The date and time of payment made, in ISO 8601 format. (ej. "2015-10-01T13:00:00-05:00") |
amount | Numeric | 1 - 15 | The amount for which the payment is being made. |
trx_no | Numeric | 1 - 12 | Point of sale transaction id. |
HTTP Request transaction:
{ "folio" : "TESTSTABC123456782", "local_date" : "2015-08-07T10:00:00-05:00", "amount" : 100.00, "trx_no" : 1234567890, }
Example using curl:
Is required that service production environment can be acceced via HTTPS
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 | 1-2 | The response code indicating the authorization result. |
authorization_number | Numeric | 6 | Number that identify the payment 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. |
Ejemplo de respuesta exitosa:
Ejemplo de respuesta fallida:
Response codes
The authorization service must returns a code indicating the authorization result:
Code | Description | Cause |
---|---|---|
0 | Successful operation | Authorized transaction. Payment will be accepted. |
12 | Invalid Transaction | Transaction rejected. |
30 | Format error | Invalid rederence format. |
88 | Invalid amount | Transaction Amount is invalid. |
93 | Invalid acquiring | System doesn't recognize reference. |
96 | System error | Service error occurred |
Payment cancellation service
The cancellation service will be called by Openpay when the store requires you to cancel a payment, usually in case of an error when registering your transaction. This service will be called at the latest 15 minutes after the authorization response.
El método de cancelación solo debe deshacer un único pago de la referencia. Una vez cancelado el pago The cancellation method must only undo a single payment of the reference. Once payment has been canceled it must be taken into account that the customer can retry to pay the reference again.
Request sended by Openpay
The request sended by Openpay will be HTTP DELETE, without content and with the value of transaction to cancel in the URL of service. The parametros sended in URL will be:
Name | Type | Length | Description |
---|---|---|---|
folio | Alfanumeric | 8 - 35 | The reference that is being authorized. This reference is always in upper case. |
local_date | Date | 25 | The date and time of payment made, in ISO 8601 format. (ej. "2015-10-01T13:00:00-05:00") |
amount | Numeric | 1 - 15 | The amount for which the payment is being made. |
trx_no | Numeric | 1 - 12 | Point of sale transaction id. |
authorization_number | Numeric | 1 - 6 | Value returned by authorization service. |
The cancellation service must be able to identify a single payment made using this data, and cancel it in your system.
HTTP request example:
Example using curl:
Service response
In this case Openpay expect a void HTTP response, with HTTP 2XX status, En este caso Openpay espera una respuesta HTTP vacía, con un estado HTTP 2xx, Preferably 200 OK or 204 No Content.
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:
- In the case of the authorization service, the transaction will be considered rejected and payment will not be accepted.
- In the event of cancellation, Openpay will only register the event and will continue with the cancellation operation.
Submit Webhooks
In case of implement Paynet validator model, the transactions validated by this service will not generate Webhooks, So the system must take this into account and use these calls to validate any purchase process.
Cancellation time
Once a transaction is authorized, it could be canceled for the next 15 minutes, so your application should consider it and be ready for that possibility.