Online references
For the purpose of offering to the clients a rapid form of payment and without complications, Openpay exposes Paynet services that allow direct interaction with convenience store chains when processing payments.
In this guide we will explain in detail the way in which they work our services so that you can integrate them in a simple and fast, and in this way your systems are connected with the network Paynet.
Flow Steps
The approval process of a reference follow the steps below:

- The customer goes to make a payment to a store in your chain.
- The chain requests authorization of payment to Paynet services.
- Openpay performs online validation with the authorized services of the merchants if required.
- The merchant validates the corresponding reference and informs Paynet if the transaction is authorized or rejected.
- Openpay will respond to your store if the transaction must be accepted or rejected.
In the event you have a problem making the authorization of the payment, it is possible to run the cancellation process which is described below:

- The customer goes to make a payment in any store of your chain.
- The chain requests authorization of payment to Paynet services.
- The store loses communication with Paynet.
- The store makes the request for cancellation.
- Paynet performs the validation of the cancellation request and replies whether or not the transaction has been cancelled.
API Endpoints
The API REST of Paynet has a tests environment (sandbox) and a production environment. Following URIs form the base of the endpoints for the supported environment:
Tests, URI base:
https://sandbox-api.paynet.com.mx
Producción, URI base:
https://production-api.paynet.com.mx
A complete endpoint is formed by the base URI of the environment, the identifier of the chain and the resource.
For example, to send a request for payment authorization, the endpoint would be:
https://sandbox-api.paynet.com.mx/v1/mzdtln0bmtms6o3kck8f/payment
To create a complete request it is necessary to send the correct HTTP headers and the information in JSON format.
Authentication
To make requests to the Paynet API, it is necessary to send the API key in all your calls to our servers. The key will be generated and delivered by Openpay.
For authentication to the API you must use basic access authentication, where the API key is the user name. The password is not required and must be left blank for the sake of simplicity.
Integration of Paynet services.
In order for the chain to interact with paynet and process payments, is needed to integrate the following services:
- Payment authorization service
- Payment cancellation service
Payment authorization service
The authorization service will be called when a customer tries to pay their reference in the store. Paynet will process the request and respond to the chain the result of the authorization.
Request for Authorization
The request must be a HTTPS POST with application/json content, encoded in UTF-8.
The body of the request will contain a JSON object with the following attributes:
Name | Type | Length | Required | Description |
---|---|---|---|---|
idGroup | Numeric | 1 - 11 | Yes | Chain identifier in Paynet. |
idChain | Numeric | 1 - 11 | Yes | Identifier of the sub-grouping of the chain. |
idStore | Numeric | 1 - 11 | Yes | Identifier of the store where the payment is being made. |
idPos | Numeric | 1 - 11 | Yes | Identifier of the box or point of sale where the payment is made. |
idEmployee | Numeric | 1 - 11 | Yes | Identifier of the employee who charges the customer. |
chainTransactionId | Numeric | 1 - 45 | Yes | Identifier generated by the chain associated with the operation. |
reference | Alphanumeric | 1 - 40 | Yes | Reference which is associated to the payment or deposit account. |
amount | Numeric | 1 - 15 | Yes | The amount for which the payment is being made. |
operationDate | Date | -- | Yes | The date and time of the payment made, in Unix format in milliseconds. |
sku | Numeric | 1 - 250 | No | Service code which is being paid. |
paymentType | Numeric | 1 - 3 | No | Payment Method |
The attributes that are not listed in the table will be ignored.
It does not matter the order of the attributes.
Example of the HTTP request:
POST https://sandbox-api.paynet.com.mx.mx/v1/{CHAIN_ID}/payment HTTP/1.1
Content-Type: application/json
{
"idGroup":555,
"idChain":1,
"idStore":1292,
"idPos":1,
"idEmployee":2,
"reference":"OPENPAY00FUCDZDQ9",
"amount":10.00,
"operationDate":1509053135780,
"chainTransactionId":170911001,
"sku":34123412341234,
"paymentType":1
}
Example using curl:
curl https://sandbox-api.paynet.com.mx.mx/v1/{CHAIN_ID}/payment \
-H "Content-type: application/json" \
-d '{
"idGroup":555,
"idChain":1,
"idStore":1292,
"idPos":1,
"idEmployee":2,
"reference":"OPENPAY00FUCDZDQ9",
"amount":10.00,
"operationDate":1509053135780,
"chainTransactionId":170911001,
"sku":34123412341234,
"paymentType":1
}' \
-X POST
Authorization service response
The service will respond HTTP 200 OK, with a body of type application/json with the following fields:
Name | Type | Descripcion |
---|---|---|
requestId | Alphanumeric | Identifier of the request |
chainTransactionId | Numeric | Identifier generated by the chain associated with the operation. |
authorization | Numeric | Authorization number of the transaction. |
operationDate | Date | The date and time of the payment made, in Unix format in milliseconds. |
responseCode | Numeric | Response code |
descriptionCode | Cadena | Description of the response code. |
customerInstructions | Cadena | Instructions for the client to clarify with merchant about the payment. |
Example of a successful response:
{
"requestId":"kuysdtcaygs67asd6",
"operationDate":1505171988,
"chainTransactionId":170911001,
"authorization":"124242",
"responseCode":0,
"descriptionCode":"Success",
"customerInstructions":"ESTIMADO CLIENTE PARA CUALQUIER DUDA O ACLARACION FAVOR DE COMUNICARSE A AL CORREO example@email.com O AL TELEFONO 0180012345678 "
}
Example of failed answer:
{
"requestId":"kuysdtcaygs67asd6",
"operationDate":1505171988,
"chainTransactionId":170911001,
"responseCode":12,
"descriptionCode":"Transacción inválida."
}
Payment cancellation service
The cancellation service identifies a single payment, using the data of the authorization request to cancel it in the system. In general, the same authorization data should be sent.
If a connection error occurs during the authorization of the payment, a cancellation request must be subsequently sent using the data of the authorization request. If there is no problem in making the authorization of the reference but if for any reason a cancellation should be made, it is preferable that the authorization number of the payment be included in addition.
Cancellation Request
The request must be a HTTPS POST with application/json content, encoded in UTF-8.
The body of the request will contain a JSON object with the following attributes:
Name | Type | Length | Required | Descripcion |
---|---|---|---|---|
idGroup | Numeric | 1 - 11 | Yes | Chain identifier in Paynet. |
idChain | Numeric | 1 - 11 | Yes | Identifier of the sub-grouping of the chain. |
idStore | Numeric | 1 - 11 | Yes | Identifier of the store where the payment is being made. |
idPos | Numeric | 1 - 11 | Yes | Identifier of the box or point of sale where the payment is made. |
idEmployee | Numeric | 1 - 11 | Yes | Identifier of the employee who charges the customer. |
chainTransactionId | Numeric | 1 - 45 | Yes | Identifier generated by the chain associated with the operation. |
reference | Alphanumeric | 1 - 40 | Yes | Reference which is associated to the payment or deposit account. |
amount | Numeric | 1 - 15 | Yes | The amount for which the payment is being made. |
operationDate | Date | -- | Yes | The date and time of the payment made, in Unix format in milliseconds. |
sku | Numeric | 1 - 250 | No | Service code which is being paid. |
paymentType | Numeric | 1 - 3 | No | Payment Method |
authorization | Numeric | 1 - 20 | No | Authorization number of the payment transaction. |
The attributes that are not listed in the table will be ignored.
It does not matter the order of the attributes.
Example of the HTTP request:
POST https://sandbox-api.paynet.com.mx.mx/v1/{CHAIN_ID}/reverse HTTP/1.1
Content-Type: application/json
{
"idGroup":555,
"idChain":1,
"idStore":1292,
"idPos":1,
"idEmployee":2,
"reference":"OPENPAY00FUCDZDQ9",
"amount":10.00,
"authorization":"9882347",
"operationDate":1509053135780,
"chainTransactionId":170911001,
"sku":34123412341234,
"paymentType":1
}
Example using curl:
curl https://sandbox-api.paynet.com.mx.mx/v1/{CHAIN_ID}/reverse \
-H "Content-type: application/json" \
-d '{
"idGroup":555,
"idChain":1,
"idStore":1292,
"idPos":1,
"idEmployee":2,
"reference":"OPENPAY00FUCDZDQ9",
"amount":10.00,
"authorization":"9882347",
"operationDate":1509053135780,
"chainTransactionId":170911001,
"sku":34123412341234,
"paymentType":1
}' \
-X POST
Cancellation service response
The service will respond HTTP 200 OK, with a body of type application/json with the following fields:
Name | Type | Descripcion |
---|---|---|
requestId | Alphanumeric | Identifier of the request. |
chainTransactionId | Numeric | Identifier generated by the chain associated with the operation. |
authorization | Numeric | Authorization number of the transaction. |
operationDate | Date | The Date and time of the payment made, in Unix format in milliseconds. |
responseCode | Numeric | Response code |
descriptionCode | Cadena | Description of the response code. |
Example of a successful response:
{
"requestId":"kuysdtcaygs67asd6",
"operationDate":1509053135780,
"chainTransactionId":170911001,
"authorization":"124242",
"responseCode":0,
"descriptionCode":"Success"
}
Example of failed answer:
{
"requestId":"kuysdtcaygs67asd6",
"operationDate":1509053135780,
"chainTransactionId":170911001,
"responseCode":12,
"descriptionCode":"Transacción inválida."
}
Response codes
The service response codes for Authorization or Cancellation are:
Code | Description | Cause |
---|---|---|
0 | Operación exitosa | Authorized transaction. The payment in the store will be accepted. |
12 | Transacción inválida | Transaction declined. |
30 | Error de formato | The format of the reference is incorrect. |
88 | Monto inválido | The amount of the transaction is invalid. |
93 | Adquiriente inválido | The system does not recognize the reference. |
96 | Error de sistema | An error occurred in the service. |
Payment types codes
The payment method codes are:
Code | Description |
---|---|
1 | Cash |
2 | Debit |
3 | Credit |
4 | Electronic Wallet |