Placetopay Docs

Cobro masivo

El servicio de cobro masivo permite procesar múltiples cobros recurrentes mediante archivos CSV cifrados. El comercio genera un archivo de entrada con las transacciones a ejecutar y recibe un archivo de respuesta con el estado final de cada cobro.

¿Cuándo usar este servicio?

Este mecanismo es recomendado cuando se necesita ejecutar una gran cantidad de cobros de forma recurrente y se desea automatizar el intercambio de información por archivos.

Flujo general del proceso

Antes de iniciar el procesamiento, el cliente debe compartir con Placetopay la información necesaria para ubicar y gestionar los archivos en su servicio SFTP:

Ruta de entrada: directorio donde el cliente depositará los archivos que Placetopay debe descargar y procesar.
Patrón del nombre del archivo: criterio utilizado para identificar los archivos a procesar. Puede definirse mediante un patrón simple, como Visa*, para tomar todos los archivos cuyo nombre inicie con Visa, o mediante una expresión regular compatible con la configuración acordada.
Ruta de salida: directorio donde Placetopay depositará los archivos resultantes una vez finalizado el procesamiento.

El nombre del archivo no está limitado a una convención única. Placetopay procesará los archivos que coincidan con la ruta de entrada y el patrón de búsqueda previamente configurados.

El proceso de integración se ejecuta de la siguiente forma:

Se establece la conexión entre servidores SFTP, mediante VPN o red pública.
Se generan y validan los datos de acceso para la comunicación SFTP.
Se define la periodicidad de procesamiento de archivos.
El cliente genera y comparte su llave pública PGP/RSA a Placetopay.
El cliente recibe la llave pública PGP/RSA de Placetopay.
El cliente genera un archivo CSV con la información necesaria para procesar los cobros.
El archivo se cifra con la llave pública de Placetopay usando PGP.
El cliente debe depositar el archivo en la ruta de entrada de su servicio SFTP, de acuerdo con el patrón del nombre compartido a Placetopay.
Placetopay descarga desde el SFTP del cliente los archivos que coincidan con la configuración definida.
Placetopay descifra el archivo.
Placetopay genera un archivo de resultados.
Placetopay cifra el archivo de resultados con PGP.
Placetopay deposita el archivo resultante en la ruta de salida definida por el cliente dentro de su servicio SFTP.
El cliente descifra la información.
El cliente actualiza su base de datos con los tokens y subtokens recibidos.

Estructura del archivo de cobro

El archivo de entrada debe estar separado por comas, incluir encabezado y respetar los nombres de columna descritos a continuación.

Name
siteId
Type
int
is Required
REQUERIDO
Description
Identificador del sitio proporcionado por Placetopay.
Name
reference
Type
string(32)
is Required
REQUERIDO
Description
Referencia única del cobro.
Name
instrumentType
Type
string(1)
is Required
REQUERIDO
Description
Tipo de instrumento a usar: T para Token o S para Subtoken.
Name
instrument
Type
string(64)
is Required
REQUERIDO
Description
Token o subtoken utilizado para ejecutar el cobro.
Name
currency
Type
string(3)
is Required
REQUERIDO
Description
Moneda conforme a ISO 421: COP, USD o EUR.
Name
amount
Type
decimal(14,2)
is Required
REQUERIDO
Description
Monto definitivo a cobrar.
Name
valueAddedTax
Type
decimal(14,2)
is Required
REQUERIDO
Description
Monto correspondiente al IVA.
Name
exciseDuty
Type
decimal(14,2)
is Required
REQUERIDO
Description
Monto correspondiente al impuesto al consumo.

Ejemplo de archivo de entrada

siteId,reference,instrumentType,instrument,currency,amount,valueAddedTax,exciseDuty
1001,KX00001,T,1860563980451111,COP,98185.71,15676.71,0

Todos los campos son requeridos. Los valores decimales deben separarse con punto (.).

Estructura del archivo de respuesta

El archivo de respuesta contiene el resultado del procesamiento de cada cobro.

Name
siteId
Type
int
is Required
REQUERIDO
Description
Identificador del sitio proporcionado por Placetopay.
Name
reference
Type
string(32)
is Required
REQUERIDO
Description
Referencia del cobro.
Name
status
Type
string(20)
is Required
REQUERIDO
Description
Estado de la transacción: APPROVED, REJECTED o FAILED.
Name
iso
Type
string(2)
is Required
REQUERIDO
Description
Código del motivo de la respuesta en formato ISO 8583 Response Code Version 1987.
Name
base24
Type
string(3)
is Required
REQUERIDO
Description
Código del motivo de respuesta en formato Base24.
Name
currency
Type
string(3)
is Required
REQUERIDO
Description
Moneda en la cual se realizó el cobro: COP, USD o EUR.
Name
amount
Type
decimal(14,2)
is Required
REQUERIDO
Description
Monto definitivo cobrado.
Name
discount
Type
decimal(10,2)
is Required
REQUERIDO
Description
Descuento aplicado en la transacción.
Name
internalReference
Type
string(20)
is Required
REQUERIDO
Description
Código interno de la transacción en Placetopay.
Name
authorization
Type
string(6)
is Required
REQUERIDO
Description
Código de autorización de la transacción.
Name
receipt
Type
string(10)
is Required
REQUERIDO
Description
Código de la transacción en la red.

Ejemplo de archivo de respuesta

siteId,reference,status,iso,base24,currency,amount,discount,internalReference,authorization,receipt
1001,KX00001,APPROVED,00,000,COP,98185.71,1234.29,12345678901234567890,000000,0000000000

Los valores decimales deben separarse con punto (.). Todos los campos son requeridos. El archivo contiene encabezado y los nombres del encabezado corresponden a los definidos en la propiedad name.

Reglas de formato

Regla	Descripción
Separador de columnas	Coma (CSV)
Encabezados	Obligatorios
Campos	Todos son requeridos
Decimales	Deben separarse con punto (`11244.13`)
Longitud de datos	Los tipos de datos proporcionados indican longitudes máximas; los archivos no son de longitud fija

Consideraciones operativas

El servidor donde se realice el cargue y descarga de archivos debe ser accesible mediante llaves RSA para que el proceso pueda ejecutarse automáticamente.
El tiempo de procesamiento, desde la descarga del archivo de entrada hasta la carga del archivo de respuesta, es variable y depende de la cantidad de transacciones, el estado de las redes, entre otros factores.
Se puede crear un cron job en el servidor del comercio para verificar la disponibilidad del archivo de respuesta cada 30 minutos a partir del cargue inicial.

Llave pública PGP de Placetopay

Uso restringido a entornos de pruebas. Esta llave no debe usarse en producción.

Datos de la llave

Fecha de expiración: 2028-08-04

Llave pública