refacil-pay-mcp 1.1.17 → 1.1.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +1538 -1612
  2. package/dist/core/resources.js +24 -24
  3. package/dist/core/resources.js.map +1 -1
  4. package/dist/core/tools.js +68 -93
  5. package/dist/core/tools.js.map +1 -1
  6. package/dist/index.js +2 -2
  7. package/package.json +63 -63
package/README.md CHANGED
@@ -1,1613 +1,1539 @@
1
- # refacil-pay MCP Server
2
-
3
- Servidor MCP (Model Context Protocol) generado automáticamente para la API refacil-pay.
4
-
5
- ## 🚀 Características
6
-
7
- - **18 herramientas** generadas automáticamente desde la colección Postman
8
- - **Autenticación flexible**: Username/Password con renovación automática de tokens
9
- - **Servidor HTTP** con Fastify
10
- - **Protocolo MCP** estándar para integración con IDEs
11
-
12
- ## 📋 Requisitos
13
-
14
- - Node.js 20+
15
- - npm o yarn
16
-
17
- ## 📦 Instalación desde NPM
18
-
19
- Si este paquete está publicado en npm, puedes instalarlo globalmente:
20
-
21
- ```bash
22
- # Instalación global (recomendado)
23
- npm install -g refacil-pay-mcp
24
-
25
- # Verificar instalación
26
- refacil-pay-mcp --version
27
- ```
28
-
29
- ### Configuración Rápida en IDEs
30
-
31
- #### Cursor
32
-
33
- 1. Abrir **Settings** → **Features** → **Model Context Protocol**
34
- 2. Click en **"Edit Config"**
35
- 3. Agregar:
36
-
37
- **Windows**: `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
38
-
39
- **macOS/Linux**: `~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
40
-
41
- ```json
42
- {
43
- "mcpServers": {
44
- "refacil-pay": {
45
- "command": "refacil-pay-mcp",
46
- "env": {
47
- "BASE_URL": "https://pay-api.qa.refacil.co",
48
- "USERNAME": "tu-usuario",
49
- "PASSWORD": "tu-contraseña",
50
- "AUTH_ENDPOINT": "/auth/login",
51
- "TOKEN_CACHE_TTL": "3600"
52
- }
53
- }
54
- }
55
- }
56
- ```
57
-
58
- 4. Reiniciar Cursor
59
-
60
- #### Claude Desktop
61
-
62
- Editar archivo de configuración:
63
-
64
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
65
-
66
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
67
-
68
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
69
-
70
- ```json
71
- {
72
- "mcpServers": {
73
- "refacil-pay": {
74
- "command": "refacil-pay-mcp",
75
- "env": {
76
- "BASE_URL": "https://pay-api.qa.refacil.co",
77
- "USERNAME": "tu-usuario",
78
- "PASSWORD": "tu-contraseña",
79
- "AUTH_ENDPOINT": "/auth/login",
80
- "TOKEN_CACHE_TTL": "3600"
81
- }
82
- }
83
- }
84
- }
85
- ```
86
-
87
- Reiniciar Claude Desktop.
88
-
89
- #### Visual Studio Code
90
-
91
- 1. Instalar extensión **MCP for VS Code**
92
- 2. Editar `settings.json`:
93
-
94
- ```json
95
- {
96
- "mcp.servers": {
97
- "refacil-pay": {
98
- "command": "refacil-pay-mcp",
99
- "env": {
100
- "BASE_URL": "https://pay-api.qa.refacil.co",
101
- "USERNAME": "tu-usuario",
102
- "PASSWORD": "tu-contraseña",
103
- "AUTH_ENDPOINT": "/auth/login",
104
- "TOKEN_CACHE_TTL": "3600"
105
- }
106
- }
107
- }
108
- }
109
- ```
110
-
111
- 3. Recargar VS Code
112
-
113
- ## 🛠️ Instalación para Desarrollo
114
-
115
- Si quieres contribuir o ejecutar desde el código fuente:
116
-
117
- ```bash
118
- # Clonar el repositorio
119
- git clone https://github.com/refacil/refacil-pay-mcp.git
120
- cd refacil-pay-mcp
121
-
122
- # Instalar dependencias
123
- npm install
124
-
125
- # Construir el proyecto
126
- npm run build
127
-
128
- # Iniciar en desarrollo
129
- npm run dev
130
-
131
- # Iniciar en producción
132
- npm start
133
- ```
134
-
135
- ## 🔧 Configuración
136
-
137
- El servidor se configura mediante variables de entorno:
138
-
139
- ```bash
140
- # Copiar archivo de ejemplo
141
- cp .env.example .env
142
-
143
- # Editar configuración
144
- nano .env
145
- ```
146
-
147
- ### Variables de Entorno
148
-
149
- | Variable | Descripción | Valor por defecto |
150
- |----------|-------------|-------------------|
151
- | `PORT` | Puerto del servidor | `3009` |
152
- | `ENVIRONMENT` | Entorno de ejecución | `development` |
153
- | `BASE_URL` | URL base de la API | `https://pay-api.qa.refacil.co` |
154
- | `USERNAME` | Usuario para autenticación | `your_username_here` |
155
- | `PASSWORD` | Contraseña para autenticación | `your_password_here` |
156
- | `AUTH_ENDPOINT` | Endpoint de autenticación | `/auth/login` |
157
- | `TOKEN_CACHE_TTL` | TTL del caché de tokens (segundos) | `3600` |
158
- | `MCP_TOKEN` | Token de autenticación del MCP | `mcp-secret-token-refacil-pay` |
159
-
160
-
161
- ## 🐳 Docker
162
-
163
- ```bash
164
- # Construir imagen
165
- docker build -t refacil-pay-mcp .
166
-
167
- # Ejecutar contenedor
168
- docker run -p 3009:3009 refacil-pay-mcp
169
-
170
- # O usar docker-compose
171
- docker-compose up
172
- ```
173
-
174
- ## ☸️ Kubernetes
175
-
176
- ```bash
177
- # Aplicar manifests
178
- kubectl apply -f k8s/
179
-
180
- # Verificar despliegue
181
- kubectl get pods -l app=refacil-pay-mcp
182
- ```
183
-
184
- ## 🔌 Uso del MCP
185
-
186
- ### Endpoints Disponibles
187
-
188
- - **`/mcp`**: Endpoint principal del protocolo MCP
189
- - **`/health`**: Health check del servidor
190
- - **`/tools`**: Lista de herramientas disponibles
191
-
192
-
193
- ## 🛠️ Herramientas Disponibles
194
-
195
- ### `auth_login`
196
-
197
- 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)).
198
-
199
- Within the post you will see below are the fields to make your request
200
-
201
- > 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.
202
- The authentication token has an expiration time of 2 hours. Only consume this service after this time has elapsed or when the services that use the token return a 401 Unauthorized response.
203
-
204
- **Parámetros:**
205
-
206
- | Name | Type | Description |
207
- | --- | --- | --- |
208
- | username | string | Campo del body: username |
209
- | password | string | Campo del body: password |
210
-
211
- ### `trx_token_generate`
212
-
213
- This service allows security validation for the execution of a transaction on the platform, generating a single-use token.
214
-
215
- > 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:
216
- 1\. For Payment Link: **“/cash-in/generate/payment-link/token”**.
217
- 2\. For Payment method: **“/cash-in/generate/payment-method/token”**.
218
- 3\. For Withdraw: **“/cash-out/generate/withdraw-method/token”**.
219
- 4\. For Merchant Key: \[ “/merchant-key/create”, “/merchant-key/cancel” \]
220
-
221
- > 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.
222
-
223
- **Parámetros:**
224
-
225
- | Name | Type | Description |
226
- | --- | --- | --- |
227
- | service | string | Campo del body: service |
228
-
229
- ### `transactional_token_method`
230
-
231
- This service allows security validation for the execution of a transaction on the platform, generating a single-use token.
232
-
233
- > 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:
234
- 1\. For Payment Link: **“/cash-in/generate/payment-link/token”**.
235
- 2\. For Payment method: **“/cash-in/generate/payment-method/token”**.
236
- 3\. For Withdraw: **“/cash-out/generate/withdraw-method/token”**.
237
- 4\. For Merchant Key: \[ “/merchant-key/create”, “/merchant-key/cancel” \]
238
-
239
- > 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.
240
-
241
- **Parámetros:**
242
-
243
- | Name | Type | Description |
244
- | --- | --- | --- |
245
- | service | string | Campo del body: service |
246
-
247
- ### `transactional_token_withdraw`
248
-
249
- This service allows security validation for the execution of a transaction on the platform, generating a single-use token.
250
-
251
- > 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:
252
- 1\. For Payment Link: **“/cash-in/generate/payment-link/token”**.
253
- 2\. For Payment method: **“/cash-in/generate/payment-method/token”**.
254
- 3\. For Withdraw: **“/cash-out/generate/withdraw-method/token”**.
255
- 4\. For Merchant Key: \[ “/merchant-key/create”, “/merchant-key/cancel” \]
256
-
257
- > 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.
258
-
259
- **Parámetros:**
260
-
261
- | Name | Type | Description |
262
- | --- | --- | --- |
263
- | service | string | Campo del body: service |
264
-
265
- ### `transactional_token_merchan_key_create`
266
-
267
- This service allows security validation for the execution of a transaction on the platform, generating a single-use token.
268
-
269
- > 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:
270
- 1\. For Payment Link: **“/cash-in/generate/payment-link/token”**.
271
- 2\. For Payment method: **“/cash-in/generate/payment-method/token”**.
272
- 3\. For Withdraw: **“/cash-out/generate/withdraw-method/token”**.
273
- 4\. For Merchant Key: \[ “/merchant-key/create”, “/merchant-key/cancel” \]
274
-
275
- > 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.
276
-
277
- **Parámetros:**
278
-
279
- | Name | Type | Description |
280
- | --- | --- | --- |
281
- | service | string | Campo del body: service |
282
-
283
- ### `transactional_token_merchant_key_cancel`
284
-
285
- This service allows security validation for the execution of a transaction on the platform, generating a single-use token.
286
-
287
- > 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:
288
- 1\. For Payment Link: **“/cash-in/generate/payment-link/token”**.
289
- 2\. For Payment method: **“/cash-in/generate/payment-method/token”**.
290
- 3\. For Withdraw: **“/cash-out/generate/withdraw-method/token”**.
291
- 4\. For Merchant Key: \[ “/merchant-key/create”, “/merchant-key/cancel” \]
292
-
293
- > 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.
294
-
295
- **Parámetros:**
296
-
297
- | Name | Type | Description |
298
- | --- | --- | --- |
299
- | service | string | Campo del body: service |
300
-
301
- ### `cash_in_generate_payment_link_token`
302
-
303
- 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.
304
-
305
- ## 📥 Request Body Parameters
306
-
307
- | **Field** | **Type** | **Required** | **Description** |
308
- | --- | --- | --- | --- |
309
- | `amount` | number | ✅ | Value of the payment. |
310
- | `brandId` | number | ❌ | ID of the customer's white label; if one is not available, the default ID 79 is sent. |
311
- | `expiresIn` | number | ❌ | Time in minutes for the expiration of the resource or payment link. |
312
- | `reference1` | string | ✅ | Customer identifier, must be between 1 and 30 characters. |
313
- | `reference2` | object | ❌ | Object for additional information. |
314
- | `reference2.Commerce` | object | ❌ | Object for information related to the store or commerce. |
315
- | `reference2.Data` | object | ❌ | Object for information related to the conciliation of the transaction. |
316
- | `reference2.Label` | object | ❌ | Object to send information to be displayed in the payment summary. |
317
- | `returnUrl` | string | ❌ | Link that the customer will see when clicking on the back to commerce button. |
318
- | `showSummary` | boolean | ❌ | Indicates whether the RefácilPay payment summary will be shown or not (false: do not show, true: show). Default: true. |
319
- | `userMetadata` | object | ✅ | Object containing key details about the user or merchant generating the payment resource. |
320
- | `userMetadata.identifier` | string | ✅ | Unique identifier of the user or merchant generating the payment resource (max 36 characters). |
321
- | `userMetadata.ip` | string | ✅ | IP address associated with the user's identifier. Must be a valid IP address. |
322
- | `userMetadata.urlCommerce` | string | ✅ | URL that identifies the commerce. Must follow valid URL structure with http:// or https:// protocol. Maximum length: 500 characters. |
323
- | `webhookUrl` | string | ✅ | URL of the client's webhook to receive real-time payment status updates. |
324
-
325
- **Parámetros:**
326
-
327
- | Name | Type | Description |
328
- | --- | --- | --- |
329
- | transactionToken | string | Header personalizado: x-transaction-token |
330
- | expiresIn | number | Campo del body: expiresIn |
331
- | amount | number | Campo del body: amount |
332
- | brandId | number | Campo del body: brandId |
333
- | webhookUrl | string | Campo del body: webhookUrl |
334
- | userMetadata | object | Campo del body: userMetadata |
335
- | returnUrl | string | Campo del body: returnUrl |
336
- | reference1 | string | Campo del body: reference1 |
337
- | reference2 | object | Campo del body: reference2 |
338
-
339
- ### `cash_in_generate_payment_method_token`
340
-
341
- This endpoint allows you to **generate payment requests** through the available _cash-in_ methods.
342
-
343
- ---
344
-
345
- ### 💡 Overview
346
-
347
- The table below lists the available payment methods along with their corresponding IDs and **minimum expiration times** (`expiresIn`) required when creating a payment request.
348
-
349
- | **Method ID** | **Description** | **Minimum Expiration (seconds)** |
350
- | --- | --- | --- |
351
- | `130` | Cash-in via **Nequi** | 43,200 |
352
- | `131` | Cash-in via **Daviplata** | 43,200 |
353
- | `133` | Cash-in via **PSE** | 1,800 |
354
- | `262` | Cash-in via **PSE Gateway** | 1,800 |
355
- | `153` | Cash-in via **Recaudo Efectivo** | 86,400 |
356
- | `163` | Cash-in via **TPaga** | 43,200 |
357
- | `248` | Cash-in via **QR Interoperable** | N/A |
358
- | `250` | Cash-in via **Llaves Bre-B** | 300 |
359
- | `273` | Cash-in via **Tarjetas** (Débito y Crédito) | 3,600 |
360
- | `277` | Cash-in via **Whatsapp** | 2,592,000 |
361
-
362
- > ⚠ **Important:**
363
- 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.**
364
-
365
-
366
- ---
367
-
368
- ## 🧩 Payment Method Details
369
-
370
- Each payment method requires a specific object structure within the `"paymentMethod"` field.
371
-
372
- ---
373
-
374
- ### **Nequi**
375
-
376
- ``` json
377
- "paymentMethod": {
378
- "id": 130,
379
- "cellphone": "3105293225"
380
- }
381
-
382
- ```
383
-
384
- ---
385
-
386
- ### **Daviplata**
387
-
388
- ``` json
389
- "paymentMethod": {
390
- "id": 131,
391
- "cellphone": "3208385715"
392
- }
393
-
394
- ```
395
-
396
- ---
397
-
398
- ### **PSE**
399
-
400
- For this payment method, depending on the `typePerson` selected, only specific document types are accepted:
401
-
402
- - **`typePerson`****:** **`"0"`** → corresponds to a **Natural Person** and only accepts the following values for `documentType`:
403
-
404
- - `RCN`
405
-
406
- - `TI`
407
-
408
- - `CC`
409
-
410
- - `TE`
411
-
412
- - `CE`
413
-
414
- - `PA`
415
-
416
- - `DIE`
417
-
418
- - **`typePerson`****:** **`"1"`** → corresponds to a **Legal Person** and only accepts the following value for `documentType`:
419
-
420
- - `NIT`
421
-
422
-
423
- ``` json
424
- "paymentMethod": {
425
- "id": 133,
426
- "documentType": "CC",
427
- "typePerson": "0",
428
- "bankId": "string",
429
- "documentNumber": "string",
430
- "name": "string",
431
- "cellphone": "string",
432
- "address": "string",
433
- "email": "string"
434
- }
435
-
436
- ```
437
-
438
- ---
439
-
440
- ### **PSE Gateway**
441
-
442
- This payment method enables direct integration with the PSE network for processing online bank payments.
443
- To consume this product, it is required to have the following parameters previously configured and associated with your product:
444
-
445
- - `entity_code`
446
-
447
- - `service_code`
448
-
449
- - `company_ciiu`
450
-
451
- - `company_name`
452
-
453
-
454
- These parameters identify your company within the PSE network and are necessary for successful transaction routing and validation.
455
-
456
- > 💬 **For more information or to request these credentials, please contact the support team.**
457
-
458
-
459
- This method follows **the same structure and validation rules** as **PSE**, but must use the following identifier:
460
-
461
- ``` json
462
- "paymentMethod": {
463
- "id": 262,
464
- "documentType": "CC",
465
- "typePerson": "0",
466
- "bankId": "string",
467
- "documentNumber": "string",
468
- "name": "string",
469
- "cellphone": "string",
470
- "address": "string",
471
- "email": "string"
472
- }
473
-
474
- ```
475
-
476
- The **PSE integration** relies heavily on the correct configuration of the `showSummary` and `returnUrl` parameters.
477
- These parameters control the **user experience** and the **finalization flow** of the payment process.
478
-
479
- | Scenario | `showSummary` | `returnUrl` | Flow Description |
480
- | --- | --- | --- | --- |
481
- | **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`. |
482
- | **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. |
483
-
484
- > ⚠️ **Note:**
485
- 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.
486
-
487
- > 🔗 **See also:**
488
-
489
-
490
- - [Transaction Summary](https://documenter.getpostman.com/view/35146358/2sA3QpDEFA#45e0d76a-fabd-442e-9b17-e2f6b8354ec5)
491
-
492
- - [Transaction Status](https://documenter.getpostman.com/view/35146358/2sA3QpDEFA#dd3ba9f5-1f10-4109-b59d-6e5aad5e3799)
493
-
494
-
495
- ---
496
-
497
- ### **Recaudo Efectivo**
498
-
499
- ``` json
500
- "paymentMethod": {
501
- "id": 153
502
- }
503
-
504
- ```
505
-
506
- ---
507
-
508
- ### **TPaga**
509
-
510
- This payment method supports an optional parameter called `isQr`, which determines the type of resource returned in the `url` field:
511
-
512
- | **Value** | **Description** |
513
- | --- | --- |
514
- | `true` | The `url` field returns a link to a **QR code** displaying transaction details. |
515
- | `false` | The `url` field returns a **deeplink** to open directly in the TPAGA wallet app. |
516
-
517
- > 🧠 **Behavior:**
518
- If `isQr` is not provided, the default behavior is equivalent to `isQr: false`.
519
- Transactions can only be completed **from a mobile device**.
520
- 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.
521
-
522
-
523
- ``` json
524
- "paymentMethod": {
525
- "id": 163,
526
- "isQr": false
527
- }
528
-
529
- ```
530
-
531
- ---
532
-
533
- ### **QR Interoperable**
534
-
535
- For this method, the following fields are **optional**:
536
-
537
- - `cellphone`
538
-
539
- - `documentNumber`
540
-
541
- - `documentType`
542
-
543
- - `merchantId`
544
-
545
-
546
- The service can function using only the payment method ID; however, providing these optional fields can **improve response time**.
547
- 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.
548
-
549
- > ⚠ **Prerequisite:**
550
- The merchant must complete the **Merchant Enrollment** process before using this method.
551
- See the _Merchant Enrollment_ section for setup details.
552
-
553
- > 🔁 **Open Resource:**
554
- The **QR Interoperable** operates as an _open resource_, meaning the generated QR can be used multiple times by the same user.
555
-
556
- > ⚙️ **Technical Note — Dynamic QR Behavior:**
557
- Dynamic QR codes may be scanned multiple times due to current limitations in the Redeban system.
558
- This is **not** an error in our platform.
559
-
560
-
561
- #### Behavior Details
562
-
563
- - Redeban does not automatically invalidate a dynamic QR after its first scan.
564
-
565
- - As a result, the same QR may generate multiple transaction records.
566
-
567
-
568
- #### Recommendations
569
-
570
- - Implement **application-level validation** to detect multiple payments from the same QR code.
571
-
572
- - Monitor dynamic QR transactions and confirm status before marking payments as completed.
573
-
574
- - Inform end-users to verify the success of a transaction before rescanning.
575
-
576
-
577
- #### Future Considerations
578
-
579
- - Redeban is evaluating support for **single-use dynamic QR control**.
580
-
581
- - Stay updated with interoperability provider announcements to adjust integrations accordingly.
582
-
583
-
584
- ``` json
585
- "paymentMethod": {
586
- "id": 248,
587
- "cellphone": "string",
588
- "documentType": "string",
589
- "documentNumber": "string",
590
- "merchantId": "string"
591
- }
592
-
593
- ```
594
-
595
- ---
596
-
597
- ### **Llaves** Dinámicas **Bre-B**
598
-
599
- For this method, the following fields are **required**:
600
-
601
- - `cellphone`
602
-
603
- - `docNumber`
604
-
605
- - `docType`
606
-
607
- - `merchantId`
608
-
609
-
610
- 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.
611
-
612
- > ⚠ **Prerequisite:**
613
- The merchant must complete the **Merchant Enrollment** process before using this method.
614
- See the _Merchant Enrollment_ section for setup details.
615
-
616
- > 🔁 **Open Resource:**
617
- The **Llaves Dinamicas Bre-B** operates as an _open resource_, meaning the generated KEY can be used multiple times by the same user.
618
-
619
- > ⚙️ **Technical Note — Dynamic Key Behavior:**
620
- Dynamic keys may receive multiple money transfers due to current limitations in the Redeban system.
621
- This behavior does not represent an error or malfunction in our platform.
622
- **Additionally, dynamic keys have a fixed validity period of 5 minutes, and this duration cannot be modified.**
623
-
624
-
625
- #### Behavior Details
626
-
627
- - Redeban does not automatically invalidate a dynamic KEY after its first send.
628
-
629
- - As a result, the same KEY may generate multiple transaction records.
630
-
631
-
632
- #### Recommendations
633
-
634
- - Implement **application-level validation** to detect multiple payments from the same KEY.
635
-
636
- - Monitor dynamic KEY transactions and confirm status before marking payments as completed.
637
-
638
- - Inform end-users to verify the success of a transaction before rescanning.
639
-
640
-
641
- #### Future Considerations
642
-
643
- - Stay updated with interoperability provider announcements to adjust integrations accordingly.
644
-
645
-
646
- ``` json
647
- "paymentMethod": {
648
- "id": 250,
649
- "cellphone": "string",
650
- "docType": "string",
651
- "docNumber": "string",
652
- "merchantId": "string"
653
- }
654
-
655
- ```
656
-
657
- ---
658
-
659
- ### **Card Payments**
660
-
661
- This payment method allows processing payments with debit and credit cards (Mastercard and Visa).
662
-
663
- For this method, the following fields are **required**:
664
-
665
- - `id`: 273
666
-
667
- - `description`: Description of the payment detail that will be displayed in the payment link
668
-
669
- - `external`: Defines the type of link generated
670
-
671
-
672
- #### PaymentMethod Parameters
673
-
674
- | **Field** | **Type** | **Required** | **Description** |
675
- | --- | --- | --- | --- |
676
- | `id` | number | ✅ | Payment method ID: 273 |
677
- | `description` | string | ✅ | Description of the payment detail that will be displayed in the payment link |
678
- | `external` | boolean | ✅ | Defines whether to generate a payment link to send directly to the client (`true`) or to embed in an iframe (`false`) |
679
-
680
- #### Behavior based on the `external` parameter
681
-
682
- | **Value** | **Description** |
683
- | --- | --- |
684
- | `true` | Generates a payment link to send directly to the client. The client can complete the payment from their browser or mobile application. |
685
- | `false` | Generates a link to embed in an iframe within your own website. The payment is processed within your site. |
686
-
687
- #### Iframe Implementation Example
688
-
689
- When `external: false`, you can embed the payment link in an iframe as follows:
690
-
691
- ``` html
692
- <html>
693
- <head>
694
- <title>Add Payment Method</title>
695
- </head>
696
- <body>
697
- <iframe
698
- src="YOUR-URL-LINK-ID"
699
- width="100%"
700
- height="600"
701
- frameborder="0"
702
- style="max-width: 500px; margin: 0 auto; display: block;">
703
- </iframe>
704
- </body>
705
- </html>
706
- ```
707
-
708
- > ⚠️ **Important:**
709
- > You must use the **complete URL** from the `url` field in the service response as the `src` attribute value in the iframe. The `src` attribute must contain the entire URL returned in the `data.url` field of the API response. For example, if the response contains:
710
-
711
- ``` json
712
- "data": {
713
- "url": "https://checkout.akua.la/links/lnk-07595544-cfe6-4d40-8894-0ed7cf3c28b9?sandbox=true"
714
- }
715
- ```
716
-
717
- Then the iframe `src` should be:
718
-
719
- ``` html
720
- <iframe src="https://checkout.akua.la/links/lnk-07595544-cfe6-4d40-8894-0ed7cf3c28b9?sandbox=true" ...></iframe>
721
- ```
722
-
723
- ``` json
724
- "paymentMethod": {
725
- "id": 273,
726
- "description": "Payment description",
727
- "external": true
728
- }
729
- ```
730
-
731
- #### Response Example
732
-
733
- ``` json
734
- {
735
- "statusCode": "00",
736
- "message": "Operación exitosa.",
737
- "data": {
738
- "url": "https://checkout.akua.la/links/lnk-07595544-cfe6-4d40-8894-0ed7cf3c28b9?sandbox=true",
739
- "reference": "db205760-d228-11f0-8923-0d9b7d755dab",
740
- "resourceId": "2762357",
741
- "expiresIn": "2025-12-06T22:22:16.000Z",
742
- "urlStatusPay": "https://mf-core.refacil.co/refacilpay/resumen/79/db205760-d228-11f0-8923-0d9b7d755dab",
743
- "resourceUrlId": "1762027",
744
- "status": 1
745
- }
746
- }
747
- ```
748
-
749
- #### Response Fields
750
-
751
- | **Field** | **Description** |
752
- | --- | --- |
753
- | `url` | Payment link URL. Can be used for direct redirection or to embed in an iframe depending on the `external` value |
754
- | `reference` | Unique transaction reference |
755
- | `resourceId` | Generated payment resource ID |
756
- | `expiresIn` | Payment link expiration date and time |
757
- | `urlStatusPay` | URL to check the payment status |
758
- | `resourceUrlId` | URL resource ID |
759
- | `status` | Resource status (1 = Active) |
760
- ---
761
-
762
- ### **Whatsapp**
763
-
764
- For this method, the following fields are **required**:
765
-
766
- - `cellphone`
767
- - `pdfUrl`
768
-
769
- > ⚠ **pdfUrl — URL standards (Meta/WhatsApp):**
770
- The value is not arbitrary. The URL must comply with the following so that the document can be sent via WhatsApp:
771
-
772
- - **Protocol:** Must be **HTTPS**.
773
- - **Access:** The resource must be **publicly accessible** (no authentication); the system downloads the file from this URL.
774
- - **Format:** The file must be a valid **PDF**.
775
- - **Size:** Document size must not exceed **100 MB** (WhatsApp Cloud API limit for documents).
776
-
777
- Sending a URL that does not meet these requirements may result in rejection or delivery failure.
778
-
779
-
780
- ``` json
781
- "paymentMethod": {
782
- "id": 277,
783
- "cellphone": "string",
784
- "pdfUrl": "string"
785
- }
786
-
787
- ```
788
-
789
- ---
790
-
791
- ## 📥 Request Body Parameters
792
-
793
- | **Field** | **Type** | **Required** | **Description** |
794
- | --- | --- | --- | --- |
795
- | `amount` | number | ✅ | Value of the payment. |
796
- | `brandId` | number | ❌ | ID of the customer's white label; if one is not available, the default ID 79 is sent. |
797
- | `expiresIn` | number | ❌ | Time in seconds for the expiration of the resource or payment link. |
798
- | `paymentMethod` | object | ✅ | Object specifying the payment method and its details. |
799
- | `paymentMethod.id` | number | ✅ | ID of the selected payment method (see available payment methods). |
800
- | `reference1` | string | ✅ | Customer identifier, must be between 1 and 30 characters. |
801
- | `reference2` | object | ❌ | Object for additional information. |
802
- | `reference2.Commerce` | object | ❌ | Object for information related to the store or commerce. |
803
- | `reference2.Data` | object | ❌ | Object for information related to the conciliation of the transaction. |
804
- | `reference2.Label` | object | ❌ | Object to send information to be displayed in the payment summary. |
805
- | `returnUrl` | string | ❌ | Link that the customer will see when clicking on the back to commerce button. |
806
- | `showSummary` | boolean | ❌ | Indicates whether the RefácilPay payment summary will be shown or not (false: do not show, true: show). Default: true. |
807
- | `userMetadata` | object | ✅ | Object containing key details about the user or merchant generating the payment resource. |
808
- | `userMetadata.identifier` | string | ✅ | Unique identifier of the user or merchant generating the payment resource (max 36 characters). |
809
- | `userMetadata.ip` | string | ✅ | IP address associated with the user's identifier. Must be a valid IP address. |
810
- | `userMetadata.urlCommerce` | string | ✅ | URL that identifies the commerce. Must follow valid URL structure with http:// or https:// protocol. Maximum length: 500 characters. |
811
- | `webhookUrl` | string | ✅ | URL of the client's webhook to receive real-time payment status updates. |
812
-
813
- **Parámetros:**
814
-
815
- | Name | Type | Description |
816
- | --- | --- | --- |
817
- | transactionToken | string | Header personalizado: x-transaction-token |
818
- | expiresIn | number | Campo del body: expiresIn |
819
- | paymentMethod | object | Campo del body: paymentMethod |
820
- | userMetadata | object | Campo del body: userMetadata |
821
- | amount | number | Campo del body: amount |
822
- | brandId | number | Campo del body: brandId |
823
- | webhookUrl | string | Campo del body: webhookUrl |
824
- | returnUrl | string | Campo del body: returnUrl |
825
- | showSummary | boolean | Campo del body: showSummary |
826
- | reference1 | string | Campo del body: reference1 |
827
- | reference2 | object | Campo del body: reference2 |
828
-
829
- ### `cash_out_generate_withdraw_method_token`
830
-
831
- This service allows you to generate withdrawal requests through the enabled dispersion means.
832
-
833
- > 🔐 Authentication
834
-
835
-
836
- All requests must include the following headers:
837
-
838
- | **Header** | **Description** | **Example** |
839
- | --- | --- | --- |
840
- | Authorization | Bearer token generated by the authentication service. | Bearer eyJhbGciOiJIUzI1NiIs... |
841
- | x-transaction-token | Transactional token specific to the service. | 9b48edde-652d-11ed-984e-02c840fe**** |
842
- | Content-Type | Content type of the request body. | application/json |
843
-
844
- > Important fields within the requests:
845
- Webhook: This is the url of the client's webhook to where our service sends the transaction status and transaction detail information.
846
-
847
- This endpoint allows you to **generate withdrawal (cash-out) requests** through the available payout methods.
848
-
849
- ---
850
-
851
- ### 💡 Overview
852
-
853
- The table below lists the available payout methods along with their corresponding IDs and brief descriptions.
854
-
855
- | **Method ID** | **Description** |
856
- | --- | --- |
857
- | `264` | Cash-out via **Bre-B** |
858
-
859
- > ⚠ **Note:**
860
- Each withdrawal method requires a specific object structure within the `"withdrawMethod"` field, as shown below.
861
-
862
-
863
- ---
864
-
865
- ## 🧩 Payout Method Details
866
-
867
- ### **Bre-B**
868
-
869
- ``` json
870
- "withdrawMethod": {
871
- "id": 264,
872
- "key": "@REPRUEBAL7717"
873
- }
874
-
875
- ```
876
-
877
- **Description:**
878
- Transfers funds directly to a Bre-B account using the beneficiary’s unique Bre-B key.
879
-
880
- > 💡 **Tip:**
881
- The `key` field must contain a valid Bre-B account alias in the format `@USERNAME`.
882
-
883
-
884
- ---
885
-
886
- ## 📥 Request Body Parameters
887
-
888
- | **Field** | **Type** | **Required** | **Description** |
889
- | --- | --- | --- | --- |
890
- | `amount` | number | ✅ | Amount to be withdrawn. |
891
- | `reference1` | string | ✅ | Unique transaction reference generated by the client (max 20 characters). |
892
- | `webhookRequest` | string | ✅ | Customer’s webhook URL to receive real-time withdrawal status updates. |
893
- | `userMetadata` | object | ✅ | Object containing metadata related to the origin of the transaction. |
894
- | `userMetadata.identifier` | string | ✅ | Identifier for the user or merchant initiating the transaction. |
895
- | `userMetadata.ip` | string | ✅ | IP address from which the transaction was initiated. |
896
- | `userMetadata.urlCommerce` | string | ✅ | Commerce or customer’s URL associated with the transaction. |
897
- | `withdrawMethod` | object | ✅ | Object specifying the withdrawal method and destination details. |
898
- | `withdrawMethod.id` | number | ✅ | ID of the selected payout method (see table above). |
899
- | `withdrawMethod.key` | string | Conditional | Required for **Bre-B** withdrawals. |
900
- | `withdrawMethod.bankName` | string | ❌ | Optional bank name, if applicable for future payout methods. |
901
-
902
- ---
903
-
904
- **Parámetros:**
905
-
906
- | Name | Type | Description |
907
- | --- | --- | --- |
908
- | transactionToken | string | Header personalizado: x-transaction-token |
909
- | amount | number | Campo del body: amount |
910
- | reference1 | string | Campo del body: reference1 |
911
- | webhookRequest | string | Campo del body: webhookRequest |
912
- | withdrawMethod | object | Campo del body: withdrawMethod |
913
- | userMetadata | object | Campo del body: userMetadata |
914
-
915
- ### `customer_getbalance`
916
-
917
- This service allows you to generate withdrawal requests through the enabled dispersion means.
918
-
919
- > 🔐 Authentication
920
-
921
-
922
- All requests must include the following headers:
923
-
924
- | **Header** | **Description** | **Example** |
925
- | --- | --- | --- |
926
- | Authorization | Bearer token generated by the authentication service. | Bearer eyJhbGciOiJIUzI1NiIs... |
927
- | x-transaction-token | Transactional token specific to the service. | 9b48edde-652d-11ed-984e-02c840fe**** |
928
- | Content-Type | Content type of the request body. | application/json |
929
-
930
- > Important fields within the requests:
931
- Webhook: This is the url of the client's webhook to where our service sends the transaction status and transaction detail information.
932
-
933
- This service allows you to consult the balance exchange and the dispersion exchange associated with the client's identifier.
934
-
935
- > To use the service, an authentication token is required, which must be sent as an Authorization header.
936
-
937
-
938
- Headers
939
-
940
- | **Name** | **Value** |
941
- | --- | --- |
942
- | Content-Type | application/json |
943
- | Authorization | Bearer |
944
-
945
- Body
946
-
947
- **Parámetros:**
948
-
949
- | Name | Type | Description |
950
- | --- | --- | --- |
951
- | userId | number | Campo del body: userId |
952
-
953
- ### `payment_status`
954
-
955
- These services will allow us to validate the status of a transaction and consult the characteristics of a payment method.
956
-
957
- 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.
958
-
959
- In the response you will get the _status_ _id_ which will mean the following
960
-
961
- 0 - Transaction Rejected
962
-
963
- 1 - Pending Transaction
964
-
965
- 2 - Transaction Approved
966
-
967
- 3 - Failed Transaction
968
-
969
- 5 - Transaction Cancelled
970
-
971
- 9 - Processing Transaction
972
-
973
- Headers
974
-
975
- | **Name** | **Value** |
976
- | --- | --- |
977
- | Content-Type | application/json |
978
- | Authorization | Bearer |
979
-
980
- Body
981
-
982
- **Parámetros:**
983
-
984
- | Name | Type | Description |
985
- | --- | --- | --- |
986
- | reference | string | Campo del body: reference |
987
-
988
- ### `payment_customer_reference_status`
989
-
990
- These services will allow us to validate the status of a transaction and consult the characteristics of a payment method.
991
-
992
- ## 🔍 Check Transaction by Customer Reference
993
-
994
- 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:
995
-
996
- - `/cash-in/generate/payment-link/token`
997
-
998
- - `/cash-in/generate/payment-method/token`
999
-
1000
- - `/cash-out/generate/withdraw-method/token`
1001
-
1002
-
1003
- This service is useful for retrieving the internal **Refacil** transaction information associated with a previously submitted customer reference.
1004
-
1005
- ---
1006
-
1007
- ## 🔐 Authentication
1008
-
1009
- This endpoint **requires** a valid Bearer Token in the request headers. Requests without valid authentication will be rejected with an `Unauthorized` error.
1010
-
1011
- ## 📤 Successful Response
1012
-
1013
- - `exists`: `true` indicates that the transaction associated with the provided `customerReference` was found.
1014
-
1015
- - `id`: Internal Refacil transaction ID.
1016
-
1017
- - `status`: Transaction status code (see table below).
1018
-
1019
- - `reference`: Full Refacil transaction reference, which can be used to query `/payment/status`.
1020
-
1021
-
1022
- ### ℹ️ Status Code Reference
1023
-
1024
- | Status Code | Meaning |
1025
- | --- | --- |
1026
- | `0` | Transaction Rejected |
1027
- | `1` | Transaction Pending |
1028
- | `2` | Transaction Approved |
1029
- | `3` | Transaction Failed |
1030
- | `5` | Transaction Cancelled |
1031
- | `9` | Transaction Processing |
1032
-
1033
- ---
1034
-
1035
- **Parámetros:**
1036
-
1037
- | Name | Type | Description |
1038
- | --- | --- | --- |
1039
- | customerReference | string | Campo del body: customerReference |
1040
-
1041
- ### `payment_features`
1042
-
1043
- These services will allow us to validate the status of a transaction and consult the characteristics of a payment method.
1044
-
1045
- This service allows you to consult the necessary characteristics of a payment method to successfully generate a resource. For example, obtain the PSE banks
1046
-
1047
- Headers
1048
-
1049
- | **Name** | **Value** |
1050
- | --- | --- |
1051
- | Content-Type | application/json |
1052
- | Authorization | Bearer |
1053
-
1054
- Body
1055
-
1056
- **Parámetros:**
1057
-
1058
- | Name | Type | Description |
1059
- | --- | --- | --- |
1060
- | id | number | Campo del body: id |
1061
-
1062
- ### `webhook_notify`
1063
-
1064
- This component must be built by the merchant to receive the transaction notification data.
1065
-
1066
- You must take into account the following steps:
1067
-
1068
- **1.**You must create a Webhook without authentication.
1069
-
1070
- **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.
1071
-
1072
- <img src="https://content.pstmn.io/10fdac74-e60a-41f2-b9ff-8b5777a7afc0/aW1hZ2UucG5n" width="322" height="117">
1073
-
1074
- 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:
1075
-
1076
- _**HASH_KEY**_ _\=This data must be requested to the support area_.
1077
-
1078
- _**let signature**_ _\= referenceId-resourceId-amount-updatedAt-HASH_KEY; signature = crypto.createHmac(“sha1”, HASH_KEY).update(signature).digest(“hex”);_
1079
-
1080
- Example of a response that will reach your Webhook
1081
-
1082
- **Response**
1083
-
1084
- ``` json
1085
- {
1086
- "realAmount": 20000,
1087
- "amount": 19405,
1088
- "cost": "$595.00",
1089
- "referenceId": "38**",
1090
- "moduleId": 9,
1091
- "productId": 117,
1092
- "referenceKey": "3538d790-ae14-11ed-be2d-4d9b1bc987e6",
1093
- "paymentMethod": "PSE",
1094
- "userId": 189067,
1095
- "resourceId": "10024**",
1096
- "updatedAt": "2023-02-16 11:11:55",
1097
- "providerId": 8,
1098
- "providerReference": "3122330",
1099
- "reference1": "435sdfsd**",
1100
- "reference2": {
1101
- "Label": {
1102
- "Information": "Por seguridad algunos datos se encuentran cifrados",
1103
- "Name": "L**A",
1104
- "Email": "l**am@**",
1105
- "CellPhone": "3**4",
1106
- "DocumentType": "C",
1107
- "DocumentNumber": "52019859",
1108
- "Description": "Abono",
1109
- "Commerce": "Skandia",
1110
- "Reference1": null,
1111
- "Reference2": null,
1112
- "Reference3": null
1113
- },
1114
- "Data": {
1115
- "ConciliationCode": "FCO",
1116
- "ConciliationContract": "1277840",
1117
- "DocType": "N",
1118
- "DocNumber": "800194363"
1119
- },
1120
- "returnUrl": "https://www.google.com/"
1121
- },
1122
- "bankId": "1022",
1123
- "bankName": "BANCO UNION COLOMBIANO",
1124
- "status": 2,
1125
- "sign": "aa2f472ad7e84524a02d1716b56fc16ec2a87***",
1126
- "error": {
1127
- "code": "20-07A",
1128
- "message": "Error técnico en Lambda"
1129
- }
1130
- }
1131
-
1132
- ```
1133
-
1134
- - 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.
1135
-
1136
- - 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.
1137
-
1138
-
1139
- **Notification for Withdraw**
1140
-
1141
- 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:
1142
-
1143
- ``` json
1144
- {
1145
- ..."webhook",
1146
- "withdraw": {
1147
- "id": "1403**",
1148
- "transactionId": "5690**",
1149
- "userId": 189067,
1150
- "providerReference": "3122330",
1151
- "accountNumber": "3051000002",
1152
- "accountId": null,
1153
- "createdAt": "2023-02-16 11:10:55",
1154
- "updatedAt": "2023-02-16 11:12:55",
1155
- "deletedAt": null,
1156
- "infoReference": "435sdfsd**",
1157
- "observation": null
1158
- },
1159
- }
1160
-
1161
- ```
1162
-
1163
- > _**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.**_
1164
-
1165
- Body
1166
-
1167
-
1168
- ### Transfer state machine
1169
-
1170
- <img src="https://content.pstmn.io/89f89557-2e1b-44c2-8dcb-d9e7d2f32c54/aW1hZ2UucG5n" width="293" height="380">
1171
-
1172
- **Parámetros:**
1173
-
1174
- | Name | Type | Description |
1175
- | --- | --- | --- |
1176
- | reference | string | Campo del body: reference |
1177
-
1178
- ### `merchant_enrollment_data`
1179
-
1180
- This service allows merchants to retrieve enrollment data for the use of the QR interoperable payment method and key creation.
1181
-
1182
- To use the service, an authentication token is required and must be sent as an `Authorization` header.
1183
-
1184
- ---
1185
-
1186
- ### **Enrollment Process**
1187
-
1188
- 1. **Retrieve Enrollment Data**
1189
-
1190
- - Retrieves the merchant’s enrollment information once the process is completed.
1191
-
1192
-
1193
- ---
1194
-
1195
- ### **Merchant Enrollment Statuses**
1196
-
1197
- - **`approved`**
1198
-
1199
- The merchant has been approved and is authorized to generate QR codes.
1200
-
1201
- - **`enrolled_other`**
1202
-
1203
- The merchant is already enrolled with another entity. To proceed:
1204
-
1205
- - Contact the commercial representative and request unenrollment from the current entity.
1206
-
1207
- - Submit a letter signed by the legal representative.
1208
-
1209
- - Be aware that this process may take up to **5 business days**.
1210
-
1211
- The commercial representative will provide guidance throughout the process.
1212
-
1213
- - **`rejected`**
1214
-
1215
- The merchant has been rejected. Please contact your commercial representative for further details.
1216
-
1217
- - **`pending`**
1218
-
1219
- 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.
1220
-
1221
- - **`not_started`**
1222
-
1223
- No enrollment process has been initiated for the requested merchant.
1224
-
1225
-
1226
- ---
1227
-
1228
- ### **Important Note on the "cellphone" Field in the Enrollment Process**
1229
-
1230
- 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**.
1231
-
1232
- 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.
1233
-
1234
- 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.
1235
-
1236
- 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.
1237
-
1238
- ### `user_webhooks`
1239
-
1240
- Service to **configure backup webhooks per client**. It allows listing, creating and activating/deactivating URLs to which RefacilPay will send notifications when the payment resource has no webhook configured (e.g. for Saldo or Dispersión).
1241
-
1242
- ---
1243
-
1244
- ### Endpoints
1245
-
1246
- 1. **List user webhooks** (GET) – Returns the backup webhooks configured for the **authenticated user** (user inferred from Bearer token).
1247
-
1248
- 2. **Create user webhook** (POST) – Creates a backup webhook for the **authenticated user** and type (Saldo or Dispersión).
1249
-
1250
- 3. **Update webhook status** (PATCH) – Activates or deactivates a backup webhook **owned by the authenticated user**.
1251
-
1252
-
1253
- All endpoints require Bearer token authentication (`Authorization: Bearer {{tokenLogin}}`). The user is always inferred from the token for security.
1254
-
1255
- ---
1256
-
1257
- ### Description
1258
-
1259
- Returns the **backup webhooks** configured for the **authenticated user**. The user is identified by the Bearer token (header `Authorization`). The response lists all webhooks for that user with their type (e.g. Saldo, Dispersión), URL and active/inactive status.
1260
-
1261
- ---
1262
-
1263
- ### What it is for
1264
-
1265
- - Query which backup webhook URLs the authenticated client has configured.
1266
-
1267
- - See the status (active/inactive) of each webhook.
1268
-
1269
- - List available webhook types (Saldo, Dispersión).
1270
-
1271
-
1272
- ---
1273
-
1274
- ### Request
1275
-
1276
-
1277
- ---
1278
-
1279
- ### Response
1280
-
1281
- - **statusCode** (string): Operation status code. `00` = success.
1282
-
1283
- - **message** (string): Descriptive message (e.g. "Operación exitosa.").
1284
-
1285
- - **data** (array): List of webhooks, each with: `id`, `userId`, `webhookTypeId`, `typeName`, `url`, `active`, `createdAt`, `updatedAt`.
1286
-
1287
-
1288
- ---
1289
-
1290
- ### Example: Success (200 OK)
1291
-
1292
- ```
1293
- GET {{protocol}}://{{serverNamePayApi}}/user-webhooks
1294
- Authorization: Bearer {{tokenLogin}}
1295
-
1296
- ```
1297
-
1298
- Response body:
1299
-
1300
- ``` json
1301
- {
1302
- "statusCode": "00",
1303
- "message": "Operación exitosa.",
1304
- "data": [
1305
- {
1306
- "id": 1,
1307
- "userId": 12345,
1308
- "webhookTypeId": 1,
1309
- "typeName": "Saldo",
1310
- "url": "https://my-server.com/webhooks/saldo",
1311
- "active": true,
1312
- "createdAt": "2025-01-15T10:00:00.000Z",
1313
- "updatedAt": "2025-01-15T10:00:00.000Z"
1314
- },
1315
- {
1316
- "id": 2,
1317
- "userId": 12345,
1318
- "webhookTypeId": 2,
1319
- "typeName": "Dispersión",
1320
- "url": "https://my-server.com/webhooks/dispersion",
1321
- "active": false,
1322
- "createdAt": "2025-01-14T08:30:00.000Z",
1323
- "updatedAt": "2025-01-16T14:20:00.000Z"
1324
- }
1325
- ]
1326
- }
1327
-
1328
- ```
1329
-
1330
- ---
1331
-
1332
- ### Example: Empty list (200 OK)
1333
-
1334
- When the user has no webhooks configured, `data` is an empty array:
1335
-
1336
- ``` json
1337
- {
1338
- "statusCode": "00",
1339
- "message": "Operación exitosa.",
1340
- "data": []
1341
- }
1342
-
1343
- ```
1344
-
1345
- ### `create_user_webhook`
1346
-
1347
- Service to **configure backup webhooks per client**. It allows listing, creating and activating/deactivating URLs to which RefacilPay will send notifications when the payment resource has no webhook configured (e.g. for Saldo or Dispersión).
1348
-
1349
- ---
1350
-
1351
- ### Endpoints
1352
-
1353
- 1. **List user webhooks** (GET) – Returns the backup webhooks configured for the **authenticated user** (user inferred from Bearer token).
1354
-
1355
- 2. **Create user webhook** (POST) – Creates a backup webhook for the **authenticated user** and type (Saldo or Dispersión).
1356
-
1357
- 3. **Update webhook status** (PATCH) – Activates or deactivates a backup webhook **owned by the authenticated user**.
1358
-
1359
-
1360
- All endpoints require Bearer token authentication (`Authorization: Bearer {{tokenLogin}}`). The user is always inferred from the token for security.
1361
-
1362
- ---
1363
-
1364
- ### Description
1365
-
1366
- Creates a **backup webhook** for a user and webhook type. When a new webhook is created, only this webhook remains active for that user and type; others of the same type are deactivated.
1367
-
1368
- ---
1369
-
1370
- ### What it is for
1371
-
1372
- - Configure the URL to which RefacilPay will send backup notifications when the resource has no `webhookRequest`.
1373
-
1374
-
1375
- ---
1376
-
1377
- ### Request
1378
-
1379
-
1380
- ---
1381
-
1382
- ### Possible values for `webhookTypeId`
1383
-
1384
- | Value | Description |
1385
- | --- | --- |
1386
- | **1** | Saldo (cash-in backup notifications) |
1387
- | **2** | Dispersión (cash-out / dispersion backup notifications) |
1388
-
1389
- ---
1390
-
1391
- ### Example: Success (200 OK)
1392
-
1393
- ```
1394
- POST {{protocol}}://{{serverNamePayApi}}/user-webhooks
1395
- Authorization: Bearer {{tokenLogin}}
1396
- Content-Type: application/json
1397
- {
1398
- "webhookTypeId": 2,
1399
- "url": "https://my-server.com/webhooks/dispersion"
1400
- }
1401
-
1402
- ```
1403
-
1404
- The user is inferred from the Bearer token; do not send `userId` in the body.
1405
-
1406
- Response body:
1407
-
1408
- ``` json
1409
- {
1410
- "statusCode": "00",
1411
- "message": "Operación exitosa.",
1412
- "data": {
1413
- "id": 3,
1414
- "userId": 12345,
1415
- "webhookTypeId": 2,
1416
- "url": "https://my-server.com/webhooks/dispersion",
1417
- "active": true,
1418
- "createdAt": "2025-01-16T12:00:00.000Z",
1419
- "updatedAt": "2025-01-16T12:00:00.000Z"
1420
- }
1421
- }
1422
-
1423
- ```
1424
-
1425
- ---
1426
-
1427
- ### Example: Webhook type not found (404 Not Found)
1428
-
1429
- When `webhookTypeId` is not an allowed value (only **1** and **2** are valid), the API returns:
1430
-
1431
- ``` json
1432
- {
1433
- "statusCode": 404,
1434
- "message": "Webhook type not found: 99",
1435
- "error": "Not Found"
1436
- }
1437
-
1438
- ```
1439
-
1440
- ---
1441
-
1442
- ### Example: Validation error (400 Bad Request)
1443
-
1444
- When the request body is invalid (e.g. missing required fields, invalid URL format), the API returns validation errors:
1445
-
1446
- ``` json
1447
- {
1448
- "statusCode": 400,
1449
- "message": [
1450
- "url must be a URL address",
1451
- "url must be a URL address"
1452
- ],
1453
- "error": "Bad Request"
1454
- }
1455
-
1456
- ```
1457
-
1458
- **Parámetros:**
1459
-
1460
- | Name | Type | Description |
1461
- | --- | --- | --- |
1462
- | webhookTypeId | number | Campo del body: webhookTypeId |
1463
- | url | string | Campo del body: url |
1464
-
1465
- ### `user_webhooks_status`
1466
-
1467
- Service to **configure backup webhooks per client**. It allows listing, creating and activating/deactivating URLs to which RefacilPay will send notifications when the payment resource has no webhook configured (e.g. for Saldo or Dispersión).
1468
-
1469
- ---
1470
-
1471
- ### Endpoints
1472
-
1473
- 1. **List user webhooks** (GET) – Returns the backup webhooks configured for the **authenticated user** (user inferred from Bearer token).
1474
-
1475
- 2. **Create user webhook** (POST) – Creates a backup webhook for the **authenticated user** and type (Saldo or Dispersión).
1476
-
1477
- 3. **Update webhook status** (PATCH) – Activates or deactivates a backup webhook **owned by the authenticated user**.
1478
-
1479
-
1480
- All endpoints require Bearer token authentication (`Authorization: Bearer {{tokenLogin}}`). The user is always inferred from the token for security.
1481
-
1482
- ---
1483
-
1484
- ### Description
1485
-
1486
- Updates the **active/inactive status** of a backup webhook **owned by the authenticated user**. The user is identified by the Bearer token; you can only update webhooks that belong to that user. If a webhook is activated, other webhooks for the same user and type are deactivated (only one active per type per user).
1487
-
1488
- ---
1489
-
1490
- ### What it is for
1491
-
1492
- - Activate or deactivate a backup webhook URL without deleting it.
1493
-
1494
- - Switch which URL receives notifications when multiple are configured (activating one deactivates others of the same type).
1495
-
1496
-
1497
- ---
1498
-
1499
- ### Request
1500
-
1501
-
1502
- ---
1503
-
1504
- ### Example: Success (200 OK)
1505
-
1506
- ```
1507
- PATCH {{protocol}}://{{serverNamePayApi}}/user-webhooks/1/status
1508
- Authorization: Bearer {{tokenLogin}}
1509
- Content-Type: application/json
1510
- {
1511
- "active": true
1512
- }
1513
-
1514
- ```
1515
-
1516
- Response body:
1517
-
1518
- ``` json
1519
- {
1520
- "statusCode": "00",
1521
- "message": "Operación exitosa.",
1522
- "data": {
1523
- "id": 1,
1524
- "userId": 12345,
1525
- "webhookTypeId": 1,
1526
- "url": "https://my-server.com/webhooks/saldo",
1527
- "active": true,
1528
- "createdAt": "2025-01-15T10:00:00.000Z",
1529
- "updatedAt": "2025-01-16T15:30:00.000Z"
1530
- }
1531
- }
1532
-
1533
- ```
1534
-
1535
- ---
1536
-
1537
- ### Example: User webhook not found (404 Not Found)
1538
-
1539
- When no webhook exists with the given `id`, the API returns:
1540
-
1541
- ``` json
1542
- {
1543
- "statusCode": 404,
1544
- "message": "User webhook not found: 999",
1545
- "error": "Not Found"
1546
- }
1547
-
1548
- ```
1549
-
1550
- ---
1551
-
1552
- ### Example: Forbidden (403 Forbidden)
1553
-
1554
- When the webhook does not belong to the authenticated user, the API returns:
1555
-
1556
- ``` json
1557
- {
1558
- "statusCode": 403,
1559
- "message": "Webhook does not belong to the authenticated user",
1560
- "error": "Forbidden"
1561
- }
1562
-
1563
- ```
1564
-
1565
- ---
1566
-
1567
- ### Example: Validation error (400 Bad Request)
1568
-
1569
- When `id` is not a valid number or body is invalid:
1570
-
1571
- ``` json
1572
- {
1573
- "statusCode": 400,
1574
- "message": "Validation failed (numeric string is expected)",
1575
- "error": "Bad Request"
1576
- }
1577
-
1578
- ```
1579
-
1580
- **Parámetros:**
1581
-
1582
- | Name | Type | Description |
1583
- | --- | --- | --- |
1584
- | active | boolean | Campo del body: active |
1585
-
1586
-
1587
- ## 📝 Logs
1588
-
1589
- El servidor genera logs detallados de todas las operaciones:
1590
-
1591
- ```
1592
- [2024-01-01T12:00:00.000Z] get_users iniciada
1593
- [2024-01-01T12:00:01.000Z] get_users completada exitosamente
1594
- ```
1595
-
1596
- ## 🔍 Troubleshooting
1597
-
1598
- ### Error de autenticación
1599
- Verificar que las credenciales estén configuradas correctamente en las variables de entorno.
1600
-
1601
- ### Error de conexión a la API
1602
- Verificar que `BASE_URL` sea accesible y la API esté funcionando.
1603
-
1604
- ### Error de puerto
1605
- Verificar que el puerto `3009` no esté siendo usado por otro servicio.
1606
-
1607
- ## 📞 Soporte
1608
-
1609
- Para soporte técnico, contactar al equipo de desarrollo.
1610
-
1611
- ---
1612
-
1
+ # refacil-pay MCP Server
2
+
3
+ Servidor MCP (Model Context Protocol) generado automáticamente para la API refacil-pay.
4
+
5
+ ## 🚀 Características
6
+
7
+ - **18 herramientas** generadas automáticamente desde la colección Postman
8
+ - **Autenticación flexible**: Username/Password con renovación automática de tokens
9
+ - **Servidor HTTP** con Fastify
10
+ - **Protocolo MCP** estándar para integración con IDEs
11
+
12
+ ## 📋 Requisitos
13
+
14
+ - Node.js 20+
15
+ - npm o yarn
16
+
17
+ ## 📦 Instalación desde NPM
18
+
19
+ Si este paquete está publicado en npm, puedes instalarlo globalmente:
20
+
21
+ ```bash
22
+ # Instalación global (recomendado)
23
+ npm install -g refacil-pay-mcp
24
+
25
+ # Verificar instalación
26
+ refacil-pay-mcp --version
27
+ ```
28
+
29
+ ### Configuración Rápida en IDEs
30
+
31
+ #### Cursor
32
+
33
+ 1. Abrir **Settings** → **Features** → **Model Context Protocol**
34
+ 2. Click en **"Edit Config"**
35
+ 3. Agregar:
36
+
37
+ **Windows**: `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
38
+
39
+ **macOS/Linux**: `~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
40
+
41
+ ```json
42
+ {
43
+ "mcpServers": {
44
+ "refacil-pay": {
45
+ "command": "refacil-pay-mcp",
46
+ "env": {
47
+ "BASE_URL": "https://pay-api.qa.refacil.co",
48
+ "USERNAME": "tu-usuario",
49
+ "PASSWORD": "tu-contraseña",
50
+ "AUTH_ENDPOINT": "/auth/login",
51
+ "TOKEN_CACHE_TTL": "3600"
52
+ }
53
+ }
54
+ }
55
+ }
56
+ ```
57
+
58
+ 4. Reiniciar Cursor
59
+
60
+ #### Claude Desktop
61
+
62
+ Editar archivo de configuración:
63
+
64
+ **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
65
+
66
+ **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
67
+
68
+ **Linux**: `~/.config/Claude/claude_desktop_config.json`
69
+
70
+ ```json
71
+ {
72
+ "mcpServers": {
73
+ "refacil-pay": {
74
+ "command": "refacil-pay-mcp",
75
+ "env": {
76
+ "BASE_URL": "https://pay-api.qa.refacil.co",
77
+ "USERNAME": "tu-usuario",
78
+ "PASSWORD": "tu-contraseña",
79
+ "AUTH_ENDPOINT": "/auth/login",
80
+ "TOKEN_CACHE_TTL": "3600"
81
+ }
82
+ }
83
+ }
84
+ }
85
+ ```
86
+
87
+ Reiniciar Claude Desktop.
88
+
89
+ #### Visual Studio Code
90
+
91
+ 1. Instalar extensión **MCP for VS Code**
92
+ 2. Editar `settings.json`:
93
+
94
+ ```json
95
+ {
96
+ "mcp.servers": {
97
+ "refacil-pay": {
98
+ "command": "refacil-pay-mcp",
99
+ "env": {
100
+ "BASE_URL": "https://pay-api.qa.refacil.co",
101
+ "USERNAME": "tu-usuario",
102
+ "PASSWORD": "tu-contraseña",
103
+ "AUTH_ENDPOINT": "/auth/login",
104
+ "TOKEN_CACHE_TTL": "3600"
105
+ }
106
+ }
107
+ }
108
+ }
109
+ ```
110
+
111
+ 3. Recargar VS Code
112
+
113
+ ## 🛠️ Instalación para Desarrollo
114
+
115
+ Si quieres contribuir o ejecutar desde el código fuente:
116
+
117
+ ```bash
118
+ # Clonar el repositorio
119
+ git clone https://github.com/refacil/refacil-pay-mcp.git
120
+ cd refacil-pay-mcp
121
+
122
+ # Instalar dependencias
123
+ npm install
124
+
125
+ # Construir el proyecto
126
+ npm run build
127
+
128
+ # Iniciar en desarrollo
129
+ npm run dev
130
+
131
+ # Iniciar en producción
132
+ npm start
133
+ ```
134
+
135
+ ## 🔧 Configuración
136
+
137
+ El servidor se configura mediante variables de entorno:
138
+
139
+ ```bash
140
+ # Copiar archivo de ejemplo
141
+ cp .env.example .env
142
+
143
+ # Editar configuración
144
+ nano .env
145
+ ```
146
+
147
+ ### Variables de Entorno
148
+
149
+ | Variable | Descripción | Valor por defecto |
150
+ |----------|-------------|-------------------|
151
+ | `PORT` | Puerto del servidor | `3009` |
152
+ | `ENVIRONMENT` | Entorno de ejecución | `development` |
153
+ | `BASE_URL` | URL base de la API | `https://pay-api.qa.refacil.co` |
154
+ | `USERNAME` | Usuario para autenticación | `your_username_here` |
155
+ | `PASSWORD` | Contraseña para autenticación | `your_password_here` |
156
+ | `AUTH_ENDPOINT` | Endpoint de autenticación | `/auth/login` |
157
+ | `TOKEN_CACHE_TTL` | TTL del caché de tokens (segundos) | `3600` |
158
+ | `MCP_TOKEN` | Token de autenticación del MCP | `mcp-secret-token-refacil-pay` |
159
+
160
+
161
+ ## 🐳 Docker
162
+
163
+ ```bash
164
+ # Construir imagen
165
+ docker build -t refacil-pay-mcp .
166
+
167
+ # Ejecutar contenedor
168
+ docker run -p 3009:3009 refacil-pay-mcp
169
+
170
+ # O usar docker-compose
171
+ docker-compose up
172
+ ```
173
+
174
+ ## ☸️ Kubernetes
175
+
176
+ ```bash
177
+ # Aplicar manifests
178
+ kubectl apply -f k8s/
179
+
180
+ # Verificar despliegue
181
+ kubectl get pods -l app=refacil-pay-mcp
182
+ ```
183
+
184
+ ## 🔌 Uso del MCP
185
+
186
+ ### Endpoints Disponibles
187
+
188
+ - **`/mcp`**: Endpoint principal del protocolo MCP
189
+ - **`/health`**: Health check del servidor
190
+ - **`/tools`**: Lista de herramientas disponibles
191
+
192
+
193
+ ## 🛠️ Herramientas Disponibles
194
+
195
+ ### `auth_login`
196
+
197
+ 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)).
198
+
199
+ Within the post you will see below are the fields to make your request
200
+
201
+ > 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.
202
+ The authentication token has an expiration time of 2 hours. Only consume this service after this time has elapsed or when the services that use the token return a 401 Unauthorized response.
203
+
204
+ **Parámetros:**
205
+
206
+ | Name | Type | Description |
207
+ | --- | --- | --- |
208
+ | username | string | Campo del body: username |
209
+ | password | string | Campo del body: password |
210
+
211
+ ### `trx_token_generate`
212
+
213
+ This service allows security validation for the execution of a transaction on the platform, generating a single-use token.
214
+
215
+ > 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:
216
+ 1\. For Payment Link: **“/cash-in/generate/payment-link/token”**.
217
+ 2\. For Payment method: **“/cash-in/generate/payment-method/token”**.
218
+ 3\. For Withdraw: **“/cash-out/generate/withdraw-method/token”**.
219
+ 4\. For Merchant Key: \[ “/merchant-key/create”, “/merchant-key/cancel” \]
220
+
221
+ > 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.
222
+
223
+ **Parámetros:**
224
+
225
+ | Name | Type | Description |
226
+ | --- | --- | --- |
227
+ | service | string | Campo del body: service |
228
+
229
+ ### `transactional_token_method`
230
+
231
+ This service allows security validation for the execution of a transaction on the platform, generating a single-use token.
232
+
233
+ > 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:
234
+ 1\. For Payment Link: **“/cash-in/generate/payment-link/token”**.
235
+ 2\. For Payment method: **“/cash-in/generate/payment-method/token”**.
236
+ 3\. For Withdraw: **“/cash-out/generate/withdraw-method/token”**.
237
+ 4\. For Merchant Key: \[ “/merchant-key/create”, “/merchant-key/cancel” \]
238
+
239
+ > 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.
240
+
241
+ **Parámetros:**
242
+
243
+ | Name | Type | Description |
244
+ | --- | --- | --- |
245
+ | service | string | Campo del body: service |
246
+
247
+ ### `transactional_token_withdraw`
248
+
249
+ This service allows security validation for the execution of a transaction on the platform, generating a single-use token.
250
+
251
+ > 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:
252
+ 1\. For Payment Link: **“/cash-in/generate/payment-link/token”**.
253
+ 2\. For Payment method: **“/cash-in/generate/payment-method/token”**.
254
+ 3\. For Withdraw: **“/cash-out/generate/withdraw-method/token”**.
255
+ 4\. For Merchant Key: \[ “/merchant-key/create”, “/merchant-key/cancel” \]
256
+
257
+ > 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.
258
+
259
+ **Parámetros:**
260
+
261
+ | Name | Type | Description |
262
+ | --- | --- | --- |
263
+ | service | string | Campo del body: service |
264
+
265
+ ### `transactional_token_merchan_key_create`
266
+
267
+ This service allows security validation for the execution of a transaction on the platform, generating a single-use token.
268
+
269
+ > 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:
270
+ 1\. For Payment Link: **“/cash-in/generate/payment-link/token”**.
271
+ 2\. For Payment method: **“/cash-in/generate/payment-method/token”**.
272
+ 3\. For Withdraw: **“/cash-out/generate/withdraw-method/token”**.
273
+ 4\. For Merchant Key: \[ “/merchant-key/create”, “/merchant-key/cancel” \]
274
+
275
+ > 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.
276
+
277
+ **Parámetros:**
278
+
279
+ | Name | Type | Description |
280
+ | --- | --- | --- |
281
+ | service | string | Campo del body: service |
282
+
283
+ ### `transactional_token_merchant_key_cancel`
284
+
285
+ This service allows security validation for the execution of a transaction on the platform, generating a single-use token.
286
+
287
+ > 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:
288
+ 1\. For Payment Link: **“/cash-in/generate/payment-link/token”**.
289
+ 2\. For Payment method: **“/cash-in/generate/payment-method/token”**.
290
+ 3\. For Withdraw: **“/cash-out/generate/withdraw-method/token”**.
291
+ 4\. For Merchant Key: \[ “/merchant-key/create”, “/merchant-key/cancel” \]
292
+
293
+ > 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.
294
+
295
+ **Parámetros:**
296
+
297
+ | Name | Type | Description |
298
+ | --- | --- | --- |
299
+ | service | string | Campo del body: service |
300
+
301
+ ### `cash_in_generate_payment_link_token`
302
+
303
+ 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.
304
+
305
+ ## 📥 Request Body Parameters
306
+
307
+ | **Field** | **Type** | **Required** | **Description** |
308
+ | --- | --- | --- | --- |
309
+ | `amount` | number | ✅ | Value of the payment. |
310
+ | `brandId` | number | ❌ | ID of the customer's white label; if one is not available, the default ID 79 is sent. |
311
+ | `expiresIn` | number | ❌ | Time in minutes for the expiration of the resource or payment link. |
312
+ | `reference1` | string | ✅ | Customer identifier, must be between 1 and 30 characters. |
313
+ | `reference2` | object | ❌ | Object for additional information. |
314
+ | `reference2.Commerce` | object | ❌ | Object for information related to the store or commerce. |
315
+ | `reference2.Data` | object | ❌ | Object for information related to the conciliation of the transaction. |
316
+ | `reference2.Label` | object | ❌ | Object to send information to be displayed in the payment summary. |
317
+ | `returnUrl` | string | ❌ | Link that the customer will see when clicking on the back to commerce button. |
318
+ | `showSummary` | boolean | ❌ | Indicates whether the RefácilPay payment summary will be shown or not (false: do not show, true: show). Default: true. |
319
+ | `userMetadata` | object | ✅ | Object containing key details about the user or merchant generating the payment resource. |
320
+ | `userMetadata.identifier` | string | ✅ | Unique identifier of the user or merchant generating the payment resource (max 36 characters). |
321
+ | `userMetadata.ip` | string | ✅ | IP address associated with the user's identifier. Must be a valid IP address. |
322
+ | `userMetadata.urlCommerce` | string | ✅ | URL that identifies the commerce. Must follow valid URL structure with http:// or https:// protocol. Maximum length: 500 characters. |
323
+ | `webhookUrl` | string | ✅ | URL of the client's webhook to receive real-time payment status updates. |
324
+
325
+ **Parámetros:**
326
+
327
+ | Name | Type | Description |
328
+ | --- | --- | --- |
329
+ | expiresIn | number | Campo del body: expiresIn |
330
+ | amount | number | Campo del body: amount |
331
+ | brandId | number | Campo del body: brandId |
332
+ | webhookUrl | string | Campo del body: webhookUrl |
333
+ | userMetadata | object | Campo del body: userMetadata |
334
+ | returnUrl | string | Campo del body: returnUrl |
335
+ | reference1 | string | Campo del body: reference1 |
336
+ | reference2 | object | Campo del body: reference2 |
337
+
338
+ ### `cash_in_generate_payment_method_token`
339
+
340
+ This endpoint allows you to **generate payment requests** through the available _cash-in_ methods.
341
+
342
+ ---
343
+
344
+ ### 💡 Overview
345
+
346
+ The table below lists the available payment methods along with their corresponding IDs and **minimum expiration times** (`expiresIn`) required when creating a payment request.
347
+
348
+ | **Method ID** | **Description** | **Minimum Expiration (seconds)** |
349
+ | --- | --- | --- |
350
+ | `130` | Cash-in via **Nequi** | 43,200 |
351
+ | `131` | Cash-in via **Daviplata** | 43,200 |
352
+ | `133` | Cash-in via **PSE** | 1,800 |
353
+ | `262` | Cash-in via **PSE Gateway** | 1,800 |
354
+ | `153` | Cash-in via **Recaudo Efectivo** | 86,400 |
355
+ | `163` | Cash-in via **TPaga** | 43,200 |
356
+ | `248` | Cash-in via **QR Interoperable** | N/A |
357
+ | `250` | Cash-in via **Llaves Bre-B** | 300 |
358
+ | `273` | Cash-in via **Tarjetas** (Débito y Crédito) | 3,600 |
359
+ | `277` | Cash-in via **Whatsapp** | 2,592,000 |
360
+
361
+ > ⚠ **Important:**
362
+ 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.**
363
+
364
+
365
+ ---
366
+
367
+ ## 🧩 Payment Method Details
368
+
369
+ Each payment method requires a specific object structure within the `"paymentMethod"` field.
370
+
371
+ ---
372
+
373
+ ### **Nequi**
374
+
375
+ ``` json
376
+ "paymentMethod": {
377
+ "id": 130,
378
+ "cellphone": "3105293225"
379
+ }
380
+
381
+ ```
382
+
383
+ ---
384
+
385
+ ### **Daviplata**
386
+
387
+ ``` json
388
+ "paymentMethod": {
389
+ "id": 131,
390
+ "cellphone": "3208385715"
391
+ }
392
+
393
+ ```
394
+
395
+ ---
396
+
397
+ ### **PSE**
398
+
399
+ For this payment method, depending on the `typePerson` selected, only specific document types are accepted:
400
+
401
+ - **`typePerson`****:** **`"0"`** → corresponds to a **Natural Person** and only accepts the following values for `documentType`:
402
+
403
+ - `RCN`
404
+
405
+ - `TI`
406
+
407
+ - `CC`
408
+
409
+ - `TE`
410
+
411
+ - `CE`
412
+
413
+ - `PA`
414
+
415
+ - `DIE`
416
+
417
+ - **`typePerson`****:** **`"1"`** → corresponds to a **Legal Person** and only accepts the following value for `documentType`:
418
+
419
+ - `NIT`
420
+
421
+
422
+ ``` json
423
+ "paymentMethod": {
424
+ "id": 133,
425
+ "documentType": "CC",
426
+ "typePerson": "0",
427
+ "bankId": "string",
428
+ "documentNumber": "string",
429
+ "name": "string",
430
+ "cellphone": "string",
431
+ "address": "string",
432
+ "email": "string"
433
+ }
434
+
435
+ ```
436
+
437
+ ---
438
+
439
+ ### **PSE Gateway**
440
+
441
+ This payment method enables direct integration with the PSE network for processing online bank payments.
442
+ To consume this product, it is required to have the following parameters previously configured and associated with your product:
443
+
444
+ - `entity_code`
445
+
446
+ - `service_code`
447
+
448
+ - `company_ciiu`
449
+
450
+ - `company_name`
451
+
452
+
453
+ These parameters identify your company within the PSE network and are necessary for successful transaction routing and validation.
454
+
455
+ > 💬 **For more information or to request these credentials, please contact the support team.**
456
+
457
+
458
+ This method follows **the same structure and validation rules** as **PSE**, but must use the following identifier:
459
+
460
+ ``` json
461
+ "paymentMethod": {
462
+ "id": 262,
463
+ "documentType": "CC",
464
+ "typePerson": "0",
465
+ "bankId": "string",
466
+ "documentNumber": "string",
467
+ "name": "string",
468
+ "cellphone": "string",
469
+ "address": "string",
470
+ "email": "string"
471
+ }
472
+
473
+ ```
474
+
475
+ The **PSE integration** relies heavily on the correct configuration of the `showSummary` and `returnUrl` parameters.
476
+ These parameters control the **user experience** and the **finalization flow** of the payment process.
477
+
478
+ | Scenario | `showSummary` | `returnUrl` | Flow Description |
479
+ | --- | --- | --- | --- |
480
+ | **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`. |
481
+ | **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. |
482
+
483
+ > ⚠️ **Note:**
484
+ 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.
485
+
486
+ > 🔗 **See also:**
487
+
488
+
489
+ - [Transaction Summary](https://documenter.getpostman.com/view/35146358/2sA3QpDEFA#45e0d76a-fabd-442e-9b17-e2f6b8354ec5)
490
+
491
+ - [Transaction Status](https://documenter.getpostman.com/view/35146358/2sA3QpDEFA#dd3ba9f5-1f10-4109-b59d-6e5aad5e3799)
492
+
493
+
494
+ ---
495
+
496
+ ### **Recaudo Efectivo**
497
+
498
+ ``` json
499
+ "paymentMethod": {
500
+ "id": 153
501
+ }
502
+
503
+ ```
504
+
505
+ ---
506
+
507
+ ### **TPaga**
508
+
509
+ This payment method supports an optional parameter called `isQr`, which determines the type of resource returned in the `url` field:
510
+
511
+ | **Value** | **Description** |
512
+ | --- | --- |
513
+ | `true` | The `url` field returns a link to a **QR code** displaying transaction details. |
514
+ | `false` | The `url` field returns a **deeplink** to open directly in the TPAGA wallet app. |
515
+
516
+ > 🧠 **Behavior:**
517
+ If `isQr` is not provided, the default behavior is equivalent to `isQr: false`.
518
+ Transactions can only be completed **from a mobile device**.
519
+ 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.
520
+
521
+
522
+ ``` json
523
+ "paymentMethod": {
524
+ "id": 163,
525
+ "isQr": false
526
+ }
527
+
528
+ ```
529
+
530
+ ---
531
+
532
+ ### **QR Interoperable**
533
+
534
+ For this method, the following fields are **optional**:
535
+
536
+ - `cellphone`
537
+
538
+ - `documentNumber`
539
+
540
+ - `documentType`
541
+
542
+ - `merchantId`
543
+
544
+
545
+ The service can function using only the payment method ID; however, providing these optional fields can **improve response time**.
546
+ 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.
547
+
548
+ > ⚠ **Prerequisite:**
549
+ The merchant must complete the **Merchant Enrollment** process before using this method.
550
+ See the _Merchant Enrollment_ section for setup details.
551
+
552
+ > 🔁 **Open Resource:**
553
+ The **QR Interoperable** operates as an _open resource_, meaning the generated QR can be used multiple times by the same user.
554
+
555
+ > ⚙️ **Technical Note — Dynamic QR Behavior:**
556
+ Dynamic QR codes may be scanned multiple times due to current limitations in the Redeban system.
557
+ This is **not** an error in our platform.
558
+
559
+
560
+ #### Behavior Details
561
+
562
+ - Redeban does not automatically invalidate a dynamic QR after its first scan.
563
+
564
+ - As a result, the same QR may generate multiple transaction records.
565
+
566
+
567
+ #### Recommendations
568
+
569
+ - Implement **application-level validation** to detect multiple payments from the same QR code.
570
+
571
+ - Monitor dynamic QR transactions and confirm status before marking payments as completed.
572
+
573
+ - Inform end-users to verify the success of a transaction before rescanning.
574
+
575
+
576
+ #### Future Considerations
577
+
578
+ - Redeban is evaluating support for **single-use dynamic QR control**.
579
+
580
+ - Stay updated with interoperability provider announcements to adjust integrations accordingly.
581
+
582
+
583
+ ``` json
584
+ "paymentMethod": {
585
+ "id": 248,
586
+ "cellphone": "string",
587
+ "documentType": "string",
588
+ "documentNumber": "string",
589
+ "merchantId": "string"
590
+ }
591
+
592
+ ```
593
+
594
+ ---
595
+
596
+ ### **Llaves** Dinámicas **Bre-B**
597
+
598
+ For this method, the following fields are **required**:
599
+
600
+ - `cellphone`
601
+
602
+ - `docNumber`
603
+
604
+ - `docType`
605
+
606
+ - `merchantId`
607
+
608
+
609
+ 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.
610
+
611
+ > ⚠ **Prerequisite:**
612
+ The merchant must complete the **Merchant Enrollment** process before using this method.
613
+ See the _Merchant Enrollment_ section for setup details.
614
+
615
+ > 🔁 **Open Resource:**
616
+ The **Llaves Dinamicas Bre-B** operates as an _open resource_, meaning the generated KEY can be used multiple times by the same user.
617
+
618
+ > ⚙️ **Technical Note — Dynamic Key Behavior:**
619
+ Dynamic keys may receive multiple money transfers due to current limitations in the Redeban system.
620
+ This behavior does not represent an error or malfunction in our platform.
621
+ **Additionally, dynamic keys have a fixed validity period of 5 minutes, and this duration cannot be modified.**
622
+
623
+
624
+ #### Behavior Details
625
+
626
+ - Redeban does not automatically invalidate a dynamic KEY after its first send.
627
+
628
+ - As a result, the same KEY may generate multiple transaction records.
629
+
630
+
631
+ #### Recommendations
632
+
633
+ - Implement **application-level validation** to detect multiple payments from the same KEY.
634
+
635
+ - Monitor dynamic KEY transactions and confirm status before marking payments as completed.
636
+
637
+ - Inform end-users to verify the success of a transaction before rescanning.
638
+
639
+
640
+ #### Future Considerations
641
+
642
+ - Stay updated with interoperability provider announcements to adjust integrations accordingly.
643
+
644
+
645
+ ``` json
646
+ "paymentMethod": {
647
+ "id": 250,
648
+ "cellphone": "string",
649
+ "docType": "string",
650
+ "docNumber": "string",
651
+ "merchantId": "string"
652
+ }
653
+
654
+ ```
655
+
656
+ ---
657
+
658
+ ### **Card Payments**
659
+
660
+ This payment method allows processing payments with debit and credit cards (Mastercard and Visa).
661
+
662
+ For this method, the following fields are **required**:
663
+
664
+ - `id`: 273
665
+
666
+ - `description`: Description of the payment detail that will be displayed in the payment link
667
+
668
+
669
+ #### Payment Method Parameters
670
+
671
+ | **Field** | **Type** | **Required** | **Description** |
672
+ | --- | --- | --- | --- |
673
+ | `id` | number | ✅ | Payment method ID: 273 |
674
+ | `description` | string | ✅ | Description of the payment detail that will be displayed in the payment link |
675
+
676
+ ``` json
677
+ "paymentMethod": {
678
+ "id": 273,
679
+ "description": "string"
680
+ }
681
+
682
+ ```
683
+
684
+ ---
685
+
686
+ ### **Whatsapp**
687
+
688
+ For this method, the following fields are **required**:
689
+
690
+ - `cellphone`
691
+
692
+ - `pdfUrl`
693
+
694
+
695
+ > **pdfUrl — URL standards (Meta/WhatsApp):**
696
+ The value is not arbitrary. The URL must comply with the following so that the document can be sent via WhatsApp:
697
+
698
+
699
+ - **Protocol:** Must be **HTTPS**.
700
+
701
+ - **Access:** The resource must be **publicly accessible** (no authentication); the system downloads the file from this URL.
702
+
703
+ - **Format:** The file must be a valid **PDF**.
704
+
705
+ - **Size:** Document size must not exceed **100 MB** (WhatsApp Cloud API limit for documents).
706
+
707
+
708
+ Sending a URL that does not meet these requirements may result in rejection or delivery failure.
709
+
710
+ ``` json
711
+ "paymentMethod": {
712
+ "id": 277,
713
+ "cellphone": "string",
714
+ "pdfUrl": "string"
715
+ }
716
+
717
+ ```
718
+
719
+ <h2>📥 Request Body Parameters</h2>
720
+
721
+ | **Field** | **Type** | **Required** | **Description** |
722
+ | --- | --- | --- | --- |
723
+ | `amount` | number | ✅ | Value of the payment. |
724
+ | `brandId` | number | ❌ | ID of the customer's white label; if one is not available, the default ID 79 is sent. |
725
+ | `expiresIn` | number | ❌ | Time in seconds for the expiration of the resource or payment link. |
726
+ | `paymentMethod` | object | ✅ | Object specifying the payment method and its details. |
727
+ | `paymentMethod.id` | number | ✅ | ID of the selected payment method (see available payment methods). |
728
+ | `reference1` | string | ✅ | Customer identifier, must be between 1 and 30 characters. |
729
+ | `reference2` | object | ❌ | Object for additional information. |
730
+ | `reference2.Commerce` | object | ❌ | Object for information related to the store or commerce. |
731
+ | `reference2.Data` | object | ❌ | Object for information related to the conciliation of the transaction. |
732
+ | `reference2.Label` | object | ❌ | Object to send information to be displayed in the payment summary. |
733
+ | `returnUrl` | string | ❌ | Link that the customer will see when clicking on the back to commerce button. |
734
+ | `showSummary` | boolean | ❌ | Indicates whether the RefácilPay payment summary will be shown or not (false: do not show, true: show). Default: true. |
735
+ | `userMetadata` | object | ✅ | Object containing key details about the user or merchant generating the payment resource. |
736
+ | `userMetadata.identifier` | string | ✅ | Unique identifier of the user or merchant generating the payment resource (max 36 characters). |
737
+ | `userMetadata.ip` | string | ✅ | IP address associated with the user's identifier. Must be a valid IP address. |
738
+ | `userMetadata.urlCommerce` | string | ✅ | URL that identifies the commerce. Must follow valid URL structure with http:// or https:// protocol. Maximum length: 500 characters. |
739
+ | `webhookUrl` | string | ✅ | URL of the client's webhook to receive real-time payment status updates. |
740
+
741
+ **Parámetros:**
742
+
743
+ | Name | Type | Description |
744
+ | --- | --- | --- |
745
+ | amount | number | Campo del body: amount |
746
+ | brandId | number | Campo del body: brandId |
747
+ | expiresIn | number | Campo del body: expiresIn |
748
+ | paymentMethod | object | Campo del body: paymentMethod |
749
+ | reference1 | string | Campo del body: reference1 |
750
+ | reference2 | object | Campo del body: reference2 |
751
+ | returnUrl | string | Campo del body: returnUrl |
752
+ | showSummary | boolean | Campo del body: showSummary |
753
+ | userMetadata | object | Campo del body: userMetadata |
754
+ | webhookUrl | string | Campo del body: webhookUrl |
755
+
756
+ ### `cash_out_generate_withdraw_method_token`
757
+
758
+ This service allows you to generate withdrawal requests through the enabled dispersion means.
759
+
760
+ > 🔐 Authentication
761
+
762
+
763
+ All requests must include the following headers:
764
+
765
+ | **Header** | **Description** | **Example** |
766
+ | --- | --- | --- |
767
+ | Authorization | Bearer token generated by the authentication service. | Bearer eyJhbGciOiJIUzI1NiIs... |
768
+ | x-transaction-token | Transactional token specific to the service. | 9b48edde-652d-11ed-984e-02c840fe**** |
769
+ | Content-Type | Content type of the request body. | application/json |
770
+
771
+ > Important fields within the requests:
772
+ Webhook: This is the url of the client's webhook to where our service sends the transaction status and transaction detail information.
773
+
774
+ This endpoint allows you to **generate withdrawal (cash-out) requests** through the available payout methods.
775
+
776
+ ---
777
+
778
+ ### 💡 Overview
779
+
780
+ The table below lists the available payout methods along with their corresponding IDs and brief descriptions.
781
+
782
+ | **Method ID** | **Description** |
783
+ | --- | --- |
784
+ | `264` | Cash-out via **Bre-B** |
785
+
786
+ > ⚠ **Note:**
787
+ Each withdrawal method requires a specific object structure within the `"withdrawMethod"` field, as shown below.
788
+
789
+
790
+ ---
791
+
792
+ ## 🧩 Payout Method Details
793
+
794
+ ### **Bre-B**
795
+
796
+ ``` json
797
+ "withdrawMethod": {
798
+ "id": 264,
799
+ "key": "@REPRUEBAL7717"
800
+ }
801
+
802
+ ```
803
+
804
+ **Description:**
805
+ Transfers funds directly to a Bre-B account using the beneficiary’s unique Bre-B key.
806
+
807
+ > 💡 **Tip:**
808
+ The `key` field must contain a valid Bre-B account alias in the format `@USERNAME`.
809
+
810
+
811
+ ---
812
+
813
+ ## 📥 Request Body Parameters
814
+
815
+ | **Field** | **Type** | **Required** | **Description** |
816
+ | --- | --- | --- | --- |
817
+ | `amount` | number | ✅ | Amount to be withdrawn. |
818
+ | `reference1` | string | ✅ | Unique transaction reference generated by the client (max 20 characters). |
819
+ | `webhookRequest` | string | ✅ | Customer’s webhook URL to receive real-time withdrawal status updates. |
820
+ | `userMetadata` | object | ✅ | Object containing metadata related to the origin of the transaction. |
821
+ | `userMetadata.identifier` | string | ✅ | Identifier for the user or merchant initiating the transaction. |
822
+ | `userMetadata.ip` | string | ✅ | IP address from which the transaction was initiated. |
823
+ | `userMetadata.urlCommerce` | string | ✅ | Commerce or customer’s URL associated with the transaction. |
824
+ | `withdrawMethod` | object | ✅ | Object specifying the withdrawal method and destination details. |
825
+ | `withdrawMethod.id` | number | ✅ | ID of the selected payout method (see table above). |
826
+ | `withdrawMethod.key` | string | Conditional | Required for **Bre-B** withdrawals. |
827
+ | `withdrawMethod.bankName` | string | ❌ | Optional bank name, if applicable for future payout methods. |
828
+
829
+ ---
830
+
831
+ **Parámetros:**
832
+
833
+ | Name | Type | Description |
834
+ | --- | --- | --- |
835
+ | amount | number | Campo del body: amount |
836
+ | reference1 | string | Campo del body: reference1 |
837
+ | webhookRequest | string | Campo del body: webhookRequest |
838
+ | withdrawMethod | object | Campo del body: withdrawMethod |
839
+ | userMetadata | object | Campo del body: userMetadata |
840
+
841
+ ### `customer_getbalance`
842
+
843
+ This service allows you to generate withdrawal requests through the enabled dispersion means.
844
+
845
+ > 🔐 Authentication
846
+
847
+
848
+ All requests must include the following headers:
849
+
850
+ | **Header** | **Description** | **Example** |
851
+ | --- | --- | --- |
852
+ | Authorization | Bearer token generated by the authentication service. | Bearer eyJhbGciOiJIUzI1NiIs... |
853
+ | x-transaction-token | Transactional token specific to the service. | 9b48edde-652d-11ed-984e-02c840fe**** |
854
+ | Content-Type | Content type of the request body. | application/json |
855
+
856
+ > Important fields within the requests:
857
+ Webhook: This is the url of the client's webhook to where our service sends the transaction status and transaction detail information.
858
+
859
+ This service allows you to consult the balance exchange and the dispersion exchange associated with the client's identifier.
860
+
861
+ > To use the service, an authentication token is required, which must be sent as an Authorization header.
862
+
863
+
864
+ Headers
865
+
866
+ | **Name** | **Value** |
867
+ | --- | --- |
868
+ | Content-Type | application/json |
869
+ | Authorization | Bearer |
870
+
871
+ Body
872
+
873
+ **Parámetros:**
874
+
875
+ | Name | Type | Description |
876
+ | --- | --- | --- |
877
+ | userId | number | Campo del body: userId |
878
+
879
+ ### `payment_status`
880
+
881
+ These services will allow us to validate the status of a transaction and consult the characteristics of a payment method.
882
+
883
+ 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.
884
+
885
+ In the response you will get the _status_ _id_ which will mean the following
886
+
887
+ 0 - Transaction Rejected
888
+
889
+ 1 - Pending Transaction
890
+
891
+ 2 - Transaction Approved
892
+
893
+ 3 - Failed Transaction
894
+
895
+ 5 - Transaction Cancelled
896
+
897
+ 9 - Processing Transaction
898
+
899
+ Headers
900
+
901
+ | **Name** | **Value** |
902
+ | --- | --- |
903
+ | Content-Type | application/json |
904
+ | Authorization | Bearer |
905
+
906
+ Body
907
+
908
+ **Parámetros:**
909
+
910
+ | Name | Type | Description |
911
+ | --- | --- | --- |
912
+ | reference | string | Campo del body: reference |
913
+
914
+ ### `payment_customer_reference_status`
915
+
916
+ These services will allow us to validate the status of a transaction and consult the characteristics of a payment method.
917
+
918
+ ## 🔍 Check Transaction by Customer Reference
919
+
920
+ 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:
921
+
922
+ - `/cash-in/generate/payment-link/token`
923
+
924
+ - `/cash-in/generate/payment-method/token`
925
+
926
+ - `/cash-out/generate/withdraw-method/token`
927
+
928
+
929
+ This service is useful for retrieving the internal **Refacil** transaction information associated with a previously submitted customer reference.
930
+
931
+ ---
932
+
933
+ ## 🔐 Authentication
934
+
935
+ This endpoint **requires** a valid Bearer Token in the request headers. Requests without valid authentication will be rejected with an `Unauthorized` error.
936
+
937
+ ## 📤 Successful Response
938
+
939
+ - `exists`: `true` indicates that the transaction associated with the provided `customerReference` was found.
940
+
941
+ - `id`: Internal Refacil transaction ID.
942
+
943
+ - `status`: Transaction status code (see table below).
944
+
945
+ - `reference`: Full Refacil transaction reference, which can be used to query `/payment/status`.
946
+
947
+
948
+ ### ℹ️ Status Code Reference
949
+
950
+ | Status Code | Meaning |
951
+ | --- | --- |
952
+ | `0` | Transaction Rejected |
953
+ | `1` | Transaction Pending |
954
+ | `2` | Transaction Approved |
955
+ | `3` | Transaction Failed |
956
+ | `5` | Transaction Cancelled |
957
+ | `9` | Transaction Processing |
958
+
959
+ ---
960
+
961
+ **Parámetros:**
962
+
963
+ | Name | Type | Description |
964
+ | --- | --- | --- |
965
+ | customerReference | string | Campo del body: customerReference |
966
+
967
+ ### `payment_features`
968
+
969
+ These services will allow us to validate the status of a transaction and consult the characteristics of a payment method.
970
+
971
+ This service allows you to consult the necessary characteristics of a payment method to successfully generate a resource. For example, obtain the PSE banks
972
+
973
+ Headers
974
+
975
+ | **Name** | **Value** |
976
+ | --- | --- |
977
+ | Content-Type | application/json |
978
+ | Authorization | Bearer |
979
+
980
+ Body
981
+
982
+ **Parámetros:**
983
+
984
+ | Name | Type | Description |
985
+ | --- | --- | --- |
986
+ | id | number | Campo del body: id |
987
+
988
+ ### `webhook_notify`
989
+
990
+ This component must be built by the merchant to receive the transaction notification data.
991
+
992
+ You must take into account the following steps:
993
+
994
+ **1.**You must create a Webhook without authentication.
995
+
996
+ **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.
997
+
998
+ <img src="https://content.pstmn.io/10fdac74-e60a-41f2-b9ff-8b5777a7afc0/aW1hZ2UucG5n" width="322" height="117">
999
+
1000
+ 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:
1001
+
1002
+ _**HASH_KEY**_ _\=This data must be requested to the support area_.
1003
+
1004
+ _**let signature**_ _\= referenceId-resourceId-amount-updatedAt-HASH_KEY; signature = crypto.createHmac(“sha1”, HASH_KEY).update(signature).digest(“hex”);_
1005
+
1006
+ Example of a response that will reach your Webhook
1007
+
1008
+ **Response**
1009
+
1010
+ ``` json
1011
+ {
1012
+ "realAmount": 20000,
1013
+ "amount": 19405,
1014
+ "cost": "$595.00",
1015
+ "referenceId": "38**",
1016
+ "moduleId": 9,
1017
+ "productId": 117,
1018
+ "referenceKey": "3538d790-ae14-11ed-be2d-4d9b1bc987e6",
1019
+ "paymentMethod": "PSE",
1020
+ "userId": 189067,
1021
+ "resourceId": "10024**",
1022
+ "updatedAt": "2023-02-16 11:11:55",
1023
+ "providerId": 8,
1024
+ "providerReference": "3122330",
1025
+ "reference1": "435sdfsd**",
1026
+ "reference2": {
1027
+ "Label": {
1028
+ "Information": "Por seguridad algunos datos se encuentran cifrados",
1029
+ "Name": "L**A",
1030
+ "Email": "l**am@**",
1031
+ "CellPhone": "3**4",
1032
+ "DocumentType": "C",
1033
+ "DocumentNumber": "52019859",
1034
+ "Description": "Abono",
1035
+ "Commerce": "Skandia",
1036
+ "Reference1": null,
1037
+ "Reference2": null,
1038
+ "Reference3": null
1039
+ },
1040
+ "Data": {
1041
+ "ConciliationCode": "FCO",
1042
+ "ConciliationContract": "1277840",
1043
+ "DocType": "N",
1044
+ "DocNumber": "800194363"
1045
+ },
1046
+ "returnUrl": "https://www.google.com/"
1047
+ },
1048
+ "bankId": "1022",
1049
+ "bankName": "BANCO UNION COLOMBIANO",
1050
+ "status": 2,
1051
+ "sign": "aa2f472ad7e84524a02d1716b56fc16ec2a87***",
1052
+ "error": {
1053
+ "code": "20-07A",
1054
+ "message": "Error técnico en Lambda"
1055
+ }
1056
+ }
1057
+
1058
+ ```
1059
+
1060
+ - 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.
1061
+
1062
+ - 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.
1063
+
1064
+
1065
+ **Notification for Withdraw**
1066
+
1067
+ 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:
1068
+
1069
+ ``` json
1070
+ {
1071
+ ..."webhook",
1072
+ "withdraw": {
1073
+ "id": "1403**",
1074
+ "transactionId": "5690**",
1075
+ "userId": 189067,
1076
+ "providerReference": "3122330",
1077
+ "accountNumber": "3051000002",
1078
+ "accountId": null,
1079
+ "createdAt": "2023-02-16 11:10:55",
1080
+ "updatedAt": "2023-02-16 11:12:55",
1081
+ "deletedAt": null,
1082
+ "infoReference": "435sdfsd**",
1083
+ "observation": null
1084
+ },
1085
+ }
1086
+
1087
+ ```
1088
+
1089
+ > _**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.**_
1090
+
1091
+ Body
1092
+
1093
+
1094
+ ### Transfer state machine
1095
+
1096
+ <img src="https://content.pstmn.io/89f89557-2e1b-44c2-8dcb-d9e7d2f32c54/aW1hZ2UucG5n" width="293" height="380">
1097
+
1098
+ **Parámetros:**
1099
+
1100
+ | Name | Type | Description |
1101
+ | --- | --- | --- |
1102
+ | reference | string | Campo del body: reference |
1103
+
1104
+ ### `merchant_enrollment_data`
1105
+
1106
+ This service allows merchants to retrieve enrollment data for the use of the QR interoperable payment method and key creation.
1107
+
1108
+ To use the service, an authentication token is required and must be sent as an `Authorization` header.
1109
+
1110
+ ---
1111
+
1112
+ ### **Enrollment Process**
1113
+
1114
+ 1. **Retrieve Enrollment Data**
1115
+
1116
+ - Retrieves the merchant’s enrollment information once the process is completed.
1117
+
1118
+
1119
+ ---
1120
+
1121
+ ### **Merchant Enrollment Statuses**
1122
+
1123
+ - **`approved`**
1124
+
1125
+ The merchant has been approved and is authorized to generate QR codes.
1126
+
1127
+ - **`enrolled_other`**
1128
+
1129
+ The merchant is already enrolled with another entity. To proceed:
1130
+
1131
+ - Contact the commercial representative and request unenrollment from the current entity.
1132
+
1133
+ - Submit a letter signed by the legal representative.
1134
+
1135
+ - Be aware that this process may take up to **5 business days**.
1136
+
1137
+ The commercial representative will provide guidance throughout the process.
1138
+
1139
+ - **`rejected`**
1140
+
1141
+ The merchant has been rejected. Please contact your commercial representative for further details.
1142
+
1143
+ - **`pending`**
1144
+
1145
+ 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.
1146
+
1147
+ - **`not_started`**
1148
+
1149
+ No enrollment process has been initiated for the requested merchant.
1150
+
1151
+
1152
+ ---
1153
+
1154
+ ### **Important Note on the "cellphone" Field in the Enrollment Process**
1155
+
1156
+ 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**.
1157
+
1158
+ 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.
1159
+
1160
+ 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.
1161
+
1162
+ 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.
1163
+
1164
+ ### `user_webhooks`
1165
+
1166
+ Service to **configure backup webhooks per client**. It allows listing, creating and activating/deactivating URLs to which RefacilPay will send notifications when the payment resource has no webhook configured (e.g. for Saldo or Dispersión).
1167
+
1168
+ ---
1169
+
1170
+ ### Endpoints
1171
+
1172
+ 1. **List user webhooks** (GET) – Returns the backup webhooks configured for the **authenticated user** (user inferred from Bearer token).
1173
+
1174
+ 2. **Create user webhook** (POST) – Creates a backup webhook for the **authenticated user** and type (Saldo or Dispersión).
1175
+
1176
+ 3. **Update webhook status** (PATCH) – Activates or deactivates a backup webhook **owned by the authenticated user**.
1177
+
1178
+
1179
+ All endpoints require Bearer token authentication (`Authorization: Bearer {{tokenLogin}}`). The user is always inferred from the token for security.
1180
+
1181
+ ---
1182
+
1183
+ ### Description
1184
+
1185
+ Returns the **backup webhooks** configured for the **authenticated user**. The user is identified by the Bearer token (header `Authorization`). The response lists all webhooks for that user with their type (e.g. Saldo, Dispersión), URL and active/inactive status.
1186
+
1187
+ ---
1188
+
1189
+ ### What it is for
1190
+
1191
+ - Query which backup webhook URLs the authenticated client has configured.
1192
+
1193
+ - See the status (active/inactive) of each webhook.
1194
+
1195
+ - List available webhook types (Saldo, Dispersión).
1196
+
1197
+
1198
+ ---
1199
+
1200
+ ### Request
1201
+
1202
+
1203
+ ---
1204
+
1205
+ ### Response
1206
+
1207
+ - **statusCode** (string): Operation status code. `00` = success.
1208
+
1209
+ - **message** (string): Descriptive message (e.g. "Operación exitosa.").
1210
+
1211
+ - **data** (array): List of webhooks, each with: `id`, `userId`, `webhookTypeId`, `typeName`, `url`, `active`, `createdAt`, `updatedAt`.
1212
+
1213
+
1214
+ ---
1215
+
1216
+ ### Example: Success (200 OK)
1217
+
1218
+ ```
1219
+ GET {{protocol}}://{{serverNamePayApi}}/user-webhooks
1220
+ Authorization: Bearer {{tokenLogin}}
1221
+
1222
+ ```
1223
+
1224
+ Response body:
1225
+
1226
+ ``` json
1227
+ {
1228
+ "statusCode": "00",
1229
+ "message": "Operación exitosa.",
1230
+ "data": [
1231
+ {
1232
+ "id": 1,
1233
+ "userId": 12345,
1234
+ "webhookTypeId": 1,
1235
+ "typeName": "Saldo",
1236
+ "url": "https://my-server.com/webhooks/saldo",
1237
+ "active": true,
1238
+ "createdAt": "2025-01-15T10:00:00.000Z",
1239
+ "updatedAt": "2025-01-15T10:00:00.000Z"
1240
+ },
1241
+ {
1242
+ "id": 2,
1243
+ "userId": 12345,
1244
+ "webhookTypeId": 2,
1245
+ "typeName": "Dispersión",
1246
+ "url": "https://my-server.com/webhooks/dispersion",
1247
+ "active": false,
1248
+ "createdAt": "2025-01-14T08:30:00.000Z",
1249
+ "updatedAt": "2025-01-16T14:20:00.000Z"
1250
+ }
1251
+ ]
1252
+ }
1253
+
1254
+ ```
1255
+
1256
+ ---
1257
+
1258
+ ### Example: Empty list (200 OK)
1259
+
1260
+ When the user has no webhooks configured, `data` is an empty array:
1261
+
1262
+ ``` json
1263
+ {
1264
+ "statusCode": "00",
1265
+ "message": "Operación exitosa.",
1266
+ "data": []
1267
+ }
1268
+
1269
+ ```
1270
+
1271
+ ### `create_user_webhook`
1272
+
1273
+ Service to **configure backup webhooks per client**. It allows listing, creating and activating/deactivating URLs to which RefacilPay will send notifications when the payment resource has no webhook configured (e.g. for Saldo or Dispersión).
1274
+
1275
+ ---
1276
+
1277
+ ### Endpoints
1278
+
1279
+ 1. **List user webhooks** (GET) – Returns the backup webhooks configured for the **authenticated user** (user inferred from Bearer token).
1280
+
1281
+ 2. **Create user webhook** (POST) – Creates a backup webhook for the **authenticated user** and type (Saldo or Dispersión).
1282
+
1283
+ 3. **Update webhook status** (PATCH) – Activates or deactivates a backup webhook **owned by the authenticated user**.
1284
+
1285
+
1286
+ All endpoints require Bearer token authentication (`Authorization: Bearer {{tokenLogin}}`). The user is always inferred from the token for security.
1287
+
1288
+ ---
1289
+
1290
+ ### Description
1291
+
1292
+ Creates a **backup webhook** for a user and webhook type. When a new webhook is created, only this webhook remains active for that user and type; others of the same type are deactivated.
1293
+
1294
+ ---
1295
+
1296
+ ### What it is for
1297
+
1298
+ - Configure the URL to which RefacilPay will send backup notifications when the resource has no `webhookRequest`.
1299
+
1300
+
1301
+ ---
1302
+
1303
+ ### Request
1304
+
1305
+
1306
+ ---
1307
+
1308
+ ### Possible values for `webhookTypeId`
1309
+
1310
+ | Value | Description |
1311
+ | --- | --- |
1312
+ | **1** | Saldo (cash-in backup notifications) |
1313
+ | **2** | Dispersión (cash-out / dispersion backup notifications) |
1314
+
1315
+ ---
1316
+
1317
+ ### Example: Success (200 OK)
1318
+
1319
+ ```
1320
+ POST {{protocol}}://{{serverNamePayApi}}/user-webhooks
1321
+ Authorization: Bearer {{tokenLogin}}
1322
+ Content-Type: application/json
1323
+ {
1324
+ "webhookTypeId": 2,
1325
+ "url": "https://my-server.com/webhooks/dispersion"
1326
+ }
1327
+
1328
+ ```
1329
+
1330
+ The user is inferred from the Bearer token; do not send `userId` in the body.
1331
+
1332
+ Response body:
1333
+
1334
+ ``` json
1335
+ {
1336
+ "statusCode": "00",
1337
+ "message": "Operación exitosa.",
1338
+ "data": {
1339
+ "id": 3,
1340
+ "userId": 12345,
1341
+ "webhookTypeId": 2,
1342
+ "url": "https://my-server.com/webhooks/dispersion",
1343
+ "active": true,
1344
+ "createdAt": "2025-01-16T12:00:00.000Z",
1345
+ "updatedAt": "2025-01-16T12:00:00.000Z"
1346
+ }
1347
+ }
1348
+
1349
+ ```
1350
+
1351
+ ---
1352
+
1353
+ ### Example: Webhook type not found (404 Not Found)
1354
+
1355
+ When `webhookTypeId` is not an allowed value (only **1** and **2** are valid), the API returns:
1356
+
1357
+ ``` json
1358
+ {
1359
+ "statusCode": 404,
1360
+ "message": "Webhook type not found: 99",
1361
+ "error": "Not Found"
1362
+ }
1363
+
1364
+ ```
1365
+
1366
+ ---
1367
+
1368
+ ### Example: Validation error (400 Bad Request)
1369
+
1370
+ When the request body is invalid (e.g. missing required fields, invalid URL format), the API returns validation errors:
1371
+
1372
+ ``` json
1373
+ {
1374
+ "statusCode": 400,
1375
+ "message": [
1376
+ "url must be a URL address",
1377
+ "url must be a URL address"
1378
+ ],
1379
+ "error": "Bad Request"
1380
+ }
1381
+
1382
+ ```
1383
+
1384
+ **Parámetros:**
1385
+
1386
+ | Name | Type | Description |
1387
+ | --- | --- | --- |
1388
+ | webhookTypeId | number | Campo del body: webhookTypeId |
1389
+ | url | string | Campo del body: url |
1390
+
1391
+ ### `user_webhooks_status`
1392
+
1393
+ Service to **configure backup webhooks per client**. It allows listing, creating and activating/deactivating URLs to which RefacilPay will send notifications when the payment resource has no webhook configured (e.g. for Saldo or Dispersión).
1394
+
1395
+ ---
1396
+
1397
+ ### Endpoints
1398
+
1399
+ 1. **List user webhooks** (GET) – Returns the backup webhooks configured for the **authenticated user** (user inferred from Bearer token).
1400
+
1401
+ 2. **Create user webhook** (POST) – Creates a backup webhook for the **authenticated user** and type (Saldo or Dispersión).
1402
+
1403
+ 3. **Update webhook status** (PATCH) – Activates or deactivates a backup webhook **owned by the authenticated user**.
1404
+
1405
+
1406
+ All endpoints require Bearer token authentication (`Authorization: Bearer {{tokenLogin}}`). The user is always inferred from the token for security.
1407
+
1408
+ ---
1409
+
1410
+ ### Description
1411
+
1412
+ Updates the **active/inactive status** of a backup webhook **owned by the authenticated user**. The user is identified by the Bearer token; you can only update webhooks that belong to that user. If a webhook is activated, other webhooks for the same user and type are deactivated (only one active per type per user).
1413
+
1414
+ ---
1415
+
1416
+ ### What it is for
1417
+
1418
+ - Activate or deactivate a backup webhook URL without deleting it.
1419
+
1420
+ - Switch which URL receives notifications when multiple are configured (activating one deactivates others of the same type).
1421
+
1422
+
1423
+ ---
1424
+
1425
+ ### Request
1426
+
1427
+
1428
+ ---
1429
+
1430
+ ### Example: Success (200 OK)
1431
+
1432
+ ```
1433
+ PATCH {{protocol}}://{{serverNamePayApi}}/user-webhooks/1/status
1434
+ Authorization: Bearer {{tokenLogin}}
1435
+ Content-Type: application/json
1436
+ {
1437
+ "active": true
1438
+ }
1439
+
1440
+ ```
1441
+
1442
+ Response body:
1443
+
1444
+ ``` json
1445
+ {
1446
+ "statusCode": "00",
1447
+ "message": "Operación exitosa.",
1448
+ "data": {
1449
+ "id": 1,
1450
+ "userId": 12345,
1451
+ "webhookTypeId": 1,
1452
+ "url": "https://my-server.com/webhooks/saldo",
1453
+ "active": true,
1454
+ "createdAt": "2025-01-15T10:00:00.000Z",
1455
+ "updatedAt": "2025-01-16T15:30:00.000Z"
1456
+ }
1457
+ }
1458
+
1459
+ ```
1460
+
1461
+ ---
1462
+
1463
+ ### Example: User webhook not found (404 Not Found)
1464
+
1465
+ When no webhook exists with the given `id`, the API returns:
1466
+
1467
+ ``` json
1468
+ {
1469
+ "statusCode": 404,
1470
+ "message": "User webhook not found: 999",
1471
+ "error": "Not Found"
1472
+ }
1473
+
1474
+ ```
1475
+
1476
+ ---
1477
+
1478
+ ### Example: Forbidden (403 Forbidden)
1479
+
1480
+ When the webhook does not belong to the authenticated user, the API returns:
1481
+
1482
+ ``` json
1483
+ {
1484
+ "statusCode": 403,
1485
+ "message": "Webhook does not belong to the authenticated user",
1486
+ "error": "Forbidden"
1487
+ }
1488
+
1489
+ ```
1490
+
1491
+ ---
1492
+
1493
+ ### Example: Validation error (400 Bad Request)
1494
+
1495
+ When `id` is not a valid number or body is invalid:
1496
+
1497
+ ``` json
1498
+ {
1499
+ "statusCode": 400,
1500
+ "message": "Validation failed (numeric string is expected)",
1501
+ "error": "Bad Request"
1502
+ }
1503
+
1504
+ ```
1505
+
1506
+ **Parámetros:**
1507
+
1508
+ | Name | Type | Description |
1509
+ | --- | --- | --- |
1510
+ | active | boolean | Campo del body: active |
1511
+
1512
+
1513
+ ## 📝 Logs
1514
+
1515
+ El servidor genera logs detallados de todas las operaciones:
1516
+
1517
+ ```
1518
+ [2024-01-01T12:00:00.000Z] get_users iniciada
1519
+ [2024-01-01T12:00:01.000Z] get_users completada exitosamente
1520
+ ```
1521
+
1522
+ ## 🔍 Troubleshooting
1523
+
1524
+ ### Error de autenticación
1525
+ Verificar que las credenciales estén configuradas correctamente en las variables de entorno.
1526
+
1527
+ ### Error de conexión a la API
1528
+ Verificar que `BASE_URL` sea accesible y la API esté funcionando.
1529
+
1530
+ ### Error de puerto
1531
+ Verificar que el puerto `3009` no esté siendo usado por otro servicio.
1532
+
1533
+ ## 📞 Soporte
1534
+
1535
+ Para soporte técnico, contactar al equipo de desarrollo.
1536
+
1537
+ ---
1538
+
1613
1539
  *Generado automáticamente por Refacil MCP Framework*