MENU
PHP CSharp Perl Ruby

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 month
expirationYear - Card expiration year
CardType - 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