Saltar al contenido principal

Almacenar datos de pago (tokenización)

nota

Recuerda que estas llamadas API serán peticiones HTTP POST a un la dirección TCP/IP donde está instalado el DeviceHub. Normalmente esta dirección será:

POST http://localhost:17000

Para su funcionamiento es necesario registrar la tarjeta aprovechando una transacción de venta o devolución para poder almacenar los datos y así autenticar la operación.

La tarjeta queda registrada con número de contracto, que posteriormente se puede utilizar para efectuar ventas o devoluciones recurrentes, sin necesidad de utilizar los datos de la tarjeta en las transacciones.

Para la realización de estos procesos, Sipay entregará unos certificados de seguridad que tendrán que estar instalados en los PC´s que utilicen esta funcionalidad.

Requerimientos para utilizar la operativa de bóveda

  • Integrar la mensajería descrita en los siguientes apartados.
  • Haber contratado este servicio a Sipay.
  • Tener instalado el servicio device hub release 5.X.X o superior.
  • Disponer de los certificados client.pem y cacert.pem almacenados en la carpeta DeviceHub.
  • Validar la configuración de ShieldServices en el DeviceHub Configurator.

Para todas las operaciones de bóveda, se utilizan la función CallSpecificFunction. A continuación, se describen las distintas funciones permitidas:

CallSpecificFunction​

Existen llamadas especiales que ofrecen su funcionalidad a través del contenido del propio mensaje XML. Son conocidas como CallSpecificFunction. Tienen los mismos elemementos comunes que todas las llamadas: ClientIdValue, ... pero además todas las de este tipo tienen los siguientes parámetros comunes:

  • Function
  • Modifier
  • Parameter 1
  • Parameter 2
  • Parameter 3

A continuación incluimos un ejemplo genérico a modo de prototipo:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:tem="http://tempuri.org/">
   <soap:Header/>
   <soap:Body>
      <tem:CallSpecificFunctionRequest>
         <tem:Header>
            <tem:ClientId>ClientIdValue</tem:ClientId>
            <tem:StoreId>StoreIdValue</tem:StoreId>
            <tem:PosId>PosValue</tem:PosId>
            <tem:Lang>Idioma</tem:Lang>
            <tem:ExtraData1></tem:ExtraData1>
         </tem:Header>
         <tem:Function>FunctionCode</tem:Function>
         <tem:Modifier>FunctionModifier</tem:Modifier>
         <tem:Parameter1>Parameter1</tem:Parameter1>
         <tem:Parameter2>Parameter1</tem:Parameter2>
         <tem:Parameter3>Parameter3</tem:Parameter3>
      </tem:CallSpecificFunctionRequest>
   </soap:Body>
</soap:Envelope>

CallSpecificFunction 13 - Almacenamiento en bóveda mediante una venta​

Esta función realiza una venta, a través del PIN Pad y almacena la tarjeta en una única operación.

Parámetros

Los datos de Header deben ser iguales que en todas las transacciones.

  • Function: 13
  • Modifier: 0
  • Parameter1: Tipo string el importe de la transacción (véase Nota 1).
  • Parameter2: Número de ticket para la venta que se va a realizar.
  • Parameter3: XML con datos relacionados con el almacenamiento de la operación.

Formato XML Parameter3:

<SHIELD>
    <CONTRACT_NUMBER>ContractNumber</CONTRACT_NUMBER>
    <EXPIRATION_DAYS>ExpirationDays</EXPIRATION_DAYS>
</SHIELD>
ETIQUETAVALORCOMENTARIOS
PANNº PANNo utilizado.
CCVNº CCVNo utilizado.
CONTRACTNº de ContratoEl número de contrato es la identificación con la que se guardará la información de tarjeta en el sistema.Esta identificación se puede usar posteriormente para realizar transacciones sobre esa tarjeta con este identificador.
TICKETNº de Ticket/boletaEl número de ticket es necesario si se quiere guardar la información de tarjeta tras una transacción de venta.
EXPIRE_DAYSCantidad de díasNúmero de días en que la tarjeta permanecerá almacenada en bóveda.Ej.: 365 = 1 año

Como todas las demás llamadas de CallSpecificfunction, la respuesta final se obtiene a través de la operativa de GetNextMessage.

Para las acciones de venta y devolución con almacenamiento en bóveda, los códigos de respuesta podrán ser:

  • 1001 > Denegada (La venta ha sido denegada, por lo tanto no se almacena la tarjeta).
  • 1000 > Aceptada (La venta ha sido aceptada y se ha almacenado correctamente la tarjeta).
  • 1005 > Aceptada (La venta ha sido aceptada, pero no se pudo almacenar la tarjeta. En este caso el comercio deberá tomar una medida para tener los datos de la tarjeta con el fin de realizar un registro posterior sin tarjeta).

Nota 1: Importe en el mismo formato que la transacción con 10 dígitos, donde los 2 últimos son céntimos. Ej.: 1.25€ -> 0000000125

Petición: CallSpecificFunction 13​

<soap:Envelope xmlns:soap=http://www.w3.org/2003/05/soap-envelope xmlns:tem=http://tempuri.org/>
   <soap:Header/>
   <soap:Body>
      <tem:CallSpecificFunctionRequest>
         <tem:Header>
            <tem:ClientId>ClientIdValue</tem:ClientId>
            <tem:StoreId>StoreIdValue</tem:StoreId>
            <tem:PosId>PosIdValue</tem:PosId>
            <tem:Lang>Idioma</tem:Lang>
            <tem:ExtraData1></tem:ExtraData1>
         </tem:Header>
         <tem:Function>13</tem:Function>
         <tem:Modifier>0</tem:Modifier>
         <tem:Parameter1>Importe</tem:Parameter1>
         <tem:Parameter2>Ticket</tem:Parameter2>
         <tem:Parameter3><SHIELD><CONTRACT_NUMBER>IdentificadorToken</CONTRACT_NUMBER><EXPIRATION_DAYS>365</EXPIRATION_DAYS><EXPIRATION_DATE>1217</EXPIRATION_DATE></SHIELD></tem:Parameter3>
      </tem:CallSpecificFunctionRequest>
   </soap:Body>
</soap:Envelope>

Respuesta: CallSpecificFunction 13​

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV=http://www.w3.org/2003/05/soap-envelope xmlns:SOAP-ENC=http://www.w3.org/2003/05/soap-encoding xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:ns2=http://tempuri.org/SipayPlusAccess xmlns:ns1=http://tempuri.org/>
    <SOAP-ENV:Header></SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <ns1:GetNextMessageResponse>
            <ns1:Result>
                <ns1:Code>0</ns1:Code>
                <ns1:Description>Ok</ns1:Description>
            </ns1:Result>
            <ns1:Message>
                <ns1:MessageCode>1000</ns1:MessageCode>
                <ns1:MessageText>OPERACIÓN ACEPTADA</ns1:MessageText>
                <ns1:PrintableData>
                    <ns1:OperationType>Venta</ns1:OperationType>
                    <ns1:AuthorizationMode>O</ns1:AuthorizationMode>
                    <ns1:ACRCode>00</ns1:ACRCode>
                    <ns1:DataInputType>C</ns1:DataInputType>
                    <ns1:DataVerificationType>*</ns1:DataVerificationType>
                    <ns1:FUCCode></ns1:FUCCode>
                    <ns1:Terminal></ns1:Terminal>
                    <ns1:HCP>BANCO DE SABADELL, S.A.</ns1:HCP>
                    <ns1:Store></ns1:Store>
                    <ns1:City></ns1:City>
                    <ns1:CardHolder></ns1:CardHolder>
                    <ns1:AID>A0000000041010</ns1:AID>
                    <ns1:DDFName>A0000000041010</ns1:DDFName>
                    <ns1:AppLabel>MASTERCARD</ns1:AppLabel>
                    <ns1:ContactlessLiteral>5</ns1:ContactlessLiteral>
                    <ns1:CardNumber>************1234</ns1:CardNumber>
                    <ns1:SequenceNumber>60083519</ns1:SequenceNumber>
                    <ns1:TerminalLabel></ns1:TerminalLabel>
                    <ns1:DateTime>19/05/2023 - 12:13:37</ns1:DateTime>
                    <ns1:TerminalSequence>0026</ns1:TerminalSequence>
                    <ns1:AuthorizationNumber>670492</ns1:AuthorizationNumber>
                    <ns1:Amount>0.01</ns1:Amount>
                    <ns1:CurrencySimbol>EUR</ns1:CurrencySimbol>
                    <ns1:InfoText>CP</ns1:InfoText>
                    <ns1:Aclaratory></ns1:Aclaratory>
                    <ns1:ExtraData1>&ldata_maskedt;&lt;/ExtraData1&gt;</ns1:ExtraData1>
                    <ns1:ExtraData2></ns1:ExtraData2>
                </ns1:PrintableData>
                <ns1:ExtraInfo>
                    <ns1:TaxFreeEnabled>0</ns1:TaxFreeEnabled>
                    <ns1:Feature1>0</ns1:Feature1>
                    <ns1:Feature2>0</ns1:Feature2>
                    <ns1:Feature3>0</ns1:Feature3>
                    <ns1:Feature4>0</ns1:Feature4>
                    <ns1:AuthorizationCode></ns1:AuthorizationCode>
                    <ns1:FeatureInfo></ns1:FeatureInfo>
                </ns1:ExtraInfo>
            </ns1:Message>
        </ns1:GetNextMessageResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

CallSpecificFunction 14 - Almacenamiento en bóveda mediante una devolución​

Esta función realiza una devolución, a través del PIN Pad y almacena la tarjeta en una única operación.

Parámetros

Los datos de Header deben ser iguales que en todas las transacciones.

  • Function: 14
  • Modifier: 0
  • Parameter1: Tipo string el importe de la transacción (véase Nota 1).
  • Parameter2: Numero de Ticket para la devolución que se va a realizar (véase Nota 2).
  • Parameter3: XML con datos relacionados con el almacenamiento de la operación.

Formato XML Parameter3:

<SHIELD>
    <CONTRACT_NUMBER>ContractNumber</CONTRACT_NUMBER>
    <EXPIRATION_DAYS>ExpirationDays</EXPIRATION_DAYS>
</SHIELD>
ETIQUETAVALORCOMENTARIOS
PANNº PANNo utilizado.
CCVNº CCVNo utilizado.
EXPIRATION_DATEFecha de caducidadFecha de caducidad de la tarjeta.Ej.: 1218 > Expira en diciembre de 2018.
CONTRACTNº de ContratoEl número de contrato es la identificación con la que se guardará la información de tarjeta en el sistema. Esta identificación se pude usar posteriormente para poder realizar transacciones sobre esa tarjeta con este identificador.
TICKETNº de Ticket/boletaEl número de ticket es necesario si se quiere guardar la información de tarjeta tras una transacción de venta.
EXPIRE_DAYSCantidad de díasNúmero de días en que la tarjeta permanecerá almacenada en bóveda. Ej.:365 = 1 año.

Como todas las demás llamadas de CallSpecific function, la respuesta final se obtiene a través de la operativa de GetNextMessage.

Para las acciones de venta y devolución con almacenamiento en bóveda, los códigos de respuesta podrán ser:

  • 1001: Denegada (La devolución ha sido denegada, por lo tanto no se almacena la tarjeta)
  • 1000: Aceptada (La devolución ha sido aceptada y se ha almacenado correctamente la tarjeta)
  • 1005: Aceptada (La devolución ha sido aceptada, pero no se ha podido almacenar la tarjeta. En este caso, el comercio deberá tomar la medida para tener los datos de la tarjeta con el fin de realizar un registro posterior sin tarjeta).

Nota 1: Importe en el mismo formato que la transacción con 10 dígitos, donde los 2 últimos son céntimos. EJ.: 1.25€ -> 0000000125

Nota 2: Para aquellos comercios que trabajen con devolución con comprobación este número de ticket debe ser igual al de la venta original.