Integración BankStore XML

  1. Introducción
  2. Cobros mediante Operativa DCC
  3. Integración BANKSTORE XML
    1. Ejecución de alta de usuario en el sistema
    2. Información del usuario
    3. Eliminación del usuario
    4. Ejecución de cobro a usuario en el sistema
    5. Ejecución de cobro a Usuario en el sistema por DCC
    6. Confirmación de moneda en pago DCC
    7. Devolución de cobro a usuario en el sistema
    8. Ejecución de alta de suscripción en el sistema
    9. Modificación de suscripción en el sistema
    10. Eliminación de Suscripción
    11. Ejecución de alta de suscripción en el sistema con USERID Y TOKENID
    12. Creación de una preautorización a usuario en el sistema
    13. Confirmación de una preautorización a usuario en el sistema
    14. Cancelación de una preautorización a usuario en el sistema
    15. Confirmación de una preautorización diferida a usuario en el sistema
    16. Cancelación de una preautorización diferida a usuario en el sistema
    17. Ejecución de alta de usuario en el sistema mediante Token
    18. Ejecución de Cobro a un usuario por Referencia
  4. Notificación caducidad tarjeta
    1. Notificación (Llamada a URL)
  5. Anexo I – Cálculo de la firma de comercio – XML Bankstore
  6. Anexo II – Tipos de operaciones

Introducción

La finalidad del presente documento es servir de referencia durante el proceso de integración de un comercio con la pasarela de pagos PAYCOMET, utilizando el sistema BankStore que almacena los datos bancarios de los clientes del comercio.

El uso de algunas operativas, las relacionadas con el uso de información de tarjetas (add_user y create_subscription), supone aceptar el requerimiento por parte del cliente de someterse trimestralmente a SAQ-AEP y escaneos ASV.

Se incluye también un apéndice de referencia y se puede conseguir en la web de PAYCOMET un documento con los códigos de error devueltos por el sistema para simplificar el proceso de depuración.

La integración IFRAME/XML mediante el servicio BankStore permite el acceso a las operaciones de pago sin intervención directa del usuario, ampliando la operativa de cobro individual a una gestión de los datos bancarios del cliente del comercio. Las peticiones parten del servidor del comercio y son procesadas por la pasarela de pago.

La tecnología escogida para la realización de las operaciones es SOAP, basada en XML y que permite el paso seguro por firewalls y a través de la red, además de IFRAME para la captación de los datos de tarjeta.

El servicio BankStore se diferencia por su comunicación entre el comercio y la pasarela aunando información sobre los datos del cliente. El comercio almacena los datos personales de su cliente y PAYCOMET los datos bancarios. Una vez el comercio da de alta el usuario PAYCOMET devuelve un identificador formado por un número único de cliente (IDUSER) y un token (TOKENUSER).

De esta forma el comercio tiene un común identificador con PAYCOMET para realizar gestiones sobre su cuenta de cliente como:

  • Alta de usuario (add_user)
  • Información de Usuario (info_user)
  • Eliminación de Usuario (remove_user)
  • Cobro de Usuario (execute_purchase)
  • Cobro de Usuario con DCC (execute_purchase_dcc)
  • Confirmación de cobro con DCC (confirm_purchase_dcc)

En el mismo servicio se ha añadido la operativa de subscripción. Esta operativa es completamente paralela a la de almacenamiento de datos bancarios del cliente. La gestión de las subscripciones se realizarán con las siguientes funciones:

  • Alta de subscripción (create_subscription)
  • Modificación de subscripción (edit_subscription)
  • Eliminación de subscripción (remove_subscription)

También están presentes las operaciones relacionadas con las preautorizaciones, a través de las funciones:

  • Alta de preautorización (create_preauthorization)
  • Confirmación de preautorizcion (preauthorization_confirm)
  • Anulación de preautorización (preauthorization_cancel)

De esta forma se dividen dos conceptos en el mismo servicio que es necesario aclarar su finalidad y diferencias:

BankStoreBankStore Subscripción
Almacenamiento de datos bancarios de cliente del comercio Gestión de subscripciones con almacenamientos de datos bancarios del cliente del comercio
Ideal para comercios con compra habitual del mismo cliente sin necesidad de volver a introducir los datos de tarjeta Ideal para subscripciones a un servicio pagos a plazos. Importante: PAYCOMET no se hará cargo de las denegaciones de cobro que pudieran ocurrir en las cuotas.
Se pueden realizar devoluciones vía XML SOAP Las devoluciones deben ser realizadas desde el Panel de Control.
El alta de la subscripción puede hacerse mediante XML SOAP o TPV WEB (IFRAME o FULLSCREEN). El alta de la subscripción puede hacerse mediante XML SOAP o TPV WEB (IFRAME o FULLSCREEN).

Cobros mediante Operativa DCC

PAYCOMET permite mediante la operativa de BankStore, realizar transacciones en modalidad DCC (Dynamic Currency Conversion).

La conversión dinámica de moneda (DCC) convierte las compras internacionales con tarjetas de crédito de Visa® y MasterCard® en la moneda local del titular de la tarjeta. Una parte del cargo de conversión se reembolsará al comercio. PAYCOMET administra todo el proceso de conversión; desde tasas de cambios directas del tesoro y procesamiento de transacciones, a conciliación de pagos diferidos, liquidación,financiamiento y apoyo.

Con DCC, los clientes internacionales sabrán exactamente cuánto es el total de la compra en su moneda local. Las tarifas de conversión generalmente son mucho más competitivas que en las empresas de cambio.

Esta operativa debe ser activada antes de su uso, contacta con nosotros para darlo de alta al producto deseado.

La integración DCC difiere de la integración convencional por el uso de un servicio específico para realizar el cobro al cliente. Los servicios dedicados al DCC son:

  • Cobro de Usuario con DCC
  • Confirmación de cobro con DCC

El procedimiento de alta de usuario: add_user, sigue siendo necesario en el caso de compras sin 3D Secure. La diferencia principal es la incorporación de un paso adicional para recibir el cambio disponible de la moneda nativa de la tarjeta en el mismo momento de la transacción:

Integración BANKSTORE XML

Debido a que todo el proceso de pago se realiza en segundo plano (de servidor a servidor) las modificaciones a realizar en el comercio son totalmente ajenas a la experiencia de usuario.

La tecnología empleada para la operativa con la pasarela de pagos PAYCOMET es SOAP, basada en HTTPS para evitar problemas de transporte a través de firewalls y otros dispositivos y a la vez garantizar la seguridad de las operaciones. Existe un soporte muy amplio para la realización de llamadas SOAP para los principales lenguajes de programación usados en entornos web.

Las peticiones se realizan mediante el protocolo de transporte HTTPS, de manera que debe asegurarse que su sistema es capaz de realizar las peticiones correctamente y gestionar los certificados de seguridad devueltos por la plataforma para una correcta utilización.

Existen varias operaciones que se podrán lanzar desde el mismo servicio. Las operaciones disponibles vienen descritas a continuación.

Ejecución de alta de usuario en el sistema

Función: (add_user)

Las variables que se requieren para dar de alta a un usuario con sus datos bancarios son (en este orden):

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_MERCHANT_PAN [0-9]{16,19} Obligatorio. Número de tarjeta, sin espacios ni guiones
DS_MERCHANT_EXPIRYDATE [0-9]{4} Obligatorio. Fecha de caducidad de la tarjeta, expresada como “mmyy” (mes en dos cifras y año en dos cifras)
DS_MERCHANT_CVV2 [0-9]{3,4} Obligatorio. Código CVC2 de la tarjeta
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS
DS_ORIGINAL_IP A.B.C.D Obligatorio. Dirección IP del cliente que inició la operación de pago (propietario de la tarjeta)

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_IDUSER [0-9]{1,13} Identificador único del usuario registrado en el sistema. Volverá vacío en caso de error.
DS_TOKEN_USER [A-Za-z0-9]{1,20} Código token asociado al DS_IDUSER.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.

Si la petición produjo un error de algún tipo (firma incorrecta, importe incorrecto, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá el campo DS_IDUSER y DS_TOKEN_USER que deberán ser almacenados por el comercio, asociándolo a la cuenta de su cliente, para posteriormente realizar cargos en su tarjeta de crédito/débito.

Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:add_user xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_MERCHANT_PAN type="xsd:string"> 1234 5678 9012 3456  </DS_MERCHANT_PAN>
        <DS_MERCHANT_EXPIRYDATE type="xsd:string"> 0535  </DS_MERCHANT_EXPIRYDATE>
        <DS_MERCHANT_CVV2 type="xsd:string"> 123  </DS_MERCHANT_CVV2>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        <DS_ORIGINAL_IP type="xsd:string"> 1.2.3.4  </DS_ORIGINAL_IP>
        <DS_MERCHANT_CARDHOLDERNAME type="xsd:string"> Francisco y Meta  </DS_MERCHANT_CARDHOLDERNAME>
        </mns:add_user>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

function addUser()
{
    $endPoint     = "https:api.paycomet.com/gateway/xml-bankstore?wsdl";
    $merchantCode = "123456";
    $terminal     = "1234";
    $password     = "yourpasswd";

    $signature = hash("sha512",
        $merchantCode
        . $token
        . $jetID
        . $terminal
        . $password
    );
    $ip = $_SERVER["REMOTE_ADDR"];

    try {
        $clientSOAP = new SoapClient($endPoint);

        $addUserResponse
            = $clientSOAP->add_user(
                $merchantCode,
                $terminal,
                $merchantPan,
                $merchantExpiryDate,
                $mtrchantCVV2,
                $signature,
                $ip
            );

        if ($addUserResponse["DS_RESPONSE"] == "1") {
             OK
            return true;
        } else {
            KO
            var_dump($addUserResponse["DS_ERROR_ID"]);
            return false;
        }
    } catch (SoapFault $e) {
        var_dump($e);
    }
}

public ServiceResponse add_user(String[] args) throws Exception {

    String merchantcode = args[0];
    String terminal = args[1];
    String password = args[2];
    String ipaddr = args[3];
    String pan = args[4];
    String expirydate = args[5];
    String cvv2 = args[6];
    String cardholdername = args[7];
    String expirydate = args[8];

    merchantsignature = makeSHA1hash(merchantcode + pan + cvv2 + terminal + password);

    ServiceResponse result = new ServiceResponse();

    SoapObject soapReq = new SoapObject("add_user");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("DS_MERCHANT_PAN", pan);
    soapReq.addProperty("DS_MERCHANT_EXPIRYDATE", expirydate);
    soapReq.addProperty("DS_MERCHANT_CVV2", cvv2);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);
    soapReq.addProperty("DS_ORIGINAL_IP", ipaddr);
    soapReq.addProperty("DS_MERCHANT_CARDHOLDERNAME", cardholdername);

    return callSoap(result, soapReq);

}

Información del usuario

Función: (info_user)

Esta función se utilizará para confirmar a los clientes del comercio la tarjeta a la que se le realizará el cobro. Este paso es opcional pero resulta conveniente para evitar desconfianzas.

Las variables que se requieren para solicitar información de un usuario son (en este orden):

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_IDUSER [0-9]{1,13} Obligatorio. Identificador único del usuario registrado en el sistema.
DS_TOKEN_USER [A-Za-z0-9]{1,20} Obligatorio. Código token asociado al DS_IDUSER.
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS
DS_ORIGINAL_IP A.B.C.D Obligatorio. Dirección IP del cliente que inició la operación de pago (propietario de la tarjeta)

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_MERCHANT_PAN [0-9]{16,19} Número de tarjeta, sin espacios ni guiones. Sólo devolverá los cuatro últimos dígitos. El resto vendrá enmascarado con X.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.
DS_CARD_BRAND [a-zA-Z]{30} Marca de la tarjeta. Si es posible identificarla, se enviará información sobre la marca de la tarjeta (Visa, MasterCard, American Express, etc). En caso contrario, el campo se devolverá en blanco.
DS_CARD_TYPE [a-zA-Z]{20} Tipo de tarjeta. Si es posible identificarla, se enviará información sobre el tipo de tarjeta (DEBIT, CREDIT, etc). En caso contrario, el campo se devolverá en blanco
DS_CARD_I_COUNTRY_ISO3 [a-zA-Z]{3} Código ISO3 del país del emisor de la tarjeta. Si es posible identificarlo, se enviará el código ISO3 del país emisor de la tarjeta. En caso contrario, el campo se devolverá en blanco
DS_EXPIRYDATE [YYYY/MM] Fecha de caducidad de la tarjeta expresada en formato YYYY/MM
DS_CARD_HASH [a-zA-Z0-9]{64} Hash no reversible generado con la información de la tarjeta que la identifica de manera única.
DS_CARD_CATEGORY [a-zA-Z0-9]{16} Categoría de la tarjeta
DS_SEPA_CARD [0-1]{1} Tarjeta pertenece a SEPA

Si la petición produjo un error de algún tipo (firma incorrecta, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error..

En caso de que la transacción sea correcta, el servicio devolverá el campo DS_MERCHANT_PAN que contendrá la tarjeta de crédito/débito enmascarada, dejando visibles sólo los 4 últimos dígitos. Esta operativa es muy útil para mostrarle al cliente del comercio con qué tarjeta se va a realizar la transacción.

Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:info_user xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_IDUSER type="xsd:string"> paycometuserid  </DS_IDUSER>
        <DS_TOKEN_USER type="xsd:string"> paycometusertoken  </DS_TOKEN_USER>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        <DS_ORIGINAL_IP type="xsd:string"> 1.2.3.4  </DS_ORIGINAL_IP>
        </mns:info_user>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

function infoUser()
{
    $endPoint = "https:api.paycomet.com/gateway/xml-bankstore?wsdl";
    $merchantCode = "123456";
    $terminal = "1234";
    $password = "yourpasswd";

    $signature = hash("sha512",
        $merchantCode
        . $token
        . $jetID
        . $terminal
        . $password
    );
    $ip = $_SERVER["REMOTE_ADDR"];

    try {
        $clientSOAP = new SoapClient($endPoint);

        $addUserResponse = $clientSOAP->add_user(
            $merchantCode,
            $terminal,
            $merchantPan,
            $merchantExpiryDate,
            $mtrchantCVV2,
            $signature,
            $ip
        );

        if ($addUserResponse["DS_RESPONSE"] == "1") {
             OK
            $infoUser = $clientSOAP->info_user(
                $merchantCode,
                $terminal,
                $addUserResponse["DS_IDUSER"],
                $addUserResponse["DS_USER_TOKEN"],
                $signature,
                $ip
            );
            var_dump($infoUser);
            return true;
        } else {
            KO
            var_dump($addUserResponse["DS_ERROR_ID"]);
            return false;
        }
    } catch (SoapFault $e) {
        var_dump($e);
    }
}


        
public ServiceResponse info_user(String[] args) {

    String merchantcode = args[0];
    String terminal = args[1];
    String password = args[2];
    String ipaddr = args[3];
    String iduser = args[4];
    String tokenuser = args[5];

    merchantsignature = makeSHA1hash(merchantcode + iduser + tokenuser + terminal + password);

    ServiceResponse result = new ServiceResponse();

    SoapObject soapReq = new SoapObject("info_user");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("DS_IDUSER", iduser);
    soapReq.addProperty("DS_TOKEN_USER", tokenuser);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);
    soapReq.addProperty("DS_ORIGINAL_IP", ipaddr);

    return callSoap(result, soapReq);
}

Eliminación del usuario

Función: (remove_user)

Esta función se utilizará para eliminar un usuario de la cuenta del comercio.

Las variables que se requieren para solicitar la baja de un usuario son (en este orden):

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_IDUSER [0-9]{1,13} Obligatorio. Identificador único del usuario registrado en el sistema.
DS_TOKEN_USER [A-Za-z0-9]{1,20} Obligatorio. Código token asociado al DS_IDUSER.
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS
DS_ORIGINAL_IP A.B.C.D Obligatorio. Dirección IP del cliente que inició la operación de pago (propietario de la tarjeta)

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_RESPONSE [0-1]{1} Resultado de la operación. 0 o vacío será operación errónea y 1 operación completada.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.

Si la petición produjo un error de algún tipo (firma incorrecta, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá el campo DS_RESPONSE cuyo valor será 0 o vacío en caso de error y 1 en caso de éxito en la eliminación.

Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:remove_user xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_IDUSER type="xsd:string"> paycometuserid  </DS_IDUSER>
        <DS_TOKEN_USER type="xsd:string"> paycometusertoken  </DS_TOKEN_USER>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        <DS_ORIGINAL_IP type="xsd:string"> 1.2.3.4  </DS_ORIGINAL_IP>
        </mns:remove_user>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


function removeUser(
    $idpayuser,
    $tokenpayuser
) {
    $signature = hash("sha512",
        $merchantCode
        . $idpayuser
        . $tokenpayuser
        . $terminal
        . $password
    );
    $ip = $_SERVER["REMOTE_ADDR"];
    try {
        $clientSOAP = new SoapClient($endpoint);
        $ans = $clientSOAP->remove_user(
            $merchantCode,
            $terminal,
            $idpayuser,
            $tokenpayuser,
            $signature,
            $ip
        );
    } catch (SoapFault $e) {
        var_dump($e);
    }
    var_dump($ans);
}

public ServiceResponse remove_user(String[] args) {

    String merchantcode = args[0];
    String terminal = args[1];
    String password = args[2];
    String ipaddr = args[3];
    String iduser = args[4];
    String tokenuser = args[5];

    merchantsignature = makeSHA1hash(merchantcode + iduser + tokenuser + terminal + password);

    ServiceResponse result = new ServiceResponse();

    SoapObject soapReq = new SoapObject("remove_user");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("DS_IDUSER", iduser);
    soapReq.addProperty("DS_TOKEN_USER", tokenuser);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);
    soapReq.addProperty("DS_ORIGINAL_IP", ipaddr);

    return callSoap(result, soapReq);
}

Ejecución de cobro a usuario en el sistema

Función: (execute_purchase)

Una vez el usuario está dado de alta en el sistema, se podrán realizar cobros a su cuenta mediante el envío de sus credenciales y datos de la operación

Las variables que se requieren para realizar un cobro a un usuario dado de alta en el sistema son (en este orden):

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_IDUSER [0-9]{1,13} Obligatorio. Identificador único del usuario registrado en el sistema.
DS_TOKEN_USER [A-Za-z0-9]{1,20} Obligatorio. Código token asociado al DS_IDUSER.
DS_MERCHANT_AMOUNT [0-9]{1,8} Obligatorio. Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Obligatorio. Referencia de la operación. Debe ser única en cada transacción válida.
DS_MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Obligatorio. Moneda de la transacción. Ver más información en el apartado MONEDAS
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS
DS_ORIGINAL_IP A.B.C.D Obligatorio. Dirección IP del cliente que inició la operación de pago (propietario de la tarjeta)
DS_MERCHANT_PRODUCTDESCRIPTION [a-zA-Z0-9]{1,40} Opcional. Descripción del producto
DS_MERCHANT_OWNER [a-zA-Z0-9]{1,40} Opcional. Descripción de la transacción
DS_MERCHANT_SCORING [0-100] Opcional. Valor de scoring de riesgo de la transacción. Entre 0 y 100.
DS_MERCHANT_DATA
JSON Opcional. Información de autenticación del cliente. Cuanta más información se proporcione en este campo, más probable será la autorización de la operación sin solicitar autenticación adicional. Por esta razón se recomienda el envío del máximo de información posible. Ver detalle
DS_MERCHANT_MERCHANTDESCRIPTOR [A-Za-z0-9]{1,25} Opcional. Permite al comercio enviar un texto de hasta 25 caracteres que se imprimirá en la factura del cliente. Uso exclusivo de caracteres simples, sin acentos ni caracteres especiales.
DS_MERCHANT_SCA_EXCEPTION
[LWV|TRA|MIT|COR] Opcional TIPO DE EXCEPCIÓN AL PAGO SEGURO. Si no se especifica PAYCOMET tratará de asignarle el más adecuado si fuera posible. Ver detalle
DS_MERCHANT_TRX_TYPE [I|R|H|E|D|M|N|C]  Condicional Obligatorio sólo si se ha elegido una excepción MIT en el campo MERCHANT_SCA_EXCEPTION. Ver detalle
DS_ESCROW_TARGETS
{
 "TARGETS": [
  {
    "ESCROW_TARGET_ID": "",
    "ESCROW_TARGET_AMOUNT": ""
  }
 ]
}
			
Opcional Identificación de los destinatarios de ingresos en operaciones ESCROW. Debe ser un objeto JSON codificado en base 64 y a su vez en URL. En pseudocódigo, sería urlencode( base64_encode( JSON_Object ) )
DS_USER_INTERACTION
[0|1] Opcional. Indicador de si es posible la interacción con el usuario por parte del comercio

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_MERCHANT_AMOUNT [0-9]{1,8} Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Referencia de la operación
DS_MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_AUTHCODE [a-zA-Z0-9]{1,40} Código bancario de autorización de la transacción (necesario para ejecutar una devolución).
DS_MERCHANT_CARDCOUNTRY [0-9]{1,3} País del emisor de la tarjeta en código ISO3 (ej: 724 = España). Puede venir vacío.
DS_RESPONSE [0-1]{1} Resultado de la operación. 0 o vacío será operación errónea y 1 operación completada.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.
DS_CHALLENGE_URL [A-Za-z0-9]{250} Si se envió el parámetro DS_USER_INTERACTION a 1, contendrá la URL a la que el comercio tendrá que redirigir al cliente

Si la petición produjo un error de algún tipo (firma incorrecta, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá el campo DS_RESPONSE cuyo valor será 0 o vacío en caso de error y 1 en caso de éxito en la eliminación.

Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:execute_purchase xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_IDUSER type="xsd:string"> paycometuserid  </DS_IDUSER>
        <DS_TOKEN_USER type="xsd:string"> paycometusertoken  </DS_TOKEN_USER>
        <DS_MERCHANT_AMOUNT type="xsd:string"> 1234 </DS_MERCHANT_AMOUNT>
        <DS_MERCHANT_ORDER type="xsd:string"> unique_operation_reference </DS_MERCHANT_ORDER>
        <DS_MERCHANT_CURRENCY type="xsd:string"> EUR </DS_MERCHANT_CURRENCY>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        <DS_ORIGINAL_IP type="xsd:string"> 1.2.3.4  </DS_ORIGINAL_IP>
        <DS_MERCHANT_PRODUCTDESCRIPTION type="xsd:string"> Product description </DS_MERCHANT_PRODUCTDESCRIPTION>
        <DS_MERCHANT_OWNER type="xsd:string"> Card Owner  </DS_MERCHANT_OWNER>
        <DS_MERCHANT_SCORING type="xsd:integer">
        <DS_MERCHANT_DATA type="xsd:string"> Comerce Data </DS_MERCHANT_DATA>
        <DS_MERCHANT_MERCHANTDESCRIPTOR type="xsd:string"> Commerce descriptor </DS_MERCHANT_MERCHANTDESCRIPTOR>
        </mns:execute_purchase>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

function executePurchase(
    $idpayuser,
    $tokenpayuser,
    $amount,
    $transreference,
    $currency,
    $productdescription,
    $owner,
    $scoring = null,
    $merchant_data = null,
    $merchant_description = null
) {
    $signature = hash("sha512",
        $merchantCode
        . $idpayuser
        . $tokenpayuser
        . $terminal
        . $amount
        . $transreference
        . $password
    );
    $ip = $_SERVER["REMOTE_ADDR"];
    try {
        $clientSOAP = new SoapClient($endpoint);
        $ans = $clientSOAP->execute_purchase(
            $merchantCode,
            $terminal,
            $idpayuser,
            $tokenpayuser,
            $amount,
            $transreference,
            $currency,
            $signature,
            $ip,
            $productdescription,
            $owner,
            $scoring,
            $merchant_data,
            $merchant_description
        );
    } catch (SoapFault $e) {
        var_dump($e);
    }
    var_dump($ans);
}

public ServiceResponse execute_purchase(String[] args) {

    String merchantcode = args[0];
    String terminal = args[1];
    String password = args[2];
    String ipaddr = args[3];
    String iduser = args[4];
    String tokenuser = args[5];
    String amount = args[6];
    String orderid = args[7];
    String currency = args[8];
    String productdescription = args[9];
    String cardholder = args[10];
    String scoring = args[11];

    merchantsignature = makeSHA1hash(merchantcode + iduser + tokenuser + terminal + amount + orderid + password);

    ServiceResponse result = new ServiceResponse();

    SoapObject soapReq = new SoapObject("execute_purchase");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("DS_IDUSER", iduser);
    soapReq.addProperty("DS_TOKEN_USER", tokenuser);
    soapReq.addProperty("DS_MERCHANT_AMOUNT", amount);
    soapReq.addProperty("DS_MERCHANT_ORDER", orderid);
    soapReq.addProperty("DS_MERCHANT_CURRENCY", currency);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);
    soapReq.addProperty("DS_ORIGINAL_IP", ipaddr);
    soapReq.addProperty("DS_MERCHANT_PRODUCTDESCRIPTION", productdescription);
    soapReq.addProperty("DS_MERCHANT_OWNER", cardholder);
    soapReq.addProperty("DS_MERCHANT_SCORING", scoring);

    return callSoap(result, soapReq);
}

Ejecución de cobro a Usuario en el sistema por DCC

Función: (execute_purchase_dcc)

Una vez el usuario está dado de alta en el sistema, se podrán realizar cobros a su cuenta mediante el envío de sus credenciales y datos de la operación. La casuística del DCC requiere que un proceso de pago se realice en dos pasos: execute_purchase_dcc, donde se recibe la moneda nativa de la tarjeta (en caso que la tarjeta tenga la misma moneda que el producto asociado a la transacción, el resultado será de conversión 1:1) y posteriormente se confirmará con el método confirm_purchase_dcc con la moneda seleccionada y la sesión original de la transacción.

Las variables que requiere el servicio para realizar un cobro DCC a un usuario dado de alta en el sistema son (en este orden):

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_IDUSER [0-9]{1,13} Obligatorio. Identificador único del usuario registrado en el sistema.
DS_TOKEN_USER [A-Za-z0-9]{1,20} Obligatorio. Código token asociado al DS_IDUSER.
DS_MERCHANT_AMOUNT [0-9]{1,8} Obligatorio. Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Obligatorio. Referencia de la operación. Debe ser única en cada transacción válida.
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS
DS_ORIGINAL_IP A.B.C.D Obligatorio. Dirección IP de la aplicación del comercio
DS_MERCHANT_PRODUCTDESCRIPTION [a-zA-Z0-9]{40} Opcional. Descripción del producto
DS_MERCHANT_OWNER [a-zA-Z0-9]{40} Opcional. Descripción de la transacción
DS_MERCHANT_MERCHANTDESCRIPTOR [A-Za-z0-9]{1,25} Opcional. Permite al comercio enviar un texto de hasta 25 caracteres que se imprimirá en la factura del cliente. Uso exclusivo de caracteres simples, sin acentos ni caracteres especiales.

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_MERCHANT_AMOUNT [0-9]{1,8} Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Referencia de la operación
DS_MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Moneda de la transacción. Siempre será la misma del producto original.
DS_MERCHANT_DCC_SESSION [a-zA-Z0-9]{1,40} Variable de sesión para la confirmación posterior de la autorización. Este valor debe ser almacenado para confirmar el pago en la moneda elegida por el usuario final.
DS_MERCHANT_DCC_CURRENCY [EUR][USD][GBP][JPY] Moneda nativa de la tarjeta del cliente.
DS_MERCHANT_DCC_CURRENCYISO3 [0-9]{1,3} Moneda nativa de la tarjeta del cliente en formato ISO3
DS_MERCHANT_DCC_CURRENCYNAME [A-Za-z0-9]{1,20} Literal de la moneda en string. Si la moneda nativa es la misma que la del producto PAYCOMET, este campo vendrá con valor 0.
DS_MERCHANT_DCC_EXCHANGE [0-9]*\.?[0-9]* Ratio de cambio entre monedas. Devuelve string aunque vendrá en formato float.
DS_MERCHANT_DCC_AMOUNT [0-9]{1,8} Importe de la operación en la moneda nativa en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_MERCHANT_DCC_MARKUP [0-9]*\.?[0-9]* Valor porcentual en float del margen DCC aplicado por la entidad financiera. Por ejemplo: 0.03 será un 3%
DS_MERCHANT_DCC_CARDCOUNTRY [0-9]{1,3} País del emisor de la tarjeta en código ISO3 (ej: 724 = España).
DS_RESPONSE [0-1]{1} Resultado de la operación. 0 o vacío será operación errónea y 1 operación completada.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.

Si la petición produjo un error de algún tipo (firma incorrecta, importe incorrecto, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá todos los campos. En este caso el campo DS_ERROR_ID será devuelto vacío. El dato a guardar para la confirmación de la operación es el DS_MERCHANT_DCC_SESSION que se trata del identificador único transaccional vinculante a la operación de compra iniciada en DCC. En el siguiente paso debe confirmarse la moneda para finalizar la transacción y vincularla a la sesión DCC.

La operativa DCC no está totalmente disponible en el entorno de pruebas, por lo que esta función realiza directamente el cobro sin devolver el identificador de sesión DCC.

Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:execute_purchase_dcc xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_IDUSER type="xsd:string"> paycometuserid  </DS_IDUSER>
        <DS_TOKEN_USER type="xsd:string"> paycometusertoken  </DS_TOKEN_USER>
        <DS_MERCHANT_AMOUNT type="xsd:string"> 1234 </DS_MERCHANT_AMOUNT>
        <DS_MERCHANT_ORDER type="xsd:string"> unique_operation_reference </DS_MERCHANT_ORDER>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        <DS_ORIGINAL_IP type="xsd:string"> 1.2.3.4  </DS_ORIGINAL_IP>
        <DS_MERCHANT_PRODUCTDESCRIPTION type="xsd:string"> Product description </DS_MERCHANT_PRODUCTDESCRIPTION>
        <DS_MERCHANT_OWNER type="xsd:string"> Card Owner  </DS_MERCHANT_OWNER>
        <DS_MERCHANT_MERCHANTDESCRIPTOR type="xsd:string"> Commerce descriptor </DS_MERCHANT_MERCHANTDESCRIPTOR>
        </mns:execute_purchase_dcc>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

function executePurchaseDcc(
    $idpayuser,
    $tokenpayuser,
    $amount,
    $transreference,
    $productdescription = false,
    $owner = false,
    $merchant_description = null
) {
    $signature = hash("sha512",
        $merchantCode
        . $idpayuser
        . $tokenpayuser
        . $terminal
        . $amount
        . $transreference
        . $password
    );
    $ip = $_SERVER["REMOTE_ADDR"];
    try {
        $clientSOAP = new SoapClient($endpoint);
        $ans = $clientSOAP->execute_purchase_dcc(
            $merchantCode,
            $terminal,
            $idpayuser,
            $tokenpayuser,
            $amount,
            $transreference,
            $signature,
            $ip,
            $productdescription,
            $owner,
            $merchant_description
        );
    } catch (SoapFault $e) {
        var_dump($e);
    }
    var_dump($ans);
}
       
public ServiceResponse execute_purchase_dcc(String[] args) {

    String merchantcode = args[0];
    String terminal = args[1];
    String password = args[2];
    String ipaddr = args[3];
    String iduser = args[4];
    String tokenuser = args[5];
    String amount = args[6];
    String orderid = args[7];
    String productdescription = args[8];
    String cardholder = args[9];

    merchantsignature = makeSHA1hash(merchantcode + iduser + tokenuser + terminal + amount + orderid + password);

    ServiceResponse result = new ServiceResponse();

    SoapObject soapReq = new SoapObject("execute_purchase_dcc");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("DS_IDUSER", iduser);
    soapReq.addProperty("DS_TOKEN_USER", tokenuser);
    soapReq.addProperty("DS_MERCHANT_AMOUNT", amount);
    soapReq.addProperty("DS_MERCHANT_ORDER", orderid);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);
    soapReq.addProperty("DS_ORIGINAL_IP", ipaddr);
    soapReq.addProperty("DS_MERCHANT_PRODUCTDESCRIPTION", productdescription);
    soapReq.addProperty("DS_MERCHANT_OWNER", cardholder);

    return callSoap(result, soapReq);
}

Confirmación de moneda en pago DCC

Función: (confirm_purchase_dcc)

Una vez se ha devuelto el parámetro DS_MERCHANT_DCC_SESSION cuando se realizó una compra por DCC, el estado de la transacción se queda “a la espera” de la confirmación de moneda. El comercio debe proponer al cliente la moneda en la que quiere pagar (mostrándole la conversión en tiempo real) y cuando la selecciona, el comercio debe confirmar la autorización con la moneda seleccionada por el usuario final.

(ejemplo de interacción con usuario final)

Las variables que se requieren para confirmar una operación en DCC en el sistema son (en este orden):

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Obligatorio. Referencia de la operación original.
DS_MERCHANT_DCC_CURRENCY [EUR][USD][GBP][JPY][...] Obligatorio. Moneda de la transacción elegida. Puede ser la del producto PAYCOMET o la nativa seleccionada por el usuario final. El importe será el enviado en execute_purchase_dcc si es el mismo del producto y el convertido en caso de ser diferente.
DS_MERCHANT_DCC_SESSION [a-zA-Z0-9]{1,40} Obligatorio. Misma sesión enviada en el proceso de execute_purchase_dcc.
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_MERCHANT_AMOUNT [0-9]{1,8} Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Referencia de la operación
DS_MERCHANT_CURRENCY [EUR][USD][GBP][JPY][...] Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_AUTHCODE [a-zA-Z0-9]{1,40} Código bancario de autorización de la transacción (necesario para ejecutar una devolución).
DS_MERCHANT_CARDCOUNTRY [0-9]{1,3} País del emisor de la tarjeta en código ISO3 (ej: 724 = España). Puede venir vacío.
DS_RESPONSE [0-1]{1} Resultado de la operación. 0 o vacío será operación errónea y 1 operación completada.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado: CÓDIGOS DE ERROR.

Si la petición produjo un error de algún tipo (firma incorrecta, importe incorrecto, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá todos los campos (excepto DS_MERCHANT_CARDCOUNTRY que es opcional) que deberán ser almacenados por el comercio de cara a una posible devolución. En este caso el campo DS_ERROR_ID será devuelto con valor 0.

Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:confirm_purchase_dcc xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_MERCHANT_ORDER type="xsd:string"> unique_operation_reference </DS_MERCHANT_ORDER>
        <DS_MERCHANT_DCC_CURRENCY type="xsd:string"> EUR </DS_MERCHANT_DCC_CURRENCY>
        <DS_MERCHANT_DCC_SESSION type="xsd:string"> dccsession  </DS_MERCHANT_DCC_SESSION>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        </mns:confirm_purchase_dcc>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

function confirmPurchaseDcc(
    $transreference,
    $dcccurrency,
    $dccsession
) {
    $signature = hash("sha512",
        $merchantCode
        . $terminal
        . $transreference
        . $dcccurrency
        . $dccsession
        . $password
    );
    try {
        $clientSOAP = new SoapClient($endpoint);
        $ans = $clientSOAP->confirm_purchase_dcc(
            $merchantCode,
            $terminal,
            $transreference,
            $dcccurrency,
            $dccsession,
            $signature
        );
    } catch (SoapFault $e) {
        var_dump($e);
    }
    var_dump($ans);
}

public ServiceResponse confirm_purchase_dcc(String[] args) {

    String merchantcode = args[0];
    String terminal = args[1];
    String ipaddr = args[2];
    String orderid = args[3];
    String dcccurrency = args[4];
    String dccsession = args[5];

    merchantsignature = makeSHA1hash(merchantcode + terminal + orderid + dcccurrency + dccsession);

    ServiceResponse result = new ServiceResponse();

    SoapObject soapReq = new SoapObject("confirm_purchase_dcc");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("DS_MERCHANT_ORDER", orderid);
    soapReq.addProperty("DS_MERCHANT_DCC_CURRENCY", dcccurrency);
    soapReq.addProperty("DS_MERCHANT_DCC_SESSION", dccsession);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);

    return callSoap(result, soapReq);
}

Devolución de cobro a usuario en el sistema

Función: (execute_refund)

Se podrán ejecutar devoluciones de las operaciones realizadas mediante esta función. Será necesario los datos identificativos del usuario y el código de autorización bancario.

Las variables que se requieren para realizar una devolución de una operación son (en este orden):

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_IDUSER [0-9]{1,13} Obligatorio. Identificador único del usuario registrado en el sistema.
DS_TOKEN_USER [A-Za-z0-9]{1,20} Obligatorio. Código token asociado al DS_IDUSER.
DS_MERCHANT_AUTHCODE [a-zA-Z0-9]{1,40} Obligatorio. Código bancario original de la autorización de la transacción
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Obligatorio. Referencia original de la operación.
DS_MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Obligatorio. Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS
DS_ORIGINAL_IP A.B.C.D Obligatorio. Dirección IP de la aplicación del comercio
DS_MERCHANT_AMOUNT [0-9]{1,8} Opcional. Para devoluciones parciales. Importe que se pretende devolver en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_MERCHANT_MERCHANTDESCRIPTOR [A-Za-z0-9]{1,25} Opcional. Permite al comercio enviar un texto de hasta 25 caracteres que se imprimirá en la factura del cliente. Uso exclusivo de caracteres simples, sin acentos ni caracteres especiales.

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Referencia de la operación
DS_MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_AUTHCODE [a-zA-Z0-9]{1,40} Código bancario de autenticación de la transacción
DS_RESPONSE [0-1]{1} Resultado de la operación. 0 o vacío será operación errónea y 1 operación completada.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.

Si la petición produjo un error de algún tipo (firma incorrecta, importe incorrecto, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá todos los campos. En este caso el campo DS_ERROR_ID será devuelto vacío. El servicio devolverá el campo DS_RESPONSE cuyo valor será 0 o vacío en caso de error y 1 en caso de éxito de la devolución.

Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:execute_refund xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_IDUSER type="xsd:string"> paycometuserid  </DS_IDUSER>
        <DS_TOKEN_USER type="xsd:string"> paycometusertoken  </DS_TOKEN_USER>
        <DS_MERCHANT_AUTHCODE type="xsd:string"> merchantauthcode </DS_MERCHANT_AUTHCODE>
        <DS_MERCHANT_ORDER type="xsd:string"> unique_operation_reference </DS_MERCHANT_ORDER>
        <DS_MERCHANT_CURRENCY type="xsd:string"> EUR </DS_MERCHANT_CURRENCY>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        <DS_ORIGINAL_IP type="xsd:string"> 1.2.3.4  </DS_ORIGINAL_IP>
        <DS_MERCHANT_AMOUNT type="xsd:string"> 1234 </DS_MERCHANT_AMOUNT>
        <DS_MERCHANT_MERCHANTDESCRIPTOR type="xsd:string"> Commerce descriptor </DS_MERCHANT_MERCHANTDESCRIPTOR>
        </mns:execute_refund>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

function executeRefund(
    $idpayuser,
    $tokenpayuser,
    $transreference,
    $currency,
    $authcode,
    $amount = null,
    $merchant_description = null
) {
    $signature = hash("sha512",
        $merchantCode
        . $idpayuser
        . $tokenpayuser
        . $terminal
        . $authcode
        . $transreference
        . $password
    );
    $ip = $_SERVER["REMOTE_ADDR"];
    try {
        $clientSOAP = new SoapClient($endpoint);
        $ans = $clientSOAP->execute_refund(
            $merchantCode,
            $terminal,
            $idpayuser,
            $tokenpayuser,
            $authcode,
            $transreference,
            $currency,
            $signature,
            $ip,
            $amount,
            $merchant_description
        );
    } catch (SoapFault $e) {
        var_dump($e);
    }
    var_dump($ans);
}

public ServiceResponse execute_refund(String[] args) {

    String merchantcode = args[0];
    String terminal = args[1];
    String password = args[2];
    String ipaddr = args[3];
    String iduser = args[4];
    String tokenuser = args[5];
    String orderid = args[6];
    String currency = args[7];
    String authcode = args[8];
    String amount = args[9];

    merchantsignature = makeSHA1hash(merchantcode + iduser + tokenuser + terminal + authcode + orderid + password);

    ServiceResponse result = new ServiceResponse();

    SoapObject soapReq = new SoapObject("execute_refund");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("DS_IDUSER", iduser);
    soapReq.addProperty("DS_TOKEN_USER", tokenuser);
    soapReq.addProperty("DS_MERCHANT_AUTHCODE", authcode);
    soapReq.addProperty("DS_MERCHANT_ORDER", orderid);
    soapReq.addProperty("DS_MERCHANT_CURRENCY", currency);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);
    soapReq.addProperty("DS_ORIGINAL_IP", ipaddr);
    soapReq.addProperty("DS_MERCHANT_AMOUNT", amount);

    return callSoap(result, soapReq);
}

Ejecución de alta de suscripción en el sistema

Función: (create_subscription)

El alta de una subscripción implica el alta de un usuario en el sistema BankStore de PAYCOMET. Este proceso es completamente independiente del cobro puntual a un cliente del comercio.

Las variables que se requieren para dar de alta a un usuario con subscripción son (en este orden):

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_MERCHANT_PAN [0-9]{16,19} Obligatorio. Número de tarjeta, sin espacios ni guiones
DS_MERCHANT_EXPIRYDATE [0-9]{4} Obligatorio. Fecha de caducidad de la tarjeta, expresada como “mmyy” (mes en dos cifras y año en dos cifras)
DS_MERCHANT_CVV2 [0-9]{3,4} Obligatorio. Código CVC2 de la tarjeta
DS_SUBSCRIPTION_STARTDATE [YYYY-MM-DD] Obligatorio. Fecha de inicio de la subscripción. Si el valor es vacío la fecha es el mismo día del alta.
DS_SUBSCRIPTION_ENDDATE [YYYY-MM-DD] Obligatorio. Fecha final de la subscripción.No podrá ser mayor que la fecha de inicio de la suscripción + 5 años
DS_SUBSCRIPTION_ORDER [A-Za-z0-9]{1,20} Obligatorio. Primeros caracteres a la referencia de la operación. IMPORTANTE: No incluir los caracteres “[“ o “]”, se utilizarán para reconocer el usuario del comercio.
DS_SUBSCRIPTION_PERIODICITY [0-9]{3} Obligatorio. Periodicidad del cobro desde la fecha de inicio. El número expresa Días. No podrá ser mayor de 365 días.
DS_SUBSCRIPTION_AMOUNT [0-9]{1,8} Obligatorio. Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_SUBSCRIPTION_CURRENCY [EUR][USD][GBP][JPY] Obligatorio. Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS
DS_ORIGINAL_IP A.B.C.D Obligatorio. Dirección IP del cliente que inició la operación de pago (propietario de la tarjeta)
DS_MERCHANT_SCORING [0-100] Opcional. Valor de scoring de riesgo de la transacción. Entre 0 y 100.
DS_MERCHANT_DATA
JSON Opcional. Información de autenticación del cliente. Cuanta más información se proporcione en este campo, más probable será la autorización de la operación sin solicitar autenticación adicional. Por esta razón se recomienda el envío del máximo de información posible. Ver detalle
DS_MERCHANT_SCA_EXCEPTION
[LWV|TRA|MIT|COR] Opcional TIPO DE EXCEPCIÓN AL PAGO SEGURO. Si no se especifica PAYCOMET tratará de asignarle el más adecuado si fuera posible. Ver detalle
DS_MERCHANT_TRX_TYPE [I|R|H|E|D|M|N|C]  Condicional Obligatorio sólo si se ha elegido una excepción MIT en el campo MERCHANT_SCA_EXCEPTION. Ver detalle
DS_ESCROW_TARGETS
{
 "TARGETS": [
  {
    "ESCROW_TARGET_ID": "",
    "ESCROW_TARGET_AMOUNT": ""
  }
 ]
}
			
Opcional Identificación de los destinatarios de ingresos en operaciones ESCROW. Debe ser un objeto JSON codificado en base 64 y a su vez en URL. En pseudocódigo, sería urlencode( base64_encode( JSON_Object ) )
DS_USER_INTERACTION
[0|1] Opcional. Indicador de si es posible la interacción con el usuario por parte del comercio

Ejemplo:

DS_SUBSCRIPTION_ORDER = Luis_3268314

El cobro de la subscripción al DS_IDUSER 32 el día 23 de Diciembre del 2030 el sistema devolverá como DS_SUBSCRIPTION_ORDER:

DS_SUBSCRIPTION_ORDER = Luis_3268314[23]20301223

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_IDUSER [0-9]{1,13} Identificador único del usuario registrado en el sistema. Volverá vacío en caso de error.
DS_TOKEN_USER [A-Za-z0-9]{1,20} Código token asociado al DS_IDUSER.
DS_SUBSCRIPTION_AMOUNT [0-9]{1,8} Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_SUBSCRIPTION_ORDER [A-Za-z0-9]{1,20} Referencia original de la operación + [DS_IDUSER] + fecha de la transacción en formato YYYYMMDD.
DS_SUBSCRIPTION_CURRENCY [EUR][USD][GBP][JPY] Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_AUTHCODE [a-zA-Z0-9]{1,40} Código bancario de autenticación de la transacción
DS_MERCHANT_CARDCOUNTRY [0-9]{1,3} País del emisor de la tarjeta en código ISO3 (ej: 724 = España). Puede venir vacío.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.

Si la petición produjo un error de algún tipo (firma incorrecta, importe incorrecto, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá los campos DS_IDUSER y DS_TOKEN_USER que deberán ser almacenados por el comercio, asociándolo a la cuenta de su cliente, para posteriormente modificar la subscripción o dar de baja la subscripción.

En caso de ejecución de la primera cuota con éxito el sistema devolverá todos los campos menos DS_ERROR_ID que quedará vacío.

Si la ejecución de la primera cuota es errónea por diferentes motivos (saldo, validez de la tarjeta, etc...), la subscripción será cancelada teniendo que crear otra subscripción nueva. En este caso sólo se devolverá DS_ERROR_ID con el código de error específico.

Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:create_subscription xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_MERCHANT_PAN type="xsd:string"> 1234 5678 9012 3456  </DS_MERCHANT_PAN>
        <DS_MERCHANT_EXPIRYDATE type="xsd:string"> 0535  </DS_MERCHANT_EXPIRYDATE>
        <DS_MERCHANT_CVV2 type="xsd:string"> 123  </DS_MERCHANT_CVV2>
        <DS_SUBSCRIPTION_STARTDATE type="xsd:string"> 2034-05-21 </DS_SUBSCRIPTION_STARTDATE>
        <DS_SUBSCRIPTION_ENDDATE type="xsd:string"> 2035-06-25 </DS_SUBSCRIPTION_ENDDATE>
        <DS_SUBSCRIPTION_ORDER type="xsd:string"> subscritionorder </DS_SUBSCRIPTION_ORDER>
        <DS_SUBSCRIPTION_PERIODICITY type="xsd:string"> 15 </DS_SUBSCRIPTION_PERIODICITY>
        <DS_SUBSCRIPTION_AMOUNT type="xsd:string"> 1234 </DS_SUBSCRIPTION_AMOUNT>
        <DS_SUBSCRIPTION_CURRENCY type="xsd:string"> EUR </DS_SUBSCRIPTION_CURRENCY>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        <DS_ORIGINAL_IP type="xsd:string"> 1.2.3.4  </DS_ORIGINAL_IP>
        <DS_EXECUTE" type="xsd:integer>
        <DS_MERCHANT_CARDHOLDERNAME type="xsd:string"> Francisco y Meta  </DS_MERCHANT_CARDHOLDERNAME>
        <DS_MERCHANT_SCORING type="xsd:integer">
        <DS_MERCHANT_DATA type="xsd:string"> Comerce Data </DS_MERCHANT_DATA>
        </mns:create_subscription>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

function createSubscription(
    $pan,
    $expdate,
    $cvv,
    $startdate,
    $enddate,
    $transreference,
    $periodicity,
    $amount,
    $currency,
    $ownerName = null,
    $scoring = null,
    $merchant_data = null
) {
    $pan = preg_replace(
        '/\s+/',
        '',
        $pan
    );
    $expdate = preg_replace(
        '/\s+/',
        '',
        $expdate
    );
    $cvv = preg_replace(
        '/\s+/',
        '',
        $cvv
    );
    $signature = hash("sha512",
        $merchantCode
        . $pan
        . $cvv
        . $terminal
        . $amount
        . $currency
        . $password
    );
    $ip = $_SERVER["REMOTE_ADDR"];
    try {
        $clientSOAP = new SoapClient($endpoint);
        $ans = $clientSOAP->create_subscription(
            $merchantCode,
            $terminal,
            $pan,
            $expdate,
            $cvv,
            $startdate,
            $enddate,
            $transreference,
            $periodicity,
            $amount,
            $currency,
            $signature,
            $ip,
            1,
            $ownerName,
            $scoring,
            $merchant_data
        );
    } catch (SoapFault $e) {
        var_dump($e);
    }
    var_dump($ans);
}

public ServiceResponse create_subscription(String[] args) {

    String merchantcode = args[0];
    String terminal = args[1];
    String password = args[2];
    String ipaddr = args[3];
    String pan = args[4];
    String expirydate = args[5];
    String cvv2 = args[6];
    String startdate = args[7];
    String enddate = args[8];
    String orderid = args[9];
    String periodicity = args[10];
    String amount = args[11];
    String currency = args[12];
    String cardholder = args[13];
    String scoring = args[14];

    merchantsignature = makeSHA1hash(merchantcode + pan + cvv2 + terminal + amount + currency + password);

    ServiceResponse result = new ServiceResponse();

    SoapObject soapReq = new SoapObject("create_subscription");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("pan", dS_MERCHANT_PAN);
    soapReq.addProperty("DS_MERCHANT_EXPIRYDATE", expirydate);
    soapReq.addProperty("DS_MERCHANT_CVV2", cvv2);
    soapReq.addProperty("DS_SUBSCRIPTION_STARTDATE", startdate);
    soapReq.addProperty("DS_SUBSCRIPTION_ENDDATE", enddate);
    soapReq.addProperty("DS_SUBSCRIPTION_ORDER", orderid);
    soapReq.addProperty("DS_SUBSCRIPTION_PERIODICITY", periodicity);
    soapReq.addProperty("DS_SUBSCRIPTION_CURRENCY", currency);
    soapReq.addProperty("DS_SUBSCRIPTION_AMOUNT", amount);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);
    soapReq.addProperty("DS_ORIGINAL_IP", ipaddr);
    soapReq.addProperty("DS_MERCHANT_CARDHOLDERNAME", cardholder);
    soapReq.addProperty("DS_MERCHANT_SCORING", scoring);

    return callSoap(result, soapReq);
}

Modificación de suscripción en el sistema

Función: (edit_subscription)

Si un usuario renueva su subscripción o simplemente se quiere aumentar la cuota del servicio, ofrecemos el servicio de modificar una subscripción. En este caso no se podrá cambiar la moneda ni los datos bancarios del cliente del comercio. La modificación de la subscripción implica el previo alta de un usuario en modo subscripción en el sistema BankStore de PAYCOMET. Este proceso es completamente independiente del cobro puntual a un cliente del comercio.

Las variables que se requieren para modificar una subscripción son (en este orden):

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_IDUSER [0-9]{1,13} Obligatorio. Identificador único del usuario registrado en el sistema.
DS_TOKEN_USER [A-Za-z0-9]{1,20} Obligatorio. Código token asociado al DS_IDUSER.
DS_SUBSCRIPTION_STARTDATE [YYYY-MM-DD] Obligatorio. Fecha de inicio de la subscripción. Si el valor es vacío la fecha es el mismo día del alta.
DS_SUBSCRIPTION_ENDDATE [YYYY-MM-DD] Obligatorio. Fecha final de la subscripción.
DS_SUBSCRIPTION_PERIODICITY [0-9]{3} Obligatorio. Periodicidad del cobro desde la fecha de inicio. El número expresa Días.
DS_SUBSCRIPTION_AMOUNT [0-9]{1,8} Obligatorio. Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS
DS_EXECUTE [0-1]{1} Obligatorio. Si el proceso de alta implica el cobro de la primera cuota el valor de DS_EXECUTE debe ser 1. Si sólo se desea el alta de la subscripción sin el cobro de la primera cuota (se ejecutará con los parámetros enviados) su valor debe ser 0.
DS_ORIGINAL_IP A.B.C.D Obligatorio. Dirección IP del cliente que inició la operación de pago (propietario de la tarjeta)

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_IDUSER [0-9]{1,13} Identificador único del usuario registrado en el sistema.
DS_TOKEN_USER [A-Za-z0-9]{1,20} Código token asociado al DS_IDUSER.
DS_SUBSCRIPTION_AMOUNT [0-9]{1,8} Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_SUBSCRIPTION_ORDER [A-Za-z0-9]{1,20} Referencia original de la operación + [DS_IDUSER] + fecha de la transacción en formato YYYYMMDD.
DS_SUBSCRIPTION_CURRENCY [EUR][USD][GBP][JPY] Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_AUTHCODE [a-zA-Z0-9]{1,40} Código bancario de autenticación de la transacción
DS_MERCHANT_CARDCOUNTRY [0-9]{1,3} País del emisor de la tarjeta en código ISO3 (ej: 724 = España). Puede venir vacío.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.

Si la petición produjo un error de algún tipo (firma incorrecta, importe incorrecto, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de ejecución de la primera cuota con éxito el sistema devolverá todos los campos menos DS_ERROR_ID que quedará vacío.

Si la ejecución de la primera cuota es errónea por diferentes motivos (saldo, validez de la tarjeta, etc...), la subscripción será cancelada teniendo que crear otra subscripción nueva. En este caso sólo se devolverá DS_ERROR_ID con el código de error específico.

Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:edit_subscription xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_IDUSER type="xsd:string"> paycometuserid  </DS_IDUSER>
        <DS_TOKEN_USER type="xsd:string"> paycometusertoken  </DS_TOKEN_USER>
        <DS_SUBSCRIPTION_STARTDATE type="xsd:string"> 2034-05-21 </DS_SUBSCRIPTION_STARTDATE>
        <DS_SUBSCRIPTION_ENDDATE type="xsd:string"> 2035-06-25 </DS_SUBSCRIPTION_ENDDATE>
        <DS_SUBSCRIPTION_PERIODICITY type="xsd:string"> 15 </DS_SUBSCRIPTION_PERIODICITY>
        <DS_SUBSCRIPTION_AMOUNT type="xsd:string"> 1234 </DS_SUBSCRIPTION_AMOUNT>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        <DS_EXECUTE" type="xsd:integer>
        <DS_ORIGINAL_IP type="xsd:string"> 1.2.3.4  </DS_ORIGINAL_IP>
        </mns:edit_subscription>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

function editSubscription(
    $idpayuser,
    $tokenpayuser,
    $startdate,
    $enddate,
    $periodicity,
    $amount,
    $execute
) {
    $signature = hash("sha512",
        $merchantCode
        . $idpayuser
        . $tokenpayuser
        . $terminal
        . $amount
        . $password
    );
    $ip = $_SERVER["REMOTE_ADDR"];
    try {
        $clientSOAP = new SoapClient($endpoint);
        $ans = $clientSOAP->edit_subscription(
            $merchantCode,
            $terminal,
            $idpayuser,
            $tokenpayuser,
            $startdate,
            $enddate,
            $periodicity,
            $amount,
            $signature,
            $execute,
            $ip
        );
    } catch (SoapFault $e) {
        var_dump($e);
    }
    var_dump($ans);
}

public ServiceResponse edit_subscription(String[] args) {

    String merchantcode = args[0];
    String terminal = args[1];
    String password = args[2];
    String ipaddr = args[3];
    String iduser = args[4];
    String tokenuser = args[5];
    String subscriptionstartdate = args[6];
    String subscriptionenddate = args[7];
    String subscriptionperiodicity = args[8];
    String subscriptionamount = args[9];

    merchantsignature = makeSHA1hash(merchantcode + iduser + tokenuser + terminal + DS_SUBSCRIPTION_AMOUNT + password);

    ServiceResponse result = new ServiceResponse();

    SoapObject soapReq = new SoapObject("edit_subscription");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("DS_SUBSCRIPTION_STARTDATE", subscriptionstartdate);
    soapReq.addProperty("DS_SUBSCRIPTION_ENDDATE", subscriptionenddate);
    soapReq.addProperty("DS_SUBSCRIPTION_PERIODICITY", subscriptionperiodicity);
    soapReq.addProperty("DS_SUBSCRIPTION_AMOUNT", subscriptionamount);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);
    soapReq.addProperty("DS_ORIGINAL_IP", ipaddr);

    return callSoap(result, soapReq);
}

Eliminación de Suscripción

Función: (remove_subscription)

Esta función se utilizará para eliminar una subscripción de la cuenta del comercio.

Las variables que se requieren para solicitar la baja de una subscripción son (en este orden):

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_IDUSER [0-9]{1,13} Obligatorio. Identificador único del usuario registrado en el sistema.
DS_TOKEN_USER [A-Za-z0-9]{1,20} Obligatorio. Código token asociado al DS_IDUSER.
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS
DS_ORIGINAL_IP A.B.C.D Obligatorio. Dirección IP de la aplicación del comercio.

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_RESPONSE [0-1]{1} Resultado de la operación. 0 o vacío será operación errónea y 1 operación completada.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.

Si la petición produjo un error de algún tipo (firma incorrecta, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá el campo DS_RESPONSE cuyo valor será 0 o vacío en caso de error y 1 en caso de éxito en la eliminación.

Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:remove_subscription xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_IDUSER type="xsd:string"> paycometuserid  </DS_IDUSER>
        <DS_TOKEN_USER type="xsd:string"> paycometusertoken  </DS_TOKEN_USER>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        <DS_ORIGINAL_IP type="xsd:string"> 1.2.3.4  </DS_ORIGINAL_IP>
        </mns:remove_subscription>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

function removeSubscription(
    $idpayuser,
    $tokenpayuser
) {
    $signature = hash("sha512",
        $merchantCode
        . $idpayuser
        . $tokenpayuser
        . $terminal
        . $password
    );
    $ip = $_SERVER["REMOTE_ADDR"];
    try {
        $clientSOAP = new SoapClient($endpoint);
        $ans = $clientSOAP->remove_subscription(
            $merchantCode,
            $terminal,
            $idpayuser,
            $tokenpayuser,
            $signature,
            $ip
        );
    } catch (SoapFault $e) {
        var_dump($e);
    }
    var_dump($ans);
}

public ServiceResponse remove_subscription(String[] args) {

    String merchantcode = args[0];
    String terminal = args[1];
    String password = args[2];
    String ipaddr = args[3];
    String iduser = args[4];
    String tokenuser = args[5];

    merchantsignature = makeSHA1hash(merchantcode + iduser + tokenuser + terminal + password);

    ServiceResponse result = new ServiceResponse();

    SoapObject soapReq = new SoapObject("remove_subscription");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("DS_IDUSER", iduser);
    soapReq.addProperty("DS_TOKEN_USER", tokenuser);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);
    soapReq.addProperty("DS_ORIGINAL_IP", ipaddr);

    return callSoap(result, soapReq);
}

Ejecución de alta de suscripción en el sistema con USERID Y TOKENID

Función: (create_subscription_token)

El alta de una subscripción por esta vía creará una suscripción a un usuario que ya fue dado de alta en el sistema, sin que sea necesario en este caso, enviar los datos de tarjeta nuevamente.

Las variables que se requieren para dar de alta la subscripción son:

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_IDUSER [0-9]{1,13} Obligatorio. Identificador único del usuario registrado en el sistema.
DS_TOKEN_USER [A-Za-z0-9]{1,20} Obligatorio. Código token asociado al DS_IDUSER.
DS_SUBSCRIPTION_STARTDATE [YYYY-MM-DD] Obligatorio. Fecha de inicio de la subscripción. Si el valor es vacío la fecha es el mismo día del alta.
DS_SUBSCRIPTION_ENDDATE [YYYY-MM-DD] Obligatorio. Fecha final de la subscripción. No podrá ser mayor que la fecha de inicio de la suscripción + 5 años
DS_SUBSCRIPTION_ORDER [A-Za-z0-9]{1,20} Obligatorio. Primeros caracteres a la referencia de la operación. IMPORTANTE: No incluir los caracteres “[“ o “]”, se utilizarán para reconocer el usuario del comercio.
DS_SUBSCRIPTION_PERIODICITY [0-9]{3} Obligatorio. Periodicidad del cobro desde la fecha de inicio. El número expresa Días. No podrá ser mayor de 365 días.
DS_SUBSCRIPTION_AMOUNT [0-9]{1,8} Obligatorio. Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_SUBSCRIPTION_CURRENCY [EUR][USD][GBP][JPY] Obligatorio. Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS
DS_ORIGINAL_IP A.B.C.D Obligatorio. Dirección IP del cliente que inició la operación de pago (propietario de la tarjeta)
DS_MERCHANT_SCORING [0-100] Opcional. Valor de scoring de riesgo de la transacción. Entre 0 y 100.
DS_MERCHANT_DATA
JSON Opcional. Información de autenticación del cliente. Cuanta más información se proporcione en este campo, más probable será la autorización de la operación sin solicitar autenticación adicional. Por esta razón se recomienda el envío del máximo de información posible. Ver detalle
DS_MERCHANT_SCA_EXCEPTION
[LWV|TRA|MIT|COR] Opcional TIPO DE EXCEPCIÓN AL PAGO SEGURO. Si no se especifica PAYCOMET tratará de asignarle el más adecuado si fuera posible. Ver detalle
DS_MERCHANT_TRX_TYPE [I|R|H|E|D|M|N|C]  Condicional Obligatorio sólo si se ha elegido una excepción MIT en el campo MERCHANT_SCA_EXCEPTION. Ver detalle
DS_ESCROW_TARGETS
{
 "TARGETS": [
  {
    "ESCROW_TARGET_ID": "",
    "ESCROW_TARGET_AMOUNT": ""
  }
 ]
}
			
Opcional Identificación de los destinatarios de ingresos en operaciones ESCROW. Debe ser un objeto JSON codificado en base 64 y a su vez en URL. En pseudocódigo, sería urlencode( base64_encode( JSON_Object ) )
DS_USER_INTERACTION
[0|1] Opcional. Indicador de si es posible la interacción con el usuario por parte del comercio

Ejemplo:

DS_SUBSCRIPTION_ORDER = Luis_3268314

El cobro de la subscripción al DS_IDUSER 32 el día 23 de Diciembre del 2030 el sistema devolverá como DS_SUBSCRIPTION_ORDER:

DS_SUBSCRIPTION_ORDER = Luis_3268314[23]20301223

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_IDUSER [0-9]{1,13} Identificador único del usuario registrado en el sistema. Volverá vacío en caso de error.
DS_TOKEN_USER [A-Za-z0-9]{1,20} Código token asociado al DS_IDUSER.
DS_SUBSCRIPTION_AMOUNT [0-9]{1,8} Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_SUBSCRIPTION_ORDER [A-Za-z0-9]{1,20} Referencia original de la operación + [DS_IDUSER] + fecha de la transacción en formato YYYYMMDD.
DS_SUBSCRIPTION_CURRENCY [EUR][USD][GBP][JPY] Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_AUTHCODE [a-zA-Z0-9]{1,40} Código bancario de autenticación de la transacción
DS_MERCHANT_CARDCOUNTRY [0-9]{1,3} País del emisor de la tarjeta en código ISO3 (ej: 724 = España). Puede venir vacío.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.

Si la petición produjo un error de algún tipo (firma incorrecta, importe incorrecto, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de ejecución de la primera cuota con éxito el sistema devolverá todos los campos menos DS_ERROR_ID que quedará vacío.

Si la ejecución de la primera cuota es errónea por diferentes motivos (saldo, validez de la tarjeta, etc...), la subscripción será cancelada teniendo que crear otra subscripción nueva. En este caso sólo se devolverá DS_ERROR_ID con el código de error específico.

Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:create_subscription_token xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_IDUSER type="xsd:string"> paycometuserid  </DS_IDUSER>
        <DS_TOKEN_USER type="xsd:string"> paycometusertoken  </DS_TOKEN_USER>
        <DS_SUBSCRIPTION_STARTDATE type="xsd:string"> 2034-05-21 </DS_SUBSCRIPTION_STARTDATE>
        <DS_SUBSCRIPTION_ENDDATE type="xsd:string"> 2035-06-25 </DS_SUBSCRIPTION_ENDDATE>
        <DS_SUBSCRIPTION_ORDER type="xsd:string"> subscritionorder </DS_SUBSCRIPTION_ORDER>
        <DS_SUBSCRIPTION_PERIODICITY type="xsd:string"> 15 </DS_SUBSCRIPTION_PERIODICITY>
        <DS_SUBSCRIPTION_AMOUNT type="xsd:string"> 1234 </DS_SUBSCRIPTION_AMOUNT>
        <DS_SUBSCRIPTION_CURRENCY type="xsd:string"> EUR </DS_SUBSCRIPTION_CURRENCY>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        <DS_ORIGINAL_IP type="xsd:string"> 1.2.3.4  </DS_ORIGINAL_IP>
        <DS_MERCHANT_SCORING type="xsd:integer">
        <DS_MERCHANT_DATA type="xsd:string"> Comerce Data </DS_MERCHANT_DATA>
        </mns:create_subscription_token>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

function CreateSubscriptionToken(
    $idpayuser,
    $tokenpayuser,
    $startdate,
    $enddate,
    $transreference,
    $periodicity,
    $amount,
    $currency,
    $scoring = null,
    $merchant_data = null
) {
    $signature = hash("sha512",
        $merchantCode
        . $idpayuser
        . $tokenpayuser
        . $terminal
        . $amount
        . $currency
        . $password
    );
    $ip = $_SERVER["REMOTE_ADDR"];
    try {
        $clientSOAP = new SoapClient($endpoint);
        $ans = $clientSOAP->create_subscription_token(
            $merchantCode,
            $terminal,
            $idpayuser,
            $tokenpayuser,
            $startdate,
            $enddate,
            $transreference,
            $periodicity,
            $amount,
            $currency,
            $signature,
            $ip,
            $scoring,
            $merchant_data
        );
    } catch (SoapFault $e) {
        var_dump($e);
    }
    var_dump($ans);
}

public ServiceResponse create_subscription_token(String[] args) {

    String merchantcode = args[0];
    String terminal = args[1];
    String password = args[2];
    String ipaddr = args[3];
    String iduser = args[4];
    String tokenuser = args[5];
    String subscriptionstartdate = args[6];
    String subscriptionenddate = args[7];
    String subscriptionorder = args[8];
    String subscriptionperiodicity = args[9];
    String subscriptionamount = args[10];
    String subscriptioncurrency = args[11];
    String merchantscoring = args[12];

    merchantsignature = makeSHA1hash(merchantcode + iduser + tokenuser + terminal + subscriptionamount + subscriptioncurrency + password);

    ServiceResponse result = new ServiceResponse();

    SoapObject soapReq = new SoapObject("create_subscription_token");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("DS_SUBSCRIPTION_STARTDATE", subscriptionstartdate);
    soapReq.addProperty("DS_SUBSCRIPTION_ENDDATE", subscriptionenddate);
    soapReq.addProperty("DS_SUBSCRIPTION_ORDER", subscriptionorder);
    soapReq.addProperty("DS_SUBSCRIPTION_PERIODICITY", subscriptionperiodicity);
    soapReq.addProperty("DS_SUBSCRIPTION_AMOUNT", subscriptionamount);
    soapReq.addProperty("DS_SUBSCRIPTION_CURRENCY", subscriptioncurrency);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);
    soapReq.addProperty("DS_ORIGINAL_IP", ipaddr);
    soapReq.addProperty("DS_MERCHANT_SCORING", merchantscoring);

    return callSoap(result, soapReq);
}

Creación de una preautorización a usuario en el sistema

Función: (create_preauthorization)

Una vez el usuario está dado de alta en el sistema, se podrán realizar operaciones de preautorización mediante el envío de sus credenciales y datos de la operación.

Las variables que se requieren para realizar una preautorización a un usuario dado de alta en el sistema son las mismas que las descritas en el apartado Ejecución de cobro a usuario en el sistema

Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:create_preauthorization xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_IDUSER type="xsd:string"> paycometuserid  </DS_IDUSER>
        <DS_TOKEN_USER type="xsd:string"> paycometusertoken  </DS_TOKEN_USER>
        <DS_MERCHANT_AMOUNT type="xsd:string"> 1234 </DS_MERCHANT_AMOUNT>
        <DS_MERCHANT_ORDER type="xsd:string"> unique_operation_reference </DS_MERCHANT_ORDER>
        <DS_MERCHANT_CURRENCY type="xsd:string"> EUR </DS_MERCHANT_CURRENCY>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        <DS_ORIGINAL_IP type="xsd:string"> 1.2.3.4  </DS_ORIGINAL_IP>
        <DS_MERCHANT_PRODUCTDESCRIPTION type="xsd:string"> Product description </DS_MERCHANT_PRODUCTDESCRIPTION>
        <DS_MERCHANT_OWNER type="xsd:string"> Card Owner  </DS_MERCHANT_OWNER>
        <DS_MERCHANT_SCORING type="xsd:integer">
        <DS_MERCHANT_DATA type="xsd:string"> Comerce Data </DS_MERCHANT_DATA>
        <DS_MERCHANT_MERCHANTDESCRIPTOR type="xsd:string"> Commerce descriptor </DS_MERCHANT_MERCHANTDESCRIPTOR>
        </mns:create_preauthorization>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

function createPreauthorization(
    $idpayuser,
    $tokenpayuser,
    $amount,
    $transreference,
    $currency,
    $productdescription = false,
    $owner = false,
    $scoring = null,
    $merchant_data = null,
    $merchant_description = null
) {
    $signature = hash("sha512",
        $merchantCode
        . $idpayuser
        . $tokenpayuser
        . $terminal
        . $amount
        . $transreference
        . $password
    );
    $ip = $_SERVER["REMOTE_ADDR"];
    try {
        $clientSOAP = new SoapClient($endpoint);
        $ans = $clientSOAP->create_preauthorization(
            $merchantCode,
            $terminal,
            $idpayuser,
            $tokenpayuser,
            $amount,
            $transreference,
            $currency,
            $signature,
            $ip,
            $productdescription,
            $owner,
            $scoring,
            $merchant_data,
            $merchant_description
        );
    } catch (SoapFault $e) {
        var_dump($e);
    }
    var_dump($ans);
}

public ServiceResponse create_preauthorization(String[] args) {

    String merchantcode = args[0];
    String terminal = args[1];
    String password = args[2];
    String ipaddr = args[3];
    String iduser = args[4];
    String tokenuser = args[5];
    String merchantamount = args[6];
    String transferenceid = args[7];
    String merchantcurrency = args[8];
    String merchantproductdescription = args[9];
    String merchantowner = args[10];
    String merchantscoring = args[11];

    merchantsignature = makeSHA1hash(merchantcode + iduser + tokenuser + terminal + merchantamount + transferenceid + password);

    ServiceResponse result = new ServiceResponse();

    SoapObject soapReq = new SoapObject("create_preauthorization");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("DS_IDUSER", iduser);
    soapReq.addProperty("DS_TOKEN_USER", tokenuser);
    soapReq.addProperty("DS_MERCHANT_AMOUNT", merchantamount);
    soapReq.addProperty("DS_MERCHANT_ORDER", transferenceid);
    soapReq.addProperty("DS_MERCHANT_CURRENCY", merchantcurrency);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);
    soapReq.addProperty("DS_ORIGINAL_IP", ipaddr);
    soapReq.addProperty("DS_MERCHANT_PRODUCTDESCRIPTION", merchantproductdescription);
    soapReq.addProperty("DS_MERCHANT_OWNER", merchantowner);
    soapReq.addProperty("DS_MERCHANT_SCORING", merchantscoring);

    return callSoap(result, soapReq);
}

Confirmación de una preautorización a usuario en el sistema

Función: (preauthorization_confirm)

Una vez realizada y autorizada una operación de preautorización, puede confirmarse para realizar el cobro efectivo dentro de los 7 días siguientes; pasada esa fecha, las preautorizaciones pierden su validez. El importe de la confirmación de preautorización puede ser menor, igual o superior en un 15% al de la preautorización original.

Las variables que se requieren para confirmar la preautorización son:

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_IDUSER [0-9]{1,13} Obligatorio. Identificador único del usuario registrado en el sistema.
DS_TOKEN_USER [A-Za-z0-9]{1,20} Obligatorio. Código token asociado al DS_IDUSER.
DS_MERCHANT_AMOUNT [0-9]{1,8} Obligatorio. Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Obligatorio. Referencia de la operación. Debe ser la que identificó la preautorización original.
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS
DS_ORIGINAL_IP A.B.C.D Obligatorio. Dirección IP del cliente que inició la operación
DS_MERCHANT_MERCHANTDESCRIPTOR [A-Za-z0-9]{1,25} Opcional. Permite al comercio enviar un texto de hasta 25 caracteres que se imprimirá en la factura del cliente. Uso exclusivo de caracteres simples, sin acentos ni caracteres especiales.

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_MERCHANT_AMOUNT [0-9]{1,8} Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Referencia de la operación
DS_MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_AUTHCODE [a-zA-Z0-9]{1,40} Código bancario de autorización de la transacción (necesario para ejecutar una devolución).
DS_MERCHANT_CARDCOUNTRY [0-9]{1,3} País del emisor de la tarjeta en código ISO3 (ej: 724 = España). Puede venir vacío.
DS_RESPONSE [0-1]{1} Resultado de la operación. 0 o vacío será operación errónea y 1 operación completada.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.
Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:preauthorization_confirm xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_IDUSER type="xsd:string"> paycometuserid  </DS_IDUSER>
        <DS_TOKEN_USER type="xsd:string"> paycometusertoken  </DS_TOKEN_USER>
        <DS_MERCHANT_AMOUNT type="xsd:string"> 1234 </DS_MERCHANT_AMOUNT>
        <DS_MERCHANT_ORDER type="xsd:string"> unique_operation_reference </DS_MERCHANT_ORDER>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        <DS_ORIGINAL_IP type="xsd:string"> 1.2.3.4  </DS_ORIGINAL_IP>
        <DS_MERCHANT_MERCHANTDESCRIPTOR type="xsd:string"> Commerce descriptor </DS_MERCHANT_MERCHANTDESCRIPTOR>
        </mns:preauthorization_confirm>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

function preauthorizationConfirm(
    $idpayuser,
    $tokenpayuser,
    $amount,
    $transreference,
    $merchant_description = null
) {
    $signature = hash("sha512",
        $merchantCode
        . $idpayuser
        . $tokenpayuser
        . $terminal
        . $transreference
        . $amount
        . $password
    );
    $ip = $_SERVER["REMOTE_ADDR"];
    try {
        $clientSOAP = new SoapClient($endpoint);
        $ans = $clientSOAP->preauthorization_confirm(
            $merchantCode,
            $terminal,
            $idpayuser,
            $tokenpayuser,
            $amount,
            $transreference,
            $signature,
            $ip,
            $merchant_description
        );
    } catch (SoapFault $e) {
        var_dump($e);
    }
    var_dump($ans);
}

public ServiceResponse preauthorization_confirm(String[] args) {

    String merchantcode = args[0];
    String terminal = args[1];
    String password = args[2];
    String ipaddr = args[3];
    String iduser = args[4];
    String tokenuser = args[5];
    String merchantamount = args[6];
    String merchantorder = args[7];

    merchantsignature = makeSHA1hash(merchantcode + iduser + tokenuser + this.terminal + merchantorder + merchantamount + password);

    ServiceResponse result = new ServiceResponse();

    SoapObject soapReq = new SoapObject("preauthorization_confirm");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("DS_IDUSER", iduser);
    soapReq.addProperty("DS_TOKEN_USER", dS_TOKEN_UtokenuserSER);
    soapReq.addProperty("DS_MERCHANT_AMOUNT", merchantamount);
    soapReq.addProperty("DS_MERCHANT_ORDER", merchantorder);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);
    soapReq.addProperty("DS_ORIGINAL_IP", ipaddr);

    return callSoap(result, soapReq);
}

Cancelación de una preautorización a usuario en el sistema

Función: (preauthorization_cancel)

Una vez realizada una preautorización, puede cancelarse la misma dentro de los 7 días siguientes.

Las variables que se requieren para cancelar la preautorización y los elementos de respuesta son los mismas que para la confirmación de preautorización.

Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:preauthorization_cancel xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_IDUSER type="xsd:string"> paycometuserid  </DS_IDUSER>
        <DS_TOKEN_USER type="xsd:string"> paycometusertoken  </DS_TOKEN_USER>
        <DS_MERCHANT_AMOUNT type="xsd:string"> 1234 </DS_MERCHANT_AMOUNT>
        <DS_MERCHANT_ORDER type="xsd:string"> unique_operation_reference </DS_MERCHANT_ORDER>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        <DS_ORIGINAL_IP type="xsd:string"> 1.2.3.4  </DS_ORIGINAL_IP>
        </mns:preauthorization_cancel>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

function preauthorizationCancel(
    $idpayuser,
    $tokenpayuser,
    $amount,
    $transreference
) {
    $signature = hash("sha512",
        $merchantCode
        . $idpayuser
        . $tokenpayuser
        . $terminal
        . $transreference
        . $amount
        . $password
    );
    $ip = $_SERVER["REMOTE_ADDR"];
    try {
        $clientSOAP = new SoapClient($endpoint);
        $ans = $clientSOAP->preauthorization_cancel(
            $merchantCode,
            $terminal,
            $idpayuser,
            $tokenpayuser,
            $amount,
            $transreference,
            $signature,
            $ip
        );
    } catch (SoapFault $e) {
        var_dump($e);
    }
    var_dump($ans);
}

public ServiceResponse preauthorization_cancel(String[] args) {

    String merchantcode = args[0];
    String terminal = args[1];
    String password = args[2];
    String ipaddr = args[3];
    String iduser = args[4];
    String tokenuser = args[5];
    String merchantamount = args[6];
    String merchantorder = args[7];

    merchantsignature = makeSHA1hash(merchantcode + iduser + tokenuser + this.terminal + merchantorder + merchantamount + password);

    ServiceResponse result = new ServiceResponse();

    SoapObject soapReq = new SoapObject("preauthorization_cancel");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("DS_IDUSER", iduser);
    soapReq.addProperty("DS_TOKEN_USER", tokenuser);
    soapReq.addProperty("DS_MERCHANT_AMOUNT", merchantamount);
    soapReq.addProperty("DS_MERCHANT_ORDER", merchantorder);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);
    soapReq.addProperty("DS_ORIGINAL_IP", ipaddr);

    return callSoap(result, soapReq);
}

Confirmación de una preautorización diferida a usuario en el sistema

Función: (deferred_preauthorization_confirm)

Una vez realizada y autorizada una operación de preautorización diferida, puede confirmarse para realizar el cobro efectivo dentro de las 72 horas siguientes; pasada esa fecha, las preautorizaciones diferidas pierden su validez. El importe de la confirmación de preautorización diferida debe ser exactamente igual al de la preautorización diferida original.

Las variables que se requieren para confirmar la preautorización diferida son las mismos que para confirmar la preautorización.

La respuesta del servicio tendrá los mismos elementos que la respuesta de la preautorización

Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:deferred_preauthorization_confirm xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_IDUSER type="xsd:string"> paycometuserid  </DS_IDUSER>
        <DS_TOKEN_USER type="xsd:string"> paycometusertoken  </DS_TOKEN_USER>
        <DS_MERCHANT_AMOUNT type="xsd:string"> 1234 </DS_MERCHANT_AMOUNT>
        <DS_MERCHANT_ORDER type="xsd:string"> unique_operation_reference </DS_MERCHANT_ORDER>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        <DS_ORIGINAL_IP type="xsd:string"> 1.2.3.4  </DS_ORIGINAL_IP>
        </mns:deferred_preauthorization_confirm>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

function deferredPreauthorizationConfirm(
    $idpayuser,
    $tokenpayuser,
    $amount,
    $transreference
) {
    $signature = hash("sha512",
        $merchantCode
        . $idpayuser
        . $tokenpayuser
        . $terminal
        . $transreference
        . $amount
        . $password
    );
    $ip = $_SERVER["REMOTE_ADDR"];
    try {
        $clientSOAP = new SoapClient($endpoint);
        $ans = $clientSOAP->deferred_preauthorization_confirm(
            $merchantCode,
            $terminal,
            $idpayuser,
            $tokenpayuser,
            $amount,
            $transreference,
            $signature,
            $ip
        );
    } catch (SoapFault $e) {
        var_dump($e);
    }
    var_dump($ans);
}

public ServiceResponse deferred_preauthorization_confirm(String[] args) {

    String merchantcode = args[0];
    String terminal = args[1];
    String password = args[2];
    String ipaddr = args[3];
    String iduser = args[4];
    String tokenuser = args[5];
    String merchantamount = args[6];
    String merchantorder = args[7];
    
    merchantsignature = makeSHA1hash(merchantcode + iduser + tokenuser + this.terminal + merchantorder + merchantamount + password);
    
    ServiceResponse result = new ServiceResponse();

    SoapObject soapReq = new SoapObject("deferred_preauthorization_confirm");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("DS_IDUSER", iduser);
    soapReq.addProperty("DS_TOKEN_USER", tokenuser);
    soapReq.addProperty("DS_MERCHANT_AMOUNT", merchantamount);
    soapReq.addProperty("DS_MERCHANT_ORDER", merchantorder);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);
    soapReq.addProperty("DS_ORIGINAL_IP", ipaddr);

    return callSoap(result, soapReq);
}

Cancelación de una preautorización diferida a usuario en el sistema

Función: (deferred_preauthorization_cancel)

Una vez realizada una preautorización diferida, puede cancelarse la misma dentro de las 72 horas siguientes.

Las variables que se requieren para cancelar la preautorización diferida y los elementos de respuesta son los mismas que para la confirmación de preautorización diferida.

Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:deferred_preauthorization_cancel xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_IDUSER type="xsd:string"> paycometuserid  </DS_IDUSER>
        <DS_TOKEN_USER type="xsd:string"> paycometusertoken  </DS_TOKEN_USER>
        <DS_MERCHANT_AMOUNT type="xsd:string"> 1234 </DS_MERCHANT_AMOUNT>
        <DS_MERCHANT_ORDER type="xsd:string"> unique_operation_reference </DS_MERCHANT_ORDER>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        <DS_ORIGINAL_IP type="xsd:string"> 1.2.3.4  </DS_ORIGINAL_IP>
        </mns:deferred_preauthorization_cancel>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

function deferredPreauthorizationCancel(
    $idpayuser,
    $tokenpayuser,
    $amount,
    $transreference
) {
    $signature = hash("sha512",
        $merchantCode
        . $idpayuser
        . $tokenpayuser
        . $terminal
        . $transreference
        . $amount
        . $password
    );
    $ip = $_SERVER["REMOTE_ADDR"];
    try {
        $clientSOAP = new SoapClient($endpoint);
        $ans = $clientSOAP->deferred_preauthorization_cancel(
            $merchantCode,
            $terminal,
            $idpayuser,
            $tokenpayuser,
            $amount,
            $transreference,
            $signature,
            $ip
        );
    } catch (SoapFault $e) {
        var_dump($e);
    }
    var_dump($ans);
}

public ServiceResponse deferred_preauthorization_cancel(String[] args) {

    String merchantcode = args[0];
    String terminal = args[1];
    String password = args[2];
    String ipaddr = args[3];
    String iduser = args[4];
    String tokenuser = args[5];
    String merchantamount = args[6];
    String merchantorder = args[7];

    ServiceResponse result = new ServiceResponse();

    merchantsignature = makeSHA1hash(merchantcode + iduser + tokenuser + terminal + merchantorder + merchantamount + password);

    SoapObject soapReq = new SoapObject("deferred_preauthorization_cancel");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("DS_IDUSER", iduser);
    soapReq.addProperty("DS_TOKEN_USER", tokenuser);
    soapReq.addProperty("DS_MERCHANT_AMOUNT", merchantamount);
    soapReq.addProperty("DS_MERCHANT_ORDER", merchantorder);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);
    soapReq.addProperty("DS_ORIGINAL_IP", ipaddr);

    return callSoap(result, soapReq);
}

Ejecución de alta de usuario en el sistema mediante Token

Función: (add_user_token)

Este método permite dar de alta un usuario en base a un token obtenido previamente mediante la solución BankStore JET

Las variables que se requieren para dar de alta a un usuario son (en este orden):

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_MERCHANT_JETTOKEN [a-z0-9]{64} Obligatorio. Token obtenido mediante javascript.
DS_MERCHANT_JETID [a-z0-9]{32} Obligatorio. Identificador para la encriptación JET.
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS
DS_ORIGINAL_IP A.B.C.D Obligatorio. Dirección IP del cliente que inició la operación

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_IDUSER [0-9]{1,13} Identificador único del usuario registrado en el sistema. Volverá vacío en caso de error.
DS_TOKEN_USER [A-Za-z0-9]{1,20} Código token asociado al DS_IDUSER.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.
Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:add_user_token xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_MERCHANT_JETTOKEN type="xsd:string"> paycomettoken  </DS_MERCHANT_JETTOKEN>
        <DS_MERCHANT_JETID type="xsd:string"> yourjetid  </DS_MERCHANT_JETID>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        <DS_ORIGINAL_IP type="xsd:string"> 1.2.3.4  </DS_ORIGINAL_IP>
        </mns:add_user_token>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

function addUserToken($jettoken)
{
    $signature 
        = hash("sha512",
             $merchantCode
            .$jettoken
            .$jetid
            .$terminal
            .$password
    );
    $ip	= $_SERVER["REMOTE_ADDR"];
    try{
        $clientSOAP = new SoapClient($endpoint);
        $ans 
            = $clientSOAP
                ->add_user_token(
                    $merchantCode,
                    $terminal,
                    $jettoken,
                    $jetid,
                    $signature,
                    $ip
                );
    } catch(SoapFault $e){
        var_dump($e);
        return false;
    }
    var_dump($ans);
    return $ans;
}

public ServiceResponse add_user_token(String[] args) {

    String merchantcode = args[0];
    String terminal = args[1];
    String password = args[2];
    String ipaddr = args[3];
    String jetid = args[4];
    String jettoken = args[5];

    merchantsignature = makeSHA1hash(merchantcode + jettoken + jetid + terminal + password);

    ServiceResponse result = new ServiceResponse();
    
    SoapObject soapReq = new SoapObject("add_user_token");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("DS_MERCHANT_JETTOKEN", jettoken);
    soapReq.addProperty("DS_MERCHANT_JETID", jetid);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);
    soapReq.addProperty("DS_ORIGINAL_IP", ipaddr);

    return callSoap(result, soapReq);
}

Ejecución de Cobro a un usuario por Referencia

Función: execute_purchase_rtoken

Este método permite ejecutar un cobro en base a un token obtenido previamente mediante la solución de Pago por Referencia

Las variables que se requieren para dar de alta a un usuario son (en este orden):

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_MERCHANT_AMOUNT [0-9]{1,8} Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_MERCHANT_ORDER [A-Za-z0-9]{1,70} Obligatorio. Referencia de la operación. Debe ser única en cada transacción válida.
DS_MERCHANT_IDENTIFIER [a-z0-9]{40} Identificador obtenido mediante anterior Pago por Referencia
DS_MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS
DS_MERCHANT_MERCHANTDESCRIPTOR [A-Za-z0-9]{1,25} Opcional. Permite al comercio enviar un texto de hasta 25 caracteres que se imprimirá en la factura del cliente. Uso exclusivo de caracteres simples, sin acentos ni caracteres especiales.

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_MERCHANT_AMOUNT [0-9]{1,8} Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Referencia de la operación
DS_MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_AUTHCODE [a-zA-Z0-9]{1,40} Código bancario de autorización de la transacción (necesario para ejecutar una devolución).
DS_MERCHANT_CARDCOUNTRY [0-9]{1,3} País del emisor de la tarjeta en código ISO3 (ej: 724 = España). Puede venir vacío.
DS_RESPONSE [0-1]{1} Resultado de la operación. 0 o vacío será operación errónea y 1 operación completada.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.

Si la petición produjo un error de algún tipo (firma incorrecta, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá el campo DS_RESPONSE cuyo valor será 0 o vacío en caso de error y 1 en caso de éxito en la eliminación.

Ejemplos de integración en diferentes lenguajes:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:Paytpv_bankStoreGateway" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
        <mns:execute_purchase_rtoken xmlns:mns="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <DS_MERCHANT_MERCHANTCODE type="xsd:string"> yourmerchantcode  </DS_MERCHANT_MERCHANTCODE>
        <DS_MERCHANT_TERMINAL type="xsd:string"> yourterminal  </DS_MERCHANT_TERMINAL>
        <DS_MERCHANT_AMOUNT type="xsd:string"> 1234 </DS_MERCHANT_AMOUNT>
        <DS_MERCHANT_ORDER type="xsd:string"> unique_operation_reference </DS_MERCHANT_ORDER>
        <DS_MERCHANT_IDENTIFIER type="xsd:string"> merchantidentifier </DS_MERCHANT_IDENTIFIER>
        <DS_MERCHANT_CURRENCY type="xsd:string"> EUR </DS_MERCHANT_CURRENCY>
        <DS_MERCHANT_MERCHANTSIGNATURE type="xsd:string"> yourgeneratedsignature12345  </DS_MERCHANT_MERCHANTSIGNATURE>
        <DS_MERCHANT_PRODUCTDESCRIPTION type="xsd:string"> Product description </DS_MERCHANT_PRODUCTDESCRIPTION>
        <DS_MERCHANT_MERCHANTDESCRIPTOR type="xsd:string"> Commerce descriptor </DS_MERCHANT_MERCHANTDESCRIPTOR>
        </mns:execute_purchase_rtoken>    
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

function executePurchaseRToken(
    $amount,
    $transreference,
    $rtoken,
    $currency,
    $productdescription = false,
    $merchant_description = null
) {
    $signature = hash("sha512",
        $terminal
        . $amount
        . $transreference
        . $rtoken
        . $password
    );
    try {
        $clientSOAP = new SoapClient($endpoint);
        $ans = $clientSOAP->execute_purchase_rtoken(
            $merchantCode,
            $terminal,
            $amount,
            $transreference,
            $rtoken,
            $currency,
            $signature,
            $productdescription,
            $merchant_description
        );
    } catch (SoapFault $e) {
        var_dump($e);
    }
    var_dump($ans);
}

public ServiceResponse execute_purchase_rtoken(String[] args) {

    String merchantcode = args[0];
    String terminal = args[1];
    String password = args[2];
    String merchantamount = args[3];
    String merchantorder = args[4];
    String merchantidentifier = args[5];
    String merchantcurrency = args[6];
    String merchantaproductdescription = args[7];

    merchantsignature = makeSHA1hash(merchantcode + this.terminal + merchantamount + merchantorder + merchantidentifier + password);

    ServiceResponse result = new ServiceResponse();

    SoapObject soapReq = new SoapObject("execute_purchase_rtoken");
    soapReq.addProperty("DS_MERCHANT_MERCHANTCODE", merchantcode);
    soapReq.addProperty("DS_MERCHANT_TERMINAL", terminal);
    soapReq.addProperty("DS_MERCHANT_AMOUNT", merchantamount);
    soapReq.addProperty("DS_MERCHANT_ORDER", merchantorder);
    soapReq.addProperty("DS_MERCHANT_IDENTIFIER", merchantidentifier);
    soapReq.addProperty("DS_MERCHANT_CURRENCY", merchantcurrency);
    soapReq.addProperty("DS_MERCHANT_MERCHANTSIGNATURE", merchantsignature);
    soapReq.addProperty("DS_MERCHANT_PRODUCTDESCRIPTION", merchantaproductdescription);

    return callSoap(result, soapReq);
}

Notificación caducidad tarjeta

Para los usuarios dados de alta en el sistema Bankstore, existe la posibilidad de recibir una notificación informativa que avisará de la próxima caducidad de la tarjeta correspondiente a ese usuario / token.

Notificación (Llamada a URL)

A la URL de destino se le pasan los parámetros de la notificación con el método POST según la siguiente tabla:

TransactionType Numérico Tipo de operación (108) Ver TIPOS DE OPERACIONES.
TransactionName Alfanumérico Descripción de operación.
IdUser Numérico Id del usuario registrado en el sistema.
Terminal Numérico Identificador del terminal.
Name Alfanumérico Nombre del producto.
Domain Alfanumérico Dominio del producto.
MonthsToExpire Numérico Meses para la caducidad.

Recibir este tipo de notificaciones debe ser habilitado específicamente por PAYCOMET. Puede consultarnos a través del portal de cliente en el menú “Soporte -> Notificación de incidencia”.

Anexo I – Cálculo de la firma de comercio – XML Bankstore

La firma deberá ser calculada en el servidor del comercio y englobará los principales parámetros de la llamada para verificar la integridad de los datos a través de Internet y el navegador del comprador.

El algoritmo de cifrado utilizado al efecto será SHA512, el cual nos permite cifrar una cadena de texto. Este tipo de algoritmos de un solo sentido impide obtener el parámetro inicial a partir del resultado.

La firma se calculará de modos distintos dependiendo de la función utilizada, para verificar la integridad de los datos de envío a la plataforma.

Para facilitar la generación de la firma en lenguajes sin las herramientas necesarias para el cálculo de algoritmos SHA512 se han incluído una serie de librerías. Puede descargar los archivos desde el apartado Soporte -> Documentación del panel de control de cliente.

Algunas de estas librerías han sido realizadas por personas o entidades ajenas a PAYCOMET. Consulte el contenido de cada archivo para más información.

CÁLCULOS DE FIRMAS DEPENDIENDO DE LA FUNCIÓN EMPLEADA

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

Función: (add_user)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_MERCHANT_PAN + DS_MERCHANT_CVV2 + DS_MERCHANT_TERMINAL + PASSWORD)

 

Función: (info_user)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_IDUSER + DS_TOKEN_USER + DS_MERCHANT_TERMINAL + PASSWORD)

 

Función: (remove_user)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_IDUSER + DS_TOKEN_USER + DS_MERCHANT_TERMINAL + PASSWORD)

 

Función: (execute_purchase)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_IDUSER + DS_TOKEN_USER + DS_MERCHANT_TERMINAL + DS_MERCHANT_AMOUNT + DS_MERCHANT_ORDER + PASSWORD)

 

Función: (execute_purchase_dcc)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_IDUSER + DS_TOKEN_USER + DS_MERCHANT_TERMINAL + DS_MERCHANT_AMOUNT + DS_MERCHANT_ORDER + PASSWORD)

 

Función: (confirm_purchase_dcc)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_MERCHANT_TERMINAL + DS_MERCHANT_ORDER + DS_MERCHANT_DCC_CURRENCY + DS_MERCHANT_DCC_SESSION + PASSWORD)

 

Función: (execute_refund)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_IDUSER + DS_TOKEN_USER + DS_MERCHANT_TERMINAL + DS_MERCHANT_AUTHCODE + DS_MERCHANT_ORDER + PASSWORD)

 

Función: (create_subscription)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_MERCHANT_PAN + DS_MERCHANT_CVV2 + DS_MERCHANT_TERMINAL + DS_SUBSCRIPTION_AMOUNT + DS_SUBSCRIPTION_CURRENCY + PASSWORD)

 

Función: (edit_subscription)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_IDUSER + DS_TOKEN_USER + DS_MERCHANT_TERMINAL + DS_SUBSCRIPTION_AMOUNT + PASSWORD)

 

Función: (remove_subscription)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_IDUSER + DS_TOKEN_USER + DS_MERCHANT_TERMINAL + PASSWORD)

 

Función: (create_subscription_token)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_IDUSER + DS_TOKEN_USER + DS_MERCHANT_TERMINAL + DS_SUBSCRIPTION_AMOUNT + DS_SUBSCRIPTION_CURRENCY + PASSWORD)

 

Función: (create_preauthorization)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_IDUSER + DS_TOKEN_USER + DS_MERCHANT_TERMINAL + DS_MERCHANT_AMOUNT + DS_MERCHANT_ORDER + PASSWORD)

 

Función: (preauthorization_confirm)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_IDUSER + DS_TOKEN_USER + DS_MERCHANT_TERMINAL + DS_MERCHANT_ORDER + DS_MERCHANT_AMOUNT + PASSWORD)

 

Función: (preauthorization_cancel)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_IDUSER + DS_TOKEN_USER + DS_MERCHANT_TERMINAL + DS_MERCHANT_ORDER + DS_MERCHANT_AMOUNT + PASSWORD)

 

Función: (deferred_preauthorization_confirm)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_IDUSER + DS_TOKEN_USER + DS_MERCHANT_TERMINAL + DS_MERCHANT_ORDER + DS_MERCHANT_AMOUNT + PASSWORD)

 

Función: (deferred_preauthorization_cancel)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_IDUSER + DS_TOKEN_USER + DS_MERCHANT_TERMINAL + DS_MERCHANT_ORDER + DS_MERCHANT_AMOUNT + PASSWORD)

 

Función: (add_user_token)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_MERCHANT_JETTOKEN + DS_MERCHANT_JETID + DS_MERCHANT_TERMINAL + PASSWORD)

 

Función: (execute_purchase_rtoken)

SHA512(DS_MERCHANT_MERCHANTCODE + DS_MERCHANT_TERMINAL + DS_MERCHANT_AMOUNT + DS_MERCHANT_ORDER + DS_MERCHANT_IDENTIFIER + PASSWORD)

 

Anexo II – Tipos de operaciones

Los tipos de operaciones que se notificarán, se detallan en la siguiente tabla:

ID Operación
1 Autorización
2 Devolución
3 Preautorización
4 Cancelación de preautorización
6 Confirmación de preautorización
9 Suscripción
13 Preautorización diferida
14 Cancelación de preautorización diferida
16 Confirmación de preautorización diferida
106 Retroceso
107 Alta de usuario Bankstore
108 Caducidad de Tarjeta