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

Flow steps

The authorization process of reference follows the following steps:

  1. The customer goes to make a payment in any chain supported by the platform.
  2. The chain sends the payment transaction to "Openpay" to validate whether or not the transaction is authorized and the transaction processed as required.
  3. 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.
  4. The trade performs the validation of the corresponding reference and notify to Openpay if it is authorized or not.
  5. 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:

  1. Openpay will detect this event and verify that the transaction required online validation.
  2. Openpay invokes the cancellation service exposed by the trade to notify the cancellation.
  3. 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:

  1. Authorization service
  2. 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-cache

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