Storing Payment Data (Tokenization)

note

Remember that these API calls will be HTTP POST requests to the TCP/IP address where DeviceHub is installed. Typically, this address will be:

POST http://localhost:17000

For its operation, it is necessary to register the card by taking advantage of a sale or return transaction in order to store the data and thus authenticate the operation.

The card is registered with a contract number, which can later be used to make recurring sales or returns, without the need to use the card data in transactions.

To carry out these processes, Sipay will provide security certificates that must be installed on the PCs using this functionality.

Requirements to use the vault operation

Integrate the messaging described in the following sections.
Have contracted this service with Sipay.
Have installed the DeviceHub service release 5.X.X or higher.
Have the client.pem and cacert.pem certificates stored in the DeviceHub folder.
Validate the ShieldServices configuration in the DeviceHub Configurator.

For all vault operations, the CallSpecificFunction function is used. Below are the different allowed functions:

CallSpecificFunction

There are special calls that offer their functionality through the content of the XML message itself. They are known as CallSpecificFunction. They have the same common elements as all calls: ClientIdValue, ... but in addition, all of this type have the following common parameters:

Function
Modifier
Parameter 1
Parameter 2
Parameter 3

Below is a generic example as a prototype:

<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 - Vault Storage via Sale

This function performs a sale through the PIN Pad and stores the card in a single operation.

Parameters

The header data must be the same as in all transactions.

Function: 13
Modifier: 0
Parameter1: String type, the amount of the transaction (see Note 1).
Parameter2: Ticket number for the sale to be performed.
Parameter3: XML with data related to the storage of the operation.

XML Parameter3 Format:

<SHIELD>
    <CONTRACT_NUMBER>ContractNumber</CONTRACT_NUMBER>
    <EXPIRATION_DAYS>ExpirationDays</EXPIRATION_DAYS>
</SHIELD>

TAG	VALUE	COMMENTS
PAN	PAN Number	Not used.
CCV	CCV Number	Not used.
CONTRACT	Contract Number	The contract number is the identification with which the card information will be stored in the system. This identification can be used later to perform transactions on that card with this identifier.
TICKET	Ticket Number	The ticket number is required if you want to store card information after a sale transaction.
EXPIRE_DAYS	Days Count	Number of days the card will remain stored in the vault. Ex: 365 = 1 year

Like all other CallSpecificfunction calls, the final response is obtained through the GetNextMessage operation.

For sale and return actions with vault storage, the response codes may be:

1001 > Denied (The sale has been denied, therefore the card is not stored).
1000 > Accepted (The sale has been accepted and the card has been stored correctly).
1005 > Accepted (The sale has been accepted, but the card could not be stored. In this case, the merchant must take action to have the card data in order to make a subsequent registration without a card).

Note 1: Amount in the same format as the transaction with 10 digits, where the last 2 are cents.

Ex: €1.25 -> 0000000125

Request: 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>

Response: 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 - Vault Storage via Return

This function performs a return through the PIN Pad and stores the card in a single operation.

Parameters

The header data must be the same as in all transactions.

Function: 14
Modifier: 0
Parameter1: String type, the amount of the transaction (see Note 1).
Parameter2: Ticket number for the return to be performed (see Note 2).
Parameter3: XML with data related to the storage of the operation.

XML Parameter3 Format:

<SHIELD>
    <CONTRACT_NUMBER>ContractNumber</CONTRACT_NUMBER>
    <EXPIRATION_DAYS>ExpirationDays</EXPIRATION_DAYS>
</SHIELD>

TAG	VALUE	COMMENTS
PAN	PAN Number	Not used.
CCV	CCV Number	Not used.
EXPIRATION_DATE	Expiry Date	Expiry date of the card. Ex: 1218 > Expires in December 2018.
CONTRACT	Contract Number	The contract number is the identification with which the card information will be stored in the system. This identification can be used later to perform transactions on that card with this identifier.
TICKET	Ticket Number	The ticket number is required if you want to store card information after a sale transaction.
EXPIRE_DAYS	Days Count	Number of days the card will remain stored in the vault. Ex: 365 = 1 year.

Like all other CallSpecific function calls, the final response is obtained through the GetNextMessage operation.

For sale and return actions with vault storage, the response codes may be:

1001: Denied (The return has been denied, therefore the card is not stored).
1000: Accepted (The return has been accepted and the card has been stored correctly).
1005: Accepted (The return has been accepted, but the card could not be stored. In this case, the merchant must take action to have the card data in order to make a subsequent registration without a card).

Note 1: Amount in the same format as the transaction with 10 digits, where the last 2 are cents. Ex: €1.25 -> 0000000125

Note 2: For those merchants who work with return verification, this ticket number must be the same as the original sale.

CallSpecificFunction​

CallSpecificFunction 13 - Vault Storage via Sale​

Request: CallSpecificFunction 13​

Response: CallSpecificFunction 13​

CallSpecificFunction 14 - Vault Storage via Return​

CallSpecificFunction

CallSpecificFunction 13 - Vault Storage via Sale

Request: CallSpecificFunction 13

Response: CallSpecificFunction 13

CallSpecificFunction 14 - Vault Storage via Return