refacil-pay-mcp 1.0.0

package/README.md

@@ -0,0 +1,931 @@
+# refacil-pay MCP Server
+
+Servidor MCP (Model Context Protocol) generado automáticamente para la API refacil-pay.
+
+## 🚀 Características
+
+- **21 herramientas** generadas automáticamente desde la colección Postman
+- **Autenticación flexible**: Sin autenticación
+- **Servidor HTTP** con Fastify
+- **Protocolo MCP** estándar para integración con IDEs
+
+## 📋 Requisitos
+
+- Node.js 20+
+- npm o yarn
+
+## 📦 Instalación desde NPM
+
+Si este paquete está publicado en npm, puedes instalarlo globalmente:
+
+```bash
+# Instalación global (recomendado)
+npm install -g refacil-pay-mcp
+
+# Verificar instalación
+refacil-pay-mcp --version
+```
+
+### Configuración Rápida en IDEs
+
+#### Cursor
+
+1. Abrir **Settings** → **Features** → **Model Context Protocol**
+2. Click en **"Edit Config"**
+3. Agregar:
+
+**Windows**: `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
+
+**macOS/Linux**: `~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+
+```json
+{
+  "mcpServers": {
+    "refacil-pay": {
+      "command": "refacil-pay-mcp",
+      "env": {
+        "BASE_URL": "https://pay-api.qa.refacil.co",
+
+      }
+    }
+  }
+}
+```
+
+4. Reiniciar Cursor
+
+#### Claude Desktop
+
+Editar archivo de configuración:
+
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+**Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "refacil-pay": {
+      "command": "refacil-pay-mcp",
+      "env": {
+        "BASE_URL": "https://pay-api.qa.refacil.co",
+
+      }
+    }
+  }
+}
+```
+
+Reiniciar Claude Desktop.
+
+#### Visual Studio Code
+
+1. Instalar extensión **MCP for VS Code**
+2. Editar `settings.json`:
+
+```json
+{
+  "mcp.servers": {
+    "refacil-pay": {
+      "command": "refacil-pay-mcp",
+      "env": {
+        "BASE_URL": "https://pay-api.qa.refacil.co",
+
+      }
+    }
+  }
+}
+```
+
+3. Recargar VS Code
+
+## 🛠️ Instalación para Desarrollo
+
+Si quieres contribuir o ejecutar desde el código fuente:
+
+```bash
+# Clonar el repositorio
+git clone https://github.com/refacil/refacil-pay-mcp.git
+cd refacil-pay-mcp
+
+# Instalar dependencias
+npm install
+
+# Construir el proyecto
+npm run build
+
+# Iniciar en desarrollo
+npm run dev
+
+# Iniciar en producción
+npm start
+```
+
+## 🔧 Configuración
+
+El servidor se configura mediante variables de entorno:
+
+```bash
+# Copiar archivo de ejemplo
+cp .env.example .env
+
+# Editar configuración
+nano .env
+```
+
+### Variables de Entorno
+
+| Variable | Descripción | Valor por defecto |
+|----------|-------------|-------------------|
+| `PORT` | Puerto del servidor | `3009` |
+| `ENVIRONMENT` | Entorno de ejecución | `development` |
+| `BASE_URL` | URL base de la API | `https://pay-api.qa.refacil.co` |
+
+
+| `MCP_TOKEN` | Token de autenticación del MCP | `mcp-secret-token-refacil-pay` |
+
+## 🐳 Docker
+
+```bash
+# Construir imagen
+docker build -t refacil-pay-mcp .
+
+# Ejecutar contenedor
+docker run -p 3009:3009 refacil-pay-mcp
+
+# O usar docker-compose
+docker-compose up
+```
+
+## ☸️ Kubernetes
+
+```bash
+# Aplicar manifests
+kubectl apply -f k8s/
+
+# Verificar despliegue
+kubectl get pods -l app=refacil-pay-mcp
+```
+
+## 🔌 Uso del MCP
+
+### Endpoints Disponibles
+
+- **`/mcp`**: Endpoint principal del protocolo MCP
+- **`/health`**: Health check del servidor
+- **`/tools`**: Lista de herramientas disponibles
+
+### Modo Multi-Usuario (HTTP)
+
+El servidor MCP soporta **múltiples usuarios simultáneamente** en modo HTTP mediante el header `X-Secret-ID`.
+
+#### ¿Cómo funciona?
+
+1. **Sin `X-Secret-ID`**: Usa el `SECRET_ID` del archivo `.env` (modo single-user)
+2. **Con `X-Secret-ID`**: Usa el secretId proporcionado en el header (modo multi-user)
+
+#### Ejemplo de uso:
+
+```bash
+# Usuario 1
+curl -X POST http://localhost:3009/mcp \
+  -H "Authorization: Bearer mcp-token" \
+  -H "X-Secret-ID: user1-secret-id" \
+  -H "Content-Type: application/json" \
+  -d '{"method": "tools/call", "params": {...}}'
+
+# Usuario 2
+curl -X POST http://localhost:3009/mcp \
+  -H "Authorization: Bearer mcp-token" \
+  -H "X-Secret-ID: user2-secret-id" \
+  -H "Content-Type: application/json" \
+  -d '{"method": "tools/call", "params": {...}}'
+```
+
+#### Ventajas del Modo Multi-Usuario:
+
+- ✅ Cada usuario usa sus propias credenciales
+- ✅ Tokens cacheados por secretId (mejor performance)
+- ✅ Un solo servidor para múltiples clientes
+- ✅ Compatible con modo single-user (fallback al .env)
+
+#### Configuración para HTTP Multi-Usuario:
+
+```bash
+# .env
+BASE_URL=https://pay-api.qa.refacil.co
+AUTH_ENDPOINT=/auth/login
+TOKEN_CACHE_TTL=3600
+MCP_TOKEN=your-mcp-token
+
+# SECRET_ID es opcional en HTTP mode
+# Si no se proporciona, DEBE enviarse via header X-Secret-ID
+```
+
+### Configuración en IDEs
+
+#### Cursor
+```json
+{
+  "mcpServers": {
+    "refacil-pay-mcp": {
+      "command": "node",
+      "args": ["/ruta/a/refacil-pay-mcp/dist/index.js"],
+      "env": {
+        "MCP_TOKEN": "tu-token-secreto"
+      }
+    }
+  }
+}
+```
+
+#### Visual Studio Code
+Configurar en la extensión MCP con:
+- **Command**: `node`
+- **Args**: `["/ruta/a/refacil-pay-mcp/dist/index.js"]`
+- **Env**: `{"MCP_TOKEN": "tu-token-secreto"}`
+
+## 🛠️ Herramientas Disponibles
+
+- **`auth_login`**: | **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| **username** \* | string | User |
+| **password** \* | string | Password |
+- **`trx_token_generate`**: | **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| **service** \* | string | Value of the service to be consumed |
+- **`trx_token_generate_3`**: | **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| **service** \* | string | Value of the service to be consumed |
+- **`trx_token_generate_4`**: | **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| **service** \* | string | Value of the service to be consumed |
+- **`trx_token_generate_5`**: | **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| **service** \* | string | Value of the service to be consumed |
+- **`trx_token_generate_6`**: | **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| **service** \* | string | Value of the service to be consumed |
+- **`cash_in_generate_payment_link_token`**: ## 📥 Request Body Parameters
+
+| **Field** | **Type** | **Required** | **Description** |
+| --- | --- | --- | --- |
+| `amount` | number | ✅ | Value of the payment. |
+| `brandId` | number | ❌ | ID of the customer's white label; if one is not available, the default ID 79 is sent. |
+| `expiresIn` | number | ❌ | Time in minutes for the expiration of the resource or payment link. |
+| `reference1` | string | ✅ | Customer identifier, must be between 1 and 30 characters. |
+| `reference2` | object | ❌ | Object for additional information. |
+| `reference2.Commerce` | object | ❌ | Object for information related to the store or commerce. |
+| `reference2.Data` | object | ❌ | Object for information related to the conciliation of the transaction. |
+| `reference2.Label` | object | ❌ | Object to send information to be displayed in the payment summary. |
+| `returnUrl` | string | ❌ | Link that the customer will see when clicking on the back to commerce button. |
+| `showSummary` | boolean | ❌ | Indicates whether the RefácilPay payment summary will be shown or not (false: do not show, true: show). Default: true. |
+| `userMetadata` | object | ✅ | Object containing key details about the user or merchant generating the payment resource. |
+| `userMetadata.identifier` | string | ✅ | Unique identifier of the user or merchant generating the payment resource (max 36 characters). |
+| `userMetadata.ip` | string | ✅ | IP address associated with the user's identifier. Must be a valid IP address. |
+| `userMetadata.urlCommerce` | string | ✅ | URL that identifies the commerce. Must follow valid URL structure with http:// or https:// protocol. Maximum length: 500 characters. |
+| `webhookUrl` | string | ✅ | URL of the client's webhook to receive real-time payment status updates. |
+
+- **`cash_in_generate_payment_method_token`**: This endpoint allows you to **generate payment requests** through the available _cash-in_ methods.
+
+---
+
+### 💡 Overview
+
+The table below lists the available payment methods along with their corresponding IDs and **minimum expiration times** (`expiresIn`) required when creating a payment request.
+
+| **Method ID** | **Description** | **Minimum Expiration (seconds)** |
+| --- | --- | --- |
+| `130` | Cash-in via **Nequi** | 43,200 |
+| `131` | Cash-in via **Daviplata** | 43,200 |
+| `133` | Cash-in via **PSE** | 1,800 |
+| `262` | Cash-in via **PSE Gateway** | 1,800 |
+| `134` | Cash-in via **IPay** | 43,200 |
+| `153` | Cash-in via **Recaudo Efectivo** | 86,400 |
+| `155` | Cash-in via **Transfiya Recaudo** | 43,200 |
+| `163` | Cash-in via **TPaga** | 43,200 |
+| `248` | Cash-in via **QR Interoperable** | N/A |
+
+> ⚠ **Important:**  
+The value provided in the `expiresIn` field **must be greater than or equal** to the minimum expiration defined for the selected payment method. 
+  
+
+---
+
+## 🧩 Payment Method Details
+
+Each payment method requires a specific object structure within the `"paymentMethod"` field.
+
+---
+
+### **Nequi**
+
+``` json
+"paymentMethod": {
+  "id": 130,
+  "cellphone": "3105293225"
+}
+
+ ```
+
+---
+
+### **Daviplata**
+
+``` json
+"paymentMethod": {
+  "id": 131,
+  "cellphone": "3208385715"
+}
+
+ ```
+
+---
+
+### **PSE**
+
+For this payment method, depending on the `typePerson` selected, only specific document types are accepted:
+
+- **`typePerson`****:** **`"0"`** → corresponds to a **Natural Person** and only accepts the following values for `documentType`:
+    
+    - `RCN`
+        
+    - `TI`
+        
+    - `CC`
+        
+    - `TE`
+        
+    - `CE`
+        
+    - `PA`
+        
+    - `DIE`
+        
+- **`typePerson`****:** **`"1"`** → corresponds to a **Legal Person** and only accepts the following value for `documentType`:
+    
+    - `NIT`
+        
+
+``` json
+"paymentMethod": {
+  "id": 133,
+  "documentType": "CC",
+  "typePerson": "0",
+  "bankId": "string",
+  "documentNumber": "string",
+  "name": "string",
+  "cellphone": "string",
+  "address": "string",
+  "email": "string"
+}
+
+ ```
+
+---
+
+### **PSE Gateway**
+
+This payment method enables direct integration with the PSE network for processing online bank payments.  
+To consume this product, it is required to have the following parameters previously configured and associated with your product:
+
+- `entity_code`
+    
+- `service_code`
+    
+- `company_ciiu`
+    
+- `company_name`
+    
+
+These parameters identify your company within the PSE network and are necessary for successful transaction routing and validation.
+
+> 💬 **For more information or to request these credentials, please contact the support team.** 
+  
+
+This method follows **the same structure and validation rules** as **PSE**, but must use the following identifier:
+
+``` json
+"paymentMethod": {
+  "id": 262,
+  "documentType": "CC",
+  "typePerson": "0",
+  "bankId": "string",
+  "documentNumber": "string",
+  "name": "string",
+  "cellphone": "string",
+  "address": "string",
+  "email": "string"
+}
+
+ ```
+
+The **PSE integration** relies heavily on the correct configuration of the `showSummary` and `returnUrl` parameters.  
+These parameters control the **user experience** and the **finalization flow** of the payment process.
+
+| Scenario | `showSummary` | `returnUrl` | Flow Description |
+| --- | --- | --- | --- |
+| **1\. Standard Redirect (Default)** | `true` or not sent | ✅ Present | Displays a transaction summary screen with key payment details and retrieves the final transaction status. After the payment is completed, the user is redirected to the specified `returnUrl`. |
+| **2\. Without Transaction Summary Screen** | `false` | ✅ Present | Skips the transaction summary screen and redirects the user directly to the `returnUrl`. In this case, the merchant’s system must display the transaction summary on the destination page. |
+
+> ⚠️ **Note:**  
+For **PSE** and **PSE Gateway**, it is **strongly recommended** to use `showSummary: true` along with a valid `returnUrl` to ensure a seamless customer experience and accurate transaction tracking. 
+  
+> 🔗 **See also:** 
+  
+
+- [Transaction Summary](https://documenter.getpostman.com/view/35146358/2sA3QpDEFA#45e0d76a-fabd-442e-9b17-e2f6b8354ec5)
+    
+- [Transaction Status](https://documenter.getpostman.com/view/35146358/2sA3QpDEFA#dd3ba9f5-1f10-4109-b59d-6e5aad5e3799)
+    
+
+---
+
+### **IPay**
+
+``` json
+"paymentMethod": {
+  "id": 134
+}
+
+ ```
+
+---
+
+### **Recaudo Efectivo**
+
+``` json
+"paymentMethod": {
+  "id": 153
+}
+
+ ```
+
+---
+
+### **Transfiya Recaudo**
+
+``` json
+"paymentMethod": {
+  "id": 155,
+  "cellphone": "3105293225"
+}
+
+ ```
+
+---
+
+### **TPaga**
+
+This payment method supports an optional parameter called `isQr`, which determines the type of resource returned in the `url` field:
+
+| **Value** | **Description** |
+| --- | --- |
+| `true` | The `url` field returns a link to a **QR code** displaying transaction details. |
+| `false` | The `url` field returns a **deeplink** to open directly in the TPAGA wallet app. |
+
+> 🧠 **Behavior:**  
+If `isQr` is not provided, the default behavior is equivalent to `isQr: false`.  
+Transactions can only be completed **from a mobile device**.  
+If the request is made from a desktop or tablet, it is recommended to send `isQr: true` so the user can scan the QR from a mobile device. 
+  
+
+``` json
+"paymentMethod": {
+  "id": 163,
+  "isQr": false
+}
+
+ ```
+
+---
+
+### **QR Interoperable**
+
+For this method, the following fields are **optional**:
+
+- `cellphone`
+    
+- `documentNumber`
+    
+- `documentType`
+    
+- `merchantId`
+    
+
+The service can function using only the payment method ID; however, providing these optional fields can **improve response time**.  
+You may retrieve this data through the `enrollment-data` service in the [Merchant Enrollment](https://documenter.getpostman.com/view/35146358/2sA3QpDEFA#8c9f5a18-a19a-4b8f-baba-cd7501aa29a0) section.
+
+> ⚠ **Prerequisite:**  
+The merchant must complete the **Merchant Enrollment** process before using this method.  
+See the _Merchant Enrollment_ section for setup details. 
+  
+> 🔁 **Open Resource:**  
+The **QR Interoperable** operates as an _open resource_, meaning the generated QR can be used multiple times by the same user. 
+  
+> ⚙️ **Technical Note — Dynamic QR Behavior:**  
+Dynamic QR codes may be scanned multiple times due to current limitations in the Redeban system.  
+This is **not** an error in our platform. 
+  
+
+#### Behavior Details
+
+- Redeban does not automatically invalidate a dynamic QR after its first scan.
+    
+- As a result, the same QR may generate multiple transaction records.
+    
+
+#### Recommendations
+
+- Implement **application-level validation** to detect multiple payments from the same QR code.
+    
+- Monitor dynamic QR transactions and confirm status before marking payments as completed.
+    
+- Inform end-users to verify the success of a transaction before rescanning.
+    
+
+#### Future Considerations
+
+- Redeban is evaluating support for **single-use dynamic QR control**.
+    
+- Stay updated with interoperability provider announcements to adjust integrations accordingly.
+    
+
+``` json
+"paymentMethod": {
+  "id": 248,
+  "cellphone": "string",
+  "documentType": "string",
+  "documentNumber": "string",
+  "merchantId": "string"
+}
+
+ ```
+
+---
+
+## 📥 Request Body Parameters
+
+| **Field** | **Type** | **Required** | **Description** |
+| --- | --- | --- | --- |
+| `amount` | number | ✅ | Value of the payment. |
+| `brandId` | number | ❌ | ID of the customer's white label; if one is not available, the default ID 79 is sent. |
+| `expiresIn` | number | ❌ | Time in seconds for the expiration of the resource or payment link. |
+| `paymentMethod` | object | ✅ | Object specifying the payment method and its details. |
+| `paymentMethod.id` | number | ✅ | ID of the selected payment method (see available payment methods). |
+| `reference1` | string | ✅ | Customer identifier, must be between 1 and 30 characters. |
+| `reference2` | object | ❌ | Object for additional information. |
+| `reference2.Commerce` | object | ❌ | Object for information related to the store or commerce. |
+| `reference2.Data` | object | ❌ | Object for information related to the conciliation of the transaction. |
+| `reference2.Label` | object | ❌ | Object to send information to be displayed in the payment summary. |
+| `returnUrl` | string | ❌ | Link that the customer will see when clicking on the back to commerce button. |
+| `showSummary` | boolean | ❌ | Indicates whether the RefácilPay payment summary will be shown or not (false: do not show, true: show). Default: true. |
+| `userMetadata` | object | ✅ | Object containing key details about the user or merchant generating the payment resource. |
+| `userMetadata.identifier` | string | ✅ | Unique identifier of the user or merchant generating the payment resource (max 36 characters). |
+| `userMetadata.ip` | string | ✅ | IP address associated with the user's identifier. Must be a valid IP address. |
+| `userMetadata.urlCommerce` | string | ✅ | URL that identifies the commerce. Must follow valid URL structure with http:// or https:// protocol. Maximum length: 500 characters. |
+| `webhookUrl` | string | ✅ | URL of the client's webhook to receive real-time payment status updates. |
+- **`cash_out_generate_withdraw_method_token`**: This endpoint allows you to **generate withdrawal (cash-out) requests** through the available payout methods.
+
+---
+
+### 💡 Overview
+
+The table below lists the available payout methods along with their corresponding IDs and brief descriptions.
+
+| **Method ID** | **Description** |
+| --- | --- |
+| `245` | Cash-out via **Transfiya** |
+| `264` | Cash-out via **Bre-B** |
+
+> ⚠ **Note:**  
+Each withdrawal method requires a specific object structure within the `"withdrawMethod"` field, as shown below. 
+  
+
+---
+
+## 🧩 Payout Method Details
+
+### **Transfiya**
+
+``` json
+"withdrawMethod": {
+  "id": 245,
+  "cellphone": "3125763074"
+}
+
+ ```
+
+**Description:**  
+Transfers funds to a recipient using their registered Transfiya cellphone number.
+
+> ⚠ **Important:**  
+Ensure the cellphone number is registered with Transfiya and capable of receiving funds. 
+  
+
+---
+
+### **Bre-B**
+
+``` json
+"withdrawMethod": {
+  "id": 264,
+  "key": "@REPRUEBAL7717"
+}
+
+ ```
+
+**Description:**  
+Transfers funds directly to a Bre-B account using the beneficiary’s unique Bre-B key.
+
+> 💡 **Tip:**  
+The `key` field must contain a valid Bre-B account alias in the format `@USERNAME`. 
+  
+
+---
+
+## 📥 Request Body Parameters
+
+| **Field** | **Type** | **Required** | **Description** |
+| --- | --- | --- | --- |
+| `amount` | number | ✅ | Amount to be withdrawn. |
+| `reference1` | string | ✅ | Unique transaction reference generated by the client (max 20 characters). |
+| `webhookRequest` | string | ✅ | Customer’s webhook URL to receive real-time withdrawal status updates. |
+| `userMetadata` | object | ✅ | Object containing metadata related to the origin of the transaction. |
+| `userMetadata.identifier` | string | ✅ | Identifier for the user or merchant initiating the transaction. |
+| `userMetadata.ip` | string | ✅ | IP address from which the transaction was initiated. |
+| `userMetadata.urlCommerce` | string | ✅ | Commerce or customer’s URL associated with the transaction. |
+| `withdrawMethod` | object | ✅ | Object specifying the withdrawal method and destination details. |
+| `withdrawMethod.id` | number | ✅ | ID of the selected payout method (see table above). |
+| `withdrawMethod.cellphone` | string | Conditional | Required for **Transfiya** withdrawals. |
+| `withdrawMethod.key` | string | Conditional | Required for **Bre-B** withdrawals. |
+| `withdrawMethod.bankName` | string | ❌ | Optional bank name, if applicable for future payout methods. |
+
+---
+- **`customer_getbalance`**: This service allows you to consult the balance exchange and the dispersion exchange associated with the client's identifier.
+
+> To use the service, an authentication token is required, which must be sent as an Authorization header. 
+  
+
+Headers
+
+| **Name** | **Value** |
+| --- | --- |
+| Content-Type | application/json |
+| Authorization | Bearer |
+
+Body
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `userId`\* | number | Integrated unique user identifier |
+- **`payment_transfiya_banks`**: This service allows you to consult the balance exchange and the dispersion exchange associated with the client's identifier.
+
+> To use the service, an authentication token is required, which must be sent as an Authorization header. 
+  
+
+Headers
+
+| **Name** | **Value** |
+| --- | --- |
+| Content-Type | application/json |
+| Authorization | Bearer |
+
+Body
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `cellphone`\* | number | The cell phone number to be used to consult the list of banks. |
+- **`payment_status`**: This service allows you to check the status of a transaction made, for this you must have the _reference_ data that returned the response when generating any payment resource.
+
+In the response you will get the _status_ _id_ which will mean the following
+
+0 - Transaction Rejected
+
+1 - Pending Transaction
+
+2 - Transaction Approved
+
+3 - Failed Transaction
+
+5 - Transaction Cancelled
+
+9 - Processing Transaction
+
+Headers
+
+| **Name** | **Value** |
+| --- | --- |
+| Content-Type | application/json |
+| Authorization | Bearer |
+
+Body
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `reference`\* | string | Product reference |
+- **`payment_customer_reference_status`**: ## 🔍 Check Transaction by Customer Reference
+
+This endpoint allows **API Pay** users to query the status of a transaction using only the `customerReference` value originally provided when generating a resource as `reference1` through any of the following endpoints:
+
+- `/cash-in/generate/payment-link/token`
+    
+- `/cash-in/generate/payment-method/token`
+    
+- `/cash-out/generate/withdraw-method/token`
+    
+
+This service is useful for retrieving the internal **Refacil** transaction information associated with a previously submitted customer reference.
+
+---
+
+## 🔐 Authentication
+
+This endpoint **requires** a valid Bearer Token in the request headers. Requests without valid authentication will be rejected with an `Unauthorized` error.
+
+## 📤 Successful Response
+
+- `exists`: `true` indicates that the transaction associated with the provided `customerReference` was found.
+    
+- `id`: Internal Refacil transaction ID.
+    
+- `status`: Transaction status code (see table below).
+    
+- `reference`: Full Refacil transaction reference, which can be used to query `/payment/status`.
+    
+
+### ℹ️ Status Code Reference
+
+| Status Code | Meaning |
+| --- | --- |
+| `0` | Transaction Rejected |
+| `1` | Transaction Pending |
+| `2` | Transaction Approved |
+| `3` | Transaction Failed |
+| `5` | Transaction Cancelled |
+| `9` | Transaction Processing |
+
+---
+- **`payment_features`**: This service allows you to consult the necessary characteristics of a payment method to successfully generate a resource. For example, obtain the PSE banks
+
+Headers
+
+| **Name** | **Value** |
+| --- | --- |
+| Content-Type | application/json |
+| Authorization | Bearer |
+
+Body
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `id`\* | integer | Product identification |
+- **`webhook_notify`**: Body
+
+| Name | Type | Description |
+| --- | --- | --- |
+| amount\* | Integer | Total transaction value |
+| cost\* | Integer | Transaction cost |
+| Resource | Object | Object |
+| id | Integer | Identifier of the payment resource |
+| updatedAt | String | Date and time at which the transaction was processed |
+| status\* | Object | Transaction status identifier |
+| transfiyaStatus | String | The TransfiYa status, see the details below |
+| id\* | String | Transaction status ID : 1 Pending , 2 Approved ,3 Failed |
+| id \* | Integer | transaction identifier |
+| description | String | Status detail |
+| Key | interger | Key |
+| PaymentMethod | Object | Payment method |
+| id | String | Method identifier |
+| name | String | payment method name |
+| type | String | method |
+| extra | Object | Object |
+| reference1\* | String | Unique reference to the transaction provided when sending the request to generate the resource |
+| reference2 | String | Allows to append extra information provided by the client |
+| reference3 | String | Allows to append extra information provided by the customer |
+| commerceId | String | Commerce identifier |
+| createdAt | String | Date and time the transaction was created |
+| signature | String | Signature generated for webhook notification |
+| data | Object | Object with all data |
+| Transaction | String |  |
+
+
+## TransfiYa Status
+
+| **transfiyaStatus** |  Description |
+| --- | --- |
+| `CREATED` |  Transfer is received and queued for processing. |
+| `PENDING` |  Transfer is valid and is waiting for the target to accept it. |
+| `ACCEPTED` | Transfer has been accepted by the target, and payment is pending in the target bank. |
+| `COMPLETED` | The payment is valid and completely processed, visible in the receiving bank account. |
+| `REJECTED` | Payment was rejected. |
+| `ERROR` | An error occurred during payment. |
+
+### Transfer state machine
+
+<img src="https://content.pstmn.io/89f89557-2e1b-44c2-8dcb-d9e7d2f32c54/aW1hZ2UucG5n" width="293" height="380">
+- **`merchant_enrollment`**: This endpoint initiates the merchant enrollment process required to use the QR interoperable payment method. Once the request is made, the enrollment process may take up to **7 minutes** to complete.
+- **`merchant_enrollment_data`**: This endpoint retrieves the merchant's enrollment details after the enrollment process has been completed. It provides necessary information to use the QR interoperable payment method.
+- **`merchant_key_create`**: This endpoint will allow you to create 4 types of keys: `alias`, `email`, `cellphone`, and `document`.
+
+⚠ **Important**:
+
+- **Alias key:** To generate this key, it is not necessary to send the `key` field and the `otp` field. A random key is generated from various parameters of the merchant user, beginning with the character @.
+    
+- **Document key:** To generate this key, it is not necessary to send the `otp` field, and the key field must contain the document provided in the technical data sheet shared with the merchant.
+    
+- **Email key:** To generate this key, you must first use the service that generates and sends the OTP to the `email` address. The key field must contain the `email` address provided in the technical data sheet.
+    
+- **Cellphone key:** To generate this key, you must first use the service that generates and sends the OTP to the `cellphone`. The key field must contain the `cellphone` number provided in the technical data sheet.
+    
+
+Headers
+
+| **Name** | **Value** |
+| --- | --- |
+| Content-Type | application/json |
+| Authorization | Bearer |
+| x-transaction-token | 9b48edde-652d-11ed-984e-02c840fe**** |
+
+Body
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `webhookUrl`\* | string | URL of the client's webhook. |
+| `userMetadata`\* | object | Object containing key details about the user or merchant generating the payment resource. |
+| `ip`\* | string | Alphanumeric parameter that provides the IP address associated with the user's identifier |
+| `identifier`\* | string | Alphanumeric parameter of 20 characters specifying the unique identifier of the user or merchant generating the payment resource. |
+| `urlCommerce`\* | string | URL that identifies the commerce. Must follow valid URL structure with http:// or https:// protocol. Maximum length: 500 characters. |
+| `reference1`\* | string | Customer identifier, must not exceed 20 characters. |
+| `reference2` | object | Object for additional information. |
+| `Label` | object | Object to send information to be displayed in the payment summary. |
+| `Data` | object | Object for information related to the conciliation of the transaction. |
+| `typeKey`\* | string | Can be `alias`, `document`, `email`, and `cellphone` |
+| `key` | string | Key to create |
+| `otp` | string | OTP code for cellphone and email keys |
+| `termsAndConditions`\* | boolean | It must always be set to true. |
+- **`merchant_key_cancel`**: This endpoint allows you to cancel an existing key, which will then become inactive and unable to receive transactions.
+
+Headers
+
+| **Name** | **Value** |
+| --- | --- |
+| Content-Type | application/json |
+| Authorization | Bearer |
+| x-transaction-token | 9b48edde-652d-11ed-984e-02c840fe**** |
+
+Body
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `userMetadata`\* | object | Object containing key details about the user or merchant generating the payment resource. |
+| `ip`\* | string | Alphanumeric parameter that provides the IP address associated with the user's identifier |
+| `identifier`\* | string | Alphanumeric parameter of 20 characters specifying the unique identifier of the user or merchant generating the payment resource. |
+| `urlCommerce`\* | string | URL that identifies the commerce. Must follow valid URL structure with http:// or https:// protocol. Maximum length: 500 characters. |
+| `key` | string | Key to cancel |
+- **`merchant_key_generate_otp`**: This endpoint will allow you to generate and send an OTP. It is only permitted and necessary for `email` and `cellphone` keys. This OTP will be sent to its corresponding destination.
+
+Headers
+
+| **Name** | **Value** |
+| --- | --- |
+| Content-Type | application/json |
+| Authorization | Bearer |
+
+Body
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `typeKey`\* | string | Can be `email` and `cellphone` |
+| `key` | string | key for which the OTP will be generated |
+- **`merchant_key_get_keys`**: This endpoint allows you to obtain all keys created and in active status that belong to the merchant.
+
+## 📝 Logs
+
+El servidor genera logs detallados de todas las operaciones:
+
+```
+[2024-01-01T12:00:00.000Z] get_users iniciada
+[2024-01-01T12:00:01.000Z] get_users completada exitosamente
+```
+
+## 🔍 Troubleshooting
+
+### Error de autenticación
+Verificar que las credenciales estén configuradas correctamente en las variables de entorno.
+
+### Error de conexión a la API
+Verificar que `BASE_URL` sea accesible y la API esté funcionando.
+
+### Error de puerto
+Verificar que el puerto `3009` no esté siendo usado por otro servicio.
+
+## 📞 Soporte
+
+Para soporte técnico, contactar al equipo de desarrollo.
+
+---
+
+*Generado automáticamente por Refacil MCP Framework*