refacil-pay-mcp 1.1.3 → 1.1.7

package/README.md

@@ -194,7 +194,12 @@ kubectl get pods -l app=refacil-pay-mcp
 
 ### `auth_login`
 
-POST /auth/login
+To make the request and obtain the login you must have very clear your username and password for each environment where you are going to perform the integration, this information should be requested to our support team ([soportetecnico@refacil.com](https://mailto:soportetecnico@refacil.co)).
+
+Within the post you will see below are the fields to make your request
+
+> Note that for the consumption of any of the API services it is necessary to send the authentication token that you get when consuming the **auth/login** service as an Authorization indicating the Type and Token.  
+The authentication token does not expire. However, if at any time it were to expire, it will be necessary to generate a new authentication token. This could occur due to internal security measures that lead to manual or mass expiration of the token.
 
 **Parámetros:**
 
@@ -205,7 +210,15 @@ POST /auth/login
 
 ### `trx_token_generate`
 
-Generates a transactional token for payment link service.
+This service allows security validation for the execution of a transaction on the platform, generating a single-use token.
+
+> The transactional token service is obtained in three ways, depending on the action to be performed. For this, the value sent in the _**service**_ parameter must be set according to what is required:  
+1\. For Payment Link: **“/cash-in/generate/payment-link/token”**.  
+2\. For Payment method: **“/cash-in/generate/payment-method/token”**.  
+3\. For Withdraw: **“/cash-out/generate/withdraw-method/token”**.  
+4\. For Merchant Key: \[ “/merchant-key/create”, “/merchant-key/cancel” \] 
+  
+> The generated token is single-use for each transaction and cannot be consumed more than once. In addition, the transactional token will be valid for 60 seconds.
 
 **Parámetros:**
 
@@ -215,7 +228,15 @@ Generates a transactional token for payment link service.
 
 ### `transactional_token_method`
 
-Generates a transactional token for payment method service.
+This service allows security validation for the execution of a transaction on the platform, generating a single-use token.
+
+> The transactional token service is obtained in three ways, depending on the action to be performed. For this, the value sent in the _**service**_ parameter must be set according to what is required:  
+1\. For Payment Link: **“/cash-in/generate/payment-link/token”**.  
+2\. For Payment method: **“/cash-in/generate/payment-method/token”**.  
+3\. For Withdraw: **“/cash-out/generate/withdraw-method/token”**.  
+4\. For Merchant Key: \[ “/merchant-key/create”, “/merchant-key/cancel” \] 
+  
+> The generated token is single-use for each transaction and cannot be consumed more than once. In addition, the transactional token will be valid for 60 seconds.
 
 **Parámetros:**
 
@@ -225,7 +246,15 @@ Generates a transactional token for payment method service.
 
 ### `transactional_token_withdraw`
 
-Generates a transactional token for withdraw service.
+This service allows security validation for the execution of a transaction on the platform, generating a single-use token.
+
+> The transactional token service is obtained in three ways, depending on the action to be performed. For this, the value sent in the _**service**_ parameter must be set according to what is required:  
+1\. For Payment Link: **“/cash-in/generate/payment-link/token”**.  
+2\. For Payment method: **“/cash-in/generate/payment-method/token”**.  
+3\. For Withdraw: **“/cash-out/generate/withdraw-method/token”**.  
+4\. For Merchant Key: \[ “/merchant-key/create”, “/merchant-key/cancel” \] 
+  
+> The generated token is single-use for each transaction and cannot be consumed more than once. In addition, the transactional token will be valid for 60 seconds.
 
 **Parámetros:**
 
@@ -235,7 +264,15 @@ Generates a transactional token for withdraw service.
 
 ### `transactional_token_merchan_key_create`
 
-Generates a transactional token for creating merchant keys.
+This service allows security validation for the execution of a transaction on the platform, generating a single-use token.
+
+> The transactional token service is obtained in three ways, depending on the action to be performed. For this, the value sent in the _**service**_ parameter must be set according to what is required:  
+1\. For Payment Link: **“/cash-in/generate/payment-link/token”**.  
+2\. For Payment method: **“/cash-in/generate/payment-method/token”**.  
+3\. For Withdraw: **“/cash-out/generate/withdraw-method/token”**.  
+4\. For Merchant Key: \[ “/merchant-key/create”, “/merchant-key/cancel” \] 
+  
+> The generated token is single-use for each transaction and cannot be consumed more than once. In addition, the transactional token will be valid for 60 seconds.
 
 **Parámetros:**
 
@@ -245,7 +282,15 @@ Generates a transactional token for creating merchant keys.
 
 ### `transactional_token_merchant_key_cancel`
 
-Generates a transactional token for canceling merchant keys.
+This service allows security validation for the execution of a transaction on the platform, generating a single-use token.
+
+> The transactional token service is obtained in three ways, depending on the action to be performed. For this, the value sent in the _**service**_ parameter must be set according to what is required:  
+1\. For Payment Link: **“/cash-in/generate/payment-link/token”**.  
+2\. For Payment method: **“/cash-in/generate/payment-method/token”**.  
+3\. For Withdraw: **“/cash-out/generate/withdraw-method/token”**.  
+4\. For Merchant Key: \[ “/merchant-key/create”, “/merchant-key/cancel” \] 
+  
+> The generated token is single-use for each transaction and cannot be consumed more than once. In addition, the transactional token will be valid for 60 seconds.
 
 **Parámetros:**
 
@@ -255,7 +300,9 @@ Generates a transactional token for canceling merchant keys.
 
 ### `cash_in_generate_payment_link_token`
 
-## 📥 Request Body Parameters
+With the following request you can obtain a payment resource with a link that will redirect your customer to the payment gateway where he will see a list of the different payment methods available.
+
+ ## 📥 Request Body Parameters
 
 | **Field** | **Type** | **Required** | **Description** |
 | --- | --- | --- | --- |
@@ -310,9 +357,11 @@ The table below lists the available payment methods along with their correspondi
 | `155` | Cash-in via **Transfiya Recaudo** | 43,200 |
 | `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 |
 
 > ⚠ **Important:**  
-The value provided in the `expiresIn` field **must be greater than or equal** to the minimum expiration defined for the selected payment method. 
+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.** 
   
 
 ---
@@ -569,27 +618,141 @@ This is **not** an error in our platform.
 
 ---
 
-## 📥 Request Body Parameters
+### **Llaves** Dinámicas **Bre-B**
+
+For this method, the following fields are **required**:
+
+- `cellphone`
+    
+- `docNumber`
+    
+- `docType`
+    
+- `merchantId`
+    
+
+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 **Llaves Dinamicas Bre-B** operates as an _open resource_, meaning the generated KEY can be used multiple times by the same user. 
+  
+> ⚙️ **Technical Note — Dynamic Key Behavior:**  
+Dynamic keys may receive multiple money transfers due to current limitations in the Redeban system.  
+This behavior does not represent an error or malfunction in our platform.  
+**Additionally, dynamic keys have a fixed validity period of 5 minutes, and this duration cannot be modified.** 
+  
+
+#### Behavior Details
+
+- Redeban does not automatically invalidate a dynamic KEY after its first send.
+    
+- As a result, the same KEY may generate multiple transaction records.
+    
+
+#### Recommendations
+
+- Implement **application-level validation** to detect multiple payments from the same KEY.
+    
+- Monitor dynamic KEY transactions and confirm status before marking payments as completed.
+    
+- Inform end-users to verify the success of a transaction before rescanning.
+    
+
+#### Future Considerations
+
+- Stay updated with interoperability provider announcements to adjust integrations accordingly.
+    
+
+``` json
+"paymentMethod": {
+  "id": 250,
+  "cellphone": "string",
+  "docType": "string",
+  "docNumber": "string",
+  "merchantId": "string"
+}
+
+ ```
+
+---
+
+### **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** |
 | --- | --- | --- | --- |
-| `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. |
+| `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>
+  </div><div>    src="YOUR-URL-LINK-ID"
+<br></div><div>    width="100%"
+<br></div><div>    height="600"
+<br></div><div>    frameborder="0"
+<br></div><div>    style="max-width: 500px; margin: 0 auto; display: block;"
+<br></div><div>  &gt;&lt;/iframe&gt;
+<br></div><div>&lt;/body&gt;
+<br></div><div>&lt;/html&gt;
+<br></div></code></pre><blockquote>⚠️ <strong >Important:</b>
+<br>You must use the <strong >complete URL</b> from the <code >url</code> field in the service response as the <code >src</code> attribute value in the iframe. The <code >src</code> attribute must contain the entire URL returned in the <code >data.url</code> field of the API response. For example, if the response contains:</blockquote>
+<br><pre class=json><code><div>"data": {
+<br></div><div>  "url": "https://checkout.akua.la/links/lnk-07595544-cfe6-4d40-8894-0ed7cf3c28b9?sandbox=true"
+<br></div><div>}
+<br></div></code></pre><p >Then the iframe <code >src</code> should be:</p><pre class=html><code><div>&lt;iframe src=&quot;https://checkout.akua.la/links/lnk-07595544-cfe6-4d40-8894-0ed7cf3c28b9?sandbox=true&quot; ...&gt;&lt;/iframe&gt;
+<br></div></code></pre><pre class=json><code><div>"paymentMethod": {
+<br></div><div>  "id": 273,
+<br></div><div>  "description": "Payment description",
+<br></div><div>  "external": true
+<br></div><div>}
+<br></div></code></pre><h4 >Response Example</h4><pre class=json><code><div>{
+<br></div><div>  "statusCode": "00",
+<br></div><div>  "message": "Operación exitosa.",
+<br></div><div>  "data": {
+<br></div><div>    "url": "https://checkout.akua.la/links/lnk-07595544-cfe6-4d40-8894-0ed7cf3c28b9?sandbox=true",
+<br></div><div>    "reference": "db205760-d228-11f0-8923-0d9b7d755dab",
+<br></div><div>    "resourceId": "2762357",
+<br></div><div>    "expiresIn": "2025-12-06T22:22:16.000Z",
+<br></div><div>    "urlStatusPay": "https://mf-core.refacil.co/refacilpay/resumen/79/db205760-d228-11f0-8923-0d9b7d755dab",
+<br></div><div>    "resourceUrlId": "1762027",
+<br></div><div>    "status": 1
+<br></div><div>  }
+<br></div><div>}
+<br></div></code></pre><h4 >Response Fields</h4><div ><table><tbody><tr ><th ><strong >Field</b></th><th ><strong >Description</b></th></tr><tr ><td ><div ><code >url</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >Payment link URL. Can be used for direct redirection or to embed in an iframe depending on the <code >external</code> value</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >reference</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >Unique transaction reference</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >resourceId</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >Generated payment resource ID</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >expiresIn</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >Payment link expiration date and time</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >urlStatusPay</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >URL to check the payment status</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >resourceUrlId</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >URL resource ID</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >status</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >Resource status (1 = Active)</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr></tbody></table></div><div ><hr contenteditable="false" /></div><h2 >📥 Request Body Parameters</h2><div ><table><tbody><tr ><th ><strong >Field</b></th><th ><strong >Type</b></th><th ><strong >Required</b></th><th ><strong >Description</b></th></tr><tr ><td ><div ><code >amount</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >number</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >✅</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >Value of the payment.</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >brandId</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >number</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >❌</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >ID of the customer&#x27;s white label; if one is not available, the default ID 79 is sent.</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >expiresIn</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >number</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >❌</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >Time in seconds for the expiration of the resource or payment link.</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >paymentMethod</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >object</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >✅</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >Object specifying the payment method and its details.</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >paymentMethod.id</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >number</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >✅</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >ID of the selected payment method (see available payment methods).</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >reference1</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >string</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >✅</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >Customer identifier, must be between 1 and 30 characters.</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >reference2</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >object</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >❌</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >Object for additional information.</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >reference2.Commerce</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >object</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >❌</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >Object for information related to the store or commerce.</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >reference2.Data</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >object</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >❌</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >Object for information related to the conciliation of the transaction.</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >reference2.Label</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >object</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >❌</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >Object to send information to be displayed in the payment summary.</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >returnUrl</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >string</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >❌</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >Link that the customer will see when clicking on the back to commerce button.</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >showSummary</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >boolean</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >❌</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >Indicates whether the RefácilPay payment summary will be shown or not (false: do not show, true: show). Default: true.</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >userMetadata</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >object</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >✅</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >Object containing key details about the user or merchant generating the payment resource.</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >userMetadata.identifier</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >string</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >✅</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >Unique identifier of the user or merchant generating the payment resource (max 36 characters).</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >userMetadata.ip</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >string</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >✅</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >IP address associated with the user&#x27;s identifier. Must be a valid IP address.</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >userMetadata.urlCommerce</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >string</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >✅</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >URL that identifies the commerce. Must follow valid URL structure with http:// or https:// protocol. Maximum length: 500 characters.</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr><tr ><td ><div ><code >webhookUrl</code></div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >string</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >✅</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td><td ><div >URL of the client&#x27;s webhook to receive real-time payment status updates.</div><div  contenteditable="false"><div ><div><div ></div></div></div><div ></div></div></td></tr></tbody></table></div><p ></p></x-turndown>
+ ```
 
 **Parámetros:**
 
@@ -609,7 +772,23 @@ This is **not** an error in our platform.
 
 ### `cash_out_generate_withdraw_method_token`
 
-This endpoint allows you to **generate withdrawal (cash-out) requests** through the available payout methods.
+This service allows you to generate withdrawal requests through the enabled dispersion means.
+
+> 🔐 Authentication 
+  
+
+All requests must include the following headers:
+
+| **Header** | **Description** | **Example** |
+| --- | --- | --- |
+| Authorization | Bearer token generated by the authentication service. | Bearer eyJhbGciOiJIUzI1NiIs... |
+| x-transaction-token | Transactional token specific to the service. | 9b48edde-652d-11ed-984e-02c840fe**** |
+| Content-Type | Content type of the request body. | application/json |
+
+> Important fields within the requests:  
+Webhook: This is the url of the client's webhook to where our service sends the transaction status and transaction detail information.
+
+ This endpoint allows you to **generate withdrawal (cash-out) requests** through the available payout methods.
 
 ---
 
@@ -701,7 +880,23 @@ The `key` field must contain a valid Bre-B account alias in the format `@USERNAM
 
 ### `customer_getbalance`
 
-This service allows you to consult the balance exchange and the dispersion exchange associated with the client's identifier.
+This service allows you to generate withdrawal requests through the enabled dispersion means.
+
+> 🔐 Authentication 
+  
+
+All requests must include the following headers:
+
+| **Header** | **Description** | **Example** |
+| --- | --- | --- |
+| Authorization | Bearer token generated by the authentication service. | Bearer eyJhbGciOiJIUzI1NiIs... |
+| x-transaction-token | Transactional token specific to the service. | 9b48edde-652d-11ed-984e-02c840fe**** |
+| Content-Type | Content type of the request body. | application/json |
+
+> Important fields within the requests:  
+Webhook: This is the url of the client's webhook to where our service sends the transaction status and transaction detail information.
+
+ 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. 
   
@@ -719,11 +914,27 @@ Body
 
 | Name | Type | Description |
 | --- | --- | --- |
-| userId | null | Campo del body: userId |
+| userId | number | Campo del body: userId |
 
 ### `payment_transfiya_banks`
 
-This service allows you to consult the balance exchange and the dispersion exchange associated with the client's identifier.
+This service allows you to generate withdrawal requests through the enabled dispersion means.
+
+> 🔐 Authentication 
+  
+
+All requests must include the following headers:
+
+| **Header** | **Description** | **Example** |
+| --- | --- | --- |
+| Authorization | Bearer token generated by the authentication service. | Bearer eyJhbGciOiJIUzI1NiIs... |
+| x-transaction-token | Transactional token specific to the service. | 9b48edde-652d-11ed-984e-02c840fe**** |
+| Content-Type | Content type of the request body. | application/json |
+
+> Important fields within the requests:  
+Webhook: This is the url of the client's webhook to where our service sends the transaction status and transaction detail information.
+
+ 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. 
   
@@ -745,7 +956,9 @@ Body
 
 ### `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.
+These services will allow us to validate the status of a transaction and consult the characteristics of a payment method.
+
+ 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
 
@@ -778,7 +991,9 @@ Body
 
 ### `payment_customer_reference_status`
 
-## 🔍 Check Transaction by Customer Reference
+These services will allow us to validate the status of a transaction and consult the characteristics of a payment method.
+
+ ## 🔍 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:
 
@@ -829,7 +1044,9 @@ This endpoint **requires** a valid Bearer Token in the request headers. Requests
 
 ### `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
+These services will allow us to validate the status of a transaction and consult the characteristics of a payment method.
+
+ 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
 
@@ -848,7 +1065,109 @@ Body
 
 ### `webhook_notify`
 
-Body
+This component must be built by the merchant to receive the transaction notification data.
+
+You must take into account the following steps:
+
+**1.**You must create a Webhook without authentication.
+
+**2\. The** Url created will be the one you send in all requests when generating the payment resource in the “_WebhookUrl_” field. It is important to keep in mind that if for some reason you change the webhook you must modify the urls that you send in each generated resource.
+
+<img src="https://content.pstmn.io/10fdac74-e60a-41f2-b9ff-8b5777a7afc0/aW1hZ2UucG5n" width="322" height="117">
+
+A signature must be generated to validate the integrity of the messages sent to the webhook and the fields must be concatenated in the following way:
+
+_**HASH_KEY**_ _\=This data must be requested to the support area_.
+
+_**let signature**_ _\= referenceId-resourceId-amount-updatedAt-HASH_KEY; signature = crypto.createHmac(“sha1”, HASH_KEY).update(signature).digest(“hex”);_
+
+Example of a response that will reach your Webhook
+
+**Response**
+
+``` json
+{
+  "realAmount": 20000,
+  "amount": 19405,
+  "cost": "$595.00",
+  "referenceId": "38**",
+  "moduleId": 9,
+  "productId": 117,
+  "referenceKey": "3538d790-ae14-11ed-be2d-4d9b1bc987e6",
+  "paymentMethod": "PSE",
+  "userId": 189067,
+  "resourceId": "10024**",
+  "updatedAt": "2023-02-16 11:11:55",
+  "providerId": 8,
+  "providerReference": "3122330",
+  "reference1": "435sdfsd**",
+  "reference2": {
+    "Label": {
+      "Information": "Por seguridad algunos datos se encuentran cifrados",
+      "Name": "L**A",
+      "Email": "l**am@**",
+      "CellPhone": "3**4",
+      "DocumentType": "C",
+      "DocumentNumber": "52019859",
+      "Description": "Abono",
+      "Commerce": "Skandia",
+      "Reference1": null,
+      "Reference2": null,
+      "Reference3": null
+    },
+    "Data": {
+      "ConciliationCode": "FCO",
+      "ConciliationContract": "1277840",
+      "DocType": "N",
+      "DocNumber": "800194363"
+    },
+    "returnUrl": "https://www.google.com/"
+  },
+  "bankId": "1022",
+  "bankName": "BANCO UNION COLOMBIANO",
+  "status": 2,
+  "transfiyaStatus": "PENDING",
+  "sign": "aa2f472ad7e84524a02d1716b56fc16ec2a87***",
+  "error": {
+        "code": "20-07A",
+        "message": "Error técnico en Lambda"
+      }
+}
+
+ ```
+
+- Within the webhook an **"error** ” object is sent that shows the error _**code**_ and _**message**_ associated with rejections received from the supplier/bank or cancellation of the transaction when the generation of the resource is not completed.
+    
+- The error codes are printed when the transaction is _**Rejected**_ by the bank or when it is _**Cancelled**_ because the resource generation could not be completed.
+    
+
+**Notification for Withdraw**
+
+For withdraws, a notification will be sent to the webhook provided in the application. This notification will follow the structure mentioned above and will additionally include the withdrawal data. An example is provided below:
+
+``` json
+{
+    ..."webhook",
+    "withdraw": {
+        "id": "1403**",
+        "transactionId": "5690**",
+        "userId": 189067,
+        "providerReference": "3122330",
+        "accountNumber": "3051000002",
+        "accountId": null,
+        "createdAt": "2023-02-16 11:10:55",
+        "updatedAt": "2023-02-16 11:12:55",
+        "deletedAt": null,
+        "infoReference": "435sdfsd**",
+        "observation": null
+    },
+}
+
+ ```
+
+> _**The implementation of the webhook by the API user is mandatory. The reception and storage of the information for the reconciliation process by the API user with RefácilPay must be ensured.**__**This item will be evaluated during the certification process and will be mandatory for the transition to Production.**_
+
+ Body
 
 
 
@@ -875,15 +1194,153 @@ Body
 
 ### `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.
+This service allows merchants to enroll 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.
+
+---
+
+### **Enrollment Process**
+
+1. **Merchant Enrollment**
+    
+    - Initiates the enrollment process. The enrollment can take up to **7 minutes** to complete.
+        
+2. **Retrieve Enrollment Data**
+    
+    - Retrieves the merchant’s enrollment information once the process is completed.
+        
+
+---
+
+### **Merchant Enrollment Statuses**
+
+- **`approved`**
+    
+    The merchant has been approved and is authorized to generate QR codes.
+    
+- **`enrolled_other`**
+    
+    The merchant is already enrolled with another entity. To proceed:
+    
+    - Contact the commercial representative and request unenrollment from the current entity.
+        
+    - Submit a letter signed by the legal representative.
+        
+    - Be aware that this process may take up to **5 business days**.
+        
+        The commercial representative will provide guidance throughout the process.
+        
+- **`rejected`**
+    
+    The merchant has been rejected. Please contact your commercial representative for further details.
+    
+- **`pending`**
+    
+    The enrollment is in progress. The query may take a few minutes. If a final status is not received shortly, contact **RefacilPay support** to verify the situation.
+    
+- **`not_started`**
+    
+    No enrollment process has been initiated for the requested merchant.
+    
+
+---
+
+### **Important Note on the "cellphone" Field in the Enrollment Process**
+
+During the merchant creation flow for the QR Interoperable product, the API retrieves the merchant's registered information from the system. However, for the **"cellphone number"** field, the **Refacil** system automatically replaces the merchant’s actual phone number with a **generic alias number**.
+
+This behavior follows technical and operational requirements from the provider, as the real phone number may already exist in the provider’s databases, potentially causing integration conflicts.
+
+To avoid these issues, a randomly generated alias is used as a placeholder. This alias is **exclusive to this product** and does **not affect** the merchant’s operation in other services.
+
+ 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.
+This service allows merchants to enroll 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.
+
+---
+
+### **Enrollment Process**
+
+1. **Merchant Enrollment**
+    
+    - Initiates the enrollment process. The enrollment can take up to **7 minutes** to complete.
+        
+2. **Retrieve Enrollment Data**
+    
+    - Retrieves the merchant’s enrollment information once the process is completed.
+        
+
+---
+
+### **Merchant Enrollment Statuses**
+
+- **`approved`**
+    
+    The merchant has been approved and is authorized to generate QR codes.
+    
+- **`enrolled_other`**
+    
+    The merchant is already enrolled with another entity. To proceed:
+    
+    - Contact the commercial representative and request unenrollment from the current entity.
+        
+    - Submit a letter signed by the legal representative.
+        
+    - Be aware that this process may take up to **5 business days**.
+        
+        The commercial representative will provide guidance throughout the process.
+        
+- **`rejected`**
+    
+    The merchant has been rejected. Please contact your commercial representative for further details.
+    
+- **`pending`**
+    
+    The enrollment is in progress. The query may take a few minutes. If a final status is not received shortly, contact **RefacilPay support** to verify the situation.
+    
+- **`not_started`**
+    
+    No enrollment process has been initiated for the requested merchant.
+    
+
+---
+
+### **Important Note on the "cellphone" Field in the Enrollment Process**
+
+During the merchant creation flow for the QR Interoperable product, the API retrieves the merchant's registered information from the system. However, for the **"cellphone number"** field, the **Refacil** system automatically replaces the merchant’s actual phone number with a **generic alias number**.
+
+This behavior follows technical and operational requirements from the provider, as the real phone number may already exist in the provider’s databases, potentially causing integration conflicts.
+
+To avoid these issues, a randomly generated alias is used as a placeholder. This alias is **exclusive to this product** and does **not affect** the merchant’s operation in other services.
+
+ 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`.
+These services allow merchants to create and manage their Bre-b keys.
+
+To use these services, an authentication token is required, which must be sent as an authorization header.
+
+---
+
+⚠ **Important**: Before using this payment method, the merchant enrollment process must be completed. Detailed instructions can be found in the **Merchant Enrollment** section.
+
+**🔄 Open resource:** The creation of a key functions as an open resource, which means that once the Bre-b key has been generated, the user can receive multiple transactions through it.
+
+---
+
+### Recommendations
+
+- API users are strongly encouraged to **implement additional application-level validations** to detect, identify, and manage multiple payment records originating from a Bre-b key.
+    
+- **Actively monitor transactions** originating from generated keys and validate the status of operations before confirming payment to the end user.
+
+ This endpoint will allow you to create 4 types of keys: `alias`, `email`, `cellphone`, and `document`.
 
 ⚠ **Important**:
 
@@ -922,7 +1379,25 @@ Body
 
 ### `merchant_key_cancel`
 
-This endpoint allows you to cancel an existing key, which will then become inactive and unable to receive transactions.
+These services allow merchants to create and manage their Bre-b keys.
+
+To use these services, an authentication token is required, which must be sent as an authorization header.
+
+---
+
+⚠ **Important**: Before using this payment method, the merchant enrollment process must be completed. Detailed instructions can be found in the **Merchant Enrollment** section.
+
+**🔄 Open resource:** The creation of a key functions as an open resource, which means that once the Bre-b key has been generated, the user can receive multiple transactions through it.
+
+---
+
+### Recommendations
+
+- API users are strongly encouraged to **implement additional application-level validations** to detect, identify, and manage multiple payment records originating from a Bre-b key.
+    
+- **Actively monitor transactions** originating from generated keys and validate the status of operations before confirming payment to the end user.
+
+ This endpoint allows you to cancel an existing key, which will then become inactive and unable to receive transactions.
 
 Headers
 
@@ -944,7 +1419,25 @@ Body
 
 ### `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.
+These services allow merchants to create and manage their Bre-b keys.
+
+To use these services, an authentication token is required, which must be sent as an authorization header.
+
+---
+
+⚠ **Important**: Before using this payment method, the merchant enrollment process must be completed. Detailed instructions can be found in the **Merchant Enrollment** section.
+
+**🔄 Open resource:** The creation of a key functions as an open resource, which means that once the Bre-b key has been generated, the user can receive multiple transactions through it.
+
+---
+
+### Recommendations
+
+- API users are strongly encouraged to **implement additional application-level validations** to detect, identify, and manage multiple payment records originating from a Bre-b key.
+    
+- **Actively monitor transactions** originating from generated keys and validate the status of operations before confirming payment to the end user.
+
+ 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
 
@@ -964,7 +1457,25 @@ Body
 
 ### `merchant_key_get_keys`
 
-This endpoint allows you to obtain all keys created and in active status that belong to the merchant.
+These services allow merchants to create and manage their Bre-b keys.
+
+To use these services, an authentication token is required, which must be sent as an authorization header.
+
+---
+
+⚠ **Important**: Before using this payment method, the merchant enrollment process must be completed. Detailed instructions can be found in the **Merchant Enrollment** section.
+
+**🔄 Open resource:** The creation of a key functions as an open resource, which means that once the Bre-b key has been generated, the user can receive multiple transactions through it.
+
+---
+
+### Recommendations
+
+- API users are strongly encouraged to **implement additional application-level validations** to detect, identify, and manage multiple payment records originating from a Bre-b key.
+    
+- **Actively monitor transactions** originating from generated keys and validate the status of operations before confirming payment to the end user.
+
+ This endpoint allows you to obtain all keys created and in active status that belong to the merchant.
 
 
 ## 📝 Logs