Integración SEPA XML

  1. Introducción
  2. Operaciones SEPA
    1. Método sepaOperations
    2. Cálculo firma
    3. Ejemplo de inserción de operaciones SEPA
  3. Documentación SEPA
    1. Método add_document
    2. Método check_document
    3. Cálculo firma
    4. Documentación mínima para cada tipo de forma legal
    5. Tipos de documento
    6. Estados de documento

Introducción

Se detalla la operativa para poder enviar a PAYCOMET los datos de las operaciones a realizar bajo el marco SEPA, así como la documentación requerida para los destinatarios de dichas operaciones, a través de los webservices habilitados a tal efecto.

La comunicación se realizará mediante protocolo SSL, rechazando activamente cualquier envío de información no securizado.

Se facilitarán los siguientes datos por parte de PAYCOMET para la correcta integración:

  • ID de proveedor.
  • PASSWORD de proveedor (con el que securizar las firmas).

En la mayoría de los casos se recomienda integrar en primer lugar la parte de documentación SEPA, puesto que lo primero que se debe hacer es subir la documentación. Posteriormente se puede integrar la operativa de operaciones.

Al subir la documentación, si el sistema no es capaz de verificar el documento, el proceso de verificación puede demorarse entre 24 y 48 horas.

Operaciones SEPA

El acceso al servicio se realiza mediante SOAP, en la siguiente URL:

https://api.paycomet.com/gateway/xml_sepa.php?wsdl

Método sepaOperations

La llamada a este método permitirá el envío de la información asociada a las operaciones SEPA: Adeudos Directos o Transferencias, entre productos de la misma cuenta. Todos los campos están declarados como string y son obligatorios; si en alguna de las operaciones, alguno de ellos no tuviese información, deberá enviarse como un string vacío.

Parámetros de entrada:

Elemento Contenido Descripción
providerID Obligatorio. El identificador único asignado por PAYCOMET para el proveedor de envío de operaciones SEPA. Disponible en el panel de control de clientes.
operations Array Obligatorio. Array de operaciones que se informan.

El array de operations deberá tener la siguiente forma:

Elemento Contenido Descripción
operationType Tipos de operaciones:
1 – Adeudo Directo (N19)
2 – Transferencia (N34)
Obligatorio. Tipo de operación. Identifica si la operación es un adeudo directo o una transferencia.
merchantCode Obligatorio. Código de cliente. Se obtiene del panel de control.
terminalIDDebtor Obligatorio. Será el número de terminal asignado al producto. Se obtiene del panel de control.
Identifica el número de terminal del deudor/ordenante en una operación SEPA. Por lo tanto, dependerá del tipo de operación (adeudo, transferencia).
uniqueIdCreditor Obligatorio. Será el identificador único de ese particular, autónomo, empresa (acreedor/beneficiario) en el cliente.
companyNameCreditor Obligatorio. Nombre de la empresa, particular o autónomo correspondiente al indicador anterior.
ibanNumberCreditor Obligatorio. Código IBAN de la cuenta del acreedor/beneficiario.
swiftCodeCreditor Código SWIFT de la cuenta bancaria del acreedor/beneficiario. Deberá proporcionarse cuando la cuenta IBAN no sea española. Si el número ibanNumberCreditor pertenece a una cuenta española, debe enviarse como string vacía.
companyTypeCreditor Obligatorio. Identificador del tipo de acreedor/beneficiario: 1: Particular / 2: Autónomo / 3: Sociedad Mercantil.
operationOrder Referencia única de la operación.
operationAmount Obligatorio. Importe en la moneda de la transacción con 2 decimales en formato entero: (2,25 € = 225).
operationCurrency Obligatorio. Tipo de moneda de la transacción. La única divisa permitida es el euro, cuyo código es "EUR".
operationDatetime Obligatorio. Fecha en la que se quiere enviar la operación / remesa SEPA. Siempre posterior al día actual.

Formato: yyyymmdd.
operationConcept Obligatorio. Concepto que se le asignará a la operación / remesa. Es el descriptor que aparecerá en los apuntes bancarios. Longitud máxima 100. Aunque el error 1273 especifica 140 caracteres, PAYCOMET reserva 40, de ahí que el máximo permitido en la entrada sea de 100.
operationSignature Obligatorio. Firma para comprobar la validez de esa operación. Se calculará conforme a lo expuesto en CÁLCULO DE LA FIRMA.

Parámetros de respuesta:

Elemento Contenido Descripción
operationResult OK|KO Resultado de la operación.
operationErrorCode [0-9]{1-4} En caso de operationResult KO, devuelve el ID del error obtenido. Ver ANEXO II TABLA DE ERRORES MÉTODO sepaOperations.
operationOrder Referencia única de la operación.

array (size=2)
	0 => object(sepaOperationResponseClass)[7]
		public 'operationResult' => string 'OK' (length=2)
		public 'operationErrorCode' => string '' (length=0)
		public 'operationOrder' => string 'AV-PROD-TEST-9987023' (length=20)
	1 => object(sepaOperationResponseClass)[30]
		public 'operationResult' => string 'KO' (length=2)
		public 'operationErrorCode' => string '1026' (length=4)
		public 'operationOrder' => string 'AV-PROD-TEST-9987023' (length=20)

Cálculo firma

El cálculo de la firma para cada una de las operaciones que se quiera notificar se realizará de la siguiente forma:

En pseudocódigo:

plainSignature = operationOrder + operationType + operationAmount + operationCurrency + providerID + merchantCode + terminalIDDebtor + uniqueIdCreditor + ibanNumberCreditor + swiftCodeCreditor + companyTypeCreditor + PASSWORD
finalSignature = TOUPPER(SHA512(plainSignature))

En código PHP:


<?php
$plainSignature = ($operation->operationOrder . $operation->operationType . $operation->operationAmount . $operation->operationCurrency . $providerID . $merchantCode . $operation->terminalIDDebtor . $operation->uniqueIdCreditor . $operation->ibanNumberCreditor . $operation->swifCodeCreditor . $operation->companyTypeCreditor . $providerPassword);

$signature = strtoupper(hash('sha512', $plainSignature));

Ejemplo de inserción de operaciones SEPA

<?php
/**
 * Test para inserción de operaciones sepa
 * Documentación y especificaciones: https://docs.paycomet.com/es/documentacion/sepa
 *
 * Tracking ID: BGD-2G6-2BB6
 *
 * @author PAYTPV ONLINE, S.L.
 * @copyright Copyright (c) 2016, PAYTPV ONLINE, S.L.
 * @version 1.0 2016-01-28
*/

date_default_timezone_set("Europe/Madrid");

$timeStart = microtime(true);

// Si se utiliza xdebug
ini_set("xdebug.var_display_max_data",-1);
ini_set("xdebug.var_display_max_children",-1);
ini_set("xdebug.var_display_max_depth",-1);

ini_set("soap.wsdl_cache_enabled", 0);
ini_set("soap.wsdl_cache_ttl", 0);
ini_set("soap.wsdl_cache_limit",0);

class sepaOperations {
	public $providerID			= 0;
	public $operationsArray		= array();
}

class operation {
	public $operationType;
	public $merchantCode;
	public $terminalIDDebtor;
	public $terminalIDCreditor;
	public $operationOrder;
	public $operationAmount;
	public $operationCurrency;
	public $operationDatetime;
	public $operationConcept;
	public $operationSignature;
}

$endPoint	= "https://api.paycomet.com/gateway/xml_sepa.php?wsdl";

$providerID	= "incluirProviderID";
$password	= "incluirProviderPassword";

$client = new SOAPClient($endPoint);

$numOperations	= 1; // Ejemplo para una operación

//-------------------------------------------------------------- sepaOperations ------------------------------------------------------------------->

$arrOperations	= array();

for ($n=1;$n<=$numOperations;$n++) {

	$operation = new operation();

	$operation->operationType		= "2";                                                                      // 2: Transferencia (N34)
	$operation->merchantCode		= "incluirMerchantCode";                                                    // Código de cliente. Se obtiene del panel de control.
	$operation->terminalIDDebtor	= "incluirTerminalIdDelDeudor";                                             // Será el número de terminal asignado al producto. Se obtiene del panel de control.
	$operation->uniqueIdCreditor	= "incluirIdentificadorUnicoDeClienteEnVuestroSistema";                     // Será el identificador único de ese particular, autónomo, empresa en vuestro sistema
	$operation->companyNameCreditor = "incluirNombreDeCliente";                                                 // Nombre de la empresa, particular o autónomo correspondiente al indicador anterior
	$operation->ibanNumberCreditor	= "incluirIBANValido";                                                      // Código IBAN de la cuenta del beneficiario.
	$operation->swiftCodeCreditor	= "";                                                                       // Código SWIFT de la cuenta bancaria del beneficiario. Recomendable en cuentas IBAN no españolas.
	$operation->companyTypeCreditor = 3;                                                                        // 1: Particular, 2: Autónomo, 3: Sociedad Mercantil
	$operation->operationOrder		= "SEPA TRANSFER-".date("Ymd H:i:s") . substr((string)microtime(), 1, 8);   // Referencia única de la operación.
	$operation->operationAmount		= "1000";                                                                   // Importe en la moneda de la transacción con 2 decimales en formato entero: (2,25 € = 225).
	$operation->operationCurrency	= "EUR";                                                                    // Tipo de moneda de la transacción. La única divisa permitida es el euro, cuyo código es "EUR"
	$operation->operationDatetime	= "20190712";                                                               // yyyyymm, fecha en la que se quiere enviar la operación / remesa SEPA. Siempre posterior al día actual
	$operation->operationConcept	= "Transferencia de XXXXXXXXX - a XXXXXXXXX: ".rand(0,9999);                // Descriptor que aparecerá en los apuntes bancarios. Longitud máxima 100 caracteres

	// Cálculo de firma
	$plainSignature = ($operation->operationOrder.$operation->operationType.$operation->operationAmount.$operation->operationCurrency.$providerID.$operation->merchantCode.$operation->terminalIDDebtor.$operation->uniqueIdCreditor.$operation->ibanNumberCreditor.$operation->swiftCodeCreditor.$operation->companyTypeCreditor.$password);
	$signature = strtoupper(hash("sha512" ,$plainSignature));
	$operation->operationSignature	= $signature;

	// Porque en caso de arrays de un solo elemento, no asigna $key numérica.
	$arrOperations[$n] = $operation;
}

//--------------------------------------------------------------->

$postData = new sepaOperations();

$postData->providerID		= $providerID;
$postData->operationsArray	= $arrOperations;
var_dump($arrOperations);

$timeRequest = microtime(true);

$response = $client->sepaOperations($postData->providerID, $postData->operationsArray);

$timeResponse = microtime(true);

var_dump($response);

$time = $timeResponse - $timeRequest;
echo "
Número de peticiones: $numOperations - Respuesta en $time"; $timeEnd = microtime(true); ?>

Documentación SEPA

El acceso al servicio se realiza mediante SOAP, en la siguiente URL:

https://api.paycomet.com/gateway/xml_sepa_documentation.php?wsdl

Método add_document

La llamada a este método permitirá el envío de la documentación que se solicita a los clientes que van a hacer uso del servicio de operaciones SEPA. Todos los campos son obligatorios.

Parámetros de entrada:

Elemento Contenido Descripción
SEPA_PROVIDER_ID String Identificador único asignado por PAYCOMET para el proveedor de envío de operaciones SEPA. Disponible en el panel de control de clientes.
MERCHANT_CODE String Identificador único como cuenta en PAYCOMET. Disponible en el panel de control de clientes.
MERCHANT_CUSTOMER_ID String Identificador único del cliente del proveedor.
MERCHANT_CUSTOMER_IBAN String Número de cuenta del cliente en formato IBAN.
DOCUMENT_TYPE Integer Identificador del tipo de documento en PAYCOMET.
Ver TIPOS DE DOCUMENTO.
FILE_CONTENT String Contenido binario del fichero a enviar, codificado en base 64.
SIGNATURE String Firma de la petición.
Ver CÁLCULO DE LA FIRMA.

NOTA: El tamaño máximo del documento está limitado a 8 Mb. Los tipos de documento permitidos son: PDF, DOC, DOCX, ODT, JPG ó PNG.

Parámetros de respuesta:

Elemento Contenido Descripción
MERCHANT_CUSTOMER_ID String Identificador único del cliente del proveedor.
MERCHANT_CUSTOMER_IBAN String Número de cuenta del cliente en formato IBAN.
DOCUMENT_TYPE Integer Identificador del tipo de documento en PAYCOMET.
Ver TIPOS DE DOCUMENTO.
DOCUMENT_STATUS Integer Identificador del estado del documento.
Ver ESTADOS DE DOCUMENTO
ERROR_ID Integer Firma de la petición.
Ver CÁLCULO DE LA FIRMA.

Método check_document

La llamada a este método permitirá consultar el estado de un documento enviado a PAYCOMET para su verificación. Todos los campos son obligatorios.

Parámetros de entrada:

Elemento Contenido Descripción
SEPA_PROVIDER_ID String Identificador único asignado por PAYCOMET para el proveedor de envío de operaciones SEPA. Disponible en el panel de control de clientes.
MERCHANT_CODE String Identificador único como cuenta en PAYCOMET. Disponible en el panel de control de clientes.
MERCHANT_CUSTOMER_ID String Identificador único del cliente del proveedor.
MERCHANT_CUSTOMER_IBAN String Número de cuenta del cliente en formato IBAN.
DOCUMENT_TYPE Integer Identificador del tipo de documento en PAYCOMET.
Ver TIPOS DE DOCUMENTO.
SIGNATURE String Firma de la petición.
Ver CÁLCULO DE LA FIRMA.

Parámetros de respuesta:

Elemento Contenido Descripción
MERCHANT_CUSTOMER_ID String Identificador único del cliente del proveedor.
MERCHANT_CUSTOMER_IBAN String Número de cuenta del cliente en formato IBAN.
DOCUMENT_TYPE Integer Identificador del tipo de documento en PAYCOMET.
Ver TIPOS DE DOCUMENTO.
DOCUMENT_STATUS Integer Identificador del estado del documento.
Ver ESTADOS DE DOCUMENTO
ERROR_ID Integer Firma de la petición.
Ver CÁLCULO DE LA FIRMA.

Cálculo firma

El cálculo de la firma para la petición se realizará de la siguiente forma:

SHA512( SEPA_PROVIDER_ID + MERCHANT_CODE + MERCHANT_CUSTOMER_ID + MERCHANT_CUSTOMER_IBAN + DOCUMENT_TYPE + PROVIDER_PASSWORD )

PHP


<?php
$data['SIGNATURE'] = hash('sha512', $data['SEPA_PROVIDER_ID'] . $data['MERCHANT_CODE'] . $data['MERCHANT_CUSTOMER_ID'] . $data['MERCHANT_CUSTOMER_IBAN'] . $data['DOCUMENT_TYPE'] . $providerPassword);

Documentación mínima para cada tipo de forma legal

Forma legal Documentos
Particular
  • DNI/PASAPORTE (Anverso) Titular real
  • DNI/PASAPORTE (Reverso) Titular real
  • Certificado de titularidad de cuenta
Autónomo
  • DNI/PASAPORTE (Anverso) Titular real
  • DNI/PASAPORTE (Reverso) Titular real
  • Certificado de titularidad de cuenta
  • Recibo autónomos o modelo 36/37
Empresa
  • Certificado de titularidad de cuenta
  • DNI/PASAPORTE (Anverso) Administrador
  • DNI/PASAPORTE (Reverso) Administrador
  • Escrituras de Constitución y otras escrituras relevantes
  • CIF

Tipos de documento

DOCUMENT_TYPE Descripción
1 DNI/PASAPORTE (Anverso) Titular real
2 DNI/PASAPORTE (Reverso) Titular real
3 Certificado de titularidad de cuenta
4 Recibo bancario
5 Recibo autónomos o modelo 36/37
6 DNI/PASAPORTE (Anverso) > 25%
7 DNI/PASAPORTE (Reverso) > 25%
8 DNI/PASAPORTE (Anverso) Administrador
9 DNI/PASAPORTE (Reverso) Administrador
10 Escrituras de apoderamiento
11 Escrituras de Constitución y otras escrituras relevantes
12 CIF
13 Declaración responsable de vigencia de la documentación
14 Certificado de estar al corriente de obligaciones tributarias
15 Licencias de actividad
16 Contrato PAYCOMET
17 Documento SEPA
18 Declaración operativa NO CES
19 Formulario complementario de licencias
20 Factura o recibo acreditativo de los servicios prestados
21 Última declaración del IRPF y de IVA

Estados de documento

DOCUMENT_STATUS Descripción
2 En revisión
3 Verificado