Operations Gateway

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. Web Programming
  3. Appendix I - Operation Types
  4. Appendix II - Ordenation Types

Introduction

The technology selected for performing the operations are SOAP, based on XML and REST, witch use JSON requests. Both permits consultation via protocol protected by firewalls and over the Internet.

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.

Call to service search_operations

Select the type of integration:

REST XML
Element Content Description
PAYTPV_OPERATIONS_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
PAYTPV_OPERATIONS_SORTYPE [0-9]{1,4} Mandatory. See SORT TYPE
PAYTPV_OPERATIONS_SORTORDER [ASC][DESC] Mandatory. Sort results ASC = Ascending, DESC = Descending.
PAYTPV_OPERATIONS_LIMIT [0-9]{4} Optional. Results limit.
PAYTPV_OPERATIONS_TERMINAL Array [0-9] {1,10} Mandatory. Array of identifiers of products to consult.
PAYTPV_OPERATIONS_OPERATIONS Array [0-9]{2} Mandatory. See OPERATIONS.
PAYTPV_OPERATIONS_MINAMOUNT [0-9]{1,8} Mandatory. Minimum amount of the operation in whole format. 1.00 EURO = 100, 4.50 EUROS = 450...
PAYTPV_OPERATIONS_MAXAMOUNT [0-9]{1,8} Mandatory. Maximum amount of the operation in whole format. 1.00 EURO = 100, 4.50 EUROS = 450...
PAYTPV_OPERATIONS_STATE [0-1-2]{1} Mandatory. Result of operation. 0 is operation failed, 1 operation correct 2 will be all.
PAYTPV_OPERATIONS_FROMDATE [YYYYMMDDHH MMSS] Mandatory. From date of search. YEAR – MONTH – DAY – HOUR – MINUTES – SECONDS
PAYTPV_OPERATIONS_TODATE [YYYYMMDDHH MMSS] Mandatory. To date of search. YEAR – MONTH – DAY – HOUR – MINUTES – SECONDS
PAYTPV_OPERATIONS_CURRENCY [EUR][USD][GBP][JPY]... Mandatory. Transaction currency. For further information see CURRENCY
PAYTPV_OPERATIONS_SIGNATURE [a-zA-Z0-9] Mandatory. See SIGNATURE CALCULATION
PAYTPV_OPERATIONS_REFERENCE [A-Za-z0-9]{70} Optional. Reference of the operation
PAYTPV_OPERATIONS_SEARCHTYPE 0: Like, 1: Equal Optional. Comparison type. 0 LIKE comparison (%xxx%) , 1 exact comparison (=)
PAYTPV_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 PAYTPV_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 "PAYTPV_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
PAYTPV_OPERATION_METHODID [0-9]{1,2} Method identifier in PAYCOMET. Complete list.
PAYTPV_OPERATION_METHODNAME [a-zA-Z0-9]{40} Method name in PAYCOMET
PAYTPV_OPERATION_ID [A-Za-z0-9]{1,8} Operation identifier
PAYTPV_OPERATION_TIMESTAMP [YYYYMMDDHH MMSS] Date of operation (YYYYMMDDHHMMSS)
PAYTPV_OPERATION_REFERENCE [A-Za-z0-9]{1,20} Operation reference
PAYTPV_OPERATION_OPERATION [0-9]{1,2} Operation type identifier. See OPERATIONS.
PAYTPV_OPERATION_OPERATIONNAME [a-zA-Z0-9]{40} Literal of the operation type.
PAYTPV_OPERATION_STATE [0-1]{1} Identifier of the state of the operation. 0 means operation failed, 1 operation correct, 2 Unfinished (for pending operations from an SCA or 3DS).
PAYTPV_OPERATION_STATENAME [a-zA-Z0-9]{40} Literal of the state of the operation.
PAYTPV_OPERATION_TERMINAL [0-9]{1,5} Customer product identifier.
PAYTPV_OPERATION_TERMINALNAME [a-zA-Z0-9]{40} Customer product name.
PAYTPV_OPERATION_PAN 123456******1234 Masked credit/debit card
PAYTPV_OPERATION_USER [a-zA-Z0-9]{40} Name of the user that will execute the operation
PAYTPV_OPERATION_AMOUNT [0-9]{1,9} Amount of the operation in full: 1 Euro = 100.
PAYTPV_OPERATION_CURRENCY [EUR][USD][GBP][JPY]... Operation currency. For further information see CURRENCY
PAYTPV_OPERATION_AMOUNTDISPLAY [a-zA-Z0-9]{40} Literal of the operation amount (with currency symbol)
PAYTPV_OPERATION_ERRORID [0-9]{1,5} Operation error identifier.
PAYTPV_OPERATION_ERRORDESC [a-zA-Z0-9]{40} Literal description of the operation error.
PAYTPV_OPERATION_FEEEURO FLOAT [0-9]{1,4} PAYCOMET fee for the transaction fixed per operation (€)
PAYTPV_OPERATION_FEEPERCENT FLOAT [0-9]{1,4} PAYCOMET fee for the transaction variable per operation (€)
PAYTPV_OPERATION_IP A.B.C.D IP of the customer of the operation.
PAYTPV_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
PAYTPV_OPERATION_SCORING [0-100]{1,3} Calculated Scoring value. If scoring value has not been calculated, it will be returned empty.
PAYTPV_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.
PAYTPV_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.
PAYTPV_OPERATION_AUTHCODE [.*] Authorization code returned by bank.

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

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

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 SHA512 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 SHA512 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.

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

SHA512(PAYTPV_OPERATIONS_MERCHANTCODE + ((TERMINAL_ID1 + TERMINAL_PASSWORD1) + (TERMINAL_ID2 + TERMINAL_PASSWORD2) + (TERMINAL_ID3 + TERMINAL_PASSWORD3)... + OPERATION_ID1 + OPERATION_ID2 + OPERATION_ID3... + PAYTPV_OPERATIONS_FROMDATE + PAYTPV_OPERATIONS_TODATE)

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

  • PAYTPV_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.
  • PAYTPV_OPERATIONS_FROMDATE: From date of request.
  • PAYTPV_OPERATIONS_TODATE: To date of request.

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>
        <PAYTPV_OPERATIONS_MERCHANTCODE xsi:type="xsd:string">*******</PAYTPV_OPERATIONS_MERCHANTCODE>
        <PAYTPV_OPERATIONS_SORTYPE xsi:type="xsd:int">1</PAYTPV_OPERATIONS_SORTYPE>
        <PAYTPV_OPERATIONS_SORTORDER xsi:type="xsd:string">ASC</PAYTPV_OPERATIONS_SORTORDER>
        <PAYTPV_OPERATIONS_LIMIT xsi:type="xsd:int">100</PAYTPV_OPERATIONS_LIMIT>
        <PAYTPV_OPERATIONS_TERMINAL xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:int[1]">
        <item xsi:type="xsd:int">****</item>
        </PAYTPV_OPERATIONS_TERMINAL>
        <PAYTPV_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>
        </PAYTPV_OPERATIONS_OPERATIONS>
        <PAYTPV_OPERATIONS_MINAMOUNT xsi:type="xsd:int">0</PAYTPV_OPERATIONS_MINAMOUNT>
        <PAYTPV_OPERATIONS_MAXAMOUNT xsi:type="xsd:int">999999999</PAYTPV_OPERATIONS_MAXAMOUNT>
        <PAYTPV_OPERATIONS_STATE xsi:type="xsd:int">1</PAYTPV_OPERATIONS_STATE>
        <PAYTPV_OPERATIONS_FROMDATE xsi:type="xsd:string">20140101000000</PAYTPV_OPERATIONS_FROMDATE>
        <PAYTPV_OPERATIONS_TODATE xsi:type="xsd:string">20140131000000</PAYTPV_OPERATIONS_TODATE>
        <PAYTPV_OPERATIONS_CURRENCY xsi:type="xsd:string">EUR</PAYTPV_OPERATIONS_CURRENCY>
        <PAYTPV_OPERATIONS_SIGNATURE xsi:type="xsd:string">**********************************</PAYTPV_OPERATIONS_SIGNATURE>

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

<search_operationsResponse>
        <return>
                <item>
                        <PAYTPV_ERROR_ID>0</PAYTPV_ERROR_ID>
                        <PAYTPV_OPERATION_ID>******</PAYTPV_OPERATION_ID>
                        <PAYTPV_OPERATION_TIMESTAMP>20140101000130</PAYTPV_OPERATION_TIMESTAMP>
                        <PAYTPV_OPERATION_REFERENCE>**********</PAYTPV_OPERATION_REFERENCE>
                        <PAYTPV_OPERATION_OPERATION>1</PAYTPV_OPERATION_OPERATION>
                        <PAYTPV_OPERATION_OPERATIONNAME>Autorización</PAYTPV_OPERATION_OPERATIONNAME>
                        <PAYTPV_OPERATION_STATE>1</PAYTPV_OPERATION_STATE>
                        <PAYTPV_OPERATION_STATENAME>Completado</PAYTPV_OPERATION_STATENAME>
                        <PAYTPV_OPERATION_TERMINAL>****</PAYTPV_OPERATION_TERMINAL>
                        <PAYTPV_OPERATION_TERMINALNAME>BANKSTORE</PAYTPV_OPERATION_TERMINALNAME>
                        <PAYTPV_OPERATION_PAN>XXX...9015</PAYTPV_OPERATION_PAN>
                        <PAYTPV_OPERATION_USER>***************</PAYTPV_OPERATION_USER>
                        <PAYTPV_OPERATION_AMOUNT>999</PAYTPV_OPERATION_AMOUNT>
                        <PAYTPV_OPERATION_CURRENCY>EUR</PAYTPV_OPERATION_CURRENCY>
                        <PAYTPV_OPERATION_AMOUNTDISPLAY>9,99 €</PAYTPV_OPERATION_AMOUNTDISPLAY>
                        <PAYTPV_OPERATION_ERRORID>0</PAYTPV_OPERATION_ERRORID>
                        <PAYTPV_OPERATION_ERRORDESC>Sin error</PAYTPV_OPERATION_ERRORDESC>
                        <PAYTPV_OPERATION_FEEEURO>0.00</PAYTPV_OPERATION_FEEEURO>
                        <PAYTPV_OPERATION_FEEPERCENT>0</PAYTPV_OPERATION_FEEPERCENT>
                        <PAYTPV_OPERATION_IP>**.**.**.**</PAYTPV_OPERATION_IP>
                        <PAYTPV_OPERATION_CARDBRAND>VISA</PAYTPV_OPERATION_CARDBRAND>
                        <PAYTPV_OPERATION_BICCODE>BMARES2MXXX</PAYTPV_OPERATION_BICCODE>
                        <PAYTPV_OPERATION_CONCEPT>Concept / description / remarks</PAYTPV_OPERATION_CONCEPT>
                        <PAYTPV_OPERATION_PANCOUNTRY>GB</PAYTPV_OPERATION_PANCOUNTRY>
                        <PAYTPV_OPERATION_COUNTRY>GB</PAYTPV_OPERATION_COUNTRY>
                        <PAYTPV_OPERATION_ISSUERBANK>NATIXIS</PAYTPV_OPERATION_ISSUERBANK>
                        <PAYTPV_OPERATION_AUTHCODE>99999/99999999</PAYTPV_OPERATION_AUTHCODE>
                        <PAYTPV_OPERATION_SPLITID>aaaa1111bbbb2222cccc3333dddd4444eeee5555ffff6666gggg7777hhhh8888ii</PAYTPV_OPERATION_SPLITID>
                </item>
                <item>
                        <PAYTPV_ERROR_ID>0</PAYTPV_ERROR_ID>
                        <PAYTPV_OPERATION_ID>*******</PAYTPV_OPERATION_ID>
                        <PAYTPV_OPERATION_TIMESTAMP>20140101000219</PAYTPV_OPERATION_TIMESTAMP>
                        <PAYTPV_OPERATION_REFERENCE>**********</PAYTPV_OPERATION_REFERENCE>
                        <PAYTPV_OPERATION_OPERATION>1</PAYTPV_OPERATION_OPERATION>
                        <PAYTPV_OPERATION_OPERATIONNAME>Autorización</PAYTPV_OPERATION_OPERATIONNAME>
                        <PAYTPV_OPERATION_STATE>1</PAYTPV_OPERATION_STATE>
                        <PAYTPV_OPERATION_STATENAME>Completado</PAYTPV_OPERATION_STATENAME>
                        <PAYTPV_OPERATION_TERMINAL>****</PAYTPV_OPERATION_TERMINAL>
                        <PAYTPV_OPERATION_TERMINALNAME>BANKSTORE</PAYTPV_OPERATION_TERMINALNAME>
                        <PAYTPV_OPERATION_PAN>XXX...8011</PAYTPV_OPERATION_PAN>
                        <PAYTPV_OPERATION_USER>***************</PAYTPV_OPERATION_USER>
                        <PAYTPV_OPERATION_AMOUNT>995</PAYTPV_OPERATION_AMOUNT>
                        <PAYTPV_OPERATION_CURRENCY>EUR</PAYTPV_OPERATION_CURRENCY>
                        <PAYTPV_OPERATION_AMOUNTDISPLAY>9,95 €</PAYTPV_OPERATION_AMOUNTDISPLAY>
                        <PAYTPV_OPERATION_ERRORID>0</PAYTPV_OPERATION_ERRORID>
                        <PAYTPV_OPERATION_ERRORDESC>Sin error</PAYTPV_OPERATION_ERRORDESC>
                        <PAYTPV_OPERATION_FEEEURO>0.00</PAYTPV_OPERATION_FEEEURO>
                        <PAYTPV_OPERATION_FEEPERCENT>0</PAYTPV_OPERATION_FEEPERCENT>
                        <PAYTPV_OPERATION_IP>**.**.**.**</PAYTPV_OPERATION_IP>
                        <PAYTPV_OPERATION_CARDBRAND>VISA</PAYTPV_OPERATION_CARDBRAND>
                        <PAYTPV_OPERATION_BICCODE>BMARES2MXXX</PAYTPV_OPERATION_BICCODE>
                        <PAYTPV_OPERATION_CONCEPT>Description / concept / remarks</PAYTPV_OPERATION_CONCEPT>
                        <PAYTPV_OPERATION_PANCOUNTRY>FR</PAYTPV_OPERATION_PANCOUNTRY>
                        <PAYTPV_OPERATION_COUNTRY>FR</PAYTPV_OPERATION_COUNTRY>
                        <PAYTPV_OPERATION_ISSUERBANK>ALLIED BANK, LTD.</PAYTPV_OPERATION_ISSUERBANK>
                        <PAYTPV_OPERATION_AUTHCODE>99999/99999999</PAYTPV_OPERATION_AUTHCODE>
                        <PAYTPV_OPERATION_SPLITID>aaaa1111bbbb2222cccc3333dddd4444eeee5555ffff6666gggg7777hhhh8888ii</PAYTPV_OPERATION_SPLITID>

                </item>
        </return>
</search_operationsResponse>

The details on this functions are explained in REST full documentation, available in this link

Appendix I - Operation Types

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

Appendix II - 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)