1.0.10 • Published 2 weeks agoCLI

collection-api-refacil-mcp

Licence

MIT

Version

1.0.10

Deps

Size

295 kB

Vulns

Weekly

Summary Dependency Versions

collection-api-refacil MCP Server

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

Características

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

Instalación para Desarrollo

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

# Clonar el repositorio
git clone https://github.com/refacil/collection-api-refacil-mcp.git
cd collection-api-refacil-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	`3008`
`ENVIRONMENT`	Entorno de ejecución	`development`
`BASE_URL`	URL base de la API	`https://collection-api.qa.refacil.co`
`SECRET_ID`	ID secreto para autenticación	`0d92fc6aa394c13... (your secret id)`
`AUTH_ENDPOINT`	Endpoint de autenticación	`/auth/jwt`
`TOKEN_CACHE_TTL`	TTL del caché de tokens (segundos)	`3600`
`MCP_TOKEN`	Token de autenticación del MCP	`mcp-secret-token-123`

Docker

# Construir imagen
docker build -t collection-api-refacil-mcp .

# Ejecutar contenedor
docker run -p 3008:3008 collection-api-refacil-mcp

# O usar docker-compose
docker-compose up

Kubernetes

# Aplicar manifests
kubectl apply -f k8s/

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

Uso del MCP

Endpoints Disponibles

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

Modo Multi-Usuario (HTTP)

El servidor MCP soporta múltiples usuarios simultáneamente en modo HTTP mediante el header X-Secret-ID.

¿Cómo funciona?

Sin X-Secret-ID: Usa el SECRET_ID del archivo .env (modo single-user)
Con X-Secret-ID: Usa el secretId proporcionado en el header (modo multi-user)

Ejemplo de uso:

# Usuario 1
curl -X POST http://localhost:3008/mcp \
  -H "Authorization: Bearer mcp-token" \
  -H "X-Secret-ID: user1-secret-id" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/call", "params": {...}}'

# Usuario 2
curl -X POST http://localhost:3008/mcp \
  -H "Authorization: Bearer mcp-token" \
  -H "X-Secret-ID: user2-secret-id" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/call", "params": {...}}'

Ventajas del Modo Multi-Usuario:

Cada usuario usa sus propias credenciales
Tokens cacheados por secretId (mejor performance)
Un solo servidor para múltiples clientes
Compatible con modo single-user (fallback al .env)

Overview

To use the Collection API, clients must follow a two-step authentication process:

Generate a JWT (Bearer Token) using their Secret ID
(Optional) Generate a One-Time Token (OTT) for secure access to specific endpoints

Each request must include the correct headers. Tokens have time-based expiration.

This endpoint allows third-party clients to generate a temporary JWT Bearer token using their assigned Secret ID.

The token is required to authenticate and access protected endpoints in the Collection API.

The token is valid for 60 minutes.
You must include the x-secret-id header to request it.

Parámetros:

Name	Type	Description
secretId *	string	Header personalizado: x-secret-id

Overview

To use the Collection API, clients must follow a two-step authentication process:

Generate a JWT (Bearer Token) using their Secret ID
(Optional) Generate a One-Time Token (OTT) for secure access to specific endpoints

Each request must include the correct headers. Tokens have time-based expiration.

This endpoint generates a single-use token that provides an extra layer of security for sensitive operations.

The token is valid for 60 seconds and can only be used once.
You must include both x-secret-id and Authorization: Bearer headers to request it.

Endpoints that require One-Time Token

HTTP Method	Endpoint URL	Description
`POST`	`/collection/submit-payment`	Registers a payment or top-up at a branch

Parámetros:

Name	Type	Description
secretId *	string	Header personalizado: x-secret-id
service	string	Campo del body: service

This endpoint handles financial transactions and collections. It processes payments, validates customers and companies, and integrates with a payment processing system. The service includes transaction amount validation, customer verification, and company balance management.

Request Body Parameters

Field	Type	Description
`reference`	Integer	The reference for the transaction. Min. 1 character, max. 50 characters.
`agreementId`	Integer	ID of the agreement (company) that is making the payment
`amount`	Integer	Amount to be charged, in COP (Colombian Pesos)
`date`	String	Transaction date in format `YYYY-MM-DD`
`time`	String	Transaction time in format `HH:mm` (24-hour clock, Bogotá time zone)
`ip`	String	IP address of the client

Available Agreements

`agreementId`	Company Name
`18252`	Apostar
`18253`	Susuerte

Only the above agreementIds are currently authorized to use this service.

Parámetros:

Name	Type	Description
secretId *	string	Header personalizado: x-secret-id
oneTimeToken *	string	Header personalizado: x-one-time-token
reference	number	Campo del body: reference
agreementId	number	Campo del body: agreementId
amount	number	Campo del body: amount
date	string	Campo del body: date
time	string	Campo del body: time
ip	string	Campo del body: ip

`auth_validate`

Collection of Own Network services. Integrators expose these endpoints so the platform can query bills, submit payments, and receive notifications in a consistent way.

Recommendations

Establish a dedicated QA environment to perform thorough testing before production deployment.
Set a minimum timeout of 60 milliseconds for API requests to handle longer processes reliably.
Provide clear and standardized error mapping, detailing error codes, messages, and causes for better troubleshooting.

Authorization

To establish a secure connection with our clients' APIs, we will generate and provide you with an authorization token. This token will allow us to authenticate with the API that our clients build.

Token format:

Authorization: Token {generate_token_value}

Example:

Authorization: Token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9**

Error handling

All errors must return an HTTP status code in the 4xx or 5xx family (i.e. 400 or above). Do not return 2xx codes when the operation has failed.

4xx (client errors): 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, etc.
5xx (server errors): 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, etc.

Error response structure

There is no single mandatory error schema across all endpoints. One of the following patterns is recommended depending on the endpoint type.

Option A — Minimum structure (recommended for all endpoints)

Return a JSON body with at least:

statusCode (number): HTTP status code of the response (must match the HTTP status).
message (string): Human-readable message describing the error.
errorCode (string, optional): Internal error code for integration/support (e.g. auth.invalid, billing.not_found).

Option B — Transactional endpoints (`queryBill`, `submitTransaction`, `rollbackTransaction`)

For transactional operations, use this structure:

message (string): Message describing the error.
reference (string): Reference associated with the operation.
amount (number): Amount (0 in case of error).
code (string): Business status code (e.g. 003, 004).
user_code (string): User code when applicable.
additional_data (array): List of { "label", "value" } objects with additional information.

Authentication errors (401/403)

Some examples only return detail (string) or a combination of message, error, and statusCode. When possible, align these responses with Option A for consistency.

In all cases, the error body must be JSON and must provide enough information for the integrator to identify the failure, correct the data, or decide whether to retry.

This endpoint allows you to validate a JWT token by sending an HTTP POST request to {{base_url}}/auth/validate.

Base URL:

Enviroment	Value
QA	https://collection-api.qa.refacil.co
PROD	https://collection-api.refacil.co

Request Body Parameters

Field	Type	Required	Description
secretId	string		The secret identifier used to validate the token. This secretId will be shared by us with the client
token	string		The JWT token to be validated

Response body parameters

Field	Type	Description
statusCode	number	The HTTP status code of the response
message	string	A message indicating the result of the operation
date	number	The timestamp of the response
payload	object	The response payload containing validation results
payload.valid	boolean	Indicates whether the token is valid or not
payload.message	string	A message related to the validation result
payload.data	object	Optional decoded token data if the token is valid

Parámetros:

Name	Type	Description
secretId	string	Campo del body: secretId
token	string	Campo del body: token

`ping`

Collection of Own Network services. Integrators expose these endpoints so the platform can query bills, submit payments, and receive notifications in a consistent way.

Recommendations

Establish a dedicated QA environment to perform thorough testing before production deployment.
Set a minimum timeout of 60 milliseconds for API requests to handle longer processes reliably.
Provide clear and standardized error mapping, detailing error codes, messages, and causes for better troubleshooting.

Authorization

To establish a secure connection with our clients' APIs, we will generate and provide you with an authorization token. This token will allow us to authenticate with the API that our clients build.

Token format:

Authorization: Token {generate_token_value}

Example:

Authorization: Token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9**

Error handling

All errors must return an HTTP status code in the 4xx or 5xx family (i.e. 400 or above). Do not return 2xx codes when the operation has failed.

4xx (client errors): 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, etc.
5xx (server errors): 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, etc.

Error response structure

There is no single mandatory error schema across all endpoints. One of the following patterns is recommended depending on the endpoint type.

Option A — Minimum structure (recommended for all endpoints)

Return a JSON body with at least:

statusCode (number): HTTP status code of the response (must match the HTTP status).
message (string): Human-readable message describing the error.
errorCode (string, optional): Internal error code for integration/support (e.g. auth.invalid, billing.not_found).

Option B — Transactional endpoints (`queryBill`, `submitTransaction`, `rollbackTransaction`)

For transactional operations, use this structure:

message (string): Message describing the error.
reference (string): Reference associated with the operation.
amount (number): Amount (0 in case of error).
code (string): Business status code (e.g. 003, 004).
user_code (string): User code when applicable.
additional_data (array): List of { "label", "value" } objects with additional information.

Authentication errors (401/403)

Some examples only return detail (string) or a combination of message, error, and statusCode. When possible, align these responses with Option A for consistency.

In all cases, the error body must be JSON and must provide enough information for the integrator to identify the failure, correct the data, or decide whether to retry.

This endpoint sends an HTTP GET request to {{customer.domain.com}}/ping/ in order to check the availability of the server.

Benefits

Fail-fast: detects unavailability before critical operations.
SLO-aware: monitor per-client availability and trigger mitigations.
Proactive ops: enables circuit breakers and routing policies.

The request does not contain a request body.

Response

Status: 200
Body: "pong"

Domain and Security Requirements

To integrate with Own Network Collection, all integration endpoint URLs must follow secure domain standards.

1) URL domain structure (all endpoints)

Must be a fully qualified domain URL, for example: https://api.yourdomain.com/path.
http://, IP-only endpoints, localhost domains, or self-signed development URLs are not accepted in production onboarding.
The domain must be publicly resolvable and reachable from Refacil infrastructure.

2) SSL/TLS mandatory requirement

Only HTTPS endpoints are accepted.
The domain must present a valid SSL/TLS certificate issued by a trusted CA.
The certificate must be active (not expired), with a complete certificate chain and valid hostname (CN/SAN match).
Requests can be rejected during merchant setup or runtime if certificate validation fails.

3) General API security restrictions

Enforce token-based authentication exactly as documented (Authorization header).
Validate payload schema, data types, and required fields before processing.
Protect endpoints against replay and duplicate processing using idempotency controls where applicable.
Do not expose secrets, tokens, or sensitive personal data in logs or error messages.
Apply network hardening controls (rate limiting, allowlisting where possible, and TLS 1.2+ minimum).

Important: If an endpoint URL does not comply with the secure domain and SSL requirements, merchant enablement and/or notification delivery can fail.

`querybill`

Collection of Own Network services. Integrators expose these endpoints so the platform can query bills, submit payments, and receive notifications in a consistent way.

Recommendations

Establish a dedicated QA environment to perform thorough testing before production deployment.
Set a minimum timeout of 60 milliseconds for API requests to handle longer processes reliably.
Provide clear and standardized error mapping, detailing error codes, messages, and causes for better troubleshooting.

Authorization

To establish a secure connection with our clients' APIs, we will generate and provide you with an authorization token. This token will allow us to authenticate with the API that our clients build.

Token format:

Authorization: Token {generate_token_value}

Example:

Authorization: Token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9**

Error handling

All errors must return an HTTP status code in the 4xx or 5xx family (i.e. 400 or above). Do not return 2xx codes when the operation has failed.

4xx (client errors): 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, etc.
5xx (server errors): 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, etc.

Error response structure

There is no single mandatory error schema across all endpoints. One of the following patterns is recommended depending on the endpoint type.

Option A — Minimum structure (recommended for all endpoints)

Return a JSON body with at least:

statusCode (number): HTTP status code of the response (must match the HTTP status).
message (string): Human-readable message describing the error.
errorCode (string, optional): Internal error code for integration/support (e.g. auth.invalid, billing.not_found).

Option B — Transactional endpoints (`queryBill`, `submitTransaction`, `rollbackTransaction`)

For transactional operations, use this structure:

message (string): Message describing the error.
reference (string): Reference associated with the operation.
amount (number): Amount (0 in case of error).
code (string): Business status code (e.g. 003, 004).
user_code (string): User code when applicable.
additional_data (array): List of { "label", "value" } objects with additional information.

Authentication errors (401/403)

Some examples only return detail (string) or a combination of message, error, and statusCode. When possible, align these responses with Option A for consistency.

In all cases, the error body must be JSON and must provide enough information for the integrator to identify the failure, correct the data, or decide whether to retry.

This endpoint allows you to query a bill by sending an HTTP POST request to {{customer.domain.com}}/queryBill/.

Benefits

Real-time validation: fresh billing info from the originator.
Standard error handling: predictable codes/messages simplify UX and support.
Lower coupling: each client exposes its endpoint; the bridge resolves routing by agreement.
Observability: traceability via transactionId from query to payment.
Multiple payment values: support for references with multiple payment options via paymentOrder.

Domain and Security Requirements

To integrate with Own Network Collection, all integration endpoint URLs must follow secure domain standards.

1) URL domain structure (all endpoints)

Must be a fully qualified domain URL, for example: https://api.yourdomain.com/path.
http://, IP-only endpoints, localhost domains, or self-signed development URLs are not accepted in production onboarding.
The domain must be publicly resolvable and reachable from Refacil infrastructure.

2) SSL/TLS mandatory requirement

Only HTTPS endpoints are accepted.
The domain must present a valid SSL/TLS certificate issued by a trusted CA.
The certificate must be active (not expired), with a complete certificate chain and valid hostname (CN/SAN match).
Requests can be rejected during merchant setup or runtime if certificate validation fails.

3) General API security restrictions

Enforce token-based authentication exactly as documented (Authorization header).
Validate payload schema, data types, and required fields before processing.
Protect endpoints against replay and duplicate processing using idempotency controls where applicable.
Do not expose secrets, tokens, or sensitive personal data in logs or error messages.
Apply network hardening controls (rate limiting, allowlisting where possible, and TLS 1.2+ minimum).

Important: If an endpoint URL does not comply with the secure domain and SSL requirements, merchant enablement and/or notification delivery can fail.

Request Body Parameters

Field	Type	Description
`codCustomer`	string	The customer code. (Is a constant that identifies us with the supplier)
`reference`	string	ID of the agreement (company) that is making the payment
`date`	string	Transaction date in format `YYYY-MM-DD`
`time`	string	Transaction time in format `HH:mm:ss` (24-hour clock, Bogotá time zone)

Response body parameters

Field	Type	Description
`message`	string	A message related to the query.
`reference`	string	The reference of the bill. Must be unique per transaction; once a payment has been made with a given reference, that reference cannot be reused.
`amount`	number	The amount of the bill.
`code`	string	The code related to the bill.
`user_code`	string	The user code related to the bill.
`additional_data`	array	An array of additional data containing label and value pairs.
`paymentOrder`	object	Payment order object containing multiple payment values. This field is optional and will only be present when the reference has multiple payment values configured. When present, the main `amount` field may be optional as the values from `paymentOrder.items` will be used.

PaymentOrder Structure

When paymentOrder is present in the response, it contains the following structure:

Field	Type	Description
`items`	array	List of available payment values (maximum 10 values). Each item contains: `id` (number, required), `description` (string, required, max 50 characters), and `amount` (number, required).
`selectionMode`	string	Indicates whether a single value ('single') or multiple values ('multiple') can be selected.

Note: When paymentOrder is provided in the response, it indicates that the reference supports multiple payment concepts. The client should use the items array to present payment options to the user, and then send the selected items in the paymentOrderItems field when submitting the transaction via submitTransaction.

Parámetros:

Name	Type	Description
codCustomer	string	Campo del body: codCustomer
reference	string	Campo del body: reference
date	string	Campo del body: date
time	string	Campo del body: time

`submittransaction`

Collection of Own Network services. Integrators expose these endpoints so the platform can query bills, submit payments, and receive notifications in a consistent way.

Recommendations

Establish a dedicated QA environment to perform thorough testing before production deployment.
Set a minimum timeout of 60 milliseconds for API requests to handle longer processes reliably.
Provide clear and standardized error mapping, detailing error codes, messages, and causes for better troubleshooting.

Authorization

To establish a secure connection with our clients' APIs, we will generate and provide you with an authorization token. This token will allow us to authenticate with the API that our clients build.

Token format:

Authorization: Token {generate_token_value}

Example:

Authorization: Token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9**

Error handling

All errors must return an HTTP status code in the 4xx or 5xx family (i.e. 400 or above). Do not return 2xx codes when the operation has failed.

4xx (client errors): 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, etc.
5xx (server errors): 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, etc.

Error response structure

There is no single mandatory error schema across all endpoints. One of the following patterns is recommended depending on the endpoint type.

Option A — Minimum structure (recommended for all endpoints)

Return a JSON body with at least:

statusCode (number): HTTP status code of the response (must match the HTTP status).
message (string): Human-readable message describing the error.
errorCode (string, optional): Internal error code for integration/support (e.g. auth.invalid, billing.not_found).

Option B — Transactional endpoints (`queryBill`, `submitTransaction`, `rollbackTransaction`)

For transactional operations, use this structure:

message (string): Message describing the error.
reference (string): Reference associated with the operation.
amount (number): Amount (0 in case of error).
code (string): Business status code (e.g. 003, 004).
user_code (string): User code when applicable.
additional_data (array): List of { "label", "value" } objects with additional information.

Authentication errors (401/403)

Some examples only return detail (string) or a combination of message, error, and statusCode. When possible, align these responses with Option A for consistency.

In all cases, the error body must be JSON and must provide enough information for the integrator to identify the failure, correct the data, or decide whether to retry.

This API endpoint allows you to submit a transaction via an HTTP POST request to {{customer.domain.com}}/submitTransaction/.

Benefits

Transactional idempotency: transactionId avoids double charges on retries/timeouts.
Eventual consistency: queues + webhook confirmations reduce manual reconciliation.
Operational scalability: async processing absorbs traffic spikes.
Multiple payment items: support for partial payments or multiple concepts within a single transaction via paymentOrderItems.

Domain and Security Requirements

To integrate with Own Network Collection, all integration endpoint URLs must follow secure domain standards.

1) URL domain structure (all endpoints)

Must be a fully qualified domain URL, for example: https://api.yourdomain.com/path.
http://, IP-only endpoints, localhost domains, or self-signed development URLs are not accepted in production onboarding.
The domain must be publicly resolvable and reachable from Refacil infrastructure.

2) SSL/TLS mandatory requirement

Only HTTPS endpoints are accepted.
The domain must present a valid SSL/TLS certificate issued by a trusted CA.
The certificate must be active (not expired), with a complete certificate chain and valid hostname (CN/SAN match).
Requests can be rejected during merchant setup or runtime if certificate validation fails.

3) General API security restrictions

Enforce token-based authentication exactly as documented (Authorization header).
Validate payload schema, data types, and required fields before processing.
Protect endpoints against replay and duplicate processing using idempotency controls where applicable.
Do not expose secrets, tokens, or sensitive personal data in logs or error messages.
Apply network hardening controls (rate limiting, allowlisting where possible, and TLS 1.2+ minimum).

Important: If an endpoint URL does not comply with the secure domain and SSL requirements, merchant enablement and/or notification delivery can fail.

Request Body Parameters

Field	Type	Description
`codCustomer`	string	The customer code. (Is a constant that identifies us with the supplier)
`transactionId`	string	The transaction ID.
`reference`	string	The reference for the transaction. Min. 1 character, max. 50 characters.
`amount`	number	The amount of the transaction.
`paymentOrderItems`	array	Array of payment order items representing individual payment values within a reference with multiple values. Maximum 10 items. Each item must contain: `id` (number, required), `description` (string, required, max 50 characters), and `amount` (number, required).
`date`	string	Transaction date in format `YYYY-MM-DD`
`time`	string	Transaction time in format `HH:mm:ss` (24-hour clock, Bogotá time zone)

PaymentOrderItems Structure

When using paymentOrderItems, each element in the array must have the following structure:

Field	Type	Description
`id`	number	Unique numeric identifier for the payment value
`description`	string	Description of the payment value (maximum 50 characters)
`amount`	number	Numeric value to be paid

Note: When paymentOrderItems is provided, it allows processing multiple payment concepts or partial payments within a single transaction. The main amount field should match the sum of all amount values in paymentOrderItems.

Response Body Parameters

Field	Type	Description
`message`	string	A message regarding the transaction submission.
`reference`	string	The reference for the submitted transaction.
`amount`	number	The amount of the submitted transaction.
`code`	string	A code related to the transaction.
`user_code`	string	User-specific code related to the transaction.
`additional_data`	array	Additional data associated with the transaction, including label and value pairs.
---

Parámetros:

Name	Type	Description
codCustomer	string	Campo del body: codCustomer
transactionId	string	Campo del body: transactionId
reference	string	Campo del body: reference
amount	number	Campo del body: amount
paymentOrderItems	array	Campo del body: paymentOrderItems
date	string	Campo del body: date
time	string	Campo del body: time

`rollbacktransaction`

Collection of Own Network services. Integrators expose these endpoints so the platform can query bills, submit payments, and receive notifications in a consistent way.

Recommendations

Establish a dedicated QA environment to perform thorough testing before production deployment.
Set a minimum timeout of 60 milliseconds for API requests to handle longer processes reliably.
Provide clear and standardized error mapping, detailing error codes, messages, and causes for better troubleshooting.

Authorization

To establish a secure connection with our clients' APIs, we will generate and provide you with an authorization token. This token will allow us to authenticate with the API that our clients build.

Token format:

Authorization: Token {generate_token_value}

Example:

Authorization: Token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9**

Error handling

All errors must return an HTTP status code in the 4xx or 5xx family (i.e. 400 or above). Do not return 2xx codes when the operation has failed.

4xx (client errors): 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, etc.
5xx (server errors): 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, etc.

Error response structure

There is no single mandatory error schema across all endpoints. One of the following patterns is recommended depending on the endpoint type.

Option A — Minimum structure (recommended for all endpoints)

Return a JSON body with at least:

statusCode (number): HTTP status code of the response (must match the HTTP status).
message (string): Human-readable message describing the error.
errorCode (string, optional): Internal error code for integration/support (e.g. auth.invalid, billing.not_found).

Option B — Transactional endpoints (`queryBill`, `submitTransaction`, `rollbackTransaction`)

For transactional operations, use this structure:

message (string): Message describing the error.
reference (string): Reference associated with the operation.
amount (number): Amount (0 in case of error).
code (string): Business status code (e.g. 003, 004).
user_code (string): User code when applicable.
additional_data (array): List of { "label", "value" } objects with additional information.

Authentication errors (401/403)

Some examples only return detail (string) or a combination of message, error, and statusCode. When possible, align these responses with Option A for consistency.

In all cases, the error body must be JSON and must provide enough information for the integrator to identify the failure, correct the data, or decide whether to retry.

This API endpoint allows you to submit a transaction via an HTTP POST request to {{customer.domain.com}}/rollbackTransaction/.

Benefits

Risk control: safe, auditable reversal for external failures/inconsistencies.
Full traceability: reversal events and contingency log.
Business continuity: formal channel for emergencies without invasive manual actions.
Multiple payment items support: allows rollback of transactions with multiple payment concepts via paymentOrderItems.

Domain and Security Requirements

To integrate with Own Network Collection, all integration endpoint URLs must follow secure domain standards.

1) URL domain structure (all endpoints)

Must be a fully qualified domain URL, for example: https://api.yourdomain.com/path.
http://, IP-only endpoints, localhost domains, or self-signed development URLs are not accepted in production onboarding.
The domain must be publicly resolvable and reachable from Refacil infrastructure.

2) SSL/TLS mandatory requirement

Only HTTPS endpoints are accepted.
The domain must present a valid SSL/TLS certificate issued by a trusted CA.
The certificate must be active (not expired), with a complete certificate chain and valid hostname (CN/SAN match).
Requests can be rejected during merchant setup or runtime if certificate validation fails.

3) General API security restrictions

Enforce token-based authentication exactly as documented (Authorization header).
Validate payload schema, data types, and required fields before processing.
Protect endpoints against replay and duplicate processing using idempotency controls where applicable.
Do not expose secrets, tokens, or sensitive personal data in logs or error messages.
Apply network hardening controls (rate limiting, allowlisting where possible, and TLS 1.2+ minimum).

Important: If an endpoint URL does not comply with the secure domain and SSL requirements, merchant enablement and/or notification delivery can fail.

Request Body Parameters

Field	Type	Description
`codCustomer`	string	The customer code. (Is a constant that identifies us with the supplier)
`transactionId`	string	The transaction ID.
`reference`	string	The reference for the transaction.
`amount`	number	The amount of the transaction.
`paymentOrderItems`	array	Array of payment order items representing individual payment values within a reference with multiple values. Maximum 10 items. Each item must contain: `id` (number, required), `description` (string, required, max 50 characters), and `amount` (number, required).
`date`	string	Transaction date in format `YYYY-MM-DD`
`time`	string	Transaction time in format `HH:mm:ss` (24-hour clock, Bogotá time zone)

PaymentOrderItems Structure

When using paymentOrderItems, each element in the array must have the following structure:

Field	Type	Description
`id`	number	Unique numeric identifier for the payment value
`description`	string	Description of the payment value (maximum 50 characters)
`amount`	number	Numeric value to be paid

Note: When paymentOrderItems is provided, it allows rollback of transactions with multiple payment concepts. The main amount field should match the sum of all amount values in paymentOrderItems.

Response Body Parameters

Field	Type	Description
`message`	string	A message indicating the status of the rollback process.
`reference`	string	The reference number of the transaction.
`amount`	number	The amount of the transaction.
`code`	string	A status code for the rollback process.
`user_code`	string	A user-specific code related to the rollback process.
`additional_data`	(array)	An array containing additional information about the rollback, including label and value pairs.
---

Parámetros:

Name	Type	Description
codCustomer	string	Campo del body: codCustomer
transactionId	string	Campo del body: transactionId
reference	string	Campo del body: reference
amount	number	Campo del body: amount
paymentOrderItems	array	Campo del body: paymentOrderItems
date	string	Campo del body: date
time	string	Campo del body: time

`webhook`

Collection of Own Network services. Integrators expose these endpoints so the platform can query bills, submit payments, and receive notifications in a consistent way.

Recommendations

Establish a dedicated QA environment to perform thorough testing before production deployment.
Set a minimum timeout of 60 milliseconds for API requests to handle longer processes reliably.
Provide clear and standardized error mapping, detailing error codes, messages, and causes for better troubleshooting.

Authorization

To establish a secure connection with our clients' APIs, we will generate and provide you with an authorization token. This token will allow us to authenticate with the API that our clients build.

Token format:

Authorization: Token {generate_token_value}

Example:

Authorization: Token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9**

Error handling

All errors must return an HTTP status code in the 4xx or 5xx family (i.e. 400 or above). Do not return 2xx codes when the operation has failed.

4xx (client errors): 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, etc.
5xx (server errors): 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, etc.

Error response structure

There is no single mandatory error schema across all endpoints. One of the following patterns is recommended depending on the endpoint type.

Option A — Minimum structure (recommended for all endpoints)

Return a JSON body with at least:

statusCode (number): HTTP status code of the response (must match the HTTP status).
message (string): Human-readable message describing the error.
errorCode (string, optional): Internal error code for integration/support (e.g. auth.invalid, billing.not_found).

Option B — Transactional endpoints (`queryBill`, `submitTransaction`, `rollbackTransaction`)

For transactional operations, use this structure:

message (string): Message describing the error.
reference (string): Reference associated with the operation.
amount (number): Amount (0 in case of error).
code (string): Business status code (e.g. 003, 004).
user_code (string): User code when applicable.
additional_data (array): List of { "label", "value" } objects with additional information.

Authentication errors (401/403)

Some examples only return detail (string) or a combination of message, error, and statusCode. When possible, align these responses with Option A for consistency.

In all cases, the error body must be JSON and must provide enough information for the integrator to identify the failure, correct the data, or decide whether to retry.

This endpoint allows you to receive transaction notifications processed by the payment system. The merchant must implement this endpoint to receive transaction status updates.

Benefits

Push notifications: eliminates polling, reduces cost and update latency.
Security: signature/auth validation for trusted origin.
Robust delivery: retries, backoff and DLQ (if applicable) ensure reception.
Simple integration: compact contract (status/timestamps/ids), quick to implement.
Multiple payment items: includes payment order items when transactions involve multiple payment concepts.

Domain and Security Requirements

To integrate with Own Network Collection, all integration endpoint URLs must follow secure domain standards.

1) URL domain structure (all endpoints)

Must be a fully qualified domain URL, for example: https://api.yourdomain.com/path.
http://, IP-only endpoints, localhost domains, or self-signed development URLs are not accepted in production onboarding.
The domain must be publicly resolvable and reachable from Refacil infrastructure.

2) SSL/TLS mandatory requirement

Only HTTPS endpoints are accepted.
The domain must present a valid SSL/TLS certificate issued by a trusted CA.
The certificate must be active (not expired), with a complete certificate chain and valid hostname (CN/SAN match).
Requests can be rejected during merchant setup or runtime if certificate validation fails.

3) General API security restrictions

Webhook validation: this endpoint authenticates incoming notifications using the HMAC-SHA1 signature in the sign field, not by JWT or token-based authentication.
Validate payload schema, data types, and required fields before processing.
Protect endpoints against replay and duplicate processing using idempotency controls where applicable.
Do not expose secrets, tokens, or sensitive personal data in logs or error messages.
Apply network hardening controls (rate limiting, allowlisting where possible, and TLS 1.2+ minimum).

Important: If an endpoint URL does not comply with the secure domain and SSL requirements, merchant enablement and/or notification delivery can fail.

Request Body Parameters

Field	Type	Description
realAmount	number	Real transaction amount (without costs)
amount	number	Total transaction amount (including costs)
cost	string	Total transaction cost
referenceId	string	Unique transaction identifier
customerReference	string	Customer reference provided during the transaction
updatedAt	string	Date and time of last update (format: "YYYY-MM-DD HHss")
status	number	Transaction status ID : 1 Pending , 2 Approved ,3 Failed
sign	string	Security signature to validate message integrity
paymentOrderItems	array	Array of payment order items that were processed. This field is optional and will only be present when the transaction included multiple payment concepts. Each item contains: `id` (number, required), `description` (string, required), and `amount` (number, required).

PaymentOrderItems Structure

When paymentOrderItems is present in the webhook payload, it indicates that the transaction processed multiple payment concepts. The structure matches the items sent in the submitTransaction request:

Field	Type	Description
`id`	number	Unique numeric identifier for the payment value
`description`	string	Description of the payment value
`amount`	number	Numeric value that was paid

Note: When paymentOrderItems is present, the amount field represents the total sum of all items. Verify that the sum of paymentOrderItems[].amount equals the total amount.

Response Body Parameters

Field	Type	Description
statusCode	number	HTTP status code of the response
message	string	Message indicating the operation result
date	number	Response timestamp
payload	object	Response payload (optional)

Security Validation

The sign field must be validated to ensure message integrity. The signature is generated by concatenating the following fields:

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

Note: The HASH_KEY will be shared by us during the integration process to ensure secure communication between systems.

Parámetros:

Name	Type	Description
realAmount	number	Campo del body: realAmount
amount	number	Campo del body: amount
cost	string	Campo del body: cost
referenceId	string	Campo del body: referenceId
customerReference	string	Campo del body: customerReference
updatedAt	string	Campo del body: updatedAt
status	number	Campo del body: status
sign	string	Campo del body: sign
paymentOrderItems	array	Campo del body: paymentOrderItems

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