refacil-pay-mcp 1.0.1 → 1.0.4

package/README.md

@@ -151,14 +151,13 @@ nano .env
 | `PORT` | Puerto del servidor | `3009` |
 | `ENVIRONMENT` | Entorno de ejecución | `development` |
 | `BASE_URL` | URL base de la API | `https://pay-api.qa.refacil.co` |
-
-
 | `USERNAME` | Usuario para autenticación | `your_username_here` |
 | `PASSWORD` | Contraseña para autenticación | `your_password_here` |
 | `AUTH_ENDPOINT` | Endpoint de autenticación | `/auth/login` |
 | `TOKEN_CACHE_TTL` | TTL del caché de tokens (segundos) | `3600` |
 | `MCP_TOKEN` | Token de autenticación del MCP | `mcp-secret-token-refacil-pay` |
 
+
 ## 🐳 Docker
 
 ```bash
@@ -190,730 +189,226 @@ kubectl get pods -l app=refacil-pay-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.
-
----
+### `auth_login`
 
-### 💡 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.
+**Parámetros:**
 
-| **Method ID** | **Description** | **Minimum Expiration (seconds)** |
+| Name | Type | Description |
 | --- | --- | --- |
-| `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**
+| username | string | Campo del body: username |
+| password | string | Campo del body: password |
 
-``` 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"
-}
-
- ```
-
----
+### `trx_token_generate`
 
-### **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**
+**Parámetros:**
 
-``` json
-"paymentMethod": {
-  "id": 134
-}
-
- ```
-
----
-
-### **Recaudo Efectivo**
+| Name | Type | Description |
+| --- | --- | --- |
+| service | string | Campo del body: service |
 
-``` json
-"paymentMethod": {
-  "id": 153
-}
+### `transactional_token_method`
 
- ```
 
----
+**Parámetros:**
 
-### **Transfiya Recaudo**
+| Name | Type | Description |
+| --- | --- | --- |
+| service | string | Campo del body: service |
 
-``` json
-"paymentMethod": {
-  "id": 155,
-  "cellphone": "3105293225"
-}
+### `transactional_token_withdraw`
 
- ```
 
----
+**Parámetros:**
 
-### **TPaga**
+| Name | Type | Description |
+| --- | --- | --- |
+| service | string | Campo del body: service |
 
-This payment method supports an optional parameter called `isQr`, which determines the type of resource returned in the `url` field:
+### `transactional_token_merchan_key_create`
 
-| **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. 
-  
+**Parámetros:**
 
-``` json
-"paymentMethod": {
-  "id": 163,
-  "isQr": false
-}
+| Name | Type | Description |
+| --- | --- | --- |
+| service | string | Campo del body: service |
 
- ```
+### `transactional_token_merchant_key_cancel`
 
----
 
-### **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"
-}
+**Parámetros:**
 
- ```
+| Name | Type | Description |
+| --- | --- | --- |
+| service | string | Campo del body: service |
 
----
+### `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 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
+**Parámetros:**
 
-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
+| Name | Type | Description |
+| --- | --- | --- |
+| expiresIn | number | Campo del body: expiresIn |
+| amount | number | Campo del body: amount |
+| brandId | number | Campo del body: brandId |
+| webhookUrl | string | Campo del body: webhookUrl |
+| userMetadata | object | Campo del body: userMetadata |
+| returnUrl | string | Campo del body: returnUrl |
+| reference1 | string | Campo del body: reference1 |
+| reference2 | object | Campo del body: reference2 |
 
-### **Transfiya**
+### `cash_in_generate_payment_method_token`
 
-``` json
-"withdrawMethod": {
-  "id": 245,
-  "cellphone": "3125763074"
-}
+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.   > ⚠ **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.   > ⚠️ **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:   > 🧠 **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
 
- ```
+**Parámetros:**
 
-**Description:**  
-Transfers funds to a recipient using their registered Transfiya cellphone number.
+| Name | Type | Description |
+| --- | --- | --- |
+| 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 |
+| reference1 | string | Campo del body: reference1 |
+| reference2 | object | Campo del body: reference2 |
 
-> ⚠ **Important:**  
-Ensure the cellphone number is registered with Transfiya and capable of receiving funds. 
-  
+### `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.   > ⚠ **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
 
-### **Bre-B**
+**Parámetros:**
 
-``` json
-"withdrawMethod": {
-  "id": 264,
-  "key": "@REPRUEBAL7717"
-}
+| Name | Type | Description |
+| --- | --- | --- |
+| 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 |
 
- ```
+### `customer_getbalance`
 
-**Description:**  
-Transfers funds directly to a Bre-B account using the beneficiary’s unique Bre-B key.
+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   Body
 
-> 💡 **Tip:**  
-The `key` field must contain a valid Bre-B account alias in the format `@USERNAME`. 
-  
+**Parámetros:**
 
----
+| Name | Type | Description |
+| --- | --- | --- |
+| userId | number | Campo del body: userId |
 
-## 📥 Request Body Parameters
+### `payment_transfiya_banks`
 
-| **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. |
+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   Body
 
----
-- **`customer_getbalance`**: This service allows you to consult the balance exchange and the dispersion exchange associated with the client's identifier.
+**Parámetros:**
 
-> To use the service, an authentication token is required, which must be sent as an Authorization header. 
-  
+| Name | Type | Description |
+| --- | --- | --- |
+| cellphone | string | Campo del body: cellphone |
 
-Headers
+### `payment_status`
 
-| **Name** | **Value** |
-| --- | --- |
-| Content-Type | application/json |
-| Authorization | Bearer |
+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   Body
 
-Body
+**Parámetros:**
 
 | 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.
+| reference | string | Campo del body: reference |
 
-> To use the service, an authentication token is required, which must be sent as an Authorization header. 
-  
+### `payment_customer_reference_status`
 
-Headers
+## 🔍 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
 
-| **Name** | **Value** |
-| --- | --- |
-| Content-Type | application/json |
-| Authorization | Bearer |
-
-Body
+**Parámetros:**
 
 | 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
+| customerReference | string | Campo del body: customerReference |
 
-2 - Transaction Approved
+### `payment_features`
 
-3 - Failed Transaction
+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   Body
 
-5 - Transaction Cancelled
+**Parámetros:**
 
-9 - Processing Transaction
+| Name | Type | Description |
+| --- | --- | --- |
+| id | number | Campo del body: id |
 
-Headers
+### `webhook_notify`
 
-| **Name** | **Value** |
-| --- | --- |
-| Content-Type | application/json |
-| Authorization | Bearer |
+Body    ## TransfiYa Status   ### Transfer state machine  <img src="https://content.pstmn.io/89f89557-2e1b-44c2-8dcb-d9e7d2f32c54/aW1hZ2UucG5n" width="293" height="380">
 
-Body
+**Parámetros:**
 
 | 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:
+| reference | string | Campo del body: reference |
 
-- `/cash-in/generate/payment-link/token`
-    
-- `/cash-in/generate/payment-method/token`
-    
-- `/cash-out/generate/withdraw-method/token`
-    
+### `merchant_enrollment`
 
-This service is useful for retrieving the internal **Refacil** transaction information associated with a previously submitted customer reference.
-
----
+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.
 
-## 🔐 Authentication
+### `merchant_enrollment_data`
 
-This endpoint **requires** a valid Bearer Token in the request headers. Requests without valid authentication will be rejected with an `Unauthorized` error.
+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.
 
-## 📤 Successful Response
+### `merchant_key_create`
 
-- `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`.
-    
+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   Body
 
-### ℹ️ Status Code Reference
+**Parámetros:**
 
-| 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
+| Name | Type | Description |
+| --- | --- | --- |
+| webhookUrl | string | Campo del body: webhookUrl |
+| reference1 | string | Campo del body: reference1 |
+| reference2 | object | Campo del body: reference2 |
+| userMetadata | object | Campo del body: userMetadata |
+| typeKey | string | Campo del body: typeKey |
+| key | string | Campo del body: key |
+| otp | string | Campo del body: otp |
+| termsAndConditions | boolean | Campo del body: termsAndConditions |
 
-Headers
+### `merchant_key_cancel`
 
-| **Name** | **Value** |
-| --- | --- |
-| Content-Type | application/json |
-| Authorization | Bearer |
+This endpoint allows you to cancel an existing key, which will then become inactive and unable to receive transactions.  Headers   Body
 
-Body
+**Parámetros:**
 
 | Name | Type | Description |
 | --- | --- | --- |
-| `id`\* | integer | Product identification |
-- **`webhook_notify`**: Body
+| userMetadata | object | Campo del body: userMetadata |
+| key | string | Campo del body: key |
 
-| 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
+### `merchant_key_generate_otp`
 
-| 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
+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   Body
+
+**Parámetros:**
 
 | 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
+| key | string | Campo del body: key |
+| typeKey | string | Campo del body: typeKey |
 
-| **Name** | **Value** |
-| --- | --- |
-| Content-Type | application/json |
-| Authorization | Bearer |
+### `merchant_key_get_keys`
 
-Body
+This endpoint allows you to obtain all keys created and in active status that belong to the merchant.
 
-| 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