Operations Gateway Integration XML

XML integration through the OperationsGateway service permits access to the operations of the products contracted with the PAYCOMET payment platform without the direct intervention of the user, increasing the operability for the list of "own brands" or integrations with the software of other customers. The requests are sent by the business server and are processed by the payment gateway.

In this manner, the business only has direct access with PAYCOMET to collect the operations performed on all its products, without the need to access the control screen, simply requesting the function: search_operations.

  1. Introduction
  2. Product Configuration
  3. Web Programming
  4. Operation Types
  5. Business Signature Calculation
  6. Ordenation Types
  7. Examples

Introduction

The technology selected for performing the operations is SOAP, based on XML and permits consultation via protocol protected by firewalls and over the Internet.

The WSDL publication that provides the outline for the use of the search_operations is:

In this manner, the business only has direct access with PAYCOMET to collect the operations performed on all its products, without the need to access the control screen, simply requesting the function: search_operations.

Product Configuration

In order to use the operations consultation service in a business, it is necessary to have the necessary configuration parameters. These can be obtained through the PAYCOMET customer management platform

Once inside the platform, the configuration of the contracted product can be reviewed through the menu My products -> Configure product.

After clicking on the "Edit" button of the chosen product, a screen will appear with the basic information of the product under the section "Technical configuration of the WEB POS". The information required during the integration process is:

  • Password
  • Terminal number
  • Customer code

Call to service search_operations

Due to the whole consultation process being performed in the background (from server to server) the modifications to be performed in the business are completely outside of the experience of the user.

The technology employed for the PAYCOMET payment gateway operations is SOAP, based on HTTPS to avoid transfer problems through firewalls and other devices whilst at the same time ensuring the security of the operations. There is a very wide range of support for the performance of SOAP requests for the main programming languages used in web environments.

The requests are made through the HTTPS transfer protocol in a manner that must ensure that the system is capable of performing the requests correctly and manage the security certificates returned by the platform for its proper use.

search_operations

The available operation is detailed below.

Element Content Description
PAYCOMET_OPERATIONS_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
PAYCOMET_OPERATIONS_SORTYPE [0-9]{1,4} Mandatory. See SORT TYPE
PAYCOMET_OPERATIONS_SORTORDER [ASC][DESC] Mandatory. Sort results ASC = Ascending, DESC = Descending.
PAYCOMET_OPERATIONS_LIMIT [0-9]{4} Optional. Results limit.
PAYCOMET_OPERATIONS_TERMINAL Array [0-9] {1,10} Mandatory. Array of identifiers of products to consult.
PAYCOMET_OPERATIONS_OPERATIONS Array [0-9]{2} Mandatory. See OPERATIONS.
PAYCOMET_OPERATIONS_MINAMOUNT [0-9]{1,8} Mandatory. Minimum amount of the operation in whole format. 1.00 EURO = 100, 4.50 EUROS = 450...
PAYCOMET_OPERATIONS_MAXAMOUNT [0-9]{1,8} Mandatory. Maximum amount of the operation in whole format. 1.00 EURO = 100, 4.50 EUROS = 450...
PAYCOMET_OPERATIONS_STATE [0-1-2]{1} Mandatory. Result of operation. 0 is operation failed, 1 operation correct 2 will be all.
PAYCOMET_OPERATIONS_FROMDATE [YYYYMMDDHH MMSS] Mandatory. From date of search. YEAR – MONTH – DAY – HOUR – MINUTES – SECONDS
PAYCOMET_OPERATIONS_TODATE [YYYYMMDDHH MMSS] Mandatory. To date of search. YEAR – MONTH – DAY – HOUR – MINUTES – SECONDS
PAYCOMET_OPERATIONS_CURRENCY [EUR][USD][GBP][JPY]... Mandatory. Transaction currency. For further information see CURRENCY
PAYCOMET_OPERATIONS_SIGNATURE [a-zA-Z0-9]{40} Mandatory. See SIGNATURE CALCULATION
PAYCOMET_OPERATIONS_REFERENCE [A-Za-z0-9]{70} Optional. Reference of the operation
PAYCOMET_OPERATIONS_SEARCHTYPE 0: Like, 1: Equal Optional. Comparison type. 0 LIKE comparison (%xxx%) , 1 exact comparison (=)
PAYCOMET_OPERATIONS_VERSION [1.00-1.10] Optional. If no parameter is sent or not any of the current versions, shall be based on version 1.00

The response of the service to the request is analysed via the return of an array of the object Operation , where PAYCOMET_ERROR_ID will contain the error (if any) of the integration to the WEBSERVICE or with a 0 value if successful.<

If the request produces an error of any type (incorrect signature, incorrect amount, user not found, etc) all the fields will be delivered void, except for "PAYCOMET_ERROR_ID" which will contain the error code.

In the event that the transaction is correct, the service will return an array with the object Operation with the lines of the operations. The format is as follows:

Service Response: search_operations
Element Content Description
PAYCOMET_OPERATION_ID [A-Za-z0-9]{1,8} Operation identifier
PAYCOMET_OPERATION_TIMESTAMP [YYYYMMDDHH MMSS] Date of operation (YYYYMMDDHHMMSS)
PAYCOMET_OPERATION_REFERENCE [A-Za-z0-9]{1,20} Operation reference
PAYCOMET_OPERATION_OPERATION [0-9]{1,2} Operation type identifier. See OPERATIONS.
PAYCOMET_OPERATION_OPERATIONNAME [a-zA-Z0-9]{40} Literal of the operation type.
PAYCOMET_OPERATION_STATE [0-1]{1} Identifier of the state of the operation. 0 means operation failed, 1 operation correct.
PAYCOMET_OPERATION_STATENAME [a-zA-Z0-9]{40} Literal of the state of the operation.
PAYCOMET_OPERATION_TERMINAL [0-9]{1,5} Customer product identifier.
PAYCOMET_OPERATION_TERMINALNAME [a-zA-Z0-9]{40} Customer product name.
PAYCOMET_OPERATION_PAN XXX...1234 Masked credit/debit card
PAYCOMET_OPERATION_USER [a-zA-Z0-9]{40} Name of the user that will execute the operation
PAYCOMET_OPERATION_AMOUNT [0-9]{1,9} Amount of the operation in full: 1 Euro = 100.
PAYCOMET_OPERATION_CURRENCY [EUR][USD][GBP][JPY]... Operation currency. For further information see CURRENCY
PAYCOMET_OPERATION_AMOUNTDISPLAY [a-zA-Z0-9]{40} Literal of the operation amount (with currency symbol)
PAYCOMET_OPERATION_ERRORID [0-9]{1,5} Operation error identifier.
PAYCOMET_OPERATION_ERRORDESC [a-zA-Z0-9]{40} Literal description of the operation error.
PAYCOMET_OPERATION_FEEEURO FLOAT [0-9]{1,4} PAYCOMET fee for the transaction fixed per operation (€)
PAYCOMET_OPERATION_FEEPERCENT FLOAT [0-9]{1,4} PAYCOMET fee for the transaction variable per operation (€)
PAYCOMET_OPERATION_IP A.B.C.D IP of the customer of the operation.
PAYCOMET_ERROR_ID [0-9]{1,5} I the event of an error, the generated error code will appear here. If there is no error, it will show a value of 0. The error codes are detailed in Error Codes
PAYCOMET_OPERATION_SCORING [0-100]{1,3} Calculated Scoring value. If scoring value has not been calculated, it will be returned empty.
PAYCOMET_OPERATION_CARDBRAND [a-zA-Z0-9]{40} From version 1.10 can be obtained if the brand of card operation is returned. For earlier versions or applications without version, it will be returned blank.
PAYCOMET_OPERATION_BICCODE [a-zA-Z0-9]{11} From version 1.10 can be obtained if the biccode of the entity by which the transaction was processed will be returned. For earlier versions or applications without version, it will be returned blank.
PAYCOMET_OPERATION_AUTHCODE [.*] Authorization code returned by bank.

The PAYCOMET commission is the total of the fields: PAYCOMET_OPERATION_FEEEURO + PAYCOMET_OPERATION_FEEPERCENT which will be expressed in FLOAT and in EUROS.

If there is no error in the operation, the PAYCOMET_OPERATION_ERRORID field will be 0.

Operation Types (OPERATIONS)

The operations are distinguished using numerical identifiers. This table shows the different values assigned to the whole numbers sent via the Webservice.

ID Valor Operation
1Authorisation
2Refund
3Pre-authorisation
5Pre-authorisation Modification
4Pre-authorisation Cancelation
6Pre-authorisation Confirmation
101Fund withdrawal
7Authorisation in person
103Settlement of funds due to elimination
104Balance adjustment
105Withdrawal request denied
106Chargeback
8SMS notification cost
9Subscription payment
10Maintenance cost
20SEPA Credit Transfer
30Denial of SEPA Credit Transfer
22Split Transfer
23Split Transfer Reversal
24Transfer
25Transfer Reversal

Business Signature Calculation

The signature will be calculated on the server of the business and shall cover the main principles of the request to verify the integrity of the data over the Internet and the browser of the buyer.

The encryption algorithm used for this purpose shall be SHA1 which allows text strings to be encrypted. These types of one direction algorithms prevent the initial parameter from being obtained using the result.

To facilitate the generation of the signature in languages without the necessary tools for the calculation of SHA1 algorithms, a series of libraries have been included. These files can be downloaded from the section Scripts.

Some of these libraries have been created by third party persons or entities not related to PAYCOMET. Consult the content of each file for further information.

Signature Calculation

The signature that the business will send to the gateway is calculated in the following manner (in pseudocode):

SHA1(PAYCOMET_OPERATIONS_MERCHANTCODE + ((TERMINAL_ID1 + TERMINAL_PASSWORD1) + (TERMINAL_ID2 + TERMINAL_PASSWORD2) + (TERMINAL_ID3 + TERMINAL_PASSWORD3)... + OPERATION_ID1 + OPERATION_ID2 + OPERATION_ID3... + PAYCOMET_OPERATIONS_FROMDATE + PAYCOMET_OPERATIONS_TODATE)

The signature is made up of the total of the following variables:

  • PAYCOMET_OPERATIONS_MERCHANTCODE: The code of the business.
  • TERMINAL_ID1 + TERMINAL_PASSWORD1: Concatenation of the terminal number + the password (as many of the above will be concatenated as those having an influence in the search_operations in the Array).
  • OPERATION_ID1: Concatenation of the operation identifiers requested in search_operations in the Array.
  • PAYCOMET_OPERATIONS_FROMDATE: From date of request.
  • PAYCOMET_OPERATIONS_TODATE: To date of request.

Ordenation Types

It can be requested of the Webservice to return the results sorted according to some of the following columns. This table shows the different values assigned to the whole numbers sent via the Webservice.

ID Valor Order by:
0No sorting assigned
1Date
2Reference
3Operation Type
4Operation state
5Terminal (Product)
6Operation amount
7User executing the Operation (Literal)

Examples

Below follows an example of a request:


        <?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<search_operations>
        <PAYCOMET_OPERATIONS_MERCHANTCODE xsi:type="xsd:string">*******</PAYCOMET_OPERATIONS_MERCHANTCODE>
        <PAYCOMET_OPERATIONS_SORTYPE xsi:type="xsd:int">1</PAYCOMET_OPERATIONS_SORTYPE>
        <PAYCOMET_OPERATIONS_SORTORDER xsi:type="xsd:string">ASC</PAYCOMET_OPERATIONS_SORTORDER>
        <PAYCOMET_OPERATIONS_LIMIT xsi:type="xsd:int">100</PAYCOMET_OPERATIONS_LIMIT>
        <PAYCOMET_OPERATIONS_TERMINAL xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:int[1]">
        <item xsi:type="xsd:int">****</item>
        </PAYCOMET_OPERATIONS_TERMINAL>
        <PAYCOMET_OPERATIONS_OPERATIONS xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:int[2]">
        <item xsi:type="xsd:int">1</item>
        <item xsi:type="xsd:int">2</item>
        </PAYCOMET_OPERATIONS_OPERATIONS>
        <PAYCOMET_OPERATIONS_MINAMOUNT xsi:type="xsd:int">0</PAYCOMET_OPERATIONS_MINAMOUNT>
        <PAYCOMET_OPERATIONS_MAXAMOUNT xsi:type="xsd:int">999999999</PAYCOMET_OPERATIONS_MAXAMOUNT>
        <PAYCOMET_OPERATIONS_STATE xsi:type="xsd:int">1</PAYCOMET_OPERATIONS_STATE>
        <PAYCOMET_OPERATIONS_FROMDATE xsi:type="xsd:string">20140101000000</PAYCOMET_OPERATIONS_FROMDATE>
        <PAYCOMET_OPERATIONS_TODATE xsi:type="xsd:string">20140131000000</PAYCOMET_OPERATIONS_TODATE>
        <PAYCOMET_OPERATIONS_CURRENCY xsi:type="xsd:string">EUR</PAYCOMET_OPERATIONS_CURRENCY>
        <PAYCOMET_OPERATIONS_SIGNATURE xsi:type="xsd:string">**********************************</PAYCOMET_OPERATIONS_SIGNATURE>

</search_operations>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
        
Response (ver 1.10):

<search_operationsResponse>
        <return>
                <Operation>
                        <PAYCOMET_ERROR_ID>0</PAYCOMET_ERROR_ID>
                        <PAYCOMET_OPERATION_ID>******</PAYCOMET_OPERATION_ID>
                        <PAYCOMET_OPERATION_TIMESTAMP>20140101000130</PAYCOMET_OPERATION_TIMESTAMP>
                        <PAYCOMET_OPERATION_REFERENCE>**********</PAYCOMET_OPERATION_REFERENCE>
                        <PAYCOMET_OPERATION_OPERATION>1</PAYCOMET_OPERATION_OPERATION>
                        <PAYCOMET_OPERATION_OPERATIONNAME>Autorización</PAYCOMET_OPERATION_OPERATIONNAME>
                        <PAYCOMET_OPERATION_STATE>1</PAYCOMET_OPERATION_STATE>
                        <PAYCOMET_OPERATION_STATENAME>Completado</PAYCOMET_OPERATION_STATENAME>
                        <PAYCOMET_OPERATION_TERMINAL>****</PAYCOMET_OPERATION_TERMINAL>
                        <PAYCOMET_OPERATION_TERMINALNAME>BANKSTORE</PAYCOMET_OPERATION_TERMINALNAME>
                        <PAYCOMET_OPERATION_PAN>XXX...9015</PAYCOMET_OPERATION_PAN>
                        <PAYCOMET_OPERATION_USER>***************</PAYCOMET_OPERATION_USER>
                        <PAYCOMET_OPERATION_AMOUNT>999</PAYCOMET_OPERATION_AMOUNT>
                        <PAYCOMET_OPERATION_CURRENCY>EUR</PAYCOMET_OPERATION_CURRENCY>
                        <PAYCOMET_OPERATION_AMOUNTDISPLAY>9,99 €</PAYCOMET_OPERATION_AMOUNTDISPLAY>
                        <PAYCOMET_OPERATION_ERRORID>0</PAYCOMET_OPERATION_ERRORID>
                        <PAYCOMET_OPERATION_ERRORDESC>Sin error</PAYCOMET_OPERATION_ERRORDESC>
                        <PAYCOMET_OPERATION_FEEEURO>0.00</PAYCOMET_OPERATION_FEEEURO>
                        <PAYCOMET_OPERATION_FEEPERCENT>0</PAYCOMET_OPERATION_FEEPERCENT>
                        <PAYCOMET_OPERATION_IP>**.**.**.**</PAYCOMET_OPERATION_IP>
                        <PAYCOMET_OPERATION_CARDBRAND>VISA</PAYCOMET_OPERATION_CARDBRAND>
                        <PAYCOMET_OPERATION_BICCODE>BMARES2MXXX</PAYCOMET_OPERATION_BICCODE>
                        <PAYCOMET_OPERATION_CONCEPT>Concept / description / remarks</PAYCOMET_OPERATION_CONCEPT>
                        <PAYCOMET_OPERATION_PANCOUNTRY>GB</PAYCOMET_OPERATION_PANCOUNTRY>
                        <PAYCOMET_OPERATION_COUNTRY>GB</PAYCOMET_OPERATION_COUNTRY>
                        <PAYCOMET_OPERATION_ISSUERBANK>NATIXIS</PAYCOMET_OPERATION_ISSUERBANK>
                        <PAYCOMET_OPERATION_AUTHCODE>99999/99999999</PAYCOMET_OPERATION_AUTHCODE>
                        <PAYCOMET_OPERATION_SPLITID>aaaa1111bbbb2222cccc3333dddd4444eeee5555ffff6666gggg7777hhhh8888ii</PAYCOMET_OPERATION_SPLITID>
                </Operation>
                <Operation>
                        <PAYCOMET_ERROR_ID>0</PAYCOMET_ERROR_ID>
                        <PAYCOMET_OPERATION_ID>*******</PAYCOMET_OPERATION_ID>
                        <PAYCOMET_OPERATION_TIMESTAMP>20140101000219</PAYCOMET_OPERATION_TIMESTAMP>
                        <PAYCOMET_OPERATION_REFERENCE>**********</PAYCOMET_OPERATION_REFERENCE>
                        <PAYCOMET_OPERATION_OPERATION>1</PAYCOMET_OPERATION_OPERATION>
                        <PAYCOMET_OPERATION_OPERATIONNAME>Autorización</PAYCOMET_OPERATION_OPERATIONNAME>
                        <PAYCOMET_OPERATION_STATE>1</PAYCOMET_OPERATION_STATE>
                        <PAYCOMET_OPERATION_STATENAME>Completado</PAYCOMET_OPERATION_STATENAME>
                        <PAYCOMET_OPERATION_TERMINAL>****</PAYCOMET_OPERATION_TERMINAL>
                        <PAYCOMET_OPERATION_TERMINALNAME>BANKSTORE</PAYCOMET_OPERATION_TERMINALNAME>
                        <PAYCOMET_OPERATION_PAN>XXX...8011</PAYCOMET_OPERATION_PAN>
                        <PAYCOMET_OPERATION_USER>***************</PAYCOMET_OPERATION_USER>
                        <PAYCOMET_OPERATION_AMOUNT>995</PAYCOMET_OPERATION_AMOUNT>
                        <PAYCOMET_OPERATION_CURRENCY>EUR</PAYCOMET_OPERATION_CURRENCY>
                        <PAYCOMET_OPERATION_AMOUNTDISPLAY>9,95 €</PAYCOMET_OPERATION_AMOUNTDISPLAY>
                        <PAYCOMET_OPERATION_ERRORID>0</PAYCOMET_OPERATION_ERRORID>
                        <PAYCOMET_OPERATION_ERRORDESC>Sin error</PAYCOMET_OPERATION_ERRORDESC>
                        <PAYCOMET_OPERATION_FEEEURO>0.00</PAYCOMET_OPERATION_FEEEURO>
                        <PAYCOMET_OPERATION_FEEPERCENT>0</PAYCOMET_OPERATION_FEEPERCENT>
                        <PAYCOMET_OPERATION_IP>**.**.**.**</PAYCOMET_OPERATION_IP>
                        <PAYCOMET_OPERATION_CARDBRAND>VISA</PAYCOMET_OPERATION_CARDBRAND>
                        <PAYCOMET_OPERATION_BICCODE>BMARES2MXXX</PAYCOMET_OPERATION_BICCODE>
                        <PAYCOMET_OPERATION_CONCEPT>Description / concept / remarks</PAYCOMET_OPERATION_CONCEPT>
                        <PAYCOMET_OPERATION_PANCOUNTRY>FR</PAYCOMET_OPERATION_PANCOUNTRY>
                        <PAYCOMET_OPERATION_COUNTRY>FR</PAYCOMET_OPERATION_COUNTRY>
                        <PAYCOMET_OPERATION_ISSUERBANK>ALLIED BANK, LTD.</PAYCOMET_OPERATION_ISSUERBANK>
                        <PAYCOMET_OPERATION_AUTHCODE>99999/99999999</PAYCOMET_OPERATION_AUTHCODE>
                        <PAYCOMET_OPERATION_SPLITID>aaaa1111bbbb2222cccc3333dddd4444eeee5555ffff6666gggg7777hhhh8888ii</PAYCOMET_OPERATION_SPLITID>

                </Operation>
        </return>
</search_operationsResponse>