Integración SEPA

  1. Introducción
  2. Operaciones SEPA
    1. Método sepaOperations
  3. Documentación SEPA
    1. Método add_document
    2. Método check_document
    3. Método check_customer
  4. Documentación mínima para cada tipo de forma legal
  5. Ejemplo para añadir y comprobar documentos SEPA
  6. Anexos
    1. Anexo I - Tipos de documento
    2. Anexo II - 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 para la carga de operaciones está disponible en las integraciones REST y XML.

Método sepaOperations

La llamada a este método permitirá el envío de la información asociada a las operaciones SEPA de 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.

A continuación, selecciona el tipo de integración:

La integración de esta función en REST está detallado en su documentación completa, disponible en este enlace

https://api.paycomet.com/gateway/xml-sepa?wsdl

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:
2 – Transferencia (N34)
Obligatorio. Tipo de operación. Identifica la operación como 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 ordenante en una operación SEPA.
uniqueIdCreditor Obligatorio. Será el identificador único de ese particular, autónomo, empresa beneficiaria 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 beneficiario.
swiftCodeCreditor Código SWIFT de la cuenta bancaria del 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 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 CÓDIGOS DE ERROR.
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 ENTIDAD DE PAGO, S.L.
 * @copyright Copyright (c) 2019, PAYTPV ONLINE ENTIDAD DE PAGO, 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?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 REST y XML, indistintamente.

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.

A continuación, selecciona el tipo de integración:

La integración de esta función en REST está detallado en su documentación completa, disponible en este enlace

https://api.paycomet.com/gateway/xml-sepa-documentation?wsdl

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 En caso de error, devuelve el identificador del error obtenido. Ver CÓDIGOS DE ERROR.

Cálculo firma add_document

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);

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.

A continuación, selecciona el tipo de integración:

La integración de esta función en REST está detallado en su documentación completa, disponible en este enlace

https://api.paycomet.com/gateway/xml-sepa-documentation?wsdl

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 En caso de error, devuelve el identificador del error obtenido. Ver CÓDIGOS DE ERROR.

Cálculo firma check_document

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);

Método check_customer

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

A continuación, selecciona el tipo de integración:

La integración de esta función en REST está detallado en su documentación completa, disponible en este enlace

https://api.paycomet.com/gateway/xml-sepa-documentation?wsdl

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.
MERCHANT_CUSTOMER_TYPE Integer Identificador del tipo de figura jurídica en PAYCOMET. 1: Particular / 2: Autónomo / 3: Sociedad Mercantil.
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.
DOCUMENTS String Cadena de texto en formato JSON con la información del estado de los documentos. La información contiene el identificador del tipo de documento y un valor booleando para identificar si está verificado o no.
Ver TIPOS DE DOCUMENTO.
ERROR_ID Integer En caso de error, devuelve el identificador del error obtenido. Ver CÓDIGOS DE ERROR.

Cálculo firma check_customer

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 + PROVIDER_PASSWORD )

PHP


<?php
$data['SIGNATURE'] = hash('sha512', $data['SEPA_PROVIDER_ID'] . $data['MERCHANT_CODE'] . $data['MERCHANT_CUSTOMER_ID'] . $data['MERCHANT_CUSTOMER_IBAN'] . $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

Ejemplo para añadir y comprobar documentos SEPA

<?php
/**
 * Test para añadir y comprobar documentos SEPA
 * Documentación y especificaciones: https://docs.paycomet.com/es/documentacion/sepa
 *
 * @author PAYCOMET
 * @copyright Copyright (c) 2020, PAYCOMET
 */

date_default_timezone_set("Europe/Madrid");

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

$endpoint = "https://api.paycomet.com/gateway/xml-sepa-documentation?wsdl";

$context = stream_context_create([
    "ssl" => [
        "verify_peer" => false,
        "verify_peer_name" => false,
        "allow_self_signed" => true
    ]
]);

$options = [
    "use" => "literal",
    "stream_context" => $context
];

########################
##### add_document #####
########################
$fileContent = base64_encode(
    file_get_contents("path_to_file.pdf")
);

$params = [];
$params["SEPA_PROVIDER_ID"] = "*** YOUR PROVIDER ID ***";
$params["MERCHANT_CODE"] = "*** YOUR MERCHANT CODE ***";
$params["MERCHANT_CUSTOMER_ID"] = "*** YOUR CUSTOMER ID";
$params["MERCHANT_CUSTOMER_IBAN"] = "ES*******************";
$params["DOCUMENT_TYPE"] = "*** YOUR DOCUMENT TYPE ID ***";
$params["FILE_CONTENT"] = $fileContent;

$providerPassword = "*** YOUR PROVIDER PASSWORD ***";
$params["SIGNATURE"] = hash("sha256", $params["SEPA_PROVIDER_ID"] . $params["MERCHANT_CODE"] . $params["MERCHANT_CUSTOMER_ID"] . $params["MERCHANT_CUSTOMER_IBAN"] . $params["DOCUMENT_TYPE"] . $providerPassword);

$client = new SoapClient($endpoint, $options);
$response = $client->add_document($params["SEPA_PROVIDER_ID"], $params["MERCHANT_CODE"], $params["MERCHANT_CUSTOMER_ID"], $params["MERCHANT_CUSTOMER_IBAN"], $params["DOCUMENT_TYPE"], $params["FILE_CONTENT"], $params["SIGNATURE"]);
var_dump($response);
die();


##########################
##### check_document #####
##########################
$params = [];
$params["SEPA_PROVIDER_ID"] = "*** YOUR PROVIDER ID ***";
$params["MERCHANT_CODE"] = "*** YOUR MERCHANT CODE ***";
$params["MERCHANT_CUSTOMER_ID"] = "*** YOUR CUSTOMER ID";
$params["MERCHANT_CUSTOMER_IBAN"] = "ES*******************";
$params["DOCUMENT_TYPE"] = "*** YOUR DOCUMENT TYPE ID ***";
$providerPassword = "*** YOUR PROVIDER PASSWORD ***";
$params["SIGNATURE"] = hash("sha256", $params["SEPA_PROVIDER_ID"] . $params["MERCHANT_CODE"] . $params["MERCHANT_CUSTOMER_ID"] . $params["MERCHANT_CUSTOMER_IBAN"] . $params["DOCUMENT_TYPE"] . $providerPassword);

$client = new SoapClient($endpoint, $options);
$response = $client->check_document($params["SEPA_PROVIDER_ID"], $params["MERCHANT_CODE"], $params["MERCHANT_CUSTOMER_ID"], $params["MERCHANT_CUSTOMER_IBAN"], $params["DOCUMENT_TYPE"], $params["SIGNATURE"]);
var_dump($response);
die();

Anexos

Anexo I - 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
22 Estados financieros, declaraciones de IVA e Impuesto de Sociedades ejercicio anterior
23 Tarjeta de identificación fiscal
24 Escritura de poderes

Anexo II - Estados de documento

DOCUMENT_STATUS Descripción
2 En revisión
3 Verificado