refacil-pay MCP Server

Servidor MCP (Model Context Protocol) generado automáticamente para la API refacil-pay.

🚀 Características

• 21 herramientas generadas automáticamente desde la colección Postman
• Autenticación flexible: Username/Password con renovación automática de tokens
• Servidor HTTP con Fastify
• Protocolo MCP estándar para integración con IDEs

📋 Requisitos

• Node.js 20+
• npm o yarn

📦 Instalación desde NPM

Si este paquete está publicado en npm, puedes instalarlo globalmente:

# Instalación global (recomendado)
npm install -g refacil-pay-mcp

# Verificar instalación
refacil-pay-mcp --version

Configuración Rápida en IDEs

Cursor

1. Abrir Settings → Features → Model Context Protocol
2. Click en "Edit Config"
3. Agregar:

Windows: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

macOS/Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "refacil-pay": {
      "command": "refacil-pay-mcp",
      "env": {
        "BASE_URL": "https://pay-api.qa.refacil.co",
        "USERNAME": "tu-usuario",
        "PASSWORD": "tu-contraseña",
        "AUTH_ENDPOINT": "/auth/login",
        "TOKEN_CACHE_TTL": "3600"
      }
    }
  }
}

4. Reiniciar Cursor

Claude Desktop

Editar archivo de configuración:

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "refacil-pay": {
      "command": "refacil-pay-mcp",
      "env": {
        "BASE_URL": "https://pay-api.qa.refacil.co",
        "USERNAME": "tu-usuario",
        "PASSWORD": "tu-contraseña",
        "AUTH_ENDPOINT": "/auth/login",
        "TOKEN_CACHE_TTL": "3600"
      }
    }
  }
}

Reiniciar Claude Desktop.

Visual Studio Code

1. Instalar extensión MCP for VS Code
2. Editar settings.json:

{
  "mcp.servers": {
    "refacil-pay": {
      "command": "refacil-pay-mcp",
      "env": {
        "BASE_URL": "https://pay-api.qa.refacil.co",
        "USERNAME": "tu-usuario",
        "PASSWORD": "tu-contraseña",
        "AUTH_ENDPOINT": "/auth/login",
        "TOKEN_CACHE_TTL": "3600"
      }
    }
  }
}

3. Recargar VS Code

🛠️ Instalación para Desarrollo

Si quieres contribuir o ejecutar desde el código fuente:

# Clonar el repositorio
git clone https://github.com/refacil/refacil-pay-mcp.git
cd refacil-pay-mcp

# Instalar dependencias
npm install

# Construir el proyecto
npm run build

# Iniciar en desarrollo
npm run dev

# Iniciar en producción
npm start

🔧 Configuración

El servidor se configura mediante variables de entorno:

# Copiar archivo de ejemplo
cp .env.example .env

# Editar configuración
nano .env

Variables de Entorno

| Variable | Descripción | Valor por defecto | |----------|-------------|-------------------| | PORT | Puerto del servidor | 3009 | | ENVIRONMENT | Entorno de ejecución | development | | BASE_URL | URL base de la API | https://pay-api.qa.refacil.co | | USERNAME | Usuario para autenticación | your_username_here | | PASSWORD | Contraseña para autenticación | your_password_here | | AUTH_ENDPOINT | Endpoint de autenticación | /auth/login | | TOKEN_CACHE_TTL | TTL del caché de tokens (segundos) | 3600 | | MCP_TOKEN | Token de autenticación del MCP | mcp-secret-token-refacil-pay |

🐳 Docker

# Construir imagen
docker build -t refacil-pay-mcp .

# Ejecutar contenedor
docker run -p 3009:3009 refacil-pay-mcp

# O usar docker-compose
docker-compose up

☸️ Kubernetes

# Aplicar manifests
kubectl apply -f k8s/

# Verificar despliegue
kubectl get pods -l app=refacil-pay-mcp

🔌 Uso del MCP

Endpoints Disponibles

• /mcp: Endpoint principal del protocolo MCP
• /health: Health check del servidor
• /tools: Lista de herramientas disponibles

🛠️ Herramientas Disponibles

auth_login

To make the request and obtain the login you must have very clear your username and password for each environment where you are going to perform the integration, this information should be requested to our support team ([email protected]).

Within the post you will see below are the fields to make your request

Note that for the consumption of any of the API services it is necessary to send the authentication token that you get when consuming the auth/login service as an Authorization indicating the Type and Token.
The authentication token does not expire. However, if at any time it were to expire, it will be necessary to generate a new authentication token. This could occur due to internal security measures that lead to manual or mass expiration of the token.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | username | string | Campo del body: username | | password | string | Campo del body: password |

trx_token_generate

This service allows security validation for the execution of a transaction on the platform, generating a single-use token.

The transactional token service is obtained in three ways, depending on the action to be performed. For this, the value sent in the service parameter must be set according to what is required:
1. For Payment Link: “/cash-in/generate/payment-link/token”.
2. For Payment method: “/cash-in/generate/payment-method/token”.
3. For Withdraw: “/cash-out/generate/withdraw-method/token”.
4. For Merchant Key: [ “/merchant-key/create”, “/merchant-key/cancel” ]

The generated token is single-use for each transaction and cannot be consumed more than once. In addition, the transactional token will be valid for 60 seconds.

Generates a transactional token for payment link service.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | service | string | Campo del body: service |

transactional_token_method

This service allows security validation for the execution of a transaction on the platform, generating a single-use token.

The transactional token service is obtained in three ways, depending on the action to be performed. For this, the value sent in the service parameter must be set according to what is required:
1. For Payment Link: “/cash-in/generate/payment-link/token”.
2. For Payment method: “/cash-in/generate/payment-method/token”.
3. For Withdraw: “/cash-out/generate/withdraw-method/token”.
4. For Merchant Key: [ “/merchant-key/create”, “/merchant-key/cancel” ]

The generated token is single-use for each transaction and cannot be consumed more than once. In addition, the transactional token will be valid for 60 seconds.

Generates a transactional token for payment method service.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | service | string | Campo del body: service |

transactional_token_withdraw

This service allows security validation for the execution of a transaction on the platform, generating a single-use token.

The transactional token service is obtained in three ways, depending on the action to be performed. For this, the value sent in the service parameter must be set according to what is required:
1. For Payment Link: “/cash-in/generate/payment-link/token”.
2. For Payment method: “/cash-in/generate/payment-method/token”.
3. For Withdraw: “/cash-out/generate/withdraw-method/token”.
4. For Merchant Key: [ “/merchant-key/create”, “/merchant-key/cancel” ]

The generated token is single-use for each transaction and cannot be consumed more than once. In addition, the transactional token will be valid for 60 seconds.

Generates a transactional token for withdraw service.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | service | string | Campo del body: service |

transactional_token_merchan_key_create

This service allows security validation for the execution of a transaction on the platform, generating a single-use token.

The transactional token service is obtained in three ways, depending on the action to be performed. For this, the value sent in the service parameter must be set according to what is required:
1. For Payment Link: “/cash-in/generate/payment-link/token”.
2. For Payment method: “/cash-in/generate/payment-method/token”.
3. For Withdraw: “/cash-out/generate/withdraw-method/token”.
4. For Merchant Key: [ “/merchant-key/create”, “/merchant-key/cancel” ]

The generated token is single-use for each transaction and cannot be consumed more than once. In addition, the transactional token will be valid for 60 seconds.

Generates a transactional token for creating merchant keys.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | service | string | Campo del body: service |

transactional_token_merchant_key_cancel

This service allows security validation for the execution of a transaction on the platform, generating a single-use token.

The transactional token service is obtained in three ways, depending on the action to be performed. For this, the value sent in the service parameter must be set according to what is required:
1. For Payment Link: “/cash-in/generate/payment-link/token”.
2. For Payment method: “/cash-in/generate/payment-method/token”.
3. For Withdraw: “/cash-out/generate/withdraw-method/token”.
4. For Merchant Key: [ “/merchant-key/create”, “/merchant-key/cancel” ]

The generated token is single-use for each transaction and cannot be consumed more than once. In addition, the transactional token will be valid for 60 seconds.

Generates a transactional token for canceling merchant keys.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | service | string | Campo del body: service |

cash_in_generate_payment_link_token

With the following request you can obtain a payment resource with a link that will redirect your customer to the payment gateway where he will see a list of the different payment methods available.

📥 Request Body Parameters

| Field | Type | Required | Description | | --- | --- | --- | --- | | amount | number | ✅ | Value of the payment. | | brandId | number | ❌ | ID of the customer's white label; if one is not available, the default ID 79 is sent. | | expiresIn | number | ❌ | Time in minutes for the expiration of the resource or payment link. | | reference1 | string | ✅ | Customer identifier, must be between 1 and 30 characters. | | reference2 | object | ❌ | Object for additional information. | | reference2.Commerce | object | ❌ | Object for information related to the store or commerce. | | reference2.Data | object | ❌ | Object for information related to the conciliation of the transaction. | | reference2.Label | object | ❌ | Object to send information to be displayed in the payment summary. | | returnUrl | string | ❌ | Link that the customer will see when clicking on the back to commerce button. | | showSummary | boolean | ❌ | Indicates whether the RefácilPay payment summary will be shown or not (false: do not show, true: show). Default: true. | | userMetadata | object | ✅ | Object containing key details about the user or merchant generating the payment resource. | | userMetadata.identifier | string | ✅ | Unique identifier of the user or merchant generating the payment resource (max 36 characters). | | userMetadata.ip | string | ✅ | IP address associated with the user's identifier. Must be a valid IP address. | | userMetadata.urlCommerce | string | ✅ | URL that identifies the commerce. Must follow valid URL structure with http:// or https:// protocol. Maximum length: 500 characters. | | webhookUrl | string | ✅ | URL of the client's webhook to receive real-time payment status updates. |

Parámetros:

| Name | Type | Description | | --- | --- | --- | | transactionToken | string | Header personalizado: x-transaction-token | | expiresIn | number | Campo del body: expiresIn | | amount | number | Campo del body: amount | | brandId | number | Campo del body: brandId | | webhookUrl | string | Campo del body: webhookUrl | | userMetadata | object | Campo del body: userMetadata | | returnUrl | string | Campo del body: returnUrl | | reference1 | string | Campo del body: reference1 | | reference2 | object | Campo del body: reference2 |

cash_in_generate_payment_method_token

This endpoint allows you to generate payment requests through the available cash-in methods.

💡 Overview

The table below lists the available payment methods along with their corresponding IDs and minimum expiration times (expiresIn) required when creating a payment request.

| Method ID | Description | Minimum Expiration (seconds) | | --- | --- | --- | | 130 | Cash-in via Nequi | 43,200 | | 131 | Cash-in via Daviplata | 43,200 | | 133 | Cash-in via PSE | 1,800 | | 262 | Cash-in via PSE Gateway | 1,800 | | 134 | Cash-in via IPay | 43,200 | | 153 | Cash-in via Recaudo Efectivo | 86,400 | | 155 | Cash-in via Transfiya Recaudo | 43,200 | | 163 | Cash-in via TPaga | 43,200 | | 248 | Cash-in via QR Interoperable | N/A |

⚠ Important:
The value provided in the expiresIn field must be greater than or equal to the minimum expiration defined for the selected payment method.

🧩 Payment Method Details

Each payment method requires a specific object structure within the "paymentMethod" field.

Nequi

"paymentMethod": {
  "id": 130,
  "cellphone": "3105293225"
}

Daviplata

"paymentMethod": {
  "id": 131,
  "cellphone": "3208385715"
}

PSE

For this payment method, depending on the typePerson selected, only specific document types are accepted:

• typePerson****: "0" → corresponds to a Natural Person and only accepts the following values for documentType:

  • RCN

  • TI

  • CC

  • TE

  • CE

  • PA

  • DIE

• typePerson****: "1" → corresponds to a Legal Person and only accepts the following value for documentType:

  • NIT

"paymentMethod": {
  "id": 133,
  "documentType": "CC",
  "typePerson": "0",
  "bankId": "string",
  "documentNumber": "string",
  "name": "string",
  "cellphone": "string",
  "address": "string",
  "email": "string"
}

PSE Gateway

This payment method enables direct integration with the PSE network for processing online bank payments.
To consume this product, it is required to have the following parameters previously configured and associated with your product:

• entity_code

• service_code

• company_ciiu

• company_name

These parameters identify your company within the PSE network and are necessary for successful transaction routing and validation.

💬 For more information or to request these credentials, please contact the support team.

This method follows the same structure and validation rules as PSE, but must use the following identifier:

"paymentMethod": {
  "id": 262,
  "documentType": "CC",
  "typePerson": "0",
  "bankId": "string",
  "documentNumber": "string",
  "name": "string",
  "cellphone": "string",
  "address": "string",
  "email": "string"
}

The PSE integration relies heavily on the correct configuration of the showSummary and returnUrl parameters.
These parameters control the user experience and the finalization flow of the payment process.

| Scenario | showSummary | returnUrl | Flow Description | | --- | --- | --- | --- | | 1. Standard Redirect (Default) | true or not sent | ✅ Present | Displays a transaction summary screen with key payment details and retrieves the final transaction status. After the payment is completed, the user is redirected to the specified returnUrl. | | 2. Without Transaction Summary Screen | false | ✅ Present | Skips the transaction summary screen and redirects the user directly to the returnUrl. In this case, the merchant’s system must display the transaction summary on the destination page. |

⚠️ Note:
For PSE and PSE Gateway, it is strongly recommended to use showSummary: true along with a valid returnUrl to ensure a seamless customer experience and accurate transaction tracking.

🔗 See also:

• Transaction Summary

• Transaction Status

IPay

"paymentMethod": {
  "id": 134
}

Recaudo Efectivo

"paymentMethod": {
  "id": 153
}

Transfiya Recaudo

"paymentMethod": {
  "id": 155,
  "cellphone": "3105293225"
}

TPaga

This payment method supports an optional parameter called isQr, which determines the type of resource returned in the url field:

| Value | Description | | --- | --- | | true | The url field returns a link to a QR code displaying transaction details. | | false | The url field returns a deeplink to open directly in the TPAGA wallet app. |

🧠 Behavior:
If isQr is not provided, the default behavior is equivalent to isQr: false.
Transactions can only be completed from a mobile device.
If the request is made from a desktop or tablet, it is recommended to send isQr: true so the user can scan the QR from a mobile device.

"paymentMethod": {
  "id": 163,
  "isQr": false
}

QR Interoperable

For this method, the following fields are optional:

• cellphone

• documentNumber

• documentType

• merchantId

The service can function using only the payment method ID; however, providing these optional fields can improve response time.
You may retrieve this data through the enrollment-data service in the Merchant Enrollment section.

⚠ Prerequisite:
The merchant must complete the Merchant Enrollment process before using this method.
See the Merchant Enrollment section for setup details.

🔁 Open Resource:
The QR Interoperable operates as an open resource, meaning the generated QR can be used multiple times by the same user.

⚙️ Technical Note — Dynamic QR Behavior:
Dynamic QR codes may be scanned multiple times due to current limitations in the Redeban system.
This is not an error in our platform.

Behavior Details

• Redeban does not automatically invalidate a dynamic QR after its first scan.

• As a result, the same QR may generate multiple transaction records.

Recommendations

• Implement application-level validation to detect multiple payments from the same QR code.

• Monitor dynamic QR transactions and confirm status before marking payments as completed.

• Inform end-users to verify the success of a transaction before rescanning.

Future Considerations

• Redeban is evaluating support for single-use dynamic QR control.

• Stay updated with interoperability provider announcements to adjust integrations accordingly.

"paymentMethod": {
  "id": 248,
  "cellphone": "string",
  "documentType": "string",
  "documentNumber": "string",
  "merchantId": "string"
}

📥 Request Body Parameters

| Field | Type | Required | Description | | --- | --- | --- | --- | | amount | number | ✅ | Value of the payment. | | brandId | number | ❌ | ID of the customer's white label; if one is not available, the default ID 79 is sent. | | expiresIn | number | ❌ | Time in seconds for the expiration of the resource or payment link. | | paymentMethod | object | ✅ | Object specifying the payment method and its details. | | paymentMethod.id | number | ✅ | ID of the selected payment method (see available payment methods). | | reference1 | string | ✅ | Customer identifier, must be between 1 and 30 characters. | | reference2 | object | ❌ | Object for additional information. | | reference2.Commerce | object | ❌ | Object for information related to the store or commerce. | | reference2.Data | object | ❌ | Object for information related to the conciliation of the transaction. | | reference2.Label | object | ❌ | Object to send information to be displayed in the payment summary. | | returnUrl | string | ❌ | Link that the customer will see when clicking on the back to commerce button. | | showSummary | boolean | ❌ | Indicates whether the RefácilPay payment summary will be shown or not (false: do not show, true: show). Default: true. | | userMetadata | object | ✅ | Object containing key details about the user or merchant generating the payment resource. | | userMetadata.identifier | string | ✅ | Unique identifier of the user or merchant generating the payment resource (max 36 characters). | | userMetadata.ip | string | ✅ | IP address associated with the user's identifier. Must be a valid IP address. | | userMetadata.urlCommerce | string | ✅ | URL that identifies the commerce. Must follow valid URL structure with http:// or https:// protocol. Maximum length: 500 characters. | | webhookUrl | string | ✅ | URL of the client's webhook to receive real-time payment status updates. |

Parámetros:

| Name | Type | Description | | --- | --- | --- | | transactionToken | string | Header personalizado: x-transaction-token | | expiresIn | number | Campo del body: expiresIn | | paymentMethod | object | Campo del body: paymentMethod | | userMetadata | object | Campo del body: userMetadata | | amount | number | Campo del body: amount | | brandId | number | Campo del body: brandId | | webhookUrl | string | Campo del body: webhookUrl | | returnUrl | string | Campo del body: returnUrl | | showSummary | boolean | Campo del body: showSummary | | reference1 | string | Campo del body: reference1 | | reference2 | object | Campo del body: reference2 |

cash_out_generate_withdraw_method_token

This service allows you to generate withdrawal requests through the enabled dispersion means.

🔐 Authentication

All requests must include the following headers:

| Header | Description | Example | | --- | --- | --- | | Authorization | Bearer token generated by the authentication service. | Bearer eyJhbGciOiJIUzI1NiIs... | | x-transaction-token | Transactional token specific to the service. | 9b48edde-652d-11ed-984e-02c840fe**** | | Content-Type | Content type of the request body. | application/json |

Important fields within the requests:
Webhook: This is the url of the client's webhook to where our service sends the transaction status and transaction detail information.

This endpoint allows you to generate withdrawal (cash-out) requests through the available payout methods.

💡 Overview

The table below lists the available payout methods along with their corresponding IDs and brief descriptions.

| Method ID | Description | | --- | --- | | 245 | Cash-out via Transfiya | | 264 | Cash-out via Bre-B |

⚠ Note:
Each withdrawal method requires a specific object structure within the "withdrawMethod" field, as shown below.

🧩 Payout Method Details

Transfiya

"withdrawMethod": {
  "id": 245,
  "cellphone": "3125763074"
}

Description:
Transfers funds to a recipient using their registered Transfiya cellphone number.

⚠ Important:
Ensure the cellphone number is registered with Transfiya and capable of receiving funds.

Bre-B

"withdrawMethod": {
  "id": 264,
  "key": "@REPRUEBAL7717"
}

Description:
Transfers funds directly to a Bre-B account using the beneficiary’s unique Bre-B key.

💡 Tip:
The key field must contain a valid Bre-B account alias in the format @USERNAME.

📥 Request Body Parameters

| Field | Type | Required | Description | | --- | --- | --- | --- | | amount | number | ✅ | Amount to be withdrawn. | | reference1 | string | ✅ | Unique transaction reference generated by the client (max 20 characters). | | webhookRequest | string | ✅ | Customer’s webhook URL to receive real-time withdrawal status updates. | | userMetadata | object | ✅ | Object containing metadata related to the origin of the transaction. | | userMetadata.identifier | string | ✅ | Identifier for the user or merchant initiating the transaction. | | userMetadata.ip | string | ✅ | IP address from which the transaction was initiated. | | userMetadata.urlCommerce | string | ✅ | Commerce or customer’s URL associated with the transaction. | | withdrawMethod | object | ✅ | Object specifying the withdrawal method and destination details. | | withdrawMethod.id | number | ✅ | ID of the selected payout method (see table above). | | withdrawMethod.cellphone | string | Conditional | Required for Transfiya withdrawals. | | withdrawMethod.key | string | Conditional | Required for Bre-B withdrawals. | | withdrawMethod.bankName | string | ❌ | Optional bank name, if applicable for future payout methods. |

Parámetros:

| Name | Type | Description | | --- | --- | --- | | transactionToken | string | Header personalizado: x-transaction-token | | amount | number | Campo del body: amount | | reference1 | string | Campo del body: reference1 | | bankName | string | Campo del body: bankName | | webhookRequest | string | Campo del body: webhookRequest | | withdrawMethod | object | Campo del body: withdrawMethod | | userMetadata | object | Campo del body: userMetadata |

customer_getbalance

This service allows you to generate withdrawal requests through the enabled dispersion means.

🔐 Authentication

All requests must include the following headers:

| Header | Description | Example | | --- | --- | --- | | Authorization | Bearer token generated by the authentication service. | Bearer eyJhbGciOiJIUzI1NiIs... | | x-transaction-token | Transactional token specific to the service. | 9b48edde-652d-11ed-984e-02c840fe**** | | Content-Type | Content type of the request body. | application/json |

Important fields within the requests:
Webhook: This is the url of the client's webhook to where our service sends the transaction status and transaction detail information.

This service allows you to consult the balance exchange and the dispersion exchange associated with the client's identifier.

To use the service, an authentication token is required, which must be sent as an Authorization header.

Headers

| Name | Value | | --- | --- | | Content-Type | application/json | | Authorization | Bearer |

Body

Parámetros:

| Name | Type | Description | | --- | --- | --- | | userId | null | Campo del body: userId |

payment_transfiya_banks

This service allows you to generate withdrawal requests through the enabled dispersion means.

🔐 Authentication

All requests must include the following headers:

| Header | Description | Example | | --- | --- | --- | | Authorization | Bearer token generated by the authentication service. | Bearer eyJhbGciOiJIUzI1NiIs... | | x-transaction-token | Transactional token specific to the service. | 9b48edde-652d-11ed-984e-02c840fe**** | | Content-Type | Content type of the request body. | application/json |

Important fields within the requests:
Webhook: This is the url of the client's webhook to where our service sends the transaction status and transaction detail information.

This service allows you to consult the balance exchange and the dispersion exchange associated with the client's identifier.

To use the service, an authentication token is required, which must be sent as an Authorization header.

Headers

| Name | Value | | --- | --- | | Content-Type | application/json | | Authorization | Bearer |

Body

Parámetros:

| Name | Type | Description | | --- | --- | --- | | cellphone | string | Campo del body: cellphone |

payment_status

These services will allow us to validate the status of a transaction and consult the characteristics of a payment method.

This service allows you to check the status of a transaction made, for this you must have the reference data that returned the response when generating any payment resource.

In the response you will get the status id which will mean the following

0 - Transaction Rejected

1 - Pending Transaction

2 - Transaction Approved

3 - Failed Transaction

5 - Transaction Cancelled

9 - Processing Transaction

Headers

| Name | Value | | --- | --- | | Content-Type | application/json | | Authorization | Bearer |

Body

Parámetros:

| Name | Type | Description | | --- | --- | --- | | reference | string | Campo del body: reference |

payment_customer_reference_status

These services will allow us to validate the status of a transaction and consult the characteristics of a payment method.

🔍 Check Transaction by Customer Reference

This endpoint allows API Pay users to query the status of a transaction using only the customerReference value originally provided when generating a resource as reference1 through any of the following endpoints:

• /cash-in/generate/payment-link/token

• /cash-in/generate/payment-method/token

• /cash-out/generate/withdraw-method/token

This service is useful for retrieving the internal Refacil transaction information associated with a previously submitted customer reference.

🔐 Authentication

This endpoint requires a valid Bearer Token in the request headers. Requests without valid authentication will be rejected with an Unauthorized error.

📤 Successful Response

• exists: true indicates that the transaction associated with the provided customerReference was found.

• id: Internal Refacil transaction ID.

• status: Transaction status code (see table below).

• reference: Full Refacil transaction reference, which can be used to query /payment/status.

ℹ️ Status Code Reference

| Status Code | Meaning | | --- | --- | | 0 | Transaction Rejected | | 1 | Transaction Pending | | 2 | Transaction Approved | | 3 | Transaction Failed | | 5 | Transaction Cancelled | | 9 | Transaction Processing |

Parámetros:

| Name | Type | Description | | --- | --- | --- | | customerReference | string | Campo del body: customerReference |

payment_features

These services will allow us to validate the status of a transaction and consult the characteristics of a payment method.

This service allows you to consult the necessary characteristics of a payment method to successfully generate a resource. For example, obtain the PSE banks

Headers

| Name | Value | | --- | --- | | Content-Type | application/json | | Authorization | Bearer |

Body

Parámetros:

| Name | Type | Description | | --- | --- | --- | | id | number | Campo del body: id |

webhook_notify

This component must be built by the merchant to receive the transaction notification data.

You must take into account the following steps:

**1.**You must create a Webhook without authentication.

2. The Url created will be the one you send in all requests when generating the payment resource in the “WebhookUrl” field. It is important to keep in mind that if for some reason you change the webhook you must modify the urls that you send in each generated resource.

A signature must be generated to validate the integrity of the messages sent to the webhook and the fields must be concatenated in the following way:

HASH_KEY =This data must be requested to the support area.

let signature = referenceId-resourceId-amount-updatedAt-HASH_KEY; signature = crypto.createHmac(“sha1”, HASH_KEY).update(signature).digest(“hex”);

Example of a response that will reach your Webhook

Response

{
  "realAmount": 20000,
  "amount": 19405,
  "cost": "$595.00",
  "referenceId": "38**",
  "moduleId": 9,
  "productId": 117,
  "referenceKey": "3538d790-ae14-11ed-be2d-4d9b1bc987e6",
  "paymentMethod": "PSE",
  "userId": 189067,
  "resourceId": "10024**",
  "updatedAt": "2023-02-16 11:11:55",
  "providerId": 8,
  "providerReference": "3122330",
  "reference1": "435sdfsd**",
  "reference2": {
    "Label": {
      "Information": "Por seguridad algunos datos se encuentran cifrados",
      "Name": "L**A",
      "Email": "l**am@**",
      "CellPhone": "3**4",
      "DocumentType": "C",
      "DocumentNumber": "52019859",
      "Description": "Abono",
      "Commerce": "Skandia",
      "Reference1": null,
      "Reference2": null,
      "Reference3": null
    },
    "Data": {
      "ConciliationCode": "FCO",
      "ConciliationContract": "1277840",
      "DocType": "N",
      "DocNumber": "800194363"
    },
    "returnUrl": "https://www.google.com/"
  },
  "bankId": "1022",
  "bankName": "BANCO UNION COLOMBIANO",
  "status": 2,
  "transfiyaStatus": "PENDING",
  "sign": "aa2f472ad7e84524a02d1716b56fc16ec2a87***",
  "error": {
        "code": "20-07A",
        "message": "Error técnico en Lambda"
      }
}

• Within the webhook an "error ” object is sent that shows the error code and message associated with rejections received from the supplier/bank or cancellation of the transaction when the generation of the resource is not completed.

• The error codes are printed when the transaction is Rejected by the bank or when it is Cancelled because the resource generation could not be completed.

Notification for Withdraw

For withdraws, a notification will be sent to the webhook provided in the application. This notification will follow the structure mentioned above and will additionally include the withdrawal data. An example is provided below:

{
    ..."webhook",
    "withdraw": {
        "id": "1403**",
        "transactionId": "5690**",
        "userId": 189067,
        "providerReference": "3122330",
        "accountNumber": "3051000002",
        "accountId": null,
        "createdAt": "2023-02-16 11:10:55",
        "updatedAt": "2023-02-16 11:12:55",
        "deletedAt": null,
        "infoReference": "435sdfsd**",
        "observation": null
    },
}

The implementation of the webhook by the API user is mandatory. The reception and storage of the information for the reconciliation process by the API user with RefácilPay must be ensured.__This item will be evaluated during the certification process and will be mandatory for the transition to Production.

Body

TransfiYa Status

| transfiyaStatus | Description | | --- | --- | | CREATED | Transfer is received and queued for processing. | | PENDING | Transfer is valid and is waiting for the target to accept it. | | ACCEPTED | Transfer has been accepted by the target, and payment is pending in the target bank. | | COMPLETED | The payment is valid and completely processed, visible in the receiving bank account. | | REJECTED | Payment was rejected. | | ERROR | An error occurred during payment. |

Transfer state machine

Parámetros:

| Name | Type | Description | | --- | --- | --- | | reference | string | Campo del body: reference |

merchant_enrollment

This service allows merchants to enroll for the use of the QR interoperable payment method and key creation.

To use the service, an authentication token is required and must be sent as an Authorization header.

Enrollment Process

1. Merchant Enrollment

   • Initiates the enrollment process. The enrollment can take up to 7 minutes to complete.

2. Retrieve Enrollment Data

   • Retrieves the merchant’s enrollment information once the process is completed.

Merchant Enrollment Statuses

• approved

  The merchant has been approved and is authorized to generate QR codes.

• enrolled_other

  The merchant is already enrolled with another entity. To proceed:

  • Contact the commercial representative and request unenrollment from the current entity.

  • Submit a letter signed by the legal representative.

  • Be aware that this process may take up to 5 business days.

    The commercial representative will provide guidance throughout the process.

• rejected

  The merchant has been rejected. Please contact your commercial representative for further details.

• pending

  The enrollment is in progress. The query may take a few minutes. If a final status is not received shortly, contact RefacilPay support to verify the situation.

• not_started

  No enrollment process has been initiated for the requested merchant.

Important Note on the "cellphone" Field in the Enrollment Process

During the merchant creation flow for the QR Interoperable product, the API retrieves the merchant's registered information from the system. However, for the "cellphone number" field, the Refacil system automatically replaces the merchant’s actual phone number with a generic alias number.

This behavior follows technical and operational requirements from the provider, as the real phone number may already exist in the provider’s databases, potentially causing integration conflicts.

To avoid these issues, a randomly generated alias is used as a placeholder. This alias is exclusive to this product and does not affect the merchant’s operation in other services.

This endpoint initiates the merchant enrollment process required to use the QR interoperable payment method. Once the request is made, the enrollment process may take up to 7 minutes to complete.

merchant_enrollment_data

This service allows merchants to enroll for the use of the QR interoperable payment method and key creation.

To use the service, an authentication token is required and must be sent as an Authorization header.

Enrollment Process

1. Merchant Enrollment

   • Initiates the enrollment process. The enrollment can take up to 7 minutes to complete.

2. Retrieve Enrollment Data

   • Retrieves the merchant’s enrollment information once the process is completed.

Merchant Enrollment Statuses

• approved

  The merchant has been approved and is authorized to generate QR codes.

• enrolled_other

  The merchant is already enrolled with another entity. To proceed:

  • Contact the commercial representative and request unenrollment from the current entity.

  • Submit a letter signed by the legal representative.

  • Be aware that this process may take up to 5 business days.

    The commercial representative will provide guidance throughout the process.

• rejected

  The merchant has been rejected. Please contact your commercial representative for further details.

• pending

  The enrollment is in progress. The query may take a few minutes. If a final status is not received shortly, contact RefacilPay support to verify the situation.

• not_started

  No enrollment process has been initiated for the requested merchant.

Important Note on the "cellphone" Field in the Enrollment Process

During the merchant creation flow for the QR Interoperable product, the API retrieves the merchant's registered information from the system. However, for the "cellphone number" field, the Refacil system automatically replaces the merchant’s actual phone number with a generic alias number.

This behavior follows technical and operational requirements from the provider, as the real phone number may already exist in the provider’s databases, potentially causing integration conflicts.

To avoid these issues, a randomly generated alias is used as a placeholder. This alias is exclusive to this product and does not affect the merchant’s operation in other services.

This endpoint retrieves the merchant's enrollment details after the enrollment process has been completed. It provides necessary information to use the QR interoperable payment method.

merchant_key_create

These services allow merchants to create and manage their Bre-b keys.

To use these services, an authentication token is required, which must be sent as an authorization header.

⚠ Important: Before using this payment method, the merchant enrollment process must be completed. Detailed instructions can be found in the Merchant Enrollment section.

🔄 Open resource: The creation of a key functions as an open resource, which means that once the Bre-b key has been generated, the user can receive multiple transactions through it.

Recommendations

• API users are strongly encouraged to implement additional application-level validations to detect, identify, and manage multiple payment records originating from a Bre-b key.

• Actively monitor transactions originating from generated keys and validate the status of operations before confirming payment to the end user.

This endpoint will allow you to create 4 types of keys: alias, email, cellphone, and document.

⚠ Important:

• Alias key: To generate this key, it is not necessary to send the key field and the otp field. A random key is generated from various parameters of the merchant user, beginning with the character @.

• Document key: To generate this key, it is not necessary to send the otp field, and the key field must contain the document provided in the technical data sheet shared with the merchant.

• Email key: To generate this key, you must first use the service that generates and sends the OTP to the email address. The key field must contain the email address provided in the technical data sheet.

• Cellphone key: To generate this key, you must first use the service that generates and sends the OTP to the cellphone. The key field must contain the cellphone number provided in the technical data sheet.

Headers

| Name | Value | | --- | --- | | Content-Type | application/json | | Authorization | Bearer | | x-transaction-token | 9b48edde-652d-11ed-984e-02c840fe**** |

Body

Parámetros:

| Name | Type | Description | | --- | --- | --- | | transactionToken | string | Header personalizado: x-transaction-token | | webhookUrl | string | Campo del body: webhookUrl | | reference1 | string | Campo del body: reference1 | | reference2 | object | Campo del body: reference2 | | userMetadata | object | Campo del body: userMetadata | | typeKey | string | Campo del body: typeKey | | key | string | Campo del body: key | | otp | string | Campo del body: otp | | termsAndConditions | boolean | Campo del body: termsAndConditions |

merchant_key_cancel

These services allow merchants to create and manage their Bre-b keys.

To use these services, an authentication token is required, which must be sent as an authorization header.

⚠ Important: Before using this payment method, the merchant enrollment process must be completed. Detailed instructions can be found in the Merchant Enrollment section.

🔄 Open resource: The creation of a key functions as an open resource, which means that once the Bre-b key has been generated, the user can receive multiple transactions through it.

Recommendations

• API users are strongly encouraged to implement additional application-level validations to detect, identify, and manage multiple payment records originating from a Bre-b key.

• Actively monitor transactions originating from generated keys and validate the status of operations before confirming payment to the end user.

This endpoint allows you to cancel an existing key, which will then become inactive and unable to receive transactions.

Headers

| Name | Value | | --- | --- | | Content-Type | application/json | | Authorization | Bearer | | x-transaction-token | 9b48edde-652d-11ed-984e-02c840fe**** |

Body

Parámetros:

| Name | Type | Description | | --- | --- | --- | | transactionToken | string | Header personalizado: x-transaction-token | | userMetadata | object | Campo del body: userMetadata | | key | string | Campo del body: key |

merchant_key_generate_otp

These services allow merchants to create and manage their Bre-b keys.

To use these services, an authentication token is required, which must be sent as an authorization header.

⚠ Important: Before using this payment method, the merchant enrollment process must be completed. Detailed instructions can be found in the Merchant Enrollment section.

🔄 Open resource: The creation of a key functions as an open resource, which means that once the Bre-b key has been generated, the user can receive multiple transactions through it.

Recommendations

• API users are strongly encouraged to implement additional application-level validations to detect, identify, and manage multiple payment records originating from a Bre-b key.

• Actively monitor transactions originating from generated keys and validate the status of operations before confirming payment to the end user.

This endpoint will allow you to generate and send an OTP. It is only permitted and necessary for email and cellphone keys. This OTP will be sent to its corresponding destination.

Headers

| Name | Value | | --- | --- | | Content-Type | application/json | | Authorization | Bearer |

Body

Parámetros:

| Name | Type | Description | | --- | --- | --- | | key | string | Campo del body: key | | typeKey | string | Campo del body: typeKey |

merchant_key_get_keys

These services allow merchants to create and manage their Bre-b keys.

To use these services, an authentication token is required, which must be sent as an authorization header.

⚠ Important: Before using this payment method, the merchant enrollment process must be completed. Detailed instructions can be found in the Merchant Enrollment section.

🔄 Open resource: The creation of a key functions as an open resource, which means that once the Bre-b key has been generated, the user can receive multiple transactions through it.

Recommendations

• API users are strongly encouraged to implement additional application-level validations to detect, identify, and manage multiple payment records originating from a Bre-b key.

• Actively monitor transactions originating from generated keys and validate the status of operations before confirming payment to the end user.

This endpoint allows you to obtain all keys created and in active status that belong to the merchant.

📝 Logs

El servidor genera logs detallados de todas las operaciones:

[2024-01-01T12:00:00.000Z] get_users iniciada
[2024-01-01T12:00:01.000Z] get_users completada exitosamente

🔍 Troubleshooting

Error de autenticación

Verificar que las credenciales estén configuradas correctamente en las variables de entorno.

Error de conexión a la API

Verificar que BASE_URL sea accesible y la API esté funcionando.

Error de puerto

Verificar que el puerto 3009 no esté siendo usado por otro servicio.

📞 Soporte

Para soporte técnico, contactar al equipo de desarrollo.

Generado automáticamente por Refacil MCP Framework