npm - refacil-pay-mcp - Versions diffs - 1.1.13 → 1.1.15 - Mend

refacil-pay-mcp 1.1.13 → 1.1.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md +485 -8
package/dist/core/resources.js +34 -6
package/dist/core/resources.js.map +1 -1
package/dist/core/tools.d.ts +5 -1
package/dist/core/tools.js +252 -152
package/dist/core/tools.js.map +1 -1
package/dist/index.js +4 -8
package/dist/index.js.map +1 -1
package/package.json +5 -2

package/README.md CHANGED Viewed

@@ -4,7 +4,7 @@ Servidor MCP (Model Context Protocol) generado automáticamente para la API refa
 ## 🚀 Características
-- **15 herramientas** generadas automáticamente desde la colección Postman
+- **18 herramientas** generadas automáticamente desde la colección Postman
 - **Autenticación flexible**: Username/Password con renovación automática de tokens
 - **Servidor HTTP** con Fastify
 - **Protocolo MCP** estándar para integración con IDEs
@@ -356,6 +356,8 @@ The table below lists the available payment methods along with their correspondi
 | `163` | Cash-in via **TPaga** | 43,200 |
 | `248` | Cash-in via **QR Interoperable** | N/A |
 | `250` | Cash-in via **Llaves Bre-B** | 300 |
+| `273` | Cash-in via **Tarjetas** (Débito y Crédito) | 3,600 |
+| `277` | Cash-in via **Whatsapp** | 2,592,000 |
 > ⚠ **Important:**
 The value provided in the expiresIn field **must be greater than or equal** to the minimum expiration defined for the selected payment method. **This does not apply to dynamic keys, which always expire 5 minutes after creation.**
@@ -654,6 +656,138 @@ This behavior does not represent an error or malfunction in our platform.
 ---
+### **Card Payments**
+This payment method allows processing payments with debit and credit cards (Mastercard and Visa).
+For this method, the following fields are **required**:
+- `id`: 273
+- `description`: Description of the payment detail that will be displayed in the payment link
+- `external`: Defines the type of link generated
+#### PaymentMethod Parameters
+| **Field** | **Type** | **Required** | **Description** |
+| --- | --- | --- | --- |
+| `id` | number | ✅ | Payment method ID: 273 |
+| `description` | string | ✅ | Description of the payment detail that will be displayed in the payment link |
+| `external` | boolean | ✅ | Defines whether to generate a payment link to send directly to the client (`true`) or to embed in an iframe (`false`) |
+#### Behavior based on the `external` parameter
+| **Value** | **Description** |
+| --- | --- |
+| `true` | Generates a payment link to send directly to the client. The client can complete the payment from their browser or mobile application. |
+| `false` | Generates a link to embed in an iframe within your own website. The payment is processed within your site. |
+#### Iframe Implementation Example
+When `external: false`, you can embed the payment link in an iframe as follows:
+``` html
+<html>
+<head>
+  <title>Add Payment Method</title>
+</head>
+<body>
+  <iframe
+    src="YOUR-URL-LINK-ID"
+    width="100%"
+    height="600"
+    frameborder="0"
+    style="max-width: 500px; margin: 0 auto; display: block;">
+  </iframe>
+</body>
+</html>
+ ```
+> ⚠️ **Important:**
+> You must use the **complete URL** from the `url` field in the service response as the `src` attribute value in the iframe. The `src` attribute must contain the entire URL returned in the `data.url` field of the API response. For example, if the response contains:
+``` json
+"data": {
+  "url": "https://checkout.akua.la/links/lnk-07595544-cfe6-4d40-8894-0ed7cf3c28b9?sandbox=true"
+}
+ ```
+Then the iframe `src` should be:
+``` html
+<iframe src="https://checkout.akua.la/links/lnk-07595544-cfe6-4d40-8894-0ed7cf3c28b9?sandbox=true" ...></iframe>
+ ```
+``` json
+"paymentMethod": {
+  "id": 273,
+  "description": "Payment description",
+  "external": true
+}
+ ```
+#### Response Example
+``` json
+{
+  "statusCode": "00",
+  "message": "Operación exitosa.",
+  "data": {
+    "url": "https://checkout.akua.la/links/lnk-07595544-cfe6-4d40-8894-0ed7cf3c28b9?sandbox=true",
+    "reference": "db205760-d228-11f0-8923-0d9b7d755dab",
+    "resourceId": "2762357",
+    "expiresIn": "2025-12-06T22:22:16.000Z",
+    "urlStatusPay": "https://mf-core.refacil.co/refacilpay/resumen/79/db205760-d228-11f0-8923-0d9b7d755dab",
+    "resourceUrlId": "1762027",
+    "status": 1
+  }
+}
+ ```
+#### Response Fields
+| **Field** | **Description** |
+| --- | --- |
+| `url` | Payment link URL. Can be used for direct redirection or to embed in an iframe depending on the `external` value |
+| `reference` | Unique transaction reference |
+| `resourceId` | Generated payment resource ID |
+| `expiresIn` | Payment link expiration date and time |
+| `urlStatusPay` | URL to check the payment status |
+| `resourceUrlId` | URL resource ID |
+| `status` | Resource status (1 = Active) |
+---
+### **Whatsapp**
+For this method, the following fields are **required**:
+- `cellphone`
+- `pdfUrl`
+> ⚠ **pdfUrl — URL standards (Meta/WhatsApp):**
+The value is not arbitrary. The URL must comply with the following so that the document can be sent via WhatsApp:
+- **Protocol:** Must be **HTTPS**.
+- **Access:** The resource must be **publicly accessible** (no authentication); the system downloads the file from this URL.
+- **Format:** The file must be a valid **PDF**.
+- **Size:** Document size must not exceed **100 MB** (WhatsApp Cloud API limit for documents).
+Sending a URL that does not meet these requirements may result in rejection or delivery failure.
+``` json
+"paymentMethod": {
+  "id": 277,
+  "cellphone": "string",
+  "pdfUrl": "string"
+}
+ ```
+---
 ## 📥 Request Body Parameters
 | **Field** | **Type** | **Required** | **Description** |
@@ -774,7 +908,6 @@ The `key` field must contain a valid Bre-B account alias in the format `@USERNAM
 | transactionToken | string | Header personalizado: x-transaction-token |
 | amount | number | Campo del body: amount |
 | reference1 | string | Campo del body: reference1 |
-| bankName | string | Campo del body: bankName |
 | webhookRequest | string | Campo del body: webhookRequest |
 | withdrawMethod | object | Campo del body: withdrawMethod |
 | userMetadata | object | Campo del body: userMetadata |
@@ -1044,7 +1177,7 @@ For withdraws, a notification will be sent to the webhook provided in the applic
 ### `merchant_enrollment_data`
-This service allows merchants to enroll for the use of the QR interoperable payment method and key creation.
+This service allows merchants to retrieve enrollment data for the use of the QR interoperable payment method and key creation.
 To use the service, an authentication token is required and must be sent as an `Authorization` header.
@@ -1052,11 +1185,7 @@ To use the service, an authentication token is required and must be sent as an `
 ### **Enrollment Process**
-1. **Merchant Enrollment**
-    - Initiates the enrollment process. The enrollment can take up to **7 minutes** to complete.
-2. **Retrieve Enrollment Data**
+1. **Retrieve Enrollment Data**
     - Retrieves the merchant’s enrollment information once the process is completed.
@@ -1106,6 +1235,354 @@ To avoid these issues, a randomly generated alias is used as a placeholder. This
  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.
+### `user_webhooks`
+Service to **configure backup webhooks per client**. It allows listing, creating and activating/deactivating URLs to which RefacilPay will send notifications when the payment resource has no webhook configured (e.g. for Saldo or Dispersión).
+---
+### Endpoints
+1. **List user webhooks** (GET) – Returns the backup webhooks configured for the **authenticated user** (user inferred from Bearer token).
+2. **Create user webhook** (POST) – Creates a backup webhook for the **authenticated user** and type (Saldo or Dispersión).
+3. **Update webhook status** (PATCH) – Activates or deactivates a backup webhook **owned by the authenticated user**.
+All endpoints require Bearer token authentication (`Authorization: Bearer {{tokenLogin}}`). The user is always inferred from the token for security.
+ ---
+### Description
+Returns the **backup webhooks** configured for the **authenticated user**. The user is identified by the Bearer token (header `Authorization`). The response lists all webhooks for that user with their type (e.g. Saldo, Dispersión), URL and active/inactive status.
+---
+### What it is for
+- Query which backup webhook URLs the authenticated client has configured.
+- See the status (active/inactive) of each webhook.
+- List available webhook types (Saldo, Dispersión).
+---
+### Request
+---
+### Response
+- **statusCode** (string): Operation status code. `00` = success.
+- **message** (string): Descriptive message (e.g. "Operación exitosa.").
+- **data** (array): List of webhooks, each with: `id`, `userId`, `webhookTypeId`, `typeName`, `url`, `active`, `createdAt`, `updatedAt`.
+---
+### Example: Success (200 OK)
+```
+GET {{protocol}}://{{serverNamePayApi}}/user-webhooks
+Authorization: Bearer {{tokenLogin}}
+ ```
+Response body:
+``` json
+{
+  "statusCode": "00",
+  "message": "Operación exitosa.",
+  "data": [
+    {
+      "id": 1,
+      "userId": 12345,
+      "webhookTypeId": 1,
+      "typeName": "Saldo",
+      "url": "https://my-server.com/webhooks/saldo",
+      "active": true,
+      "createdAt": "2025-01-15T10:00:00.000Z",
+      "updatedAt": "2025-01-15T10:00:00.000Z"
+    },
+    {
+      "id": 2,
+      "userId": 12345,
+      "webhookTypeId": 2,
+      "typeName": "Dispersión",
+      "url": "https://my-server.com/webhooks/dispersion",
+      "active": false,
+      "createdAt": "2025-01-14T08:30:00.000Z",
+      "updatedAt": "2025-01-16T14:20:00.000Z"
+    }
+  ]
+}
+ ```
+---
+### Example: Empty list (200 OK)
+When the user has no webhooks configured, `data` is an empty array:
+``` json
+{
+  "statusCode": "00",
+  "message": "Operación exitosa.",
+  "data": []
+}
+ ```
+### `create_user_webhook`
+Service to **configure backup webhooks per client**. It allows listing, creating and activating/deactivating URLs to which RefacilPay will send notifications when the payment resource has no webhook configured (e.g. for Saldo or Dispersión).
+---
+### Endpoints
+1. **List user webhooks** (GET) – Returns the backup webhooks configured for the **authenticated user** (user inferred from Bearer token).
+2. **Create user webhook** (POST) – Creates a backup webhook for the **authenticated user** and type (Saldo or Dispersión).
+3. **Update webhook status** (PATCH) – Activates or deactivates a backup webhook **owned by the authenticated user**.
+All endpoints require Bearer token authentication (`Authorization: Bearer {{tokenLogin}}`). The user is always inferred from the token for security.
+ ---
+### Description
+Creates a **backup webhook** for a user and webhook type. When a new webhook is created, only this webhook remains active for that user and type; others of the same type are deactivated.
+---
+### What it is for
+- Configure the URL to which RefacilPay will send backup notifications when the resource has no `webhookRequest`.
+---
+### Request
+---
+### Possible values for `webhookTypeId`
+| Value | Description |
+| --- | --- |
+| **1** | Saldo (cash-in backup notifications) |
+| **2** | Dispersión (cash-out / dispersion backup notifications) |
+---
+### Example: Success (200 OK)
+```
+POST {{protocol}}://{{serverNamePayApi}}/user-webhooks
+Authorization: Bearer {{tokenLogin}}
+Content-Type: application/json
+{
+  "webhookTypeId": 2,
+  "url": "https://my-server.com/webhooks/dispersion"
+}
+ ```
+The user is inferred from the Bearer token; do not send `userId` in the body.
+Response body:
+``` json
+{
+  "statusCode": "00",
+  "message": "Operación exitosa.",
+  "data": {
+    "id": 3,
+    "userId": 12345,
+    "webhookTypeId": 2,
+    "url": "https://my-server.com/webhooks/dispersion",
+    "active": true,
+    "createdAt": "2025-01-16T12:00:00.000Z",
+    "updatedAt": "2025-01-16T12:00:00.000Z"
+  }
+}
+ ```
+---
+### Example: Webhook type not found (404 Not Found)
+When `webhookTypeId` is not an allowed value (only **1** and **2** are valid), the API returns:
+``` json
+{
+  "statusCode": 404,
+  "message": "Webhook type not found: 99",
+  "error": "Not Found"
+}
+ ```
+---
+### Example: Validation error (400 Bad Request)
+When the request body is invalid (e.g. missing required fields, invalid URL format), the API returns validation errors:
+``` json
+{
+  "statusCode": 400,
+  "message": [
+    "url must be a URL address",
+    "url must be a URL address"
+  ],
+  "error": "Bad Request"
+}
+ ```
+**Parámetros:**
+| Name | Type | Description |
+| --- | --- | --- |
+| webhookTypeId | number | Campo del body: webhookTypeId |
+| url | string | Campo del body: url |
+### `user_webhooks_status`
+Service to **configure backup webhooks per client**. It allows listing, creating and activating/deactivating URLs to which RefacilPay will send notifications when the payment resource has no webhook configured (e.g. for Saldo or Dispersión).
+---
+### Endpoints
+1. **List user webhooks** (GET) – Returns the backup webhooks configured for the **authenticated user** (user inferred from Bearer token).
+2. **Create user webhook** (POST) – Creates a backup webhook for the **authenticated user** and type (Saldo or Dispersión).
+3. **Update webhook status** (PATCH) – Activates or deactivates a backup webhook **owned by the authenticated user**.
+All endpoints require Bearer token authentication (`Authorization: Bearer {{tokenLogin}}`). The user is always inferred from the token for security.
+ ---
+### Description
+Updates the **active/inactive status** of a backup webhook **owned by the authenticated user**. The user is identified by the Bearer token; you can only update webhooks that belong to that user. If a webhook is activated, other webhooks for the same user and type are deactivated (only one active per type per user).
+---
+### What it is for
+- Activate or deactivate a backup webhook URL without deleting it.
+- Switch which URL receives notifications when multiple are configured (activating one deactivates others of the same type).
+---
+### Request
+---
+### Example: Success (200 OK)
+```
+PATCH {{protocol}}://{{serverNamePayApi}}/user-webhooks/1/status
+Authorization: Bearer {{tokenLogin}}
+Content-Type: application/json
+{
+  "active": true
+}
+ ```
+Response body:
+``` json
+{
+  "statusCode": "00",
+  "message": "Operación exitosa.",
+  "data": {
+    "id": 1,
+    "userId": 12345,
+    "webhookTypeId": 1,
+    "url": "https://my-server.com/webhooks/saldo",
+    "active": true,
+    "createdAt": "2025-01-15T10:00:00.000Z",
+    "updatedAt": "2025-01-16T15:30:00.000Z"
+  }
+}
+ ```
+---
+### Example: User webhook not found (404 Not Found)
+When no webhook exists with the given `id`, the API returns:
+``` json
+{
+  "statusCode": 404,
+  "message": "User webhook not found: 999",
+  "error": "Not Found"
+}
+ ```
+---
+### Example: Forbidden (403 Forbidden)
+When the webhook does not belong to the authenticated user, the API returns:
+``` json
+{
+  "statusCode": 403,
+  "message": "Webhook does not belong to the authenticated user",
+  "error": "Forbidden"
+}
+ ```
+---
+### Example: Validation error (400 Bad Request)
+When `id` is not a valid number or body is invalid:
+``` json
+{
+  "statusCode": 400,
+  "message": "Validation failed (numeric string is expected)",
+  "error": "Bad Request"
+}
+ ```
+**Parámetros:**
+| Name | Type | Description |
+| --- | --- | --- |
+| active | boolean | Campo del body: active |
 ## 📝 Logs