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

Se establece la conexión entre servidores, mediante VPN o red pública.
Se generan y validan los datos de acceso para la comunicación SFTP (PlacetoPay es quien se conecta a los servidores del cliente).
Se define la periodicidad de procesamiento de archivos.
El comercio genera y comparte su llave pública PGP/RSA a PlacetoPay.
El comercio recibe y confía en la llave pública PGP/RSA de PlacetoPay.
El comercio genera el archivo plano CSV.
El archivo se cifra con la llave pública de PlacetoPay.
El archivo se carga en el servidor con la convención:
```
EMPRESAX_YYYYMMDD.csv.asc
```
Al finalizar el procesamiento, se cargará el archivo con la convención:
```
EMPRESAX_YYYYMMDD_RESULT.csv.asc
```
El procedimiento se repite en cada periodo de recurrencia, desde los pasos 6 al 9.

Estructura del archivo de cobro

Estructura del archivo CSV para cobrar

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
REQUIRED
Description
Identificador del sitio proporcionado por PlacetoPay.
Name
reference
Type
string(32)
is Required
REQUIRED
Description
Referencia única del cobro.
Name
instrumentType
Type
string(1)
is Required
REQUIRED
Description
Tipo de instrumento a usar: T para Token o S para Subtoken.
Name
instrument
Type
string(64)
is Required
REQUIRED
Description
Token o subtoken utilizado para ejecutar el cobro.
Name
currency
Type
string(3)
is Required
REQUIRED
Description
Moneda conforme a ISO 421: COP, USD o EUR.
Name
amount
Type
decimal(14,2)
is Required
REQUIRED
Description
Monto definitivo a cobrar.
Name
valueAddedTax
Type
decimal(14,2)
is Required
REQUIRED
Description
Monto correspondiente al IVA.
Name
exciseDuty
Type
decimal(14,2)
is Required
REQUIRED
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

Estructura del archivo CSV resultante

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

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