I.V.R. Integration
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.
Important
XML integration is deprecated. We recommend using REST integration.
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)
Information:
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-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:
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
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