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
Flow 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 example:
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,
}Example using 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 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
1-2
Description of error, in case of failed authorization. This is only for Openpay to review posible errors.
Successful response example:
{
"response_code" : 0,
"authorization_number" : 123456
}Example of failed response:
{
"response_code" : 12,
"error_description" : "Agotadas existencias"
}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 send 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:
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-cacheExample using 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 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
Communication time between Openpay and the 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 communication
Although in the Sandbox environment the service is allowed to be HTTP, do not forget that in the production environment the service is required to be available 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.
