refacil-pay-mcp 1.1.32 → 1.1.33

package/README.md

@@ -4,7 +4,7 @@ Servidor MCP (Model Context Protocol) generado automáticamente para la API refa
 
 ## 🚀 Características
 
-- **18 herramientas** generadas automáticamente desde la colección Postman
+- **20 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
@@ -353,14 +353,16 @@ The table below lists the available payment methods along with their correspondi
 | `262` | Cash-in via **PSE Gateway** | 1,800 |
 | `153` | Cash-in via **Recaudo Efectivo** | 86,400 |
 | `163` | Cash-in via **TPaga** | 43,200 |
-| `248` | Cash-in via **QR Interoperable** | N/A |
+| `248` | Cash-in via **QR Dinámico** (QR Interoperable dinámico) | N/A |
+| `280` | Cash-in via **QR Híbrido** (QR Interoperable híbrido con monto, cantidad de usos y fecha de expiración variables) | N/A |
 | `250` | Cash-in via **Llaves Bre-B** | N/A |
 | `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.  
-> For **QR Interoperable (ID 248)**, the `expiresIn` parameter **must be omitted**. If provided, the system will **ignore it automatically**. The resource expiration is managed internally by the provider and is set to the **end of the same day the resource is generated**.  
+> For **QR Dinámico (ID 248)**, the `expiresIn` parameter **must be omitted**. If provided, the system will **ignore it automatically**. The resource expires at the **end of the day on which it is generated** (23:59:59 America/Bogota).  
+> For **QR Híbrido (ID 280)**, the `expiresIn` parameter **must be omitted**. If provided, the system will **ignore it automatically**. The resource expiration is determined by the `expirationDate` parameter configured in the request.  
 > For **Llaves Dinámicas Bre-B (ID 250)**, the `expiresIn` parameter **must be omitted**. If provided, the system will **ignore it automatically**. The key has a **fixed validity period of 10 minutes** from the moment of creation, determined by the server configuration. 
   
 
@@ -531,7 +533,58 @@ If the request is made from a desktop or tablet, it is recommended to send `isQr
 
 ---
 
-### **QR Interoperable**
+### **QR Interoperable Dinámico**
+
+> ⚠ **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 Dinámico** 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. 
+  
+> 🕐 **Expiration Behavior:**  
+The `expiresIn` parameter **does not apply** to this payment method and should be **omitted** from the request.  
+If a value is sent, the system will **ignore it automatically**.  
+The QR resource expiration is controlled exclusively by the provider (Redeban) and is always set to the **end of the day on which the resource is generated** (23:59:59 America/Bogota). 
+  
+
+#### 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.
+    
+
+#### Request Structure
+
+``` json
+"paymentMethod": {
+  "id": 248
+}
+
+ ```
+
+#### Optional Fields
 
 For this method, the following fields are **optional**:
 
@@ -547,57 +600,84 @@ For this method, the following fields are **optional**:
 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.
 
+---
+
+### **QR Interoperable Híbrido**
+
 > ⚠ **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. 
+> 🔁 **Reusable Resource:**  
+The **QR Interoperable Híbrido** can be scanned up to the number of times specified in `quantityUses`. 
   
-> ⚙️ **Technical Note — Dynamic QR Behavior:**  
-Dynamic QR codes may be scanned multiple times due to current limitations in the Redeban system.  
+> ⚙️ **Technical Note — Hybrid QR Behavior:**  
+The Hybrid QR is a static QR code with a pre-set fixed amount. It generates a closed payment URL valid for a defined number of uses and time period.  
 This is **not** an error in our platform. 
   
 > 🕐 **Expiration Behavior:**  
 The `expiresIn` parameter **does not apply** to this payment method and should be **omitted** from the request.  
 If a value is sent, the system will **ignore it automatically**.  
-The QR resource expiration is controlled exclusively by the provider (Redeban) and is always set to the **end of the day on which the resource is generated** (23:59:59 America/Bogota). 
+The QR validity period is controlled by the `expirationDate` parameter sent in the request. 
   
 
 #### Behavior Details
 
-- Redeban does not automatically invalidate a dynamic QR after its first scan.
+- The QR is valid until it reaches the maximum number of scans defined in `quantityUses` or until the `expirationDate`, whichever comes first.
     
-- As a result, the same QR may generate multiple transaction records.
+- Once the usage limit or expiration date is reached, the QR is automatically invalidated.
     
 
 #### Recommendations
 
-- Implement **application-level validation** to detect multiple payments from the same QR code.
+- Set a `quantityUses` value appropriate for your use case (1–3 uses).
     
-- Monitor dynamic QR transactions and confirm status before marking payments as completed.
+- Set a realistic `expirationDate` to avoid leaving open QR codes active longer than intended.
     
-- Inform end-users to verify the success of a transaction before rescanning.
+- Monitor hybrid QR transactions and confirm status before marking payments as completed.
     
 
 #### Future Considerations
 
-- Redeban is evaluating support for **single-use dynamic QR control**.
-    
 - Stay updated with interoperability provider announcements to adjust integrations accordingly.
     
 
+#### Required Parameters
+
+These parameters are **required** for QR Interoperable Híbrido:
+
+| **Field** | **Type** | **Required** | **Valid values** | **Description** |
+| --- | --- | --- | --- | --- |
+| `quantityUses` | `string` | ✅ | `"1"`, `"2"` or `"3"` | Maximum number of times the QR can be scanned/used. Must be sent as a numeric string. |
+| `expirationDate` | `string` | ✅ | `YYYY-MM-DD` format, from today up to `2100-12-31` | Date until which the QR remains valid. Must be a real calendar date. |
+
+#### Request Structure
+
 ``` json
 "paymentMethod": {
-  "id": 248,
-  "cellphone": "string",
-  "documentType": "string",
-  "documentNumber": "string",
-  "merchantId": "string"
+  "id": 280,
+  "quantityUses": "2",
+  "expirationDate": "2027-12-31"
 }
 
  ```
 
+#### Optional Fields
+
+For this method, the following fields are **optional**:
+
+- `cellphone`
+    
+- `documentNumber`
+    
+- `documentType`
+    
+- `merchantId`
+    
+
+The service can function using only the payment method ID and the required parameters; 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.
+
 ---
 
 ### **Llaves** Dinámicas **Bre-B**
@@ -721,11 +801,11 @@ For this method, the following fields are **optional**:
 
 ``` json
 "paymentMethod": {
-  "id": 277,
-  "cellphone": "string",
-  "pdfUrl": "string",
-  "whatsappAccountId": "string",
-  "templateName": "string"
+  "id": 277, // required
+  "cellphone": "string", // required
+  "pdfUrl": "string", // optional
+  "whatsappAccountId": "string", // required
+  "templateName": "string" // optional
 }
 
  ```
@@ -736,7 +816,7 @@ For this method, the following fields are **optional**:
 | --- | --- | --- | --- |
 | `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. Not applicable for **QR Interoperable (ID 248)** and **Llaves Dinámicas Bre-B (ID 250)** — if provided, the system ignores it. For QR Interoperable, expiration is set to end of day; for Llaves Dinámicas Bre-B, expiration is always 10 minutes from creation. |
+| `expiresIn` | number | ❌ | Time in seconds for the expiration of the resource or payment link. Not applicable for **QR Dinámico (ID 248)**, **QR Híbrido (ID 280)** and **Llaves Dinámicas Bre-B (ID 250)** — if provided, the system ignores it. For QR products, expiration is set to end of day; for Llaves Dinámicas Bre-B, expiration is always 10 minutes from creation. |
 | `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 36 characters. |
@@ -757,16 +837,16 @@ For this method, the following fields are **optional**:
 | Name | Type | Description |
 | --- | --- | --- |
 | body | string | Body del request |
-| expiresIn | number | Campo del body: expiresIn |
-| paymentMethod | object | Campo del body: paymentMethod |
-| userMetadata | object | Campo del body: userMetadata |
 | amount | number | Campo del body: amount |
 | brandId | number | Campo del body: brandId |
-| webhookUrl | string | Campo del body: webhookUrl |
-| returnUrl | string | Campo del body: returnUrl |
-| showSummary | boolean | Campo del body: showSummary |
+| paymentMethod | object | Campo del body: paymentMethod |
 | reference1 | string | Campo del body: reference1 |
 | reference2 | object | Campo del body: reference2 |
+| returnUrl | string | Campo del body: returnUrl |
+| showSummary | boolean | Campo del body: showSummary |
+| userMetadata | object | Campo del body: userMetadata |
+| webhookUrl | string | Campo del body: webhookUrl |
+| expiresIn | number | Campo del body: expiresIn |
 
 ### `cash_out_generate_withdraw_method_token`
 
@@ -1116,6 +1196,341 @@ For withdraws, a notification will be sent to the webhook provided in the applic
 | --- | --- | --- |
 | reference | string | Campo del body: reference |
 
+### `ecommerce_self_register_link`
+
+<img src="https://content.pstmn.io/d2c9fab1-0bbf-40ea-9022-6cc52b24dbb3/aW1hZ2UucG5n" width="214" height="104">
+
+This guide explains how **API clients** (eCommerce platforms, marketplaces, plugins) onboard **merchants** (their end customers) and process payments on their behalf through Refácil Pay.
+
+---
+
+## Overview
+
+The eCommerce integration follows three steps:
+
+1. **Generate a Self Register Link** — Your platform calls the API to obtain a unique registration URL for each merchant.
+2. **Merchant registration** — The merchant opens the link and completes onboarding in Refácil Pay.
+3. **API consumption** — After successful registration, process payments using either **direct** or **delegated** integration (see below).
+
+> **Prerequisites:** Your platform must already be registered with Refácil Pay and have valid API credentials (`Authorization` token from the **Authorization** section).
+
+---
+
+## Integration flow
+
+```
+┌─────────────────┐     POST /ecommerce/self-register/link      ┌──────────────┐
+│  API client     │ ──────────────────────────────────────────► │ Refácil Pay  │
+│  (your platform)│ ◄──────────────── { link } ─────────────────│              │
+└────────┬────────┘                                               └──────────────┘
+         │ share link
+         ▼
+┌─────────────────┐     completes registration                  ┌──────────────┐
+│  Merchant       │ ──────────────────────────────────────────► │ Refácil Pay  │
+└─────────────────┘                                               └──────┬───────┘
+                                                                         │
+         ◄──────── POST webhook (registration completed) ───────────────┘
+┌─────────────────┐
+│  API client     │
+└─────────────────┘
+```
+
+---
+
+## Step 1 — Generate Self Register Link
+
+Call **Generate Self Register Link** with:
+
+- `storeId` — Your unique identifier for the merchant within your platform.
+- `returnUrl` — HTTPS URL where Refácil Pay will notify you when the merchant completes registration successfully (also referred to as your **webhook URL**).
+
+The response contains a `link` URL. Share this link with the merchant (email, dashboard, plugin UI, etc.).
+
+See the **Generate Self Register Link** request in this section for full request/response details.
+
+---
+
+## Step 2 — Merchant registration & webhook
+
+The merchant opens the registration link and completes the Refácil Pay onboarding flow (identity verification and account setup).
+
+When registration completes successfully, **Refácil Pay sends a notification to the webhook URL** (`returnUrl`) you provided in Step 1.
+
+See **Registration completion webhook** in this section for payload format, headers, and signature verification.
+
+> **Important:** Your webhook endpoint must be publicly reachable over HTTPS and respond with HTTP `2xx` to acknowledge receipt.
+
+---
+
+## Step 3 — API consumption
+
+After registration, choose one of the following integration modes.
+
+### Option A — Direct merchant integration
+
+The registered merchant obtains their own Refácil Pay API credentials and consumes the API directly. All transactions are naturally associated with that merchant account.
+
+No additional fields are required beyond the standard payment APIs documented in the **Payments** section.
+
+### Option B — Delegated integration (on behalf of the merchant)
+
+Your platform continues to authenticate with **your own API credentials**, but operations are executed **on behalf of the registered merchant**.
+
+Include the following object in `reference2` when generating payment resources:
+
+
+**Example — Generate Payment Link (delegated mode)**
+
+``` json
+{
+  "expiresIn": 12360,
+  "amount": 18000,
+  "brandId": 61,
+  "webhookUrl": "https://your-platform.com/webhooks/payment-status",
+  "returnUrl": "https://your-platform.com/payment/return",
+  "showSummary": true,
+  "reference1": "CGOOsiYQspMpgDD",
+  "reference2": {
+    "Label": {
+      "Name": "Juanita Perez",
+      "Email": "pqacLO87V77DgF62P8PXENA==do",
+      "CellPhone": "1VM6daPPJcXCD4Cw93272oQ==8",
+      "PersonType": "N",
+      "DocumentType": "C",
+      "DocumentNumber": 79706920
+    },
+    "Commerce": {
+      "origin": 1,
+      "storeId": "12345"
+    }
+  }
+}
+
+ ```
+
+These identifiers allow Refácil Pay to associate each transaction with the correct merchant while authentication remains under your platform credentials.
+
+---
+
+## Related sections
+
+| Section | Purpose |
+| --- | --- |
+| **Authorization** | Obtain `Bearer` token for API calls |
+| **Transactional token** | Required before generating payment resources |
+| **Payments** | Generate payment links and cash-in resources |
+| **Webhook Notification** | Payment status notifications (separate from registration webhook) |
+
+---
+
+## Best practices
+
+- Generate a **unique `storeId`** per merchant and persist the mapping on your side.
+- Use **HTTPS** for all webhook URLs.
+- Implement **idempotent** webhook handlers (the same registration event may be retried).
+- Verify the **`x-refacil-signature`** header on registration webhooks (see webhook request).
+- For delegated payments, always send **`reference2.Commerce`** with both `origin` and `storeId`.
+- Use the **QA environment** for end-to-end testing before production certification.
+
+ Generates a **Self Register Link** for a merchant to onboard in Refácil Pay.
+
+Use this endpoint when your platform needs to register merchants under your eCommerce integration. Provide a stable `storeId` for each merchant and an HTTPS `returnUrl` (webhook URL) to receive the registration completion notification.
+
+> **Authentication:** Requires a valid Bearer token obtained from **Login** in the Authorization section.
+
+
+### Response
+
+
+### Error responses
+
+| **HTTP** | **When** |
+| --- | --- |
+| **401** | Missing or invalid Bearer token. |
+| **403** | The eCommerce store is not associated with your account. |
+| **409** | Store already registered, or store configuration incomplete. |
+| **500** | Unexpected error. Retry with backoff; contact support if unresolved.
+
+**Parámetros:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| storeId | string | Campo del body: storeId |
+| returnUrl | string | Campo del body: returnUrl |
+
+### `webhooks_merchant_registration`
+
+<img src="https://content.pstmn.io/d2c9fab1-0bbf-40ea-9022-6cc52b24dbb3/aW1hZ2UucG5n" width="214" height="104">
+
+This guide explains how **API clients** (eCommerce platforms, marketplaces, plugins) onboard **merchants** (their end customers) and process payments on their behalf through Refácil Pay.
+
+---
+
+## Overview
+
+The eCommerce integration follows three steps:
+
+1. **Generate a Self Register Link** — Your platform calls the API to obtain a unique registration URL for each merchant.
+2. **Merchant registration** — The merchant opens the link and completes onboarding in Refácil Pay.
+3. **API consumption** — After successful registration, process payments using either **direct** or **delegated** integration (see below).
+
+> **Prerequisites:** Your platform must already be registered with Refácil Pay and have valid API credentials (`Authorization` token from the **Authorization** section).
+
+---
+
+## Integration flow
+
+```
+┌─────────────────┐     POST /ecommerce/self-register/link      ┌──────────────┐
+│  API client     │ ──────────────────────────────────────────► │ Refácil Pay  │
+│  (your platform)│ ◄──────────────── { link } ─────────────────│              │
+└────────┬────────┘                                               └──────────────┘
+         │ share link
+         ▼
+┌─────────────────┐     completes registration                  ┌──────────────┐
+│  Merchant       │ ──────────────────────────────────────────► │ Refácil Pay  │
+└─────────────────┘                                               └──────┬───────┘
+                                                                         │
+         ◄──────── POST webhook (registration completed) ───────────────┘
+┌─────────────────┐
+│  API client     │
+└─────────────────┘
+```
+
+---
+
+## Step 1 — Generate Self Register Link
+
+Call **Generate Self Register Link** with:
+
+- `storeId` — Your unique identifier for the merchant within your platform.
+- `returnUrl` — HTTPS URL where Refácil Pay will notify you when the merchant completes registration successfully (also referred to as your **webhook URL**).
+
+The response contains a `link` URL. Share this link with the merchant (email, dashboard, plugin UI, etc.).
+
+See the **Generate Self Register Link** request in this section for full request/response details.
+
+---
+
+## Step 2 — Merchant registration & webhook
+
+The merchant opens the registration link and completes the Refácil Pay onboarding flow (identity verification and account setup).
+
+When registration completes successfully, **Refácil Pay sends a notification to the webhook URL** (`returnUrl`) you provided in Step 1.
+
+See **Registration completion webhook** in this section for payload format, headers, and signature verification.
+
+> **Important:** Your webhook endpoint must be publicly reachable over HTTPS and respond with HTTP `2xx` to acknowledge receipt.
+
+---
+
+## Step 3 — API consumption
+
+After registration, choose one of the following integration modes.
+
+### Option A — Direct merchant integration
+
+The registered merchant obtains their own Refácil Pay API credentials and consumes the API directly. All transactions are naturally associated with that merchant account.
+
+No additional fields are required beyond the standard payment APIs documented in the **Payments** section.
+
+### Option B — Delegated integration (on behalf of the merchant)
+
+Your platform continues to authenticate with **your own API credentials**, but operations are executed **on behalf of the registered merchant**.
+
+Include the following object in `reference2` when generating payment resources:
+
+
+**Example — Generate Payment Link (delegated mode)**
+
+``` json
+{
+  "expiresIn": 12360,
+  "amount": 18000,
+  "brandId": 61,
+  "webhookUrl": "https://your-platform.com/webhooks/payment-status",
+  "returnUrl": "https://your-platform.com/payment/return",
+  "showSummary": true,
+  "reference1": "CGOOsiYQspMpgDD",
+  "reference2": {
+    "Label": {
+      "Name": "Juanita Perez",
+      "Email": "pqacLO87V77DgF62P8PXENA==do",
+      "CellPhone": "1VM6daPPJcXCD4Cw93272oQ==8",
+      "PersonType": "N",
+      "DocumentType": "C",
+      "DocumentNumber": 79706920
+    },
+    "Commerce": {
+      "origin": 1,
+      "storeId": "12345"
+    }
+  }
+}
+
+ ```
+
+These identifiers allow Refácil Pay to associate each transaction with the correct merchant while authentication remains under your platform credentials.
+
+---
+
+## Related sections
+
+| Section | Purpose |
+| --- | --- |
+| **Authorization** | Obtain `Bearer` token for API calls |
+| **Transactional token** | Required before generating payment resources |
+| **Payments** | Generate payment links and cash-in resources |
+| **Webhook Notification** | Payment status notifications (separate from registration webhook) |
+
+---
+
+## Best practices
+
+- Generate a **unique `storeId`** per merchant and persist the mapping on your side.
+- Use **HTTPS** for all webhook URLs.
+- Implement **idempotent** webhook handlers (the same registration event may be retried).
+- Verify the **`x-refacil-signature`** header on registration webhooks (see webhook request).
+- For delegated payments, always send **`reference2.Commerce`** with both `origin` and `storeId`.
+- Use the **QA environment** for end-to-end testing before production certification.
+
+ When a merchant **successfully completes registration**, Refácil Pay sends an HTTPS **POST** notification to the `returnUrl` (webhook URL) you provided in **Generate Self Register Link**.
+
+This notification confirms that the merchant is ready for API consumption. It is **not** a payment status webhook — see **Webhook Notification** for transaction events.
+
+### Headers sent by Refácil Pay
+
+
+### Body fields
+
+
+### Verification
+
+1. Read the raw request body.
+2. Compute HMAC-SHA256 using your **signing secret** (provided by Refácil Pay).
+3. Compare with the `x-refacil-signature` header.
+4. Reject requests with invalid signatures.
+
+### Handler requirements
+
+- Respond with HTTP **2xx** to acknowledge receipt.
+- Implement **idempotency** using `eventId`.
+- Persist the `storeId` ↔ `userId` mapping for delegated integrations.
+
+> **Note:** Do not expose this endpoint without signature verification.
+
+**Parámetros:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| refacilSignature * | string | Header personalizado: x-refacil-signature |
+| refacilTimestamp * | string | Header personalizado: x-refacil-timestamp |
+| originCommerce * | string | Header personalizado: x-origin-commerce |
+| storeId | string | Campo del body: storeId |
+| userId | number | Campo del body: userId |
+| eventId | string | Campo del body: eventId |
+| activatedAt | string | Campo del body: activatedAt |
+
 ### `merchant_enrollment_data`
 
 This service allows merchants to retrieve enrollment data for the use of the QR interoperable payment method and key creation.