Recaudar con Alias de pago (CVU)

Con los Alias de pago generás CVUs recaudadores propios para recibir transferencias bancarias. El CVU (Clave Virtual Uniforme) es el equivalente al CBU para las cuentas virtuales. Cada transferencia llega identificada, así sabés quién te pagó sin intervención manual.

En esta guía vas a ver el flujo completo: crear un alias por cliente, recibir los cobros, definir qué transferencias aceptás, enterarte de cada novedad, seguir las liquidaciones y descargar reportes para conciliar.

Qué es un Alias de pago

Un Alias de pago es un CVU recaudador asociado a tu comercio, con un alias bancario legible (por ejemplo cliente.00123.p360). Cualquier persona le transfiere desde un banco o una billetera virtual, como a cualquier otra cuenta.

Te recomendamos crear un alias por cliente (o por contrato, unidad, sucursal, etc.). Cada CVU es único, así que cada transferencia que entra ya viene identificada con el alias que la recibió y, a través de él, con tu external_reference. Así identificás cada pago sin pedirle comprobantes al pagador ni cruzar montos a mano.

Así funciona:

Creás un alias por cliente con tu propia external_reference.
Le compartís al cliente el CVU o el alias.
El cliente transfiere cuando quiere, las veces que quiera.
Cada transferencia aceptada se registra como un cobro vinculado a ese alias.
Los cobros se liquidan periódicamente a tu comercio: PAGOS360 los agrupa en una liquidación para pagártelos.

Antes de empezar

Entornos

Entorno	URL base
Pruebas (QA)	`https://api-pct.qa.pagos360.com/v1`
Producción	`https://api-pct.pagos360.com/v1`

Autenticación

Todas las peticiones llevan tu API Key en el header X-API-Key:

curl 'https://api-pct.qa.pagos360.com/v1/collector' \ -H 'X-API-Key: <API Key>'

Importante

La API de Alias de pago usa su propia API Key y un header distinto al de la API de PAGOS360 (Authorization: Bearer ...). Cada entorno tiene sus propias credenciales. Guardá la API Key en tu backend y mantenela fuera del código client-side y de los repositorios.

Si la API Key falta, es inválida o está inactiva, la API responde 401.

Flujo completo

sequenceDiagram autonumber participant S as Tu sistema participant A as API Alias de pago participant C as Tu cliente participant B as Banco / billetera del cliente S->>A: POST /collector (external_reference, name) A-->>S: 201 id, cvu, alias S->>C: Compartís CVU / alias C->>B: Transfiere al CVU B->>A: Llega la transferencia A->>A: Evalúa reglas de validación activas alt Cumple todas las reglas A->>A: Registra el cobro (RECEIVED) A-->>S: Webhook COLLECTION_RECEIVED else No cumple alguna regla A->>B: Devuelve la transferencia al origen A-->>S: Webhook COLLECTION_REJECTED end A->>A: Liquidación periódica de cobros pendientes A-->>S: Webhook SETTLEMENT_COMPLETED / SETTLEMENT_FAILED S->>A: GET /collection?settlement_id=... / POST /report

1. Crear un alias por cliente

POST /collector

Campo	Tipo	Requerido	Descripción
`external_reference`	string	Sí	Tu identificador del cliente. De 1 a 100 caracteres: letras, números, `_`, `-` y `.`. No puede repetirse entre tus alias activos.
`name`	string	Sí	Nombre del alias (por ejemplo, el nombre del cliente). De 1 a 255 caracteres: letras, números y espacios.
`id_number`	string	No	CUIT/CUIL/DNI asociado, solo dígitos, de 1 a 11 caracteres.
`alias`	string	No	Alias bancario deseado. De 6 a 20 caracteres: letras, números, `.` y `-`. Se guarda en minúsculas. Si no lo enviás, se genera automáticamente.

curl -X POST 'https://api-pct.qa.pagos360.com/v1/collector' \ -H 'X-API-Key: <API Key>' \ -H 'Content-Type: application/json' \ -d '{ "external_reference": "cliente-00123", "name": "Juan Perez", "id_number": "20111111112" }'

Respuesta 201 Created (recortada):

{ "id": 42, "id_number": "20111111112", "external_reference": "cliente-00123", "name": "Juan Perez", "alias": "micomercio.cliente-00123", "cvu": "0000000000000000000042", "state": "ACTIVE", "merchant": { "id": 1, "name": "Mi Comercio SA" } }

Guardá en tu sistema el id, el cvu y el alias junto a tu cliente.

Tip

Usá como external_reference el identificador que ya usás en tu sistema (ID de cliente, número de contrato). Es la clave que después te permite filtrar cobros y generar reportes por cliente.

Si enviás un alias que ya está en uso, la API responde 400 con el mensaje El alias '...' ya está en uso. Por favor, elija uno diferente.. Si la external_reference ya existe en otro alias activo, responde 409.

Gestionar tus alias

Acción	Método y ruta	Referencia
Listar alias	`GET /collector`	Listar alias
Consultar un alias	`GET /collector/{id}`	Consultar alias
Modificar nombre, `external_reference`, `id_number` o `state`	`PUT /collector/{id}`	Modificar alias
Cambiar el alias bancario	`PUT /collector/{id}/alias`	Modificar alias de un alias
Eliminar	`DELETE /collector/{id}`	Eliminar alias

Filtros de GET /collector: name, external_reference, id_number, alias, cvu, created_date_from, created_date_to.

El state de un alias puede ser ACTIVE o INACTIVE.
El alias bancario se puede cambiar una vez cada 24 horas y el nuevo valor tiene que ser distinto del actual.
DELETE responde 204 y da de baja el CVU. Después de eliminarlo podés crear otro alias con la misma external_reference.

2. Compartir el CVU o el alias con tu cliente

Mostrale a tu cliente el cvu (22 dígitos) o el alias en tu app, factura, email o portal de autogestión. Tu cliente transfiere desde cualquier banco o billetera virtual, el monto que quiera y cuando quiera. Si necesitás fijar un monto o una fecha límite, usá las reglas de validación (paso 4).

3. Recibir cobros

Cada transferencia aceptada genera un cobro (collection). Consultalos con:

GET /collection: listado paginado con filtros (referencia).
GET /collection/{id}: detalle completo de un cobro (referencia).

Filtros de GET /collection:

Parámetro	Descripción
`collector_external_reference`	Cobros de los alias con esa `external_reference`.
`collector_cvu` / `collector_alias` / `collector_name`	Cobros de un alias por CVU (exacto), alias (búsqueda parcial) o nombre.
`sender_name`	Nombre del titular de la cuenta origen.
`coelsa_id`	Identificador de la transferencia en COELSA.
`amount_from` / `amount_to`	Rango de montos.
`settled`	`true` para cobros liquidados, `false` para pendientes.
`settlement_id`	Cobros incluidos en una liquidación.
`created_date_from` / `created_date_to`	Fecha de registro del cobro.
`occurrence_date_from` / `occurrence_date_to`	Fecha de ocurrencia de la transferencia.
`settlement_date_from` / `settlement_date_to`	Fecha de liquidación.
`tags`	IDs de etiquetas separados por coma (máximo 5).

Los filtros de fecha usan ISO-8601 con zona horaria, por ejemplo 2026-09-01T00:00:00-03:00 o 2026-09-01T03:00:00Z.

curl -G 'https://api-pct.qa.pagos360.com/v1/collection' \ -H 'X-API-Key: <API Key>' \ --data-urlencode 'collector_external_reference=cliente-00123' \ --data-urlencode 'created_date_from=2026-09-01T00:00:00-03:00' \ --data-urlencode 'sort=createdDate,desc'

Respuesta 200 (recortada):

{ "data": [ { "id": 1001, "amount": 15000.50, "status": "RECEIVED", "coelsa_id": "ABC123XYZ", "collector": { "id": 42, "name": "Juan Perez", "external_reference": "cliente-00123", "alias": "micomercio.cliente-00123", "cvu": "0000000000000000000042" }, "origin": { "id_number": "20111111112", "cvu": "0000000000000000000099", "name": "Juan Perez", "bank": "Banco Ejemplo" }, "settled_date": null, "tags": [], "occurrence_date": "2026-09-02T13:05:10", "created_date": "2026-09-02T13:05:12.123456" } ], "count_per_page": 1, "size": 20, "total_count": 1, "total_pages": 1 }

El estado de un cobro es RECEIVED (recibido, pendiente de liquidar) o SETTLED (liquidado). En el listado el campo se llama status, y en el detalle (GET /collection/{id}), state.

Tip

Para identificar al pagador, usá el alias que recibió la transferencia (collector.external_reference), no el nombre del titular de origen: un mismo cliente puede transferir desde cuentas de terceros.

4. Reglas de validación (opcional)

Con las reglas de validación aceptás solo las transferencias que cumplen las condiciones que definís. Las reglas se configuran por alias. Cuando llega una transferencia, se evalúan todas las reglas activas de ese alias. Si alguna no se cumple, la transferencia se rechaza: no se registra como cobro y el dinero vuelve a la cuenta de origen.

Tipo (`rule_type`)	Qué valida	Valores
`ALLOWED_CUIL_CUIT`	Que el CUIL/CUIT del titular de la cuenta origen esté en la lista.	Uno o más CUIL/CUIT de 11 dígitos, sin repetir.
`MIN_AMOUNT`	Monto mayor o igual al valor.	Un único monto mayor a 0.
`MAX_AMOUNT`	Monto menor o igual al valor.	Un único monto mayor a 0.
`EXACT_AMOUNT`	Monto exactamente igual al valor.	Un único monto mayor a 0.
`MAX_DATE`	Transferencia realizada hasta esa fecha y hora, inclusive.	Una fecha ISO-8601 con zona horaria y posterior al momento actual, por ejemplo `2026-12-31T23:59:59-03:00`.

Al armar tus reglas, tené en cuenta estas condiciones:

Solo puede haber una regla de cada tipo por alias, y el name de la regla no puede repetirse dentro del mismo alias.
EXACT_AMOUNT no se puede combinar con MIN_AMOUNT ni con MAX_AMOUNT.
Si combinás MIN_AMOUNT y MAX_AMOUNT, el mínimo tiene que ser menor que el máximo.
Solo ALLOWED_CUIL_CUIT admite agregar valores (POST /validation-rule/{id}/value). En las demás, modificás el valor existente con PUT /validation-rule/{id}/value/{id_value}.
Una regla siempre tiene que tener al menos un valor.
Los estados de una regla son ACTIVE e INACTIVE. Solo se evalúan las reglas ACTIVE.

Importante

Antes de crear o activar una regla, configurá y activá el webhook COLLECTION_REJECTED (ver el paso 5). Sin ese webhook, la API responde 400. Por el mismo motivo, ese webhook tiene que seguir activo mientras tengas reglas activas: no podés inactivarlo ni eliminarlo.

Ejemplo: aceptar solo transferencias de $15.000 en adelante para un alias.

curl -X POST 'https://api-pct.qa.pagos360.com/v1/validation-rule' \ -H 'X-API-Key: <API Key>' \ -H 'Content-Type: application/json' \ -d '{ "collector_id": 42, "name": "Monto minimo cuota", "rule_type": "MIN_AMOUNT", "values": ["15000.00"] }'

Respuesta 201 (recortada):

{ "id": 7, "collector_id": 42, "name": "Monto minimo cuota", "rule_type": "MIN_AMOUNT", "state": "ACTIVE", "values": [ { "id": 11, "value": "15000.00" } ] }

Más detalle en Reglas de validación, Nueva regla, Nuevo valor y Listar reglas. También podés consultar los tipos y estados disponibles con GET /validation-rule/options/rule-types y GET /validation-rule/options/states.

5. Enterarte de las novedades (webhooks)

Con los webhooks, PAGOS360 te envía una notificación HTTP POST a tu servidor cuando ocurre alguno de estos eventos:

Evento	Cuándo se envía
`COLLECTION_RECEIVED`	Se registró un cobro nuevo en uno de tus alias.
`COLLECTION_REJECTED`	Una transferencia no cumplió las reglas de validación y se devuelve.
`SETTLEMENT_COMPLETED`	Una liquidación se completó.
`SETTLEMENT_FAILED`	Una liquidación falló.

Para configurarlos:

Entrá al portal web de Alias de pago con un usuario de tu comercio. Los webhooks se gestionan desde ahí: la API Key de integración no tiene permisos para hacerlo.
Hay una configuración por tipo de evento. Para cambiar la URL, modificá la existente.
La URL de destino tiene que usar HTTPS y tener hasta 255 caracteres.
Podés definir headers personalizados (un JSON de hasta 255 caracteres), por ejemplo un token propio para validar que la notificación viene de PAGOS360.

El cuerpo de cada evento tiene esta estructura:

{ "entity_name": "collection", "type": "COLLECTION_RECEIVED", "entity_id": 1001, "timestamp": "2026-09-02T13:05:12.456", "payload": { "id": 1001, "collector_id": 42, "amount": 15000.50, "sender_name": "Juan Perez" } }

Contenido de payload según el evento:

Evento	`entity_name`	Campos de `payload`
`COLLECTION_RECEIVED`	`collection`	`id`, `collector_id`, `amount`, `sender_name`
`COLLECTION_REJECTED`	`collection_attempt`	`amount`, `sender_id`, `sender_name`, `collector_id`, `rejection_reason`, `rules_failed` (con `name`, `rule_type`, `values`)
`SETTLEMENT_COMPLETED` / `SETTLEMENT_FAILED`	`settlement`	`id`, `state`, `total_amount`, `settlement_date`, `external_reference`

Tip

Usá el webhook como aviso y confirmá con la API. Antes de dar por pagado algo en tu sistema, consultá el cobro con GET /collection/{entity_id}. Así también cubrís el caso de que una notificación no te llegue.

6. Liquidaciones

Periódicamente, PAGOS360 agrupa los cobros pendientes de tu comercio (RECEIVED) y los liquida. Cuando la liquidación termina, los cobros incluidos pasan a SETTLED y tienen settled_date.

GET /settlement: listado paginado de liquidaciones (referencia). Filtros: state (STARTED, COMPLETED, FAILED), settlement_date_from y settlement_date_to.
GET /collection?settlement_id={id}: los cobros que forman parte de una liquidación.

curl -G 'https://api-pct.qa.pagos360.com/v1/settlement' \ -H 'X-API-Key: <API Key>' \ --data-urlencode 'state=COMPLETED' \ --data-urlencode 'settlement_date_from=2026-09-01T00:00:00-03:00'

{ "data": [ { "id": 305, "settlement_date": "2026-09-03T05:00:00", "total_amount": 184500.50, "state": "COMPLETED", "created_date": "2026-09-03T05:00:00.000000", "last_modified_date": "2026-09-03T05:00:02.000000" } ], "count_per_page": 1, "size": 20, "total_count": 1, "total_pages": 1 }

7. Reportes (COLLECTIONS y SETTLEMENT)

Los reportes se generan de forma asincrónica (en segundo plano, después de que los pedís) y se descargan en CSV o XLSX. Para saber cuándo un reporte está listo, consultá su estado: los reportes no envían webhooks.

Tipo	Para qué sirve	Campos del pedido
`COLLECTIONS`	Detalle de los cobros de un período, de todos tus alias o de uno solo.	`date_from` y `date_to` (obligatorios, ISO-8601 con zona horaria, rango máximo de un año). `collector_external_reference` es opcional. No se envía `settlement_id`.
`SETTLEMENT`	Detalle de una liquidación.	`settlement_id` (obligatorio, la liquidación tiene que estar `COMPLETED`). No se envían fechas ni `collector_external_reference`.

Paso 1: pedir el reporte

curl -X POST 'https://api-pct.qa.pagos360.com/v1/report' \ -H 'X-API-Key: <API Key>' \ -H 'Content-Type: application/json' \ -d '{ "report_type": "COLLECTIONS", "date_from": "2026-09-01T00:00:00-03:00", "date_to": "2026-09-30T23:59:59-03:00" }'

{ "id": 88, "report_type": "COLLECTIONS", "state": "IN_PROGRESS", "date_from": "2026-09-01T03:00:00", "date_to": "2026-10-01T02:59:59", "collector": null, "settlement": null }

Si no hay cobros en el período (o para el alias indicado), la API responde 404.

Paso 2: esperar a que esté listo

GET /report devuelve tus reportes con su state: IN_PROGRESS, READY o FAILED. Filtros: report_type, state, file_name, created_date_from y created_date_to.

curl -G 'https://api-pct.qa.pagos360.com/v1/report' \ -H 'X-API-Key: <API Key>' \ --data-urlencode 'state=READY' \ --data-urlencode 'sort=createdDate,desc'

Cuando el reporte está READY, trae además file_name, total_amount y quantity.

Paso 3: descargar el archivo

GET /report/file?report_id={id}&format={CSV|XLSX} (los dos parámetros son obligatorios).

curl -G 'https://api-pct.qa.pagos360.com/v1/report/file' \ -H 'X-API-Key: <API Key>' \ --data-urlencode 'report_id=88' \ --data-urlencode 'format=CSV' \ -o reporte.csv

Si el reporte todavía no está READY, la API responde 400 con el mensaje El reporte aún no está disponible.

Referencias: Nuevo reporte, Listar reportes, Descargar archivo.

Paginación

Los listados (GET /collector, /collection, /settlement, /report, /validation-rule) aceptan:

Parámetro	Descripción
`page`	Número de página, empezando en 0.
`size`	Elementos por página (por defecto, 20).
`sort`	Campo y dirección, por ejemplo `createdDate,desc`.

Y responden con este envoltorio:

{ "data": [], "count_per_page": 0, "size": 20, "total_count": 0, "total_pages": 0 }

count_per_page es la cantidad de elementos de la página actual y total_count, el total de resultados.

Errores

Todos los errores tienen el mismo formato:

{ "timestamp": "2026-09-02T13:05:12.123456", "status": 422, "error": "Unprocessable Entity", "message": "La referencia externa es obligatoria y no puede estar vacía", "path": "/v1/collector", "errors": [ { "property": "externalReference", "message": "La referencia externa es obligatoria y no puede estar vacía" } ] }

message repite el primer error. errors detalla cada campo y solo viene en los errores de validación (en el resto puede venir en null).

Código	Cuándo
`400`	Regla de negocio no cumplida (por ejemplo, alias ya en uso, cambio de alias antes de 24 h, reporte no disponible) o parámetro con tipo inválido.
`401`	API Key ausente, inválida o inactiva.
`403`	La API Key no tiene permiso para esa operación.
`404`	El recurso no existe o no pertenece a tu comercio.
`409`	Recurso duplicado (por ejemplo, `external_reference` repetida).
`422`	Error de validación del body o de los parámetros (formato, longitud, campos obligatorios, JSON mal formado).
`500`	Error interno. Reintentá más tarde.

Tip

Estas operaciones se hacen desde el portal, con un usuario de tu comercio. Existen en la API, pero con la API Key devuelven 403: gestionar webhooks, consultar el monto disponible a liquidar (GET /settlement/available-amount) y eliminar reportes.

Checklist de integración

Crear un alias por cliente y guardar id, cvu y alias junto a tu external_reference.
Mostrar el CVU o el alias al cliente.
Configurar los webhooks COLLECTION_RECEIVED y SETTLEMENT_COMPLETED (y COLLECTION_REJECTED si vas a usar reglas).
Confirmar cada cobro con GET /collection/{id} antes de imputarlo.
Conciliar a diario con GET /collection?settled=false y las liquidaciones del día.
Probar todo en QA antes de pasar a producción.

Última actualización el