IVR Service API
This service allows you to create a tokenKey
which is a pointer to a storage location used by
the automated phone system to get card information from a consumer. You will then use the tokenKey
to retrieve the tokenized card information after the phone call has completed.
A tokenKey
is a pointer to a secure storage location used by the automated phone system to store tokenized card data.
You will use the tokenKey
whenever you need to retrieve this tokenized data.
Authentication and authorization for the IVRService
will be done by JWT
in the
HTTP Authorization Header
. This JWT
can be obtained by passing a valid username
and password
to the AuthenticationService.
Token Keys
POST
to retrieve a new token key.
Request Parameters
test wsdl:
https://ivrdemo.pdc4u.com/IVRService/api/v1_0/tokenkeys
live wsdl:
https://ivr.pdc4u.com/IVRService/api/v1_0/tokenkeys
Attribute | Description |
timeout
Numeric
Required
|
The number of minutes the token key is allowed to be updated with tokenized information. |
roundTripNVPS
ListN/A
|
List of roundTripNVP objects. These are Name/Value passthrough values.
See object definition below. |
Response
Attribute | Description |
tokenKey
Alphanumeric20
|
This will be used to retrieve the saved tokenized data. |
responseStatus
Alpha7
|
The tokenKey returned from the POST request.
Valid values:
SUCCESS - See responseMessage for description.ERROR - See responseMessage for description of error.
|
responseMessage
AlphanumericN/A
|
Description of the responseStatus. |
GET
to retrieve tokenized information
test wsdl:
https://ivrdemo.pdc4u.com/IVRService/api/v1_0/tokenkeys/{tokenkey}
live wsdl:
https://ivr.pdc4u.com/IVRService/api/v1_0/tokenkeys/{tokenkey}
Request Parameters
Attribute | Description |
tokenKey
Alphanumeric20
Required
|
The tokenKey returned from the POST request.
|
Response
Attribute | Description |
token
Alphanumeric16
|
The tokenized card number. |
tokenType
Alpha15
|
The type of data that was tokenized.
Valid values:
CARD - Card number.
|
responseStatus
Alpha7
|
The tokenKey returned from the POST request.
Valid values:
SUCCESS - See responseMessage for description.ERROR - See responseMessage for description of error.
|
responseMessage
AlphanumericN/A
|
Description of the responseStatus. |
roundTripNVPS
ListN/A
|
List of roundTripNVP objects. These are Name/Value passthrough values.
See object definition below. This will include any roundTripNVP objects that were passed with the original POST request,
and will also include:expirationMonth - Card expiration monthexpirationYear - Card expiration yearCardType - Card type |
RoundTripNVP
Attribute | Description |
rtName
Alphanumeric75
Required
|
The name of a round trip name value pair. |
rtValue
Alphanumeric75
Required
|
The value of a round trip name value pair. |
REST Fault
RequestErrorList
Attribute | Description |
requestErrorList
ListN/A
|
A list of RequestError objects containing validation errors.
Constraint(s): Only returned when validation errors occur. See object definition below.
|
RequestError
Attribute | Description |
code
Alpha3
|
The code for the validation error. |
description
AlphanumericN/A
|
The description of the validation error. |
Sample Code
This section offers some client implementation examples in different languages. Keep in mind, these are only minimalistic examples used to demonstrate the IVR Service REST API and are not meant for production use. Endpoints are secured via Authentication JWT
Result Status Codes
Expected Http Status codes
Status '200':
Description = 'Success.'
Status: '400':
Description = 'Malformed request. The request is either incorrectly formatted, or there are validation errors.'
Status '401':
Description = 'Invalid credentials.'
Status '403':
Description = 'Service not activated.'
Status '404':
Description = 'The requested signature/document/image was not found.'
Status '405':
Description = 'POST, GET, PUT request not supported for resource.'
Status '498'
Description = 'JWT validation token is expired'
Status '500':
Description = 'An internal error has occurred.'
Status '503':
Description = 'The requested service (IVR, TOKENIZE) is not activated.'
All requests will return a status code. For example, in the case of status code 400
, check for a requestErrorList
in the response, containing information on validation failure.
Sample Token key generation
<?php
$url = 'https://ivrdemo.pdc4u.com/IVRService/api/v1_0/tokenkeys?';
$jwt = 'jwt_from_authenticationservice';
$authorization = "Authorization: Bearer " . $jwt;
$data = [
'timeout' => '30'
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_POST, 1);
$data = json_encode($data, JSON_UNESCAPED_SLASHES);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', $authorization));
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT ,5); //num seconds to try connecting
curl_setopt($curl, CURLOPT_TIMEOUT, 30); //max number of seconds to allow execution
$result = curl_exec($curl);
$statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
// View response
print_r(json_decode($result, true));
if ($statusCode == '200')
{
//Handle success
}
else
{
//Handle error according to status code
}
curl_close($curl);
#!/usr/bin/perl
use LWP::UserAgent;
use HTTP::Request;
use HTTP::Request::Common;
use JSON::XS;
use IO::Socket::SSL qw(debug3); # verbose for troubleshooting
eval {
my $data = {
'timeout' => '30'
};
$data = JSON::XS->new->utf8->encode ($data);
my $url = 'https://ivrdemo.pdc4u.com/IVRService/api/v1_0/tokenkeys';
my $jwt = 'jwt_from_authenticationservice';
my $authHeader = HTTP::Headers->new('Authorization' => 'Bearer '. $jwt);
my $req = HTTP::Request->new( 'POST', $url, $authHeader );
$req->content_type('application/json');
$req->content_length( length($data) );
$req->content( $data );
my $lwp = LWP::UserAgent->new;
$lwp->timeout(30);
my $response = $lwp->request( $req );
if ( $response->is_success ) {
print "Success: " . $response->decoded_content;
}
else {
die $response->status_line . ": " . $response->decoded_content;
}
};
if ( $@ ) {
print "Error: $@\n";
}
#!/usr/bin/ruby
require 'curl'
require 'curb'
require 'json'
require 'base64'
begin
data = {
'timeout' => '30'
}
jwt = 'jwt_from_authenticationservice'
c = Curl::Easy.new
c.url = 'https://ivrdemo.pdc4u.com/IVRService/api/v1_0/tokenkeys'
c.headers["Authorization: Bearer"] = jwt
c.connect_timeout = 5
c.timeout = 30
c.verbose = true
headers={}
headers['Content-Type'] = 'application/json'
headers['Content-Length'] = data.to_json.length
payload = data.to_json
c.headers = headers
c.http_post(payload)
puts JSON.parse c.body_str
if c.response_code == 200 then
puts "Success " + c.status
else
puts "Error " + c.status
end
rescue
puts "Caught: #$!\n"
end
Send an HTTP POST
request to:
test wsdl:
https://ivrdemo.pdc4u.com/IVRService/api/v1_0/tokenkeys
live wsdl:
https://ivr.pdc4u.com/IVRService/api/v1_0/tokenkeys
Sample Tokenized data retrieval
<?php
$url = 'https://ivrdemo.pdc4u.com/IVRService/api/v1_0/tokenkeys/';
$jwt = 'jwt_from_authenticationservice';
$authorization = "Authorization: Bearer " . $jwt;
$reportParams = [
'tokenKey' => '4q3zmwd3n66'
];
$url .= $reportParams['tokenKey'];
$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', $authorization));
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT ,5); //num seconds to try connecting
curl_setopt($curl, CURLOPT_TIMEOUT, 30); //max number of seconds to allow execution
$result = curl_exec($curl);
$statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
// View response
print_r(json_decode($result, true));
if ($statusCode == '200')
{
//Handle success
}
else
{
//Handle error according to status code
}
curl_close($curl);
#!/usr/bin/perl
use LWP::UserAgent;
use HTTP::Request;
use JSON::XS;
use IO::Socket::SSL qw(debug3); # verbose for troubleshooting
eval {
my $uri = URI->new("https://ivrdemo.pdc4u.com/IVRService/api/v1_0/tokenkeys/4q3zmwd3n66");
my $jwt = 'jwt_from_authenticationservice';
my $authHeader = HTTP::Headers->new('Authorization' => 'Bearer '. $jwt);
my $req = HTTP::Request->new( 'GET', $uri, $authHeader );
my $lwp = LWP::UserAgent->new;
my $response = $lwp->request( $req );
if ( $response->is_success ) {
print "Success: " . $response->decoded_content;
}
else {
die $response->status_line . ": " . $response->decoded_content;
}
};
if ( $@ ) {
print "Error: $@\n";
}
#!/usr/bin/ruby
require 'curl'
require 'curb'
require 'json'
begin
jwt = 'jwt_from_authenticationservice'
url = "https://ivrdemo.pdc4u.com/IVRService/api/v1_0/tokenkeys/4q3zmwd3n66"
c = Curl::Easy.new( url )
c.headers["Authorization: Bearer"] = jwt
c.connect_timeout = 5
c.timeout = 30
c.verbose = true
c.perform
puts JSON.parse c.body_str
if c.response_code == 200 then
puts "Success " + c.status
else
puts "Error " + c.status
end
rescue
puts "Caught: #$!\n"
end
Send an HTTP GET
request to:
test wsdl:
https://ivrdemo.pdc4u.com/IVRService/api/v1_0/tokenkeys
live wsdl:
https://ivr.pdc4u.com/IVRService/api/v1_0/tokenkeys