{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"6adfb59f-9593-4aa1-96c7-a467e67389a6","name":"PuntoRed API Technical Specification","description":"**PuntoRed** provides an API which make it possible the interconnection of many types of clients to consume electronic services, entertainment, prepaid services, and process payments.\n\nFor the use of this API it is necessary that the distributor is correctly registered in the Sales Portal, having completed the following steps:\n\n
Distributor Registration.
Registration of device (s) through which you will have connection with the Portal Sales, these can be, web console, point of sale, mobile device etc.
Prepaid distributor balance.
Registration of services that the distributor may offer.
\n\n
Security on payload
\n\n**All the requests sent to the API must be protected with a custom implementation of JWT developed by PuntoRed** which defines a compact and autonomous way to securely transmit the information.\n\nEach JWT has an expiration of 24 hrs. It is the responsibility of the implementer to obtain a new token in case the expiration is not valid `HTTP status code: 403`\n\n**PuntoRed** verifies the JWT sent to the API considering:\n\n
structure
expiration time
\n\n**Warning: One token must be taken per day, with this token all transactions will be encrypted.**\n\nThe submission of the payload used in each API call must be sent encrypted using **AES256**. \nThe list of parameters must be set up in JSON to be subsequently encrypted using a **\"key previously provided\"** to you.\n\n> // Test key pair \nSECRET_KEY = \"HPo7OLqB4Fkk4E2yGOtwqw8H5fHR9kNx67OR4g4UdlA=\" \nIV = \"p5ldmBPdd/9pjC0bDC/nSg==\" \n \n\n
Encryption Snipplets
\n\nSince client applications need to encrypt the data using the **SECRET_KEY** provided to them before sending to the API, the following are some code examples on different programming languages to help you implementing an **Encryption** routine, with which the JSON payload must be encrypted **before** sending it to the API\n\n
Encryption (AES) - Node.js
\n\n``` javascript\n// All codes in nodejs \nconst crypto = require('crypto');\nencrypt(plainText, iv, secretKey){\n let buffIv = Buffer.from(iv, 'base64');\n let buffKey = Buffer.from(secretKey, 'base64');\n let cipher = crypto.createCipheriv('aes-256-cbc', buffKey, buffIv);\n let encrypted = cipher.update(JSON.stringify(plainText), 'utf8', 'base64');\n encrypted += cipher.final('base64');\n return encrypted\n}\n\n ```\n\n
Encryption (AES) - Java
\n\n``` java\npackage AES;\nimport javax.crypto.Cipher;\nimport javax.crypto.spec.IvParameterSpec;\nimport javax.crypto.spec.SecretKeySpec;\nimport javax.crypto.SecretKey;\nimport java.util.Base64;\npublic class AesEncryption {\n public static String AESCipher(String mode, String input, String IV, String KEY) {\n byte[] iv = Base64.getDecoder().decode(IV);\n byte[] key = Base64.getDecoder().decode(KEY);\n System.out.println(\"iv: \" + iv + \" || iv length: \" + iv.length);\n System.out.println(\"key: \" + key + \" || key length: \" + key.length);\n IvParameterSpec ivspec = new IvParameterSpec(iv);\n SecretKey secretKey = new SecretKeySpec(key, 0, key.length, \"AES\");\n if (mode.equals(\"ENCRYPT\")) {\n return encrypt(input, secretKey, ivspec);\n } else if (mode.equals(\"DECRYPT\")) {\n return decrypt(input, secretKey, ivspec);\n }\n return null;\n }\n // Cipher to encrypt\n public static String encrypt(String input, SecretKey secretKey, IvParameterSpec ivspec) {\n try {\n Cipher cipher = Cipher.getInstance(\"AES/CBC/PKCS5Padding\");\n cipher.init(Cipher.ENCRYPT_MODE, secretKey, ivspec);\n return Base64.getEncoder().encodeToString(cipher.doFinal(input.getBytes(\"UTF-8\")));\n } catch (Exception e) {\n System.out.println(\"Error while encrypting: \" + e.toString());\n }\n return null;\n }\n // Cypher to decrypt\n public static String decrypt(String input, SecretKey secretKey, IvParameterSpec ivspec) {\n try {\n Cipher cipher = Cipher.getInstance(\"AES/CBC/PKCS5PADDING\");\n cipher.init(Cipher.DECRYPT_MODE, secretKey, ivspec);\n return new String(cipher.doFinal(Base64.getDecoder().decode(input)));\n } catch (Exception e) {\n System.out.println(\"Error while decrypting: \" + e.toString());\n }\n return null;\n }\n public enum Mode {\n ENCRYPT, DECRYPT\n }\n}\n\n ```\n\n
\n\nAfter you encrypt the JSON payload with your own encryption tool, you will get some randomized data.\n\n> +LWZ7icI60/DAI8ggv/SpDvJpFYeaYOZ5J7hPGK7g/87r9PRJfgFRBoBLYpBxW33ouvuwQPnhhKHXqzbiqLhMSH4gSH8SMvW6PvHfeklNfTrZnbgWFWDPSy/nqFCP0B/gKavafHG0tW5UP4KPwyhECZK2pLT+I3qYAA85uQaAPQ= \n \n\n
Key Points
\n\n- This token must be used to authenticate **all subsequent calls to the API**, where it must be added in the `Authorization header` in the form of a `Bearer token`.\n \n- The `X-API-Key` should be included _if you were provided_ with any.\n \n\nThis is a `HTTP` Request with the `Authorization header` and the `Bearer Token` in it along with the `X-API-Key` if it applies.\n\n> // Request Headers \n \n\n**It's not allowed** to get a new token for each request that the implementer makes to the API.\n\n
Expired TOKEN
\n\n**Once the Token EXPIRES** every following API request will response with the `HTTP status code: 403` and the following `JSON Payload`\n\n``` json\n{\n \"success\": false,\n \"token\": \"EXPIRED\",\n \"message\": \"Your token is expired. Is just valid for 24 hours, get a new token with the /authenticate/ method\"\n}\n\n ```\n\n
Connection Timeout
\n\nIs a time period within which a connection between a client and a server must be established. Sometimes this response may never arrive for various reasons (e.g. server is offline / connection issues / high server loads and others). So if there is still no response from the server after **\"62 seconds\"**, The API will 'give up' on waiting and it will be necessary to invoke the **\"confirmTx\"** API call which will tell us the \"Transaction\" status (Applied / Not Applied).\n\n``` XML\n\n -1\n \n 82\n Tiempo de espera alcanzado, la transacción no ha sido registrada\n \n\n\n ```\n\n**NOTE**: The confirmTx method has a **lifetime of 24 hours**, once the sendTx method has been executed. It should not be executed after this time.\n\n# **UPC (Unique Payment Code)**\n\n##### **What is the UPC?**\n\nUPC stands for Unique Payment Code. It is a required field used to uniquely identify each transaction submitted via the API. It is generated by the integrator and sent with every transaction request.\n\n##### **Purpose**\n\nThe UPC helps the system detect and reject duplicate transaction attempts, which may occur due to:\n\n- Network errors\n \n- Response timeouts\n \n- Automatic retries from the client system\n \n\n##### **Requirements**\n\n- The UPC must be unique per transaction.\n \n- Recommended format: alphanumeric (use of UUID or internal transaction ID is suggested).\n \n- Maximum length: X characters (adjust based on your system).\n \n- Required for all transactions where duplicate detection is enforced.\n \n\n###### Duplicate Validation Rules by Service Type\n\n###### 1\\. Airtime Top-up and Entertainment PINs\n\n###### A transaction is considered duplicate if:\n\n- The same UPC is received,\n \n- Within the last 15 minutes,\n \n\n###### For th**e same service type.**\n\n###### Example:\n\n| **Date/Time** | **UPC** | **Result** |\n| --- | --- | --- |\n| 2025-08-03 14:00:00 | ABC123 | Accepted |\n| 2025-08-03 14:05:00 | ABC123 | Rejected (duplicate) |\n\n###### 2\\. Bill Payment Services\n\n###### A transaction is considered duplicate if either of the following conditions are met within the last 24 hours:\n\n- The same UPC is received, or\n \n- The same service and same payment amount combination is found.\n \n\n###### Example 1: Same service and amount\n\n| **Date/Time** | **Service** | **Amount** | **Result** |\n| --- | --- | --- | --- |\n| 2025025-08-03 13:00:00 | CFE | $500 | Accepted |\n| 2025-08-03 14:30:00 | CFE | $500 | Rejected (duplicate) |\n\n###### Example 2: Same UPC\n\n| **Date/Time** | | **Service** | **Amount** | **Result** |\n| --- | --- | --- | --- | --- |\n| 2025-08-03 09:00:00 | PQR456 | Telmex | $150 | Accepted |\n| 2025-08-03 10:00:00 | **PQR456** | Telmex | $500 | Rejected (duplicate) |\n\n# Log evidence\n\nIt is mandatory for the implementer to save the requests and responses that are exchanged between **PuntoRed** and the implementer server in some type of log. The log can be a file or database, but it is necessary to have the data that is sent and received for any type of revision or clarification.\n\n
Recommendations for using the API demo
\n\n
Analyze the Gestopago transaction flow.
Use the Authenticate method to get your Bearer token.
Enter the credentials to test the API flow.
The Encrypt method will only be used here to facilitate the encryption of the signed, it is the responsibility of each implementer to develop the encryption method.
In this document PuntoRedSandbox Top-Up/Services you will find several test scenarios.