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. Additional configuration
  4. Appendixes
    1. Appendix I - Operation types
    2. Appendix II – Currencies

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 default integration system, collecting card information through IVR. interactive voice response systems.

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

Take a look at that documentation for obtaining an overview of the purchase process and different inflows and outflows

Web programming

The technologies used for the operation with the PAYCOMET payment Gateway are SOAP (XML) and REST, both 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 and REST 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.

Select the type of integration:

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

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,5} 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] 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. IMPORTANTE: Las suscripciones se cobran en la primera ejecución si este campo tiene valor se tendrá en cuenta para los futuros cargos.
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 (if "same" is indicated, it will return to the same extension that called us).
IVR_CALLBACK_STATION_OK Optional. Extension of return in case of operation OK (if "same" is indicated, it will return to the same extension that called us).
IVR_CALLBACK_STATION_KO Optional. Extension of return in case of operation KO (if "same" is indicated, it will return to the same extension that called us).
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.

Signature calculation:

For IVR_TRANSACTION_TYPE = 1, 3, 9

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

 

For IVR_TRANSACTION_TYPE = 107

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

 

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.

Select the type of integration:

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

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,5} Mandatory. Terminal number
IVR_MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Operation reference.
IVR_PROVIDER_SIGNATURE [a-zA-Z0-9] Mandatory. See SIGNATURE CALCULATION

Signature calculation:

SHA512(IVR_MERCHANT_CODE + IVR_MERCHANT_TERMINAL + IVR_MERCHANT_ORDER + PROVIDERPASSWORD)

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-7]{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
6: Operation cancelled by the agent
7: Call ended. Waiting for next call
IVR_SESSION_RESULT [0-5]{1} The possible values are the following:
0: No error
1: Payment operation error
2: Error entering card data
3: Error entering expiration month
4: Error entering expiration year
5: Error entering CVV
IVR_TIME_LEFT [0-9]{1,3} Time remaining expressed in seconds for finishing the IVR session. In state 0, 1 and 7 the remaining time will be returned. In states 2, 3, 4, 5 and 6 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://api.paycomet.com/gateway/post_ivr.php

The parameters which must be sent are the following:

The response is described in the following table:

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,5} Mandatory. Terminal number
IVR_MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Operation reference.
IVR_PROVIDER_SIGNATURE [a-zA-Z0-9] Mandatory. See SIGNATURE CALCULATION
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-7]{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
6: Operation cancelled by the agent
7: Call ended. Waiting for next call
IVR_TIME_LEFT [0-9]{1,3} Time remaining expressed in seconds for finishing the IVR session. In state 0, 1 and 7 the remaining time will be returned. In states 2, 3, 4, 5 and 6 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://api.paycomet.com/gateway/post_ivr.php",
                        data: "getIVRData="+JSON.stringify(obj),
                        success: function(returnData){
                        var objR = JSON.parse(returnData);
                        console.log(objR);
                }
        });
}
                        
                

Additional configuration

{{ __('Call TPV la solución PAYCOMET') }}

In the section (Terminals->"Terminal name"->IVR ) you will find the configuration options:

  • Maximum number of attempts

  • Return extension if timed out

  • Return extension if successful

  • Return extension if failure

Appendix I - 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

Appendix II – Currencies

The codes of currencies in which operations may be carried out is detailed at section Currencies