Apéndice 1 – Órdenes de cobro SEPA
Este apéndice detalla la composición del detalle de órdenes de cobro a ejecutar mediante peticiones al servicio de recepción de órdenes de cobro.
Volviendo a la estructura del mensaje esperado por este servicio, nos centraremos en el bloque JSON remarcado
{
"idCliente": "bb9e34635fb7",
"SEPADetails":{
"msgIdentifier": "123131232",
"presenterID": "ES123130011234567",
"creditorIBAN": "ES2401821234001234987645",
"collectionDate": "2020-10-17",
"currency": 978,
"submittedOperations": 125,
"submittedAmount": 1345.25,
"signature": "ABC123EEFB2AED6511F1A"
},
"requestDetails":
{
"fileUrl": "https://www.kineox.com/files/sepa/1E2A45FDD4321CBAF",
"typeXML": false,
"signature": "1E2A45FDD4321CBAF"
},
"signature": "AFA3BCADFF5427DAC"
}
Estructura del elemento requestDetails
Este elemento del mensaje recoge el detalle de las órdenes presentadas. La información esperada en el mismo es la siguiente:
| Campo/Bloque | Tipo de dato | Requerido | Descripción |
|---|---|---|---|
| fileURL | Alfanumérico | No | URL desde la que obtener el fichero de detalles |
| paymentRequests | List «PeticiónSepa» | No | Lista de solicitudes de cobro |
| typeXML | Verdadero/Falso | No | Indica si el formato del fichero es xml |
| signature | Alfanumérico | Si | Firma del mensaje |
Fichero de descarga(fileURL)
Gestoría Virtual buscará un fichero con codificación UFT/8 en la URL indicada en este campo (fileURL). El nombre del fichero deberá coincidir con el contenido del campo signature.
El fichero podrá contener las órdenes en formato JSON y, contendrá un único elemento, paymentRequests que será una lista de elementos PeticionSEPA con la misma estructura que los datos que puedan comunicarse online:
{
"paymentRequests":
[
{payment request 1},
{payment request 2},
...
{payment request n}
]
)
Si se opta por la opción XML, se deberá indicar (true) en el parámetro TypeXML y añadir la ruta del fichero. Este fichero contendrá las órdenes en formato ISO 20022 para emisión de Adeudos Directos SEPA.
Independientemente de si se opta por un envío mediante fichero separado (ejemplo anterior) o si se opta por un envío embebido en la petición (ideal para peticiones de un nº reducido de elementos), la estructura de los datos a intercambiar es exactamente la misma.
paymentRequest
Lista de órdenes de cobro, con estructura detallada más adelante.
signature
Esta firma se generará mediante la aplicación de una función SHA-256 a la concatenación de todas las firmas de todos los elementos peticionSEPA contenidos en el campo paymentRequests. El resultado de esta petición será convertido a una cadena Hexadecimal y representado en mayúsculas.
Estructura del elemento peticionSEPA
Este elemento contiene la información necesaria para emitir una orden de pago mediante SEPA.
Agrupamos la información del mismo en torno a tres elementos:
| Campo/Bloque | Tipo de dato | Obligatorio | Descripción |
|---|---|---|---|
| SEPADetails | DetallesSEPA | Si | Información para generar el adeudo |
| paymentDetails | detallesPago | Si | Lista de solicitudes de cobro |
| signature | Alfanumérico | Si | Firma del mensaje |
SEPADetails
Elemento que contiene la información adicional SEPA necesaria para la emisión del adeudo
| Campo/bloque | Tipo de dato | Requerido | Descripción |
|---|---|---|---|
| mandate | Alfanumérico | Si | Identificación del mandato |
| mandateIssueDate | Alfanumérico | Si | Fecha de emisión del mandato |
| OriginalIBANAccount | Alfanumérico | No | Cuenta para la que se generó inicialmente el mandato. Si coincide con la cuenta de cargo, no informar |
| IBAN | Alfanumérico | Si | Cuenta IBAN sobre la que ejecutar el adeudo |
| purpose | Alfanumérico | No | Opcional. Según codificación SEPA. Si no se especifica, se utilizará el valor OTHR |
| seqType | Alfanumérico | No | Opcional. Según codificación SEPA. Si no se especifica, se utilizará el valor RCUR |
| concept | Alfanumérico | Si | Concepto a incluir en el adeudo |
| schema | Alfanumérico | No | Esquema SEPA a utilizar. Valores válidos: – CORE (Predeterminado) – B2B |
Detalles del pago a ejecutar. Esta información se combinará con la incluida en los detalles SEPA para generar el adeudo. Además, será utilizada para gestionar el recobro en caso que el adeudo sea rechazado por cualquier motivo
paymentDetails
| Campo | Tipo de dato | Requerido | Descripción |
|---|---|---|---|
| cifDeudor | Alfanumérico | Si | Documento de identidad del deudor |
| nombreDeudor | Alfanumérico | Si | Nombre del deudor |
| razonSocial | Alfanumérico | No | Razón social del deudor |
| telefono | Alfanumérico | No | Teléfono del deudor donde se envía SMS |
| Alfanumérico | No | Email del deudor donde se envía correo | |
| numFactura | Alfanumérico | Si | Número de la factura |
| importe | Decimal | Si | Importe total a cobrar en EUROS |
| fechaVencimiento | Alfanumérico | Si | Fecha vencimiento de la factura y fecha de cobro del adeudo (YYYY-MM-DD) |
| descripcioonPago | Alfanumérico | Si* | Texto que acompaña a la URL de pago en el SMS o Email que recibe el deudor con la descripción de esa factura (max 60 caracteres) |
| numeroVencimiento | Entero | Si* | Vencimiento reclamado de la factura |
| totalVencimiento | Entero | Si* | Número total de vencimientos |
| enviarComunicacion | Verdadero/Falso | Si | True si se desea enviar comunicación |
| tipoComunicacion | Entero | No | Tipo de comunicación(Ver tabla) |
| urlCallBack | Alfanumérico | No | URL de callback para las notificaciones de pago |
| documentList | List «dataDocument» | No | Objeto dataDocument( ver info) |
| importeMinimo | Decimal | No | Importe mínimo del pago parcial. Si no se admiten pagos parciales, no informar el campo |
| importeMaximo | Decimal | No | Importe máximo del pago parcial. Si no se admiten pagos parciales, no informar el campo |
| lenguaje | Alfanumérico | No | Lenguaje para la página de pago (ver tabla de posibles lenguajes) |
*Los campos marcados como requeridos con asterisco, sólo se validarán si enviarComunicacion se envía como true.
Las tablas auxiliares para los campos indicados están descritas en el apartado de las funcionalidades de la factura de esta misma web.
Signature
Cada una de las órdenes de pago incorporará un campo que se usará para validar la autenticidad e integridad del mismo.
Este campo se calculará como el resultado de una función SHA-256 sobre la concatenación de los siguientes campos de la petición:
detallesSEPA.mandate
detallesSEPA.mandateIssueDate
detallesSEPA.IBAN
detallesSEPA.concept
detallesSEPA.schema
paymentDetails.cifDeudor
paymentDetails.nombreDeudor
paymentDetails.numFactura
paymentDetails.importe
paymentDetails.fechaVencimiento
paymentDetails.descripcionPago
ClavePrivada
El resultado de esta función hash será convertido a una cadena Hexadecimal y representado en
mayúsculas.
Composición de Adeudo
A partir de la información recibida, Gestoría Virtual generará órdenes de adeudo para cada una de las solicitudes recibidas. Esta información se trasladará, para cada adeudo, de la siguiente manera:
| Campo petición | Campo petición SEPA XML |
|---|---|
| paymentDetails.importe | DrctDbtTxInf.InstdAmt |
| detallesSEPA.mandate | DrctDbtTxInf.DrctDbtTx.MndtRltdInf.MndtId |
| detallesSEPA.mandateIssueDate | DrctDbtTxInf.DrctDbtTx.MndtRltdInf.DtOfSgntr |
| paymentDetails.nombreDeudor | DrctDbtTxInf.Dbtr.Nm |
| pamyentDetails.cifDeudor | DrctDbtTxInf.Dbtr.Id.PrvtId.Othr.Id |
| detallesSEPA.IBAN | DrctDbtTxInf.DbtrAcct.Id.IBAN |
| detallesSEPA.purpose | DrctDbtTxInf.Purp.Cd |
| detallesSEPA.seqType | PmtInf.PmtTpInf.SeqTp |
| detallesSEPA.concept | DrctDbtTxInf.RmtInf.Ustrd |
Ejemplo de petición
{
"idCliente": "bb9e34635fb7",
"SEPADetails": {
"msgIdentifier": "123131232",
"presenterID": "ES123130011234567",
"creditorIBAN": "ES2401821234001234987645",
"collectionDate": "2020-09-01",
"currency": 978,
"submittedOperations": 2,
"submittedAmount": 1345.25,
"signature": "ABC123EEFB2AED6511F1A"
},
"requestDetails": {
"paymentRequests": [
{
"SEPADetails": {
"mandate": "A1233456S",
"mandateIssueDate": "2017-10-21",
"IBAN": "ES24018212345432211234567890",
"concept": "Factura septiembre 2020",
"seqType": "RCUR",
"schema": "CORE"
},
"paymentDetails": {
"cifDeudor": "12345678Z",
"nombreDeudor": "JUAN GARCIA GARCIA",
"numFactura": "A2433212313",
"fechaVencimiento": "2020-09-01",
"descripcionPago": "Impago recibo septiembre 2020",
"importe": 1000,
"numeroVencimiento": 1,
"totalVencimiento": 1,
"enviarComunicacion": "True"
},
"signature": "ACABD44412EEFA955D2FFA123"
},
{
"SEPADetails": {
"mandate": "CPAAA41231",
"mandateIssueDate": "2017-10-21",
"IBAN": "ES24018222221432211234567890",
"concept": "Factura septiembre 2020",
"seqType": "RCUR”,
"schema": "B2B"
},
"paymentDetails": {
"cifDeudor": "87654321Z",
"nombreDeudor": "ANA GONZÁLEZ GONZÁLEZ",
"numFactura": "kQ321243/2020",
"fechaVencimiento": "2020-09-01",
"descripcionPago": "recibo septiembre 2020",
"importe": 345.25,
"numeroVencimiento": 1,
"totalVencimiento": 1,
"enviarComunicacion": "True"
},
"signature": "BAD4D44412EEFA955D2FFA123"
}
],
"signature": "1E2A45FDD4321CBAF"
},
"signature": "AFA3BCADFF5427DAC"
}