I.V.R. Integration

  1. Introduction
  2. Web programming
    1. IVR session request
    2. Check of IVR session status
    3. Bis Check of IVR HTTP POST session status
  3. Signature calculation
  4. Operation types

Introduction

The purpose of this annex is to serve as a reference during the integration process of a business with the PAYCOMET payment gateway, using the BankStore system, collecting card information through IVR. interactive voice response systems

Except for some exceptions detailed in this document (authorised operations, signature calculations), all documentation relating to Bankstore is fully valid for implementation through IVR.

Send said documentation for obtaining an overview of the purchase process and different inflows and outflows

Web programming

The technology used for the operation with the PAYCOMET payment Gateway is SOAP, based on HTTPS to avoid transport problems through firewalls and other devices, while guaranteeing the security of operations. There is very broad support for carrying out SOAP calls for the main programming languages used in web environments.

Requests are made through the HTTPS transport protocol, so it must be ensured that your system is capable of creating the requests correctly and managing the security certifications returned by the platform for correct use.

There are several operations which can be launched from the same service.
The operations available are described below:

IVR session request

Method: get_ivr_session

To start a conversation with the IVR system, it is necessary to first make the following call in which the start of the session will be established.

The variables required for making an IVR session request are (in this order):

Element Content Description
IVR_PROVIDER_ID [0-9]{1,6} Mandatory. Supplier / IVR integrator code
IVR_STATION_ID [A-Za-z0-9]{255} Mandatory. Location identifier
IVR_MERCHANT_CODE [A-Za-z0-9]{1,8} Mandatory. Client code
IVR_MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
IVR_MERCHANT_AMOUNT [0-9]{1,8} Mandatory. Amount of the operation in full format. 1,00 EURO = 100, 4,50 EUROS = 450...
IVR_MERCHANT_CURRENCY [EUR][USD][GBP]… Mandatory. Transaction currency. See more information in the CURRENCIES section
IVR_MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Operation reference. It must be unique i each valid transaction.
IMPORTANT IN CASE OF SUBSCRIPTIONS: Do not include the characters “[“ or “]”, they will be used to recognise the business idUser.
IVR_MERCHANT_LANGUAGE [a-zA-Z0-9]{2} Mandatory. Language (iso2) in which the IVR phrases will be sent
IVR_TRANSACTION_TYPE [0-9]{3} Mandatory. Possible types:
107 Bankstore user registration
1 Authorisation
3 Pre-authorisation
9 Subscription
IVR_PROVIDER_SIGNATURE [a-zA-Z0-9]{40} Mandatory. See SIGNATURE CALCULATION
IVR_MERCHANT_CONCEPT [a-zA-Z0-9]{255} Optional. Operation concept.
IVR_SUBSCRIPTION_STARTDATE [YYYY-MM-DD] Mandatory in subscriptions. Subscription start date.
IVR_SUBSCRIPTION_ENDDATE [YYYY-MM-DD] Mandatory in subscriptions. Subscription end date. Cannot be later than the subscription start date + 5 years
IVR_SUBSCRIPTION_PERIODICITY [0-9]{3} Mandatory in subscriptions. Frequency of the payment from the start date. The number is expressed in Days. It cannot be more than 365 days.
IVR_MAX_RETRIES [0-9]{1} Optional. Number of attempts permitted
IVR_SESSION_TIMEOUT [0-9]{3} Optional. Maximum session time. In seconds
IVR_CALLBACK_STATION_TIMEOUT Optional. Extension of return in case of timeout
IVR_CALLBACK_STATION_OK Optional. Extension of return in case of operation OK
IVR_CALLBACK_STATION_KO Optional. Extension of return in case of operation KO
IVR_CALLER_PHONE_NUMBER Optional. Number of incoming call.
IVR_PROVIDER_DATA_01 Optional.
IVR_PROVIDER_DATA_02 Optional.
IVR_PROVIDER_DATA_03 Optional.
IVR_PROVIDER_DATA_04 Optional.
IVR_PROVIDER_DATA_05 Optional.
The description of the “Contents” column refers to the regular expression that must comply with the information present in the corresponding element. In this way “[A-Z]” indicate any character from “A” to “Z” and the brackets indicate the number of characters. For example “1{2,4}” validates the numbers “11”, “111” and “1111”.

The response from the service is described in the following table:

IVR_RESPONSE [0-1]{1} Result of the session request:
0: It will indicate that it was not possible to establish the IVR session.
1: The IVR session was established correctly.
IVR_ERROR_ID [0-9]{1,5} In case of error, here a code will be produced for the error generated. If there is no error the field will contain a 0. The error codes are specified in the ERROR CODS section.

Check of IVR session status

Method: get_ivr_sessionstate

This method allows the collection of information on the state of an IVR session.

The variables required for carrying out the consultation are (in this order):

Element Content Description
IVR_PROVIDER_ID [0-9]{1,6} Mandatory. Supplier / IVR integrator code
IVR_MERCHANT_CODE [A-Za-z0-9]{1,8} Mandatory. Client code
IVR_MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
IVR_MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Operation reference.
IVR_PROVIDER_SIGNATURE [a-zA-Z0-9]{40} Mandatory. See SIGNATURE CALCULATION

The description of the “Contents” column refers to the regular expression which this information must fulfil in the corresponding element. In this way “[A-Z]” indicates any character from “A” to “Z” and the brackets indicate the number of characters. For example “1{2,4}” validates the numbers “11”, “111” and “1111”.

The response from the service is described in the following table:

IVR_RESPONSE [0-1]{1} Result of the session consultation:
0: It will indicate that it was not possible to localise the IVR session.
1: The session information have been found and will be returned afterwards.
IVR_SESSION_STATE [0-1]{1} The possible values are the following:
0: Waiting
1: Processing
2: Finalised. OK
3: Finalised. KO
4: Communication time exceeded
5: Reference not found
IVR_TIME_LEFT [0-9]{1,3} Time remaining expressed in seconds for finishing the IVR session. In state 0, the established maximum time will be returned. In state 1 the remaining time will be returned. In states 2, 3, 4 and 5 0 will be returned.
IVR_DIGIT_PAN [0-9]{1,16} When the IVR session is underway, the number of digits of the credit card that the client has entered will be returned. 0 will be returned if this information is not available.
IVR_DIGIT_EXP [0-9]{1,4} When the IVR session is underway, the number of digits of the expiry date that the client has entered will be returned. 0 will be returned if this information is not available.
IVR_DIGIT_CVC [0-9]{1,4} When the IVR session is underway, the number of digits of the CVC2 that the client has entered will be returned. 0 will be shown if this information is not available.
IVR_ERROR_ID [0-9]{1,5} In case of error, here a code will be produced for the error generated. The errors may be in entry/validation or correspond to the IVR_SESSION_STATE = 3 status. If there is no error, the field will contain a 0. The error codes are specified in the ERROR CODES section.

Bis Check of IVR HTTP POST session status

Additionally, to facilitate the operation of recovering information from an IVR session, for example through ajax, it is possible to make the call directly through POST.

The URL is the following: https://secure.paytpv.com/gateway/post_ivr.php

The parameters which must be sent are the following:

Element Content Description
getIVRData {Obj} Mandatory. This parameter will be a JSON codified object that will contain the fields detailed below
OPERATION [0-9]{1,9} Mandatory. Operation required in the call. Possible values:
1: get_ivr_sessionstate
IVR_PROVIDER_ID [0-9]{1,6} Mandatory. Supplier / IVR integrator code
IVR_MERCHANT_CODE [A-Za-z0-9]{1,8} Mandatory. Client code
IVR_MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
IVR_MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Operation reference.
IVR_PROVIDER_SIGNATURE [a-zA-Z0-9]{40} Mandatory. See SIGNATURE CALCULATION
La descripción de la columna “Contenido” se refiere a la expresión regular que debe cumplir la información presente en el elemento correspondiente. De esta manera “[A-Z]” indica cualquier carácter de la “A” a la “Z” y los corchetes indican el número de caracteres. Por ejemplo “1{2,4}” valida los números “11”, “111” y “1111”.

The response is described in the following table:

returnData {Obj} The response will be a JSON codified object that will contain the fields detailed below:
IVR_RESPONSE [0-1]{1} Result of the session consultation:
0: It will indicate that it has not been possible to localise the IVR session.
1: The session information has been found and are returned afterwards.
IVR_SESSION_STATE [0-1]{1} The possible values are the following:
0: Waiting
1: Processing
2: Finalised. OK
3: Finalised. KO
4: Communication time exceeded
5: Reference not found
IVR_TIME_LEFT [0-9]{1,3} Time remaining expressed in seconds for finishing the IVR session. In state 0, the established maximum time will be returned. In state 1 the remaining time will be returned. In states 2, 3, 4 and 5 0 will be returned.
IVR_DIGIT_PAN [0-9]{1,16} When the IVR session is underway, the number of digits of the credit card that the client has entered will be returned. 0 will be returned if this information is not available.
IVR_DIGIT_EXP [0-9]{1,4} When the IVR session is underway, the number of digits of the expiry date that the client has entered will be returned. 0 will be returned if this information is not available.
IVR_DIGIT_CVC [0-9]{1,4} When the IVR session is underway, the number of digits of the CVC2 that the client has entered will be returned. 0 will be shown if this information is not available.
IVR_ERROR_ID [0-9]{1,5} In case of error, here a code will be produced for the error generated. The errors may be in entry/validation or correspond to the IVR_SESSION_STATE = 3 status. If there is no error, the field will contain a 0. The error codes are specified in the ERROR CODES section.

Example of javascript call:



function get_ivr_sessionstate() {
        var obj = {};
        obj.OPERATION= '1';
        obj.IVR_PROVIDER_ID= '**Identificador del proveedor/integrador IVR**';
        obj.IVR_MERCHANT_CODE= '**Código de cliente**';
        obj.IVR_MERCHANT_TERMINAL= '**Número de terminal**';
        obj.IVR_MERCHANT_ORDER= '**Referencia**';
        obj.IVR_PROVIDER_SIGNATURE= 'c292caae75bc62aaaaaaaaaaaaa655ead726471f';


        $.ajax({
                        type: "POST",
                        async: false,
                        url: "https://secure.paytpv.com/gateway/post_ivr.php",
                        data: "getIVRData="+JSON.stringify(obj),
                        success: function(returnData){
                        var objR = JSON.parse(returnData);
                        console.log(objR);
                }
        });
}
                        
                

SIGNATURE CALCULATION

The signature that the business will send to the gateway will be calculated in the following way (in pseudo code):

FUNCTION: get_ivr_session

For IVR_TRANSACTION_TYPE = 1, 3, 9

SHA1(IVR_MERCHANT_CODE + IVR_MERCHANT_TERMINAL + IVR_TRANSACTION_TYPE + IVR_MERCHANT_ORDER + IVR_MERCHANT_AMOUNT + IVR_MERCHANT_CURRENCY + PROVIDERPASSWORD)

 

For IVR_TRANSACTION_TYPE = 107

SHA1(IVR_MERCHANT_CODE + IVR_MERCHANT_TERMINAL + IVR_TRANSACTION_TYPE + IVR_MERCHANT_ORDER + PROVIDERPASSWORD)

 

FUNCTION: get_ivr_sessionstate

SHA1(IVR_MERCHANT_CODE + IVR_MERCHANT_TERMINAL + IVR_MERCHANT_ORDER + PROVIDERPASSWORD)

OPERATION TYPES

The types of operations authorised in the IVR integration are the following:

ID Operation
1 Authorisation
3 Pre-authorisation
9 Subscription
107 Bankstore user registration

ANNEX I – CURRENCIES

ANNEX I – CURRENCY AND AMOUNT where the codes of currencies in which operations may be carried out are detailed, is in section Currencies