Descarga PDF - Gobierno de Canarias

Interoperabilidad de los servicios telemáticos de la
Administración Pública de la CAC
Página 1 de 31
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 :
PLA-DOC-FIN-v2.1-Vol IV. Servicio de Pasarela de Pagos Telematicos
Ubicación en eRoom:
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: 10/05/2016
Fecha: 10/05/2016
Fecha: 10/05/2016
Índice de contenido
1 DESCRIPCIÓN GENERAL ..........................................................................................3
2 VERSIÓN DEL SERVICIO...........................................................................................3
3 CASOS DE USO..........................................................................................................4
3.1 CU-PPA-04: Verificar NRC..................................................................................... 5
3.1.1 Interfaz..............................................................................................................5
3.1.2 Entrada del servicio..........................................................................................5
3.1.3 Salida del servicio.............................................................................................7
3.1.4 Excepciones..................................................................................................... 7
3.2 CU-PPA-05: Obtener Versión del Servicio.............................................................8
3.2.1 Interfaz..............................................................................................................8
3.2.2 Entrada del servicio..........................................................................................8
3.2.3 Salida del servicio.............................................................................................8
3.3 CU-PPA-06: Realizar Pago Firmado......................................................................9
3.3.1 Interfaz..............................................................................................................9
3.3.2 Entrada del servicio..........................................................................................9
3.3.3 Salida del servicio...........................................................................................13
3.3.4 Excepciones................................................................................................... 15
3.4 CU-PPA-07: Realizar Consulta Firmada.............................................................. 16
3.5 CU-PPA-08: Realizar una BusquedaSPT:............................................................17
3.5.1 Interfaz:...........................................................................................................17
3.5.2 Entrada del servicio:.......................................................................................17
3.5.3 Salida del servicio:..........................................................................................19
3.5.4 Excepciones:.................................................................................................. 20
3.6 EXCEPCIONES....................................................................................................20
3.7 InvalidParameterValueException......................................................................... 20
3.8 MalFormedXmlDatosException............................................................................20
3.9 ExcepcionPasarelaFirmaInvalida.........................................................................21
3.10 ExcepcionPasarelaErrorFirma........................................................................... 21
4 INFORMACIÓN ADICIONAL DEL SERVICIO.......................................................... 22
4.1 Códigos de respuesta del Servicio de Pago Telemático......................................22
4.2 Códigos de retorno de la entidades financieras...................................................27
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.
2
VERSIÓN DEL SERVICIO
Este documento corresponde a la versión 2.1 del servicio en la arquitectura de Platino
2.0.
3
CASOS DE USO
A continuación se muestra el diagrama de casos de uso del servicio de Pasarela de
Pago:
Estos casos de uso han dado lugar a la siguiente interfaz de servicio:
Operaciones
3.1
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.
3.1.1
Interfaz
3.1.2
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
Descripción
verificacionNRCXml
String que contiene los datos necesarios para comprobar la validez del
NRC
El xml de entrada debe corresponderse con el siguiente esquema.
peticion_verificacion.xsd
<xs:schema
version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<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>
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
N
Código emisor del Gobierno de Canarias, debe asignarse el
valor 65006.
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.
Autoliquidaciones 9054258
Liquidaciones 9054357
fechaOperacion
N(8)
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
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>0411864306474223E54B16</nrc>
<organismoEmisor>65006</organismoEmisor>
<codigoOrganismo>GOB_CANARIAS</codigoOrganismo>
<cpr>9053466</cpr>
<fechaOperacion>20140714</fechaOperacion>
<justificante>4118643064742</justificante>
<nif>44444444A</nif>
</peticionVerificacion>
3.1.3
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.
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="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns2:verificarNRCResponse xmlns:ns2="http://platino.gobcan.es/servicios/pasarelaPagosTelematico">
<return>true</return>
</ns2:verificarNRCResponse>
</soapenv:Body>
</soapenv:Envelope>
3.1.4
Excepciones
Este servicio puede lanzar las siguientes excepciones en caso de encontrar errores
•
MalFormedXmlDatosException
•
InvalidParameterValueException
3.2
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.
3.2.1
Interfaz.
3.2.2
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="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pas="http://platino.gobcan.es/servicios/pasarelaPagos">
<soapenv:Header/>
<soapenv:Body>
<pas:getVersion/>
</soapenv:Body>
</soapenv:Envelope>
3.2.3
Salida del servicio
Ejemplo de salida del servicio.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns2:getVersionResponse xmlns:ns2="http://platino.gobcan.es/servicios/pasarelaPagosTelematico">
<return>1.20140729.0</return>
</ns2:getVersionResponse>
</soapenv:Body>
</soapenv:Envelope>
3.3
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.
3.3.1
Interfaz
3.3.2
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:
Parámetro
Descripción
datosPagoXml
String que contiene los datos de la solicitud del pago rellenas por el
ciudadano
firma
Bytes de la firma en formato CAdES realizada por el usuario, del String
datosPagoXml.
norma
Valor correspondiente a la norma 65, siguiendo la especificación de
Red.es.
modalidad
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.
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="http://www.w3.org/2001/XMLSchema">
<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">
<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
idAplicacion
TIPO
DESCRIPCIÓN
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 65006.
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 débito
3 = Pago con tarjeta crédito
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
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:
•
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
•
•
•
3.3.3
“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
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.
A continuación vemos los valores que podemos esperar al realizar un pago.
NOMBRE
DESCRIPCIÓN
codigoRespuesta
Código de respuesta
Telemático(SPT)
descripcionRespuesta
Descripción de la respuesta devuelta por el Servicio de Pagos
Telemático(SPT)
cpr
Código de procedimiento de recaudación del pago.
tipoPeticion
Tipo de petición, devuelto por la EEFF (alta de un pago)
medioPago
Identificador medio de pago:
1 = Cargo en cuenta
2 = Pago con tarjeta
numeroMedioPago
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
importeOperacion
Importe de la operación de pago
nifPrimerRepresentante
NIF/CIF/NIE del primer representante (titular de la cuenta)
nifSegundoRepresentante
NIF/CIF/NIE del segundo representante
contribuyente
Apellidos y nombres del contribuyente
primerRepresentante
Apellidos y nombre del primer representante (titular de la cuenta)
segundoRepresentante
Apellidos y nombre del segundo representante
codigoOrganismo
Organismo admitido en la Pasarela
modelo
Modelo admitido por la Pasarela para el Organismo indicado
ejercicio
Valor del ejercicio fiscal con formato AAAA
periodo
Valor del periodo con formato MM
nifContribuyente
NIF del contribuyente
nifSolicitante
NIF del solicitante del pago
anagrama
Anagrama fiscal del contribuyente
codigoTerritorial
Valor del código territorial
fechaDevengo
Fecha de devengo con formato AAAAMMDD
justificante
Número de justificante que identifica unívocamente la operación de
pago.
info
Reservada para información específica
conceptoAutoliquidacion
Concepto de la autoliquidación
datosOrganismo
Reservada para el uso del organismo
acreditacionTerceros
Indica si el representante está autorizado a realizar el pago en
nombre del contribuyente.
1 = tercero autorizado.
0 = tercero no autorizado.
devuelto
por
el
Servicio
de
Pagos
nrc
NRC correspondiente a la operación de pago
codigoRetorno
Código de retorno de la entidad financiera
fechaOperacion
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="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:pagoFirmadoResponse xmlns:ns2="http://platino.gobcan.es/servicios/pasarelaPagosTelematico">
<return>
<codigoOrganismo>65006</codigoOrganismo>
<codigoRespuesta>OK</codigoRespuesta>
<codigoRetorno>00</codigoRetorno>
<codigoTerritorial>065021</codigoTerritorial>
<cpr>9054258</cpr>
<datosOrganismo>65006</datosOrganismo>
<descripcionConcepto>0001</descripcionConcepto>
<descripcionRespuesta>Operación finalizada OK</descripcionRespuesta>
<ejercicio>2014</ejercicio>
<fechaDevengo>20130429</fechaDevengo>
<fechaOperacion>20140718</fechaOperacion>
<idPasarela>01</idPasarela>
<importeOperacion>12.5</importeOperacion>
<justificante>4113731827222</justificante>
<medioPago>1</medioPago>
<modelo>411</modelo>
<nifContribuyente>44444444A</nifContribuyente>
<nifSolicitante>44444444A</nifSolicitante>
<nrc>04113731827222B661E9D6</nrc>
<numeroMedioPago>ES70null</numeroMedioPago>
<periodo>01</periodo>
<reservada>1GOB_CANARIAS
ES70</reservada>
<tipoPeticion>01</tipoPeticion>
</return>
</ns2:pagoFirmadoResponse>
</soap:Body>
</soapenv:Envelope>
3.3.4
Excepciones
Este servicio puede lanzar las siguientes excepciones en caso de encontrar errores
•
Exception
•
MalFormedXmlDatosException
•
InvalidParameterValueException
•
ExcepcionPasarelaFirmaInvalida
•
ExcepcionPasarelaFirmaError
3.4
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.
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
3.5
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.
3.5.1
Interfaz:
3.5.2
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
Descripción
datosBusquedaXml
String que contiene los datos necesarios para realizar la búsqueda
deseada.
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="http://www.w3.org/2001/XMLSchema">
<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
NRC
N(22)
DESCRIPCIÓN
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
N
Número del lote que queremos consultar. Obligatorio
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
idLote
referencia
N(12-13)
superOrganismo
AN(20)
N – Numérico
An – AlfaNumérico
Código emisor del Gobierno de Canarias, debe
asignarse el valor 65006.
Campo identificador de un pago. Habrá sido
generado previamente por el Organismo Emisor.
Código de súperorganismo
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="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pas="http://platino.gobcan.es/servicios/pasarelaPagosTelematico">
<soapenv:Header/>
<soapenv:Body>
<pas:busquedaSPT>
<!--Optional:-->
<datosBusquedaXml><![CDATA[<peticionNorma65>
<idAplicacion>AP001</idAplicacion>
<organismoEmisor>65006</organismoEmisor>
<codigoOrganismo>GOB_CANARIAS</codigoOrganismo>
<cpr>9054258</cpr>
<importeOperacion>12.5</importeOperacion>
<codigoEntidad>2100</codigoEntidad>
<acreditacionTerceros>0</acreditacionTerceros>
<medioPago>1</medioPago>
<numeroMedioPago>ES2821000555350201327185</numeroMedioPago>
<modelo>620</modelo>
<concepto>0000</concepto>
<ejercicio>2014</ejercicio>
<periodo>01</periodo>
<justificante>6200559545092</justificante>
<anagrama>
</anagrama>
<codigoTerritorial>103507</codigoTerritorial>
<fechaDevengo>20140329</fechaDevengo>
<contribuyente>Apellido1PF1 Apellido2PF1 NombrePF1</contribuyente>
<nifContribuyente>44444444A</nifContribuyente>
<nifSolicitante>44444444A</nifSolicitante>
</peticionNorma65>]]></datosBusquedaXml>
</pas:busquedaSPT>
</soapenv:Body>
</soapenv:Envelope>
3.5.3
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 3.3.3.
Ejemplo de Salida
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:busquedaSPTResponse xmlns:ns2="http://platino.gobcan.es/servicios/pasarelaPagosTelematico">
<return>
<acreditacionTerceros>0</acreditacionTerceros>
<anagrama></anagrama>
<codigoOrganismo>65006</codigoOrganismo>
<codigoRespuesta>OK</codigoRespuesta>
<codigoRetorno>00</codigoRetorno>
<codigoTerritorial>103507</codigoTerritorial>
<cpr>9054258</cpr>
<datosOrganismo>65006</datosOrganismo>
<descripcionConcepto>0000</descripcionConcepto>
<descripcionRespuesta>Operación finalizada OK</descripcionRespuesta>
<ejercicio>2014</ejercicio>
<fechaDevengo>20140329</fechaDevengo>
<fechaOperacion>20140625</fechaOperacion>
<idPasarela>01</idPasarela>
<importeOperacion>12.5</importeOperacion>
<justificante>6200559545092</justificante>
<medioPago>1</medioPago>
<modelo>620</modelo>
<nifContribuyente>44444444A</nifContribuyente>
<nifSolicitante>44444444A</nifSolicitante>
<nombreContribuyente>Apellido1PF1 Apellido2PF1 NombrePF1</nombreContribuyente>
<nrc>06200559545092329AA926</nrc>
<numeroMedioPago>ES2821000555350201327185</numeroMedioPago>
<periodo>01</periodo>
<reservada>1GOB_CANARIAS
ES28</reservada>
<tipoPeticion>01</tipoPeticion>
</return>
</ns2:busquedaSPTResponse>
</soap:Body>
</soap:Envelope>
3.5.4
Excepciones:
Este servicio puede lanzar las siguientes excepciones en caso de encontrar errores:
3.6
•
Exception
•
MalformedXMLDatosException
•
InvalidParameterValueException
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.
3.9
ExcepcionPasarelaFirmaInvalida
Esta excepción será lanzada, cuando la firma del xml que se recibe como parámetro,
no sea válida.
3.10
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.
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
DESCRIPCIÓN
EF
Error devuelto y controlado por la EEFF.
J0
Error en el campo nif de certificado es obligatorio y no ha sido informado.
J1
Error en el campo nif de certificado no contiene un valor válido.
J2
Error en el campo fecha es obligatorio y no ha sido informado.
J3
Error en el campo fecha no contiene un valor válido.
J4
Error en el campo hora es obligatorio y no ha sido informado.
J5
Error en el campo hora no contiene un valor válido.
J6
Error en el campo CPR es obligatorio y no ha sido informado.
J7
Error en el campo CPR no contiene un valor válido.
J8
Error en el campo pasarela es obligatorio y no ha sido informado.
J9
Error en el campo pasarela no contiene un valor válido.
JA
Error en el campo tipo de petición es obligatorio y no ha sido informado.
JB
Error en el campo tipo de petición no contiene un valor válido.
JC
Error en el campo código de la entidad financiera es obligatorio y no ha sido
informado.
JD
Error en el campo código de la entidad financiera no contiene un valor válido.
JE
Error al validar la MAC de la Fecha y Hora es un dato incorrecto.
JF
Error en el campo código identificador medio de pago es obligatorio y no ha
sido informado.
JG
Error en el campo código identificador medio de pago no contiene un valor
válido.
JH
Error en el campo tipo medio de pago (Código Cuenta Cliente o Número de
tarjeta) es obligatorio y no ha sido informado.
JI
Error en el campo tipo medio de pago (Código Cuenta Cliente o Número de
tarjeta) no contiene un valor válido.
JJ
Error en el campo Fecha de caducidad es obligatorio y no ha sido informado.
JK
Error en el campo importe es obligatorio y no ha sido informado.
JL
Error en el campo importe no contiene un valor válido.
JM
Error en el campo nif del representante 1 no contiene un valor válido.
JN
Error en el campo nif del representante 2 no contiene un valor válido.
JO
Error en el campo nombre del representante 1 no contiene un valor válido
(Supera los 40 caracteres).
JP
Error en el campo nombre del representante 2 no contiene un valor válido
(Supera los 40 caracteres)
JQ
Error en el campo nombre del contribuyente no contiene un valor válido
(Supera los 40 caracteres).
JR
Error en el campo reservado es obligatorio y no ha sido informado.
JS
Error en el campo reservado no contiene un valor válido.
JT
Error en el campo código de organismo en el campo reservado contiene un
valor no válido.
JU
Error en el campo código del organismo emisor es obligatorio y no ha sido
informado.
JV
Error en el campo superorganismo no contiene un valor válido.
JW
Error en el campo organismo emisor no contiene un valor válido.
JX
Error en el campo idioma es obligatorio y no ha sido informado.
JY
Error en el campo idioma no contiene un valor válido.
JZ
Error en el campo url es obligatorio y no ha sido informado.
K0
Error en el campo url no contiene un valor válido.
K1
Error en el campo Referencia es obligatorio y no ha sido informado.
K2
Error en el campo Referencia no contiene un valor válido.
K3
Error en el campo (ident1) la primera parte de la identificación es obligatorio y
no ha sido informado
K4
Error en el campo (ident1) la primera parte de la identificación no contiene un
valor válido.
K5
Error en el campo (ident2) la segunda parte de la identificación es obligatorio y
no ha sido informado.
K6
Error en el campo (ident2) la segunda parte de la identificación no contiene un
valor válido.
K7
Error en el campo Concepto no contiene un valor válido.
K8
Error en el campo código domiciliación es obligatorio y no ha sido informado.
K9
Error en el campo código domiciliación no contiene un valor válido.
KA
Error en el campo ccc de domiciliación es obligatorio y no ha sido informado.
KB
Error en el campo ccc de domiciliación no contiene un valor válido.
KC
Error en el campo justificante es obligatorio y no ha sido informado.
KD
Error en el campo justificante no contiene un valor válido.
KE
Error en el campo nif contribuyente es obligatorio y no ha sido informado.
KF
Error en el campo nif contribuyente no contiene un valor válido.
KG
Error en el campo código de modelo es obligatorio y no ha sido informado.
KH
Error en el campo código de modelo no contiene un valor válido.
KI
Error en el campo acreditación de pagos por cuenta de terceros es obligatorio y
no ha sido informado.
KJ
KError en el campo acreditación de pagos por cuenta de terceros no contiene
un valor válido.
KK
Error en el campo la acreditación de pagos por cuenta de terceros el
NIF_CERTIFICADO es distinto del NIF_CONTRIBUYENTE.
KL
Error en el campo expediente no contiene un valor válido.
KM
Error en el campo fecha de devengo no contiene un valor válido.
KN
Error en el campo información específica no contiene un valor válido.
KO
Error en el campo anagrama fiscal es obligatorio y no ha sido informado.
KP
Error en el campo anagrama fiscal no contiene un valor válido.
KQ
Error en el campo código territorial no contiene un valor válido.
KR
Error en el campo concepto autoliquidación no contiene un valor válido.
KS
Error en el campo identificación no contiene un valor válido.
KT
El cuaderno no tiene un código de organismo válido.
KU
El SOAP recibido es incorrecto.
KV
La petición no viene firmada.
KW
No se pudo conectar con ASF.
KX
No viene un nif del certificado en el pago.
KY
Pago firmado por más de dos firmantes. Error de validación.
KZ
Número de serie no validado contra el superorganismo.
L0
Error al obtener del repositorio los datos del organismo.
L1
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.
L2
No coinciden el número de serie del certificado con el existente en la B.B.D.D
L3
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.
L4
No coincide el número de serie de ningún firmante con el que está configurado
para el organismo.
L5
Certificado no autorizado para el pago.
L6
Verificación NO correcta.
L7
Error detectado en la aplicación de firma webservice.
L8
Firma No Válida.
L9
Certificado no válido (Intervalo de validez incorrecto).
LA
Certificado no verificado (la firma de la CA sobre el mismo no es correcta).
LB
Certificado revocado (el certificado ha sido revocado, posteriormente se
añadirán a este código las razones de revocación).
LC
El estado de revocación del certificado no se ha podido verificar.
LE
El uso del certificado en esta aplicación y operación no es válido.
LF
El algoritmo de firma no está definido.
LG
El algoritmo de firma no es valido.
LH
El certificado no se encontró.
LI
Formato de la firma es incorrecto.
LJ
No se encontró la cadena del certificado de la firma.
LK
Los datos del pago no han superado la validación XSS.
LL
El dígito de control del campo Justificante no es válido.
LM
El dígito de control del campo Referencia no es válido.
LQ
No se ha informado del IBAN asociado al CCC.
LR
No se ha informado del IBAN asociado a la CCC domiciliada.
LS
Error en el código IBAN asociado al CCC.
LT
Error en el código IBAN asociado al CCC domiciliada.
LU
Error no hay un CCC pero se informan de un código IBAN.
LV
Error no hay un CCC Domiciliada pero se informan de un código IBAN.
OK
Operación finalizada OK
4.2
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
00
DESCRIPCIÓN
Operación finalizada OK
1
Número de justificante o importe erróneo o ausente
2
Modelo o tipo de operación no soportado
3
Solicitud anulada
4
El certificado firmante no está autorizado para realizar el pago por personas
ajenas
5
El representante del certificado firmante no está autorizado para realizar el pago
por personas ajenas
6
El certificado firmante no está autorizado para pagar y presentar este modelo
7
El certificado firmante no está autorizado para realizar este pago por convenio
8
La entidad emisora de esta tarjeta no admite este tipo de servicio
10
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
35
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 02
56
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
60
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
85
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
NRC no existe
A6
NIF no existe
A7
NRC ya constituido. Inténtelo por consulta
A8
NRC no preconstituido. Inténtelo por consulta
A9
NRC ya existe
B6
NRC no disponible para devolución
B8
NRC ya liberado
C1
Incoherencia de datos
C2
NRC de operación ya existe
F2
NRC no disponible para devolución, ya devuelto
H4
Imposible cobro, NRC ya cobrado
I3
Dígito de control erróneo.
I4
Carácter de control erróneo.
I6
Error en el modelo de operación.
I7
Error en el código del Banco de España.
I8
Error en el código IBAN