MARCO DE REFERENCIA PARA LA PLATAFORMA DE INTEROPERABILIDAD VOLUMEN IV: MANUAL DEL DESARROLLADOR SERVICIO DE PASARELA DE PAGOS TELEMÁTICOS

Transcripción

1 Interoperabilidad de los servicios telemáticos de la Administración Pública de la CAC Página 1 de 45 MARCO DE REFERENCIA PARA LA PLATAFORMA DE INTEROPERABILIDAD VOLUMEN IV: MANUAL DEL DESARROLLADOR SERVICIO DE PASARELA DE PAGOS TELEMÁTICOS Historial de revisiones en la siguiente página Documento : Ubicación en eroom: PLA-DOC-FIN Vol IV. Telematicos Preparado por Revisado por Aprobado por D. Gral. de Telecomunicaciones y Nuevas Tecnologías D. Gral. de Telecomunicaciones y Nuevas Tecnologías D. Gral. de Telecomunicaciones y Nuevas Tecnologías Fecha: 24/02/2015 Fecha: 24/02/2015 Fecha: 24/02/2015

2 Página 2 de 45 Rev. Fecha Descripción 0 29/07/14 Telemáticos - Manual del Desarrollador 1 28/10/14 Se cambia el versionado a tipo OSGI. 2 10/11/14 Se corrigen erratas en los códigos de respuesta y se agregan los códigos de respuesta del SPT en objeto PeticionResponse 3 24/02/15 Modificar la consulta de los Pagos firmado de modo que consuma el método BusquedaSPT a sugerencia de Red.es

3 Página 3 de 45 ÍNDICE 1 DESCRIPCIÓN GENERAL Cambios en el documento con respecto a versiones anteriores VERSIÓN DEL SERVICIO CASOS DE USO CU-PPA-04: Verificar NRC Interfaz Entrada del servicio Salida del servicio Excepciones CU-PPA-05: Obtener Versión del Servicio Interfaz Entrada del servicio Salida del servicio CU-PPA-06: Realizar Pago Firmado Interfaz Entrada del servicio...16 Pagos bajo Norma Salida del servicio Excepciones CU-PPA-07: Realizar Consulta Firmada CU-PPA-08: Realizar una BusquedaSPT: Interfaz: Entrada del servicio: Salida del servicio: Excepciones: EXCEPCIONES InvalidParameterValueException MalFormedXmlDatosException ExcepcionPasarelaFirmaInvalida ExcepcionPasarelaErrorFirma INFORMACIÓN ADICIONAL DEL SERVICIO Códigos de respuesta del Servicio de Pago Telemático Códigos de retorno de la entidades financieras...40

4 Página 4 de 45 1 DESCRIPCIÓN GENERAL La Pasarela de Pagos de PLATINO es una infraestructura común que permite a la Administración incorporar el pago electrónico en sus tramitaciones. Como tal infraestructura básica, el objetivo principal es abstraer a procedimientos y aplicaciones de tramitación de la complejidad del pago electrónico. Para lograr este objetivo la pasarela se basa en: Estandarizar un formato de intercambio único con todas las Entidades Financieras. Estandarizar un interfaz programático único con las aplicaciones que deseen incorporar pago. Estandarizar una operativa de pago, independientemente de la naturaleza del pago, la tramitación o la Administración concreta. No interferir en los acuerdos entre Entidades Financieras y Administraciones. Estos planteamientos proporcionan una serie de ventajas que se enumeran a continuación: Para las Administraciones una infraestructura única permite: Independizar a las aplicaciones de las de las complejidades técnicas del pago electrónico. La incorporación de una nueva Entidad Financiera es transparente. Cualquier nueva funcionalidad está disponible para todas las Administraciones. Para las Entidades Financieras, hay una Pasarela única, válida para todas las Administraciones en lugar de una por cada una de ellas con los ahorros de desarrollo y mantenimiento que esto conlleva. El establecimiento de un interfaz de usuario único en los procesos de pago con la Administración da confianza a los ciudadanos/as en el pago Electrónico. Cualquier transacción económica que se realice con esta plataforma de pago será notificada a la Dirección General de Tributos, mediante mensajes. Este servicio se apoya en una aplicación desarrollada por la empresa Red.es denominada "Plataforma de Pagos", de forma que actuará como fachada de las funcionalidades que proporciona.

5 Página 5 de Cambios en el documento con respecto a versiones anteriores Cambios en la versión: Modificar la consulta de Pagos firmada de modo que consuma el método BusquedaSPT a sugerencia de Red.es, ya que al llamar a la consulta de Pagos firmada se caían sus servidores. Además se realiza un evolutivo en la fachada para cuando no exista el pago consultado que se devuelva en el campo código de retorno y código de respuesta el valor 71 ( No existe cargo con los datos consultados ), con anterioridad el programa abortaba. Cambios en la versión: Se corrigen errores detectados en el manual con los códigos de retorno. Además se realiza un evolutivo en la fachada para que se retorne en el campo código de respuesta del objeto PeticionResponse aquellos los valores devueltos por el propio Servicio de Pago Telemático de red.es. Mientras que los valores devueltos por las Entidades Financieras serán retornados en el campo código de retorno del mismo objeto PeticionResponse. Quedando de la siguente manera: Código de Respuesta => Códigos del Servicio de Pago Telemático (SPT) de red.es Código de Retorno => Códigos de las Entidades Financieras. Cambios en la versión: Se aplica un nuevo versionado tipo OSGI a este servicio con el objetivo de eliminar los bloqueos entre servicios. El versionado tipo OSGI tiene la siguiente forma: X.Y.Z.AAAMMDD. La explicación de cada uno de los dígitos es la siguiente: El dígito X aumenta cuando hay un cambio de interfaz no retrocompatible, es necesario regenerar los clientes para poder consumir el servicio. El dígito Y aumenta cuando hay un cambio de interfaz retrocompatible, no es necesario regenerar los clientes salvo aquellos usuarios que quieran beneficiarse de los cambios en la nueva versión. El dígito Z aumenta cuando ha habido un cambio en la lógica del servicio ya sea para corregir errores o agregar evolutivos. Los dígitos AAAAMMDD indica la fecha en la que se despliega el servicio en el entorno de PRE-explotación.

6 Página 6 de 45 2 VERSIÓN DEL SERVICIO Este documento corresponde a la versión del servicio en la arquitectura de Platino 2.0.

7 Página 7 de 45 3 CASOS DE USO A continuación se muestra el diagrama de casos de uso del servicio de Pasarela de Pago:

8 Página 8 de 45 Estos casos de uso han dado lugar a la siguiente interfaz de servicio: Operaciones

9 Página 9 de CU-PPA-04: Verificar NRC Esta funcionalidad permite realizar una solicitud de comprobación de validez de un NRC emitido por una entidad financiera. En caso de éxito en la invocación, devolverá un booleano indicando si el NRC es correcto o no Interfaz Entrada del servicio El parámetro de entrada que espera este método, es un xml con los datos básicos del NRC a verificar. Parámetro verificacionnrcxml Descripción String que contiene los datos necesarios para comprobar la validez del NRC

10 Página 10 de 45 El xml de entrada debe corresponderse con el siguiente esquema. peticion_verificacion.xsd <xs:schema version="1.0" xmlns:xs=" <xs:element name="peticionverificacion"> <xs:complextype > <xs:sequence> <xs:element name="nrc" type="alfanumerico" minoccurs="1"/> <xs:element name="organismoemisor" type="numerico" minoccurs="1" /> <xs:element name="codigoorganismo" type="alfanumerico" minoccurs="1" /> <xs:element name="cpr" type="numerico" minoccurs="1" /> <xs:element name="fechaoperacion" type="numerico" minoccurs="1"/> <xs:element name="justificante" type="numerico" minoccurs="1" /> <xs:element name="nif" type="alfanumerico" minoccurs="1"/> </xs:sequence> </xs:complextype> </xs:element> <xs:simpletype name="alfanumerico"> <xs:restriction base="xs:string"> <xs:minlength value="1" /> </xs:restriction> </xs:simpletype> <xs:simpletype name="numerico"> <xs:restriction base="xs:string"> <xs:pattern value="[0-9]+" /> </xs:restriction> </xs:simpletype> </xs:schema>

11 Página 11 de 45 Breve descripción de lo que se espera en cada elemento del xml. Nombre Tipo Descripción nrc N(22) NRC que se va a verificar organismoemisor codigoorganismo cpr fechaoperacion N AN N(7) N(8) Código emisor del Gobierno de Canarias, debe asignarse el valor Código de organismo del Gobierno de Canarias, debe asignarse el valor GOB_CANARIAS. Código de procedimiento de Recaudación. Autoliquidaciones Liquidaciones Fecha en la que se realizó la operación de pago, con el formato AAAAMMDD justificante N(13) Número de justificante de la operación asociada al NRC nif AN(8) NIF del contribuyente que realizó el pago N Numérico An AlfaNumérico

12 Página 12 de 45 Un ejemplo típico de una invocación a esta operación es la que se muestra a continuación: Ejemplo de Entrada <peticionverificacion> <nrc> e54b16</nrc> <organismoemisor>65006</organismoemisor> <codigoorganismo>gob_canarias</codigoorganismo> <cpr> </cpr> <fechaoperacion> </fechaoperacion> <justificante> </justificante> <nif> a</nif> </peticionverificacion> Salida del servicio A continuación se muestra el modelo de datos que devuelve el Servicio en respuesta a una invocación con éxito de esta operación.

13 Página 13 de 45 Un ejemplo típico de respuesta de esta operación es la que se muestra a continuación: Ejemplo de Salida <soapenv:envelope xmlns:soapenv=" <soapenv:body> <ns2:verificarnrcresponse xmlns:ns2=" <return>true</return> </ns2:verificarnrcresponse> </soapenv:body> </soapenv:envelope> Excepciones Este servicio puede lanzar las siguientes excepciones en caso de encontrar errores MalFormedXmlDatosException InvalidParameterValueException

14 Página 14 de CU-PPA-05: Obtener Versión del Servicio Este caso de uso permite averiguar la versión en formato X.Y.Z.YYYYMMDD del servicio web desplegado Interfaz Entrada del servicio. Este método no tiene parámetros de entrada. Un ejemplo típico de una invocación a esta operación es la que se muestra a continuación. Ejemplo de Entrada <soapenv:envelope xmlns:soapenv=" xmlns:pas=" <soapenv:header/> <soapenv:body> <pas:getversion/> </soapenv:body> </soapenv:envelope>

15 Página 15 de Salida del servicio Ejemplo de salida del servicio. <soapenv:envelope xmlns:soapenv=" <soapenv:body> <ns2:getversionresponse xmlns:ns2=" <return> </return> </ns2:getversionresponse> </soapenv:body> </soapenv:envelope>

16 Página 16 de CU-PPA-06: Realizar Pago Firmado Esta funcionalidad permite a los backoffices que se integren con PLATINO, la realización de un pago telemático. El usuario, a través de un formulario, introducirá y firmará los parámetros referentes al pago y el sistema, devolverá el resultado de la operación. El pago permitido actualmente es el correspondiente a la norma 65, según la especificación de Red.es. NOTA: Para la generación de los datos referentes al pago y su firma, consultar el apartado 5.2. Firma de un formulario Interfaz Entrada del servicio A continuación se muestra el modelo de datos que se ha de utilizar cuando queremos invocar a la operación de pago:

17 Página 17 de 45 Parámetro datospagoxml firma norma modalidad Descripción String que contiene los datos de la solicitud del pago rellenas por el ciudadano Bytes de la firma en formato XML-Signature realizada por el usuario, del String datospagoxml. Valor correspondiente a la norma 65, siguiendo la especificación de Red.es. En caso de tratarse de un pago bajo la norma 60, además se debe especificar la modalidad, que pueden ser 1, 2 o 3. Para la norma 65, este campo no se tiene en cuenta, por tanto puede dejarse vacío.

18 Página 18 de 45 Pagos bajo Norma65 El xml que llega en el parámetro datospagoxml, debe cumplir el siguiente esquema. peticion_norma65.xsd <?xml version="1.0" encoding="utf-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs=" <xs:element name="peticionnorma65"> <xs:complextype > <xs:sequence> <xs:element name="idaplicacion" type="alfanumerico" minoccurs="0" /> <xs:element name="organismoemisor" type="numerico" minoccurs="1"/> <xs:element name="codigoorganismo" type="alfanumerico" minoccurs="1"/> <xs:element name="cpr" type="numerico" minoccurs="1"/> <xs:element name="cvc" type="numerico" minoccurs="0"/> <xs:element name="importeoperacion" type="decimal" minoccurs="1"/> <xs:element name="codigoentidad" type="numerico" minoccurs="1"/> <xs:element name="acreditacionterceros" type="numerico" minoccurs="1"/> <xs:element name="mediopago" type="numerico" minoccurs="1"/> <xs:element name="numeromediopago" type="alfanumerico" minoccurs="1"/> <xs:element name="primerrepresentante" type="alfanumerico" minoccurs="0"/> <xs:element name="nifprimerrepresentante" type="alfanumerico" minoccurs="0"/> <xs:element name="segundorepresentante" type="alfanumerico" minoccurs="0"/> <xs:element name="nifsegundorepresentante" type="alfanumerico" minoccurs="0"/> <xs:element name="modelo" type="numerico" minoccurs="1"/> <xs:element name="concepto" type="numerico" minoccurs="1"/> <xs:element name="ejercicio" type="numerico" minoccurs="0"/> <xs:element name="periodo" type="alfanumerico" minoccurs="0"/> <xs:element name="justificante" type="numerico" minoccurs="1"/> <xs:element name="anagrama" type="alfanumerico" minoccurs="1"/> <xs:element name="codigoterritorial" type="alfanumerico" minoccurs="0"/> <xs:element name="fechadevengo" type="numerico" minoccurs="0"/> <xs:element name="contribuyente" type="alfanumerico" minoccurs="1"/> <xs:element name="nifcontribuyente" type="alfanumerico" minoccurs="1"/> <xs:element name="nifsolicitante" type="alfanumerico" minoccurs="0"/> <xs:element name="info" type="alfanumerico" minoccurs="0"/> <xs:element name="datosorganismo" type="alfanumerico" minoccurs="0"/> </xs:sequence> </xs:complextype> </xs:element> <xs:simpletype name="alfanumerico"> <xs:restriction base="xs:string"> <xs:minlength value="1" /> </xs:restriction> </xs:simpletype> <xs:simpletype name="numerico"> <xs:restriction base="xs:string">

19 Página 19 de 45 <xs:pattern value="[0-9]+" /> </xs:restriction> </xs:simpletype> <xs:simpletype name="decimal"> <xs:restriction base="xs:string"> <xs:pattern value="[0-9]+(\.[0-9]+)?" /> </xs:restriction> </xs:simpletype> </xs:schema> La descripción de cada uno de los elementos descritos en el XSD es la siguiente: NOMBRE TIPO DESCRIPCIÓN idaplicacion An(10) Código de la aplicación que realiza la invocación al servicio organismoemisor N Código emisor del Gobierno de Canarias, debe asignarse el valor codigoorganismo AN Código de organismo del Gobierno de Canarias, debe asignarse el valor GOB_CANARIAS. cpr N(7) Código de procedimiento de recaudación del pago. cvc N(3) Corresponde al código que se encuentra en el reverso de la tarjeta de crédito. importeoperacion Número decimal Importe de la operación de pago codigoentidad An(4) Código de la entidad financiera dada de alta en la Pasarela (⁴) acreditacionterceros N(1) Indica si el representante está autorizado a realizar el pago en nombre del contribuyente.(²) mediopago N(1) Identificador medio de pago: 1 = Cargo en cuenta 2 = Pago con tarjeta numeromediopago N(20) En el caso de pagos en cuenta corriente, se corresponde con el IBAN donde se hará el cargo. El formato a seguir es N(24) En el caso de pagos con tarjeta, se compone del número de la tarjeta, seguida por el mes y año de

20 Página 20 de 45 caducidad. Se debe seguir este formato N(16)MMAA primerrepresentante An(40) Apellidos y nombre del primer representante (titular de la cuenta) nifprimerrepresentante AN(8) NIF/CIF/NIE del primer representante (titular de la cuenta) segundorepresentante An(40) Apellidos y nombre del segundo representante nifsegundorepresentante AN(8) NIF/CIF/NIE del segundo representante modelo N(3) Modelo admitido por la Pasarela para el Organismo indicado concepto N(4) Concepto correspondiente al Modelo y al Organismo indicado ejercicio N(4) Valor del ejercicio fiscal con formato AAAA periodo N(2) Valor del periodo con formato MM (9) justificante N(13) Número de justificante que identifica unívocamente la operación de pago. ( ⁵) anagrama An(4) Anagrama fiscal del contribuyente. (Si no se aporta, la pasarela asigna el valor 0000). codigoterritorial An(6) Valor del código territorial. fechadevengo N(8) Fecha de devengo con formato AAAAMMDD contribuyente An(40) Apellidos y nombres del contribuyente nifcontribuyente AN(8) NIF del contribuyente nifsolicitante AN(8) NIF del solicitante del pago (³) info An(25) Reservada para información específica datosorganismo An(59) Reservada para el uso del organismo N Numérico An AlfaNumérico ( ¹ ) Los tipos de trama válidos son los siguientes:

21 Página 21 de 45 2, correspondiente a la TRAMA65 de Red.es. En caso de no especificarse ninguna, se utilizará por defecto la trama 2. En caso de especificar otro valor, se devolverá un código de respuesta TT, correspondiente a un tipo de trama desconocida. (²) Los posibles valores para este elemento son: 1 = tercero autorizado. 0 = tercero no autorizado. Si no se aporta ninguno, la pasarela lo asigna automáticamente siguiendo el siguiente patrón: si el NIF del firmante es igual al NIF del Contribuyente, asigna valor 0. Si el NIF del firmante es diferente al NIF del Contribuyente, asigna valor 1. (³) Si no se indica ningún valor se tomará por defecto el siguiente: Si se especifica el NIF del primer representante, se tomará ese valor. Si no se especifica el NIF del primer representante, entonces se utilizará el NIF del contribuyente. (⁴) Si no se indica ningún valor se tomará el código de organismo o se determinará a través del número del medio de pago. ( ⁵ ) Este campo tiene la siguiente forma: [MMMYZZZZZZZZD], siendo: "M : modelo Y : indicador de datos a obtener pudiendo tomar los siguientes valores: 0: No se obtienen datos opcionales 1: Expediente 2: Fecha de devengo 3: Expediente y fecha de devengo 4: Datos específicos 5: Expediente y datos específicos 6: Fecha de devengo y datos específicos 7: Fecha de devengo, datos específicos y expediente Z : número secuencial D : dígito de control

22 Página 22 de Salida del servicio El método en cuestión, devolverá un objeto tipo PeticionResponse, con los datos de la respuesta que llega desde la Pasarela de Pagos.

23 Página 23 de 45 A continuación vemos los valores que podemos esperar al realizar un pago. NOMBRE codigorespuesta descripcionrespuesta cpr tipopeticion mediopago numeromediopago importeoperacion nifprimerrepresentante nifsegundorepresentante contribuyente primerrepresentante segundorepresentante codigoorganismo modelo ejercicio periodo nifcontribuyente nifsolicitante DESCRIPCIÓN Código de respuesta devuelto por el Servicio de Pagos Telemático(SPT) Descripción de la respuesta devuelta por el Servicio de Pagos Telemático(SPT) Código de procedimiento de recaudación del pago. Tipo de petición, devuelto por la EEFF (alta de un pago) Identificador medio de pago: 1 = Cargo en cuenta 2 = Pago con tarjeta En el caso de pagos en cuenta corriente, se corresponde con el CCC donde se hará el cargo. El formato a seguir es N(20) En el caso de pagos con tarjeta, se compone del número de la tarjeta, seguida por el mes y año de caducidad. Se debe seguir este formato N(16)MMAA Importe de la operación de pago NIF/CIF/NIE del primer representante (titular de la cuenta) NIF/CIF/NIE del segundo representante Apellidos y nombres del contribuyente Apellidos y nombre del primer representante (titular de la cuenta) Apellidos y nombre del segundo representante Organismo admitido en la Pasarela Modelo admitido por la Pasarela para el Organismo indicado Valor del ejercicio fiscal con formato AAAA Valor del periodo con formato MM NIF del contribuyente NIF del solicitante del pago

24 Página 24 de 45 anagrama codigoterritorial fechadevengo justificante info conceptoautoliquidacion datosorganismo acreditacionterceros nrc codigoretorno fechaoperacion Anagrama fiscal del contribuyente Valor del código territorial Fecha de devengo con formato AAAAMMDD Número de justificante que identifica unívocamente la operación de pago. Reservada para información específica Concepto de la autoliquidación Reservada para el uso del organismo Indica si el representante está autorizado a realizar el pago en nombre del contribuyente. 1 = tercero autorizado. 0 = tercero no autorizado. NRC correspondiente a la operación de pago Código de retorno de la entidad financiera Fecha de la operación Un ejemplo típico de respuesta de esta operación es la que se muestra a continuación: Ejemplo de Salida <soapenv:envelope xmlns:soapenv=" <soap:body> <ns2:pagofirmadoresponse xmlns:ns2=" <return> <codigoorganismo>65006</codigoorganismo> <codigorespuesta>ok</codigorespuesta> <codigoretorno>00</codigoretorno> <codigoterritorial>065021</codigoterritorial> <cpr> </cpr> <datosorganismo>65006</datosorganismo> <descripcionconcepto>0001</descripcionconcepto> <descripcionrespuesta>operación finalizada OK</descripcionRespuesta> <ejercicio>2014</ejercicio> <fechadevengo> </fechadevengo> <fechaoperacion> </fechaoperacion> <idpasarela>01</idpasarela>

25 Página 25 de 45 <importeoperacion>12.5</importeoperacion> <justificante> </justificante> <mediopago>1</mediopago> <modelo>411</modelo> <nifcontribuyente> a</nifcontribuyente> <nifsolicitante> a</nifsolicitante> <nrc> b661e9d6</nrc> <numeromediopago>es70null</numeromediopago> <periodo>01</periodo> <reservada>1gob_canarias ES70</reservada> <tipopeticion>01</tipopeticion> </return> </ns2:pagofirmadoresponse> </soap:body> </soapenv:envelope> Excepciones Este servicio puede lanzar las siguientes excepciones en caso de encontrar errores Exception MalFormedXmlDatosException InvalidParameterValueException ExcepcionPasarelaFirmaInvalida ExcepcionPasarelaFirmaError

26 Página 26 de CU-PPA-07: Realizar Consulta Firmada Esta funcionalidad permite a los backoffices que se integren con PLATINO, la realización de una consulta sobre un determinado pago realizado con anterioridad. El usuario, a través de un formulario, introducirá y firmará los parámetros referentes a la consulta, y el sistema devolverá el resultado de la operación. NOTA: Para la generación de los datos referentes a la consulta y su firma, consultar el apartado 5.2. Firma de un formulario. De cara al cliente, este método se comporta de la misma forma que lo hace pagofirmado. Admite los mismos parámetros de entrada y devuelve los mismos objetos con los mismos valores. Por tanto, para su comprensión detallada, remítase al apartado CU-PPA-06: Realizar Pago Firmado

27 Página 27 de CU-PPA-08: Realizar una BusquedaSPT: Esta funcionalidad permite a los backoffices que se integren con PLATINO, la realización de búsquedas contra la pasarela de pagos de Red.es, en lugar de contra la entidad financiera Interfaz: Entrada del servicio: El parámetro de entrada que espera este método, es un xml con los datos básicos de la búsqueda a realizar: Parámetro datosbusquedaxml Descripción String que contiene los datos necesarios para realizar la búsqueda deseada.

28 Página 28 de 45 El xml que llega en el parámetro datospagoxml, debe cumplir el siguiente esquema. peticion_busqueda_sop.xsd <xs:schema version="1.0" xmlns:xs=" <xs:element name="busquedasop"> <xs:complextype> <xs:sequence> <xs:element name="nrc" nillable="true" type="xs:string" /> <xs:element name="codorganismo" nillable="true" type="xs:string" /> <xs:element name="cpr" nillable="true" type="xs:string" /> <xs:element name="estado" nillable="true" type="xs:string" /> <xs:element name="fechadesde" nillable="true" type="xs:string" /> <xs:element name="fechahasta" nillable="true" type="xs:string" /> <xs:element name="idlote" nillable="true" type="xs:string" /> <xs:element name="justificante" nillable="true" type="xs:string" /> <xs:element name="nifcertificado" nillable="true" type="xs:string" /> <xs:element name="nifcontribuyente" nillable="true" type="xs:string" /> <xs:element name="organismoemisor" nillable="true" type="xs:string" /> <xs:element name="referencia" nillable="true" type="xs:string" /> <xs:element name="superorganismo" nillable="true" type="xs:string" /> </xs:sequence> </xs:complextype> </xs:element> </xs:schema> La descripción de cada uno de los elementos descritos en el XSD es la siguiente: NOMBRE TIPO DESCRIPCIÓN NRC N(22) NRC correspondiente a la operación de pago. codigoorganismo AN Código de organismo del Gobierno de Canarias, debe asignarse el valor GOB_CANARIAS. cpr N(7) Código de procedimiento de recaudación del pago. estado AN Estado en que se encuentra el pago que desea buscarse. fechadesde N(8) Fecha desde la que se empezará la búsqueda, con el formato AAAAMMDD fechahasta N(8) Fecha hasta la que se realizará la búsqueda, con el formato AAAAMMDD idlote N Número del lote que queremos consultar. Obligatorio

29 Página 29 de 45 si queremos consultar lote. justificante N(13) Número de justificante de la operación asociada al NRC nifcertificado AN(8) Nif del certificado con el que se realiza la firma nifcontribuyente AN(8) Nif del certificado correspondiente al contribuyente organismoemisor N Código emisor del Gobierno de Canarias, debe asignarse el valor referencia N(12-13) Campo identificador de un pago. Habrá sido generado previamente por el Organismo Emisor. superorganismo AN(20) Código de súperorganismo N Numérico An AlfaNumérico

30 Página 30 de 45 Un ejemplo típico de una invocación a esta operación es la que se muestra a continuación: Ejemplo de Entrada <soapenv:envelope xmlns:soapenv=" xmlns:pas=" <soapenv:header/> <soapenv:body> <pas:busquedaspt> <!--Optional:--> <datosbusquedaxml><![cdata[<peticionnorma65> <idaplicacion>ap001</idaplicacion> <organismoemisor>65006</organismoemisor> <codigoorganismo>gob_canarias</codigoorganismo> <cpr> </cpr> <importeoperacion>12.5</importeoperacion> <codigoentidad>2100</codigoentidad> <acreditacionterceros>0</acreditacionterceros> <mediopago>1</mediopago> <numeromediopago>es </numeromediopago> <modelo>620</modelo> <concepto>0000</concepto> <ejercicio>2014</ejercicio> <periodo>01</periodo> <justificante> </justificante> <anagrama> </anagrama> <codigoterritorial>103507</codigoterritorial> <fechadevengo> </fechadevengo> <contribuyente>apellido1pf1 Apellido2PF1 NombrePF1</contribuyente> <nifcontribuyente> a</nifcontribuyente> <nifsolicitante> a</nifsolicitante> </peticionnorma65>]]></datosbusquedaxml> </pas:busquedaspt> </soapenv:body> </soapenv:envelope> Salida del servicio: El método en cuestión, devolverá un objeto tipo PeticionResponse, con los datos de la respuesta que llega desde la Pasarela de Pagos. Para más información remítase al punto

31 Página 31 de 45 Ejemplo de Salida <soap:envelope xmlns:soap=" <soap:body> <ns2:busquedasptresponse xmlns:ns2=" <return> <acreditacionterceros>0</acreditacionterceros> <anagrama></anagrama> <codigoorganismo>65006</codigoorganismo> <codigorespuesta>ok</codigorespuesta> <codigoretorno>00</codigoretorno> <codigoterritorial>103507</codigoterritorial> <cpr> </cpr> <datosorganismo>65006</datosorganismo> <descripcionconcepto>0000</descripcionconcepto> <descripcionrespuesta>operación finalizada OK</descripcionRespuesta> <ejercicio>2014</ejercicio> <fechadevengo> </fechadevengo> <fechaoperacion> </fechaoperacion> <idpasarela>01</idpasarela> <importeoperacion>12.5</importeoperacion> <justificante> </justificante> <mediopago>1</mediopago> <modelo>620</modelo> <nifcontribuyente> a</nifcontribuyente> <nifsolicitante> a</nifsolicitante> <nombrecontribuyente>apellido1pf1 Apellido2PF1 NombrePF1</nombreContribuyente> <nrc> aa926</nrc> <numeromediopago>es </numeromediopago> <periodo>01</periodo> <reservada>1gob_canarias ES28</reservada> <tipopeticion>01</tipopeticion> </return> </ns2:busquedasptresponse> </soap:body> </soap:envelope> Excepciones: Este servicio puede lanzar las siguientes excepciones en caso de encontrar errores: Exception MalformedXMLDatosException

32 Página 32 de 45 InvalidParameterValueException 3.6 EXCEPCIONES Para que los clientes tengan más conocimiento de lo que ocurre cuando se encuentra algún error, se ha planteado un pequeño control de errores basados en excepciones. Cada vez que algo vaya mal en las invocaciones a los distintos métodos, el servicio de Pasarela de Pagos devolverá una excepción concreta, que ayudará a determinar más fehacientemente el motivo del error. A continuación, vemos explicadas más en detalle todas las excepciones que se pueden encontrar. 3.7 InvalidParameterValueException Esta excepción se lanza cuando alguno de los parámetros de entrada es inválido. Cabe destacar que no se hace una comprobación exhaustiva de todos los parámetros. Por ejemplo, aquellos que vengan dentro de los xml, se delegan a la propia aplicación de Pasarela de Pagos. Si se encontrase un error en este punto, esta devolverá una respuesta con su correspondiente código de error. 3.8 MalFormedXmlDatosException Cada vez que se recibe un parámetro en forma de xml, a este se le aplica una operación de unmarshalling, para obtener un objeto de dominio con el que se pueda trabajar más fácilmente. Es en este proceso donde se realiza la validación con el esquema correspondiente. Si ocurre algún tipo de error, una excepción del tipo MalFormedXmlDatosException es lanzada.

33 Página 33 de ExcepcionPasarelaFirmaInvalida Esta excepción será lanzada, cuando la firma del xml que se recibe como parámetro, no sea válida ExcepcionPasarelaErrorFirma Esta excepción será lanzada cuando se encuentre algún error en el proceso de verificación de la firma o en el momento de extraer el NIF del firmante del certificado.

34 Página 34 de 45 4 INFORMACIÓN ADICIONAL DEL SERVICIO 4.1 Códigos de respuesta del Servicio de Pago Telemático A continuación se presentan todos los valores de código de respuesta, que se contemplan como propios de la aplicación del Servicio de Pago Telemático. Estos son devueltos en el objeto PeticionResponse, en el atributo codigorespuesta. CÓDIGO RESPUESTA EF J0 J1 J2 J3 J4 J5 J6 J7 J8 J9 JA JB JC DESCRIPCIÓN Error devuelto y controlado por la EEFF. Error en el campo nif de certificado es obligatorio y no ha sido informado. Error en el campo nif de certificado no contiene un valor válido. Error en el campo fecha es obligatorio y no ha sido informado. Error en el campo fecha no contiene un valor válido. Error en el campo hora es obligatorio y no ha sido informado. Error en el campo hora no contiene un valor válido. Error en el campo CPR es obligatorio y no ha sido informado. Error en el campo CPR no contiene un valor válido. Error en el campo pasarela es obligatorio y no ha sido informado. Error en el campo pasarela no contiene un valor válido. Error en el campo tipo de petición es obligatorio y no ha sido informado. Error en el campo tipo de petición no contiene un valor válido. Error en el campo código de la entidad financiera es obligatorio y no ha sido

35 Página 35 de 45 informado. JD JE JF JG JH JI JJ JK JL JM JN JO JP JQ JR JS Error en el campo código de la entidad financiera no contiene un valor válido. Error al validar la MAC de la Fecha y Hora es un dato incorrecto. Error en el campo código identificador medio de pago es obligatorio y no ha sido informado. Error en el campo código identificador medio de pago no contiene un valor válido. Error en el campo tipo medio de pago (Código Cuenta Cliente o Número de tarjeta) es obligatorio y no ha sido informado. Error en el campo tipo medio de pago (Código Cuenta Cliente o Número de tarjeta) no contiene un valor válido. Error en el campo Fecha de caducidad es obligatorio y no ha sido informado. Error en el campo importe es obligatorio y no ha sido informado. Error en el campo importe no contiene un valor válido. Error en el campo nif del representante 1 no contiene un valor válido. Error en el campo nif del representante 2 no contiene un valor válido. Error en el campo nombre del representante 1 no contiene un valor válido (Supera los 40 caracteres). Error en el campo nombre del representante 2 no contiene un valor válido (Supera los 40 caracteres) Error en el campo nombre del contribuyente no contiene un valor válido (Supera los 40 caracteres). Error en el campo reservado es obligatorio y no ha sido informado. Error en el campo reservado no contiene un valor válido.

36 Página 36 de 45 JT JU JV JW JX JY JZ K0 K1 K2 K3 K4 K5 K6 K7 K8 K9 KA Error en el campo código de organismo en el campo reservado contiene un valor no válido. Error en el campo código del organismo emisor es obligatorio y no ha sido informado. Error en el campo superorganismo no contiene un valor válido. Error en el campo organismo emisor no contiene un valor válido. Error en el campo idioma es obligatorio y no ha sido informado. Error en el campo idioma no contiene un valor válido. Error en el campo url es obligatorio y no ha sido informado. Error en el campo url no contiene un valor válido. Error en el campo Referencia es obligatorio y no ha sido informado. Error en el campo Referencia no contiene un valor válido. Error en el campo (ident1) la primera parte de la identificación es obligatorio y no ha sido informado Error en el campo (ident1) la primera parte de la identificación no contiene un valor válido. Error en el campo (ident2) la segunda parte de la identificación es obligatorio y no ha sido informado. Error en el campo (ident2) la segunda parte de la identificación no contiene un valor válido. Error en el campo Concepto no contiene un valor válido. Error en el campo código domiciliación es obligatorio y no ha sido informado. Error en el campo código domiciliación no contiene un valor válido. Error en el campo ccc de domiciliación es obligatorio y no ha sido informado.

37 Página 37 de 45 KB KC KD KE KF KG KH KI KJ KK KL KM KN KO KP KQ KR KS KT Error en el campo ccc de domiciliación no contiene un valor válido. Error en el campo justificante es obligatorio y no ha sido informado. Error en el campo justificante no contiene un valor válido. Error en el campo nif contribuyente es obligatorio y no ha sido informado. Error en el campo nif contribuyente no contiene un valor válido. Error en el campo código de modelo es obligatorio y no ha sido informado. Error en el campo código de modelo no contiene un valor válido. Error en el campo acreditación de pagos por cuenta de terceros es obligatorio y no ha sido informado. KError en el campo acreditación de pagos por cuenta de terceros no contiene un valor válido. Error en el campo la acreditación de pagos por cuenta de terceros el NIF_CERTIFICADO es distinto del NIF_CONTRIBUYENTE. Error en el campo expediente no contiene un valor válido. Error en el campo fecha de devengo no contiene un valor válido. Error en el campo información específica no contiene un valor válido. Error en el campo anagrama fiscal es obligatorio y no ha sido informado. Error en el campo anagrama fiscal no contiene un valor válido. Error en el campo código territorial no contiene un valor válido. Error en el campo concepto autoliquidación no contiene un valor válido. Error en el campo identificación no contiene un valor válido. El cuaderno no tiene un código de organismo válido.

38 Página 38 de 45 KU KV KW KX KY KZ L0 L1 L2 L3 L4 L5 L6 L7 L8 L9 LA LB El SOAP recibido es incorrecto. La petición no viene firmada. No se pudo conectar con ASF. No viene un nif del certificado en el pago. Pago firmado por más de dos firmantes. Error de validación. Número de serie no validado contra el superorganismo. Error al obtener del repositorio los datos del organismo. El código de Validación del organismo indica que debería venir el pago firmado por el ciudadano y el organismo, y sólo está firmado una vez. No coinciden el número de serie del certificado con el existente en la B.B.D.D El código de Validación del organismo indica que debería venir el pago firmado sólo por el organismo, y hay dos firmantes. No coincide el número de serie de ningún firmante con el que está configurado para el organismo. Certificado no autorizado para el pago. Verificación NO correcta. Error detectado en la aplicación de firma webservice. Firma No Válida. Certificado no válido (Intervalo de validez incorrecto). Certificado no verificado (la firma de la CA sobre el mismo no es correcta). Certificado revocado (el certificado ha sido revocado, posteriormente se añadirán a este código las razones de revocación).

39 Página 39 de 45 LC LE LF LG LH LI LJ LK LL LM LQ LR LS LT LU LV OK El estado de revocación del certificado no se ha podido verificar. El uso del certificado en esta aplicación y operación no es válido. El algoritmo de firma no está definido. El algoritmo de firma no es valido. El certificado no se encontró. El XML no tiene el formato XMLDSig correcto. No se encontró la cadena del certificado de la firma. Los datos del pago no han superado la validación XSS. El dígito de control del campo Justificante no es válido. El dígito de control del campo Referencia no es válido. No se ha informado del IBAN asociado al CCC. No se ha informado del IBAN asociado a la CCC domiciliada. Error en el código IBAN asociado al CCC. Error en el código IBAN asociado al CCC domiciliada. Error no hay un CCC pero se informan de un código IBAN. Error no hay un CCC Domiciliada pero se informan de un código IBAN. Operación finalizada OK

40 Página 40 de Códigos de retorno de la entidades financieras A continuación se presentan aquellos valores de código de retorno devueltos por las entidades financieras para una operación ya sea de consulta o de pago. Su contenido tendrá significado únicamente en los siguientes casos: Cuando para una operación de pago se obtenga de la pasarela un codigorespuesta con valor EF Cuando para una operación de consulta se obtenga de la pasarela un codigorespuesta con valor 00 En ambos casos el significado de los códigos de retorno son los que se muestran a continuación: CÓDIGO RETORNO DESCRIPCIÓN 00 Operación finalizada OK 1 Número de justificante o importe erróneo o ausente Modelo o tipo de operación no soportado Solicitud anulada El certificado firmante no está autorizado para realizar el pago por personas ajenas El representante del certificado firmante no está autorizado para realizar el pago por personas ajenas El certificado firmante no está autorizado para pagar y presentar este modelo El certificado firmante no está autorizado para realizar este pago por convenio La entidad emisora de esta tarjeta no admite este tipo de servicio

41 Página 41 de Concepto o modelo erróneo 11 Falta concepto o modelo 12 Ejercicio fiscal erróneo 13 Falta ejercicio fiscal 14 Período erróneo 15 Falta período 16 Tipo de moneda erróneo (distinto de E) 17 NIF/CIF incorrecto para este modelo 18 Falta tipo de moneda 19 Importe ingreso erróneo 20 Falta importe de ingreso 21 NIF contribuyente erróneo 22 Falta NIF del contribuyente 23 NIF del primer representante erróneo 24 Falta NIF del representante 25 Sobra NIF del representante 26 Falta nombre del contribuyente 27 Falta nombre del representante 28 Sobra nombre del representante 29 Código administración erróneo 30 Falta código administración 31 Anagrama erróneo 32 Falta anagrama 33 Sobra anagrama 34 Importe total y parcial no cuadra

42 Página 42 de Falta importe total 36 Sobra importe total 37 Opción fraccionamiento errónea 38 Falta opción fraccionamiento 39 C.C.C. (Código Cuenta Cliente) erróneo 40 Falta C.C.C. (Código Cuenta Cliente) 41 Falta importe redenominación erróneo 42 Falta importe redenominación 43 Tipo de operación erróneo 44 Falta tipo de operación 45 Tipo de petición erróneo (distinto de 01 o 02) 46 Falta tipo de petición 47 Tipo de autoliquidación erróneo (distinto de I o D) 48 Falta tipo de autoliquidación 49 NIF del segundo representante erróneo 50 Concepto o modelo no permitidos 51 Ejercicio fiscal no permitido 52 Período no permitido 53 Ingreso no fraccionable por estar fuera del período voluntario 54 Ingreso fuera de período 55 Movimiento distinto de 01 y NIF certificado distinto a NIF tecleado 57 NIF primer certificado distinto a NIF tecleado 58 NIF segundo certificado distinto a NIF tecleado 59 El horario de servicio es desde las 2:00 h. hasta las 23:00 h. diariamente

43 Página 43 de Fecha de presentación fuera de plazo 61 Importe total de la deuda erróneo 62 Autoridad certificadora errónea 63 Certificado caducado 64 Certificado revocado 65 Presentador no autorizado en nombre de terceras personas 66 Ha firmado dos veces con el mismo representante 67 Período impositivo concluido errónea 68 Fecha de conclusión período impositivo errónea 69 Error de formato en los datos de la petición 70 Petición duplicada 71 No existe cargo con los datos consultados 72 C.C.C. cancelado 73 C.C.C. bloqueado (judicialmente) 74 C.C.C. con saldo no disponible 75 C.C.C. con saldo insuficiente 76 C.C.C. cuenta no es de ahorro a la vista 77 C.C.C. inexistente 78 C.C.C. inoperante 79 NIF del contribuyente no titular a la cuenta 80 NIF representante no apoderado de la cuenta 81 Contribuyente no persona jurídica (e informa representante) 82 Falta segundo NIF por se cuenta conjunta 83 El segundo NIF no corresponde a titular de la cuenta 84 MAC erróneo

44 Página 44 de No hay suficientes apoderados 86 Esta entidad no atiende la solicitud de cargo por esta vía en este rango horario (y se le añade opcionalmente explicación de horario de servicio que puede venir en la cadena de respuesta desde la posición 211 hasta la 400) 87 Texto de la Entidad Colaboradora en la cadena de respuesta desde la posición 211 hasta la 400 con explicación amplia sobre la incidencia y teléfono de atención al cliente. 88 Contribuyente no identificado 89 Fecha de validez/caducidad de la tarjeta excedida, errónea o ausente 90 No está autorizado para realizar el pago por personas ajenas 91 Número de tarjeta no valido, erróneo o ausente 92 El titular del certificado con el que se ha firmado no es el titular de la tarjeta 93 Se ha excedido el límite de la operación 94 Tipo de tarjeta no soportado 95 Solo se aceptan tarjetas emitidas por la propia entidad 99 Error técnico A4 A6 A7 A8 A9 B6 B8 C1 C2 NRC no existe NIF no existe NRC ya constituido. Inténtelo por consulta NRC no preconstituido. Inténtelo por consulta NRC ya existe NRC no disponible para devolución NRC ya liberado Incoherencia de datos NRC de operación ya existe

45 Página 45 de 45 F2 H4 I3 I4 I6 I7 I8 NRC no disponible para devolución, ya devuelto Imposible cobro, NRC ya cobrado Dígito de control erróneo. Carácter de control erróneo. Error en el modelo de operación. Error en el código del Banco de España. Error en el código IBAN