Additional Functions

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

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>

Referenced Returns [BeginDevolution]

In this case, having an amount and a ticket number, the return transaction is launched, requesting financial authorization. The response code reflects whether the request has been delivered to the DeviceHub service. To obtain the transaction result, it is necessary to use the GetNextMessage function.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:tem="http://tempuri.org/">
   <soap:Header/>
   <soap:Body>
      <tem:BeginDevolutionRequest>
         <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:Amount>Importe</tem:Amount>
         <tem:TicketNumber>TicketNumber</tem:TicketNumber>
      </tem:BeginDevolutionRequest>
   </soap:Body>
</soap:Envelope>

Request: BeginDevolutionRequest

TYPE	NAME	COMMENTS
Header	Header	Data used during subsequent queries.
String	Amount	Refund amount. Amount of the operation with 10 numeric digits, where the last two digits represent the cents.
String	TicketNumber	Refund receipt number.

Header

TYPE	NAME	COMMENTS
String	Clientid	Merchant identifier.
String	Storeid	Store identifier.
String	Posid	Point of Sale Terminal identifier.
String	Language	Language identifier: 0 Spanish 1 English.
String	ExtraData1	Not used.

Note: The Posid field must not exceed 30 characters, and it is recommended not to use the following symbols within the field: {"/","\"}

Output Parameters

Response: BeginDevolutionResponse

TYPE	NAME	COMMENTS
Result	Result	Returns 0=OK or an error code and its description.

Result

TYPE	NAME	COMMENTS
Int	Code	Error code.
String	Description	Error description

Ticket Printing Information

The cash register software must include a series of data for ticket printing. The mandatory and optional fields are as follows:

MANDATORY RETURN RECEIPT FIELDS
Operation type
Merchant name
City of merchant
Card number replacing the first 12 digits with '*'
Application label with the following priority 'ApplicationLabel(T50), 'Terminal label'(Only if the operation was carried out with EMV card)
Operation date and time (DDMMYY hhmm)
Authorization number
Operation amount with currency indication
Merchant's receipt: Indicate that it is a copy and that it is for the merchant
Customer receipt: Merchant signature box indicating that the receipt is for the customer
Other copies: Indicate that it is a copy

OPTIONAL FIELDS
Cardholder (some companies include it and others do not)
Authorizing center
Payment gateway

Ticket printing depends on the Pin Pad model used:

Fixed PIN Pads (integrated): Printing and ticket fields depend on the POS.
Wireless PIN Pads (stand-alone): Printing and ticket fields depend on the Sipay gateway.

IMPORTANT: It should be noted that ticket printing represents the completion of the transaction. If the ticket is not printed (on the POS or on the PIN Pad itself), the operation will not be completed, and it will be necessary to send a cancellation of the ongoing operation by the POS.

For those merchants who wish to work with return verification (return associated with a sale whose amount can never exceed that of the original sale), they must request the configuration from Sipay. The ticket number must be the same as that of the original sale. The verification return has a maximum return period of 3 months.

File 3000 Loading [CallSpecificFunction 20]

This operation allows the loading of a 3000 configuration file to the PIN Pads (file provided by Sipay Plus). During the process, no financial operations can be carried out.

The manufacturer recommends deleting the current parameters before performing a 3000 file upload. This deletion must be performed by the device keyboard, so if you need more information, please contact the Sipay support team.

Parameters:

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

Function: 20
Modifier: 0
Parameter1: Path and name of the 3000 file to load.

<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>20</tem:Function>
         <tem:Modifier>0</tem:Modifier>
         <tem:Parameter1>C:\path\to\file.txt</tem:Parameter1>
         <tem:Parameter2></tem:Parameter2>
         <tem:Parameter3></tem:Parameter3>
      </tem:CallSpecificFunctionRequest>
   </soap:Body>
</soap:Envelope>

PINOnline Key Loading [CallSpecificFunction 4]

Parameters:

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

Function: 4
Modifier: 0
Parameter1: Drawer number to update (1.9).
Parameter2: Not used.
Parameter3: Not used.

This functionality is only used on devices that work with PINOnline, and it triggers the request to update the keys with the processing entity.

It should be used when requested by the authorizing entity or when an initial PINOnline loading is to be performed on a compatible device. To carry out this action, you must contact the Sipay support team, as the device could become unusable in case of improper operation.

<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>4</tem:Function>
         <tem:Modifier>0</tem:Modifier>
         <tem:Parameter1>2</tem:Parameter1>
         <tem:Parameter2></tem:Parameter2>
         <tem:Parameter3></tem:Parameter3>
      </tem:CallSpecificFunctionRequest>
   </soap:Body>
</soap:Envelope>

Cancellation from POS [CallSpecificFunction 0]

At the moment when the waiting time is exceeded or there is an error during the transaction, it is very important to call the Cancel function with the ticket number.

After launching the cancellation call, the circuit must be followed to check with the GetNextMessage function. Getting a 1000 means that the DeviceHub has received the cancellation request correctly, but it does not indicate that it has been processed at that moment. The cancellation process is asynchronous and will be carried out when the DeviceHub has a connection with the entity.

To verify that the operation has been canceled, it is necessary to check the Sipay operations website, bearing in mind that this process can take up to 24 hours.

Parameters:

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

Function: 0
Modifier: 0
Parameter1: String type, amount of the original transaction to be canceled. (See Note 1)
Parameter2: Ticket number of the operation to be canceled or the sequence number.
Parameter3: Not used.

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

<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>0</tem:Function>
         <tem:Modifier>0</tem:Modifier>
         <tem:Parameter1>0000000001</tem:Parameter1>
         <tem:Parameter2>ticketnumber</tem:Parameter2>
         <tem:Parameter3></tem:Parameter3>
      </tem:CallSpecificFunctionRequest>
   </soap:Body>
</soap:Envelope>

Preauthorization [BeginPreAuthorization]

This call is used to perform a preauthorization for the desired amount. Once the request is made, the amount will be reserved in the customer's account, and it will not be available for other purchases or payments until replaced or canceled.

Consider the following:

If a preauthorization is not confirmed, replaced, or canceled and the bank-defined time limit expires, the preauthorization will be automatically released, and a new preauthorization request must be made. It will not be possible to confirm or replace a preauthorization after the time limit has passed.
A preauthorization can always be confirmed for the total amount or a lesser amount, but it cannot be partially confirmed multiple times to reach the total amount. Once a confirmation is made for part of the total amount, the rest is automatically released.
Preauthorization cancellations cannot be canceled. If a preauthorization has been canceled, the only way to preauthorize the amount again is by making a new preauthorization request.
The duration time limit of a preauthorization is set by the bank. The maximum is usually 30 days, but the standard is between 7 and 15 days. Each customer must negotiate with their bank the number of days to be configured. Recommendation: if working with multiple banks at different merchants, it is recommended to set the limit to the lowest value among all banks.
If a preauthorization request is made for an amount, and then a replacement of that preauthorization is made for a higher amount, and the customer does not have sufficient funds in the account, the replacement cannot be processed. The original preauthorization with the initial amount of the request will remain active.

Below is the method detail to launch the transaction to request a reservation given an amount.

Request: BeginPreAuthorizationRequest

TYPE	NAME	COMMENTS
Header	Header	Data used during subsequent queries.
String	Amount	Amount and Operation Ticket. The ticket is not mandatory, but its use is recommended. The format of the field can be:
String	No Ticket	Amount of the operation with 10 numeric digits, where the last two digits represent the cents. Ex: €1 -> 0000000100; €2.25 -> 0000000225
String	With Ticket:	Amount of the operation in the same format as without a ticket, plus the ticket number, separated by a @. Ex: Amount of €1.15 and ticket number 453AF01 -> 0000000115@453AF01

Header

TYPE	NAME	COMMENTS
String	Clientid	Merchant identifier.
String	Storeid	Store identifier.
String	Posid	Point of Sale Terminal identifier.
String	Language	Language identifier: 0 Spanish 1 English.
String	ExtraData1	Not used.

Note: The Posid field must not exceed 30 characters, and it is recommended not to use the following symbols within the field: {"/","\"}.

Response: BeginPreAuthorizationResponse

TYPE	NAME	COMMENTS
Result	Result	Returns 0=OK or an error code and its description.

Result

TYPE	NAME	COMMENTS
Int	Code	Error code.
String	Description	Error description.

Preauthorization Confirmation [ProcessPreAuthorization]

Confirmation involves charging the preauthorization. It can be done for the total preauthorized amount or for lesser amounts. If confirmed for a lesser amount, the remaining amount of the preauthorization is released. Once a preauthorization is confirmed, if you wish to continue preauthorizing the difference, a new preauthorization request must be made for the desired amount.

It will also be important to establish the availability conditions for confirming this type of operation. If this operation is not confirmed within the period stipulated by the entity, the initial preauthorization will be released.

Request: ProcessPreAuthorizationRequest

TYPE	NAME	COMMENTS
Header	Header	Data used during subsequent queries.
String	Amount	Authorized amount for payment reservation with a margin, according to the financial entity processing it. Amount of the operation with 10 numeric digits, where the last two digits represent the cents. Ex: €1 -> 0000000100; €2.25 -> 0000000225
String	AuthorizationCode	Authorization code or transaction's original ticket number (in the case of the ticket, it must be a unique value).
String	Ticket	Available starting from version 4.0.1.0 of the device hub. The maximum length of the ticket must not exceed 40 characters. It is the original ticket sent in the initial preauthorization.
If provided, the AuthorizationCode field is not mandatory.

Header

TYPE	NAME	COMMENTS
String	Clientid	Merchant identifier.
String	Storeid	Store identifier.
String	Posid	Point of Sale Terminal identifier.
String	Language	Language identifier: 0 Spanish 1 English.
String	ExtraData1	Not used.

Note: The Posid field must not exceed 30 characters, and it is recommended not to use the following symbols within the field: {"/","\"}.

Response: ProcessPreAuthorizationResponse

TYPE	NAME	COMMENTS
Result	Result	Returns 0=OK or an error code and its description.

Result

TYPE	NAME	COMMENTS
Int	Code	Error code.
String	Description	Error description.

Preauthorization Cancellation [CancelPreAuthorization]

Release the preauthorized amount without charging the customer. If you want to release a preauthorization without charging the customer, you must cancel the preauthorization. Cancellations must always be for the total amount of the preauthorization; it is not possible to cancel for a lesser amount.

This method cancels the reservation requested with the authorization code or the original ticket number.

Request: CancelPreAuthorizationRequest

TYPE	NAME	COMMENTS
Header	Header	Data used during subsequent queries.
String	Amount	Authorized amount for payment reservation. Amount of the operation with 10 numeric digits, where the last two digits represent the cents. Ex: €1 -> 0000000100; €2.25 -> 0000000225
String	AuthorizationCode	Authorization code or the original ticket number (in the case of the ticket, it must be a unique value).
String	Ticket	Available starting from version 4.0.1.0 of the device hub. The maximum length of the ticket must not exceed 40 characters. It is the original ticket sent in the initial preauthorization.
If provided, the AuthorizationCode field is not mandatory.

Header

TYPE	NAME	COMMENTS
String	Clientid	Merchant identifier.
String	Storeid	Store identifier.
String	Posid	Point of Sale Terminal identifier.
String	Language	Language identifier: 0 Spanish 1 English.
String	ExtraData1	Not used.

Note: The Posid field must not exceed 30 characters, and it is recommended not to use the following symbols within the field: {"/","\"}.

Response: CancelPreAuthorizationResponse

TYPE	NAME	COMMENTS
Result	Result	Returns 0=OK or an error code and its description.

Result

TYPE	NAME	COMMENTS
Int	Code	Error code.
String	Description	Error description.

Note: There is no possibility to cancel a preauthorization cancellation.

Preauthorization Replacement [ReplacePreAuthorization]

Message used to replace an unconfirmed preauthorization. The new preauthorization can have a value equal to or different from the original. In both cases, the retention period of the preauthorization is modified, taking into account the date of this operation as the base.

Replacement is usually used in the following cases:

Before the expiration of the time limits set by the bank to extend the preauthorization.
Modify the preauthorized amount, either for a lower or higher amount.

Available starting from version 4.0.1.0 of the device hub.

Request: ReplacePreAuthorizationRequest

TYPE	NAME	COMMENTS
Header	Header	Data used during subsequent queries.
String	Amount	Amount of the operation with 10 numeric digits, where the last two digits represent the cents. Ex: €1 -> 0000000100; €2.25 -> 0000000225
String	Ticket	The operation ticket can be the same as the original or a new ticket number. It must not exceed 35 characters. It is important that tickets are not repeated among different merchants, thus avoiding any confusion between operations.
String	OriginalTicket	Ticket number of the preauthorization to be replaced. If provided, the OriginalAuthorization field is not mandatory.
String	OriginalAuthorization	Authorization code of the original transaction. (In the case of the ticket, it must be a unique value).

Header

TYPE	NAME	COMMENTS
String	Clientid	Merchant identifier.
String	Storeid	Store identifier.
String	Posid	Point of Sale Terminal identifier.
String	Language	Language identifier: 0 Spanish 1 English.
String	ExtraData1	Not used.

Note: The Posid field must not exceed 30 characters, and it is recommended not to use the following symbols within the field: {"/","\"}.

Response: ReplacePreAuthorizationResponse

TYPE	NAME	COMMENTS
Result	Result	Returns 0=OK or an error code and its description.

Result

TYPE	NAME	COMMENTS
Int	Code	Error code.
String	Description	Error description.

Signature Retrieval [CallSpecificFunction 3]

Parameters:

The header data must be identical to that used in all transactions.

Function: 3
Modifier: 0
Parameter1: Not used.
Parameter2: Not used.
Parameter3: Not used.

This function returns the signature captured on the PIN Pad in the format defined by the PIN Pad (which may vary depending on brands and models). The signature formats are specified in the TYPE field and can be:

00: Proprietary format
01: BMP Type
02: JPG
03: TIF
05: BMP

In GetNextMessageResponse→Message→ExpansionData, the XML with the signature data can be found in the same way that signature transactions handle it.

Example of ExpansionData for ISC250 signature:

<EXPANSION>
    <SIGNATURE>
        <<TYPESIGNATURE>03</TYPE><- >Firma digitalizada en format ASCII<- Tipo de imagen( 03 = .tiff )
        4D4D002A00000008000D00FE0004000000010000000001000004000000010000012001010004000000010000007
        8010200030000000100010000010300030000000100020000010600030000000100000000011100040000000F00
        0000DC011600040000000100000008011700040000000F00000118011A000500000001000000AA011B000500000
        001000000B2013100020000000E000000BA0132000200000014000000C8000000000000012C000000010000012C
        00000001496E67656E69636F000000000000323031333A30383A33302031313A34313A353800000001540000016
        40000017D000001A3000001CB000001F30000021F000002520000028A000002C2000002F20000031A0000033A00
        00035A0000037A00000010000000190000002600000028000000280000002C00000033000000380000003800000
        03000000028000000200000002000000020000000166E366E366E366E366E366E366E366E366E366E366E366E36
        5C0AD9A85D41C6665C619D19005F57A2335CE69D19805F9834685DD9346891A404B66A92531A5B1C92C3135B709
        2AC2CB700929E50B760905452B780916C56B7C0915E5AB7E0914408B73090AC14B740909EA4B67090D4A5ED0090
        16A8B618924D556F409288916F50903D616EA090C9656EB0957AD7B4E096BADAD880907ADFB2E09234A5B080953
        4B5B50097E97ED58096664B690094665ECC0090F99AD818D9A6B5DAD8D0D996B547B1B0DA56B69D3AD898DADA5B DD3AD8A0DACEB6A10FEC54DAC24A50875B17D92694AFD940DAAA4AEFD948DA9E94B16CACDA924B59ECACD85696B 3D960D82A3258875B2CD96E64B10EB65AD95E66B13AD968D95233EF75B040D94A3358AD6C10D9423358AD6C14D9
        423258B16C14D80DA8545B52090D28545B530901A7CEB6A6090127485B5409184E885B5409244E885B5509134E835B55092 B43FABA3258B16C28D9420822458B96C280D94C70828B172D8580D96042D57FAD858090DAB535B52092
        DAA892843AD56C9090443AA96C9090343AAD6C9091743A4EB64890843A10B6AA90C8BFB54090C4AD6D4C927493D 85895680D6C2895680D6C2895486D6C149292D8289292D828929AD820929AD820929AD820929AD820929AD82092
        9AD820929AD820929AD820929AD8209292D8289292D8289292D8289292D8289292D8289292D828905AD850905AD
        850905AD850905AD850905AD8509292D8289292D8289292D828929AD820929AD82092A2D9686E366E366E366E36 6E36
        </SIGNATURE>
    </SIGNATURE>
</EXPANSION>

Check DeviceHub Version [CallSpecificFunction 24]

This call allows retrieving information about the installed version of DeviceHub.

Parameters:

Header data must be the same as in all transactions.

Function: 24
Modifier: 0
Parameter1: Not used.
Parameter2: Not used.
Parameter3: Not used.

<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>24</tem:Function>
         <tem:Modifier>0</tem:Modifier>
         <tem:Parameter1></tem:Parameter1>
         <tem:Parameter2></tem:Parameter2>
         <tem:Parameter3></tem:Parameter3>
      </tem:CallSpecificFunctionRequest>
   </soap:Body>
</soap:Envelope>

Referenced Returns [BeginDevolution]​

Request: BeginDevolutionRequest​

Response: BeginDevolutionResponse​

Ticket Printing Information​

File 3000 Loading [CallSpecificFunction 20]​

PINOnline Key Loading [CallSpecificFunction 4]​

Cancellation from POS [CallSpecificFunction 0]​

Preauthorization [BeginPreAuthorization]​

Request: BeginPreAuthorizationRequest​

Response: BeginPreAuthorizationResponse​

Preauthorization Confirmation [ProcessPreAuthorization]​

Request: ProcessPreAuthorizationRequest​

Response: ProcessPreAuthorizationResponse​

Preauthorization Cancellation [CancelPreAuthorization]​

Request: CancelPreAuthorizationRequest​

Response: CancelPreAuthorizationResponse​

Preauthorization Replacement [ReplacePreAuthorization]​

Request: ReplacePreAuthorizationRequest​

Response: ReplacePreAuthorizationResponse​

Signature Retrieval [CallSpecificFunction 3]​

Check DeviceHub Version [CallSpecificFunction 24]​

Referenced Returns [BeginDevolution]

Request: BeginDevolutionRequest

Response: BeginDevolutionResponse

Ticket Printing Information

File 3000 Loading [CallSpecificFunction 20]

PINOnline Key Loading [CallSpecificFunction 4]

Cancellation from POS [CallSpecificFunction 0]

Preauthorization [BeginPreAuthorization]

Request: BeginPreAuthorizationRequest

Response: BeginPreAuthorizationResponse

Preauthorization Confirmation [ProcessPreAuthorization]

Request: ProcessPreAuthorizationRequest

Response: ProcessPreAuthorizationResponse

Preauthorization Cancellation [CancelPreAuthorization]

Request: CancelPreAuthorizationRequest

Response: CancelPreAuthorizationResponse

Preauthorization Replacement [ReplacePreAuthorization]

Request: ReplacePreAuthorizationRequest

Response: ReplacePreAuthorizationResponse

Signature Retrieval [CallSpecificFunction 3]

Check DeviceHub Version [CallSpecificFunction 24]