Introduction
Welcome to the PDCflow API Docs! Here you can find information and examples on the diverse selection of APIs used to integrate with PDCflow.
Attribute Tables
Attribute tables include all of the critical information that you will use to integrate with our APIs. The example below shows you where to find each piece of information for an Attribute.
| Attribute | Description |
|---|---|
|
Attribute Name
FormatMax Length
If Required/Conditional
|
This is where there will be a description of the Attribute and what it is used for.
Format: formatted-sample
Constraint(s): Explanation of constraint(s)
Valid value(s):
value1, value2Default: The Default Value
|
Code Samples
// Libraries needed. On an Ubuntu system, run the following commands:
sudo apt-get install php7.0-soap
sudo apt-get install php-curl
sudo apt-get install php-json
Debugging SOAP in PHP:
Add tracing:
<?php $client = new SoapClient($url, array('trace' => 1)); ?>
Output the results of the trace:
<?php var_dump( $client->__getLastRequest() ); ?>
Debugging REST in PHP:
<?php curl_setopt($curl, CURLOPT_VERBOSE, true); ?>
# Libraries needed. On an Ubuntu system, run the following commands:
sudo apt-get install cpanminus
sudo cpan App::cpanminus (take defaults)
sudo cpanm LWP::Authen::Wsse
sudo cpanm SOAP::Lite
# Libraries needed. On an Ubuntu system, run the following commands:
sudo apt-get install ruby-dev
sudo apt-get install zlib1g-dev
sudo gem install savon
sudo gem install curl
sudo apt-get install libcurl4-gnutls-dev
sudo gem install curb
You can view sample code in the dark area to the right. We provide examples in PHP, Perl, & Ruby. For the code samples to work, each language will require the installation of specific libraries which are listed to the right.
Integrator Forum
If you can’t find the information you are looking for, need an example not provided here, or have a specific question you want answered head over to our API Forum.
Auth Signature Audit API [DEPRECATED]
Request an audit report for a signature request. This would be used in conjunction with Auth Signature API
API Request
Retrieve an audit report for a signature transaction request.
SignatureAuditRetrievalRequest
test wsdl:
https://wssignaturedemo.pdc4u.com/AuthSignatureAuditService/ws/retrieveauditservices/retrieveauditservice.wsdl
live wsdl:
https://wssignature.pdc4u.com/AuthSignatureAuditService/ws/retrieveauditservices/retrieveauditservice.wsdlnamespace:
http://www.pdc4u.com/retrieveauditservices_v1_0method:
SignatureAuditRetrievalRequest
| Attribute | Description |
|---|---|
|
TransId
Numeric20
Required
|
The id of the transaction to retrieve audit report for. |
|
EmailTo
Alphanumeric65
Required
|
What email address should the audit report be sent to. |
|
Format
Alpha3
Required
|
The desired format for the audit report.
Valid value(s):
PDF, XML |
|
Version
Numeric3
Required
|
The version being used.
Valid value(s):
1.0, 1.4, 1.5, 1.6Default: 1.0
|
API Response
SignatureAuditRetrievalResponse
| Attribute | Description |
|---|---|
|
TransId
Numeric20
|
The id of the transaction that the audit request is for. |
|
DetailData
Base64N/A
|
Base64 representation of the audit report. |
|
Format
Alpha3
|
The format that the report is in.
Valid value(s):
PDF, XML |
|
Result
Alpha3
|
The result of the audit report request.
Valid value(s):
OK, ERR |
|
ErrorMessage
Alphanumeric60
|
A message explaining the error.
Constraint(s): Only populated if
Result is ERR.
|
Sample Code
Web Service Security
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-2" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:Username>SomeSecretUsername</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">SomeEvenMoreSecretPassword</wsse:Password>
<wsu:Created>2014-05-07T20:33:48.015Z</wsu:Created>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
........
Each SOAP request submitted to PDCflow must contain a security header as part of the message. This header is based on an established standard: Web Services Security - UsernameToken Profile 1.1. An example of this header is shown to the right.
See: http://docs.oasis-open.org/wss-m/wss/v1.1.1/os/wss-UsernameTokenProfile-v1.1.1-os.html
Retrieve audit report
<?php
//special handling to create a WSSE-compliant header
class WsseAuthHeader extends SoapHeader {
private $wss_ns = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd';
function __construct($user, $pass) {
$auth = new stdClass();
$auth->Username = new SoapVar($user, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$auth->Password = new SoapVar($pass, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$username_token = new stdClass();
$username_token->UsernameToken = new SoapVar($auth, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns);
$security_sv = new SoapVar(
new SoapVar($username_token, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns),
SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'Security', $this->wss_ns);
parent::__construct($this->wss_ns, 'Security', $security_sv, true);
}
}
$url='https://wssignaturedemo.pdc4u.com/AuthSignatureAuditService/ws/retrieveauditservices/retrieveauditservice.wsdl';
$namespace = 'http://www.pdc4u.com/retrieveauditservices_v1_0';
$method = 'SignatureAuditRetrieval';
$wsse_header = new WsseAuthHeader('SomeSecretUsername', 'SomeSecretPassword');
$client = new SoapClient($url);
$client->__setSoapHeaders([$wsse_header]);
$SignatureAuditRetrievalRequest = [
'TransId' => '00000000',
'EmailTo' => 'SomeEmailAddress',
'Format' => 'PDF',
'Version' => '1.6',
];
try {
$response = $client->__soapCall(
$method,
[$SignatureAuditRetrievalRequest, $namespace]
);
print_r($response);
}
catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
my $soap = SOAP::Lite
->readable(1) # nice for debugging
->autotype(0)
# Extract the targetNamespace from the .wsdl definitions for the desired method
->default_ns( 'http://www.pdc4u.com/signatureAudit/message/pdc_v1/sar' )
->proxy( 'https://wssignaturedemo.pdc4u.com/AuthSignatureAuditService/ws/retrieveauditservices/retrieveauditservice.wsdl' );
my $username = 'SomeSecretUsername';
my $password = 'SomeSecretPassword';
my $security = SOAP::Header->name("wsse:Security")->attr({
'xmlns:wsse' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'
});
my $userToken =SOAP::Header->name("wsse:UsernameToken" =>
\SOAP::Header->value(
SOAP::Header->name('wsse:Username')->value($username)->type(''),
SOAP::Header->name('wsse:Password')->value($password)->type('')->attr(
{'Type'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText'}))
)->attr({'xmlns:wsu'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'});
my %params = (
'TransId' => '00000000',
'EmailTo' => 'SomeEmailAddress',
'Format' => 'PDF',
'Version' => '1.6',
);
my @data;
foreach my $key ( keys %params ) {
push @data, SOAP::Data->name( $key => $params{$key} );
}
print $soap->call( 'SignatureAuditRetrievalRequest', $security->value(\$userToken), @data )->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://wssignaturedemo.pdc4u.com/AuthSignatureAuditService/ws/retrieveauditservices/retrieveauditservice.wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
params = {
'TransId' => '00000000',
'EmailTo' => 'SomeEmailAddress',
'Format' => 'PDF',
'Version' => '1.6',
}
response = client.call(:signature_audit_retrieval, message: params) do |locals|
locals.wsse_auth "SomeSecretUsername", "SomeSecretPassword"
end
puts response
rescue
puts "Caught: #$!\n"
end
test wsdl:
https://wssignaturedemo.pdc4u.com/AuthSignatureAuditService/ws/retrieveauditservices/retrieveauditservice.wsdl
live wsdl:
https://wssignature.pdc4u.com/AuthSignatureAuditService/ws/retrieveauditservices/retrieveauditservice.wsdl
The namespace to use is:
http://www.pdc4u.com/retrieveauditservices_v1_0
The method to use is:
SignatureAuditRetrieval
Auth Signature API [DEPRECATED]
The Auth Signature Service consists of a few web services:
- Send Request - send a request for a signature, document approval, and more.
- Retrieve Signatures - get a signature image back.
- Reporting - get reports/details about sent requests.
- Modify Signatures - cancel a signature request.
Send Request
test wsdl:
https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl
live wsdl:
https://wssignature.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdlnamespace:
http://www.pdc4u.com/authsig/message/pdc_v1/pslmethod:
PrepareSendLink
Send a text/email to customer with a link to a secure website for capturing their signature/payment or displaying a document.
PrepareSendLinkRequest
| Attribute | Description |
|---|---|
|
PayorFirstName
Alphanumeric45
Required
|
The first name of your client. |
|
PayorLastName
Alphanumeric45
Required
|
The last name of your client. |
|
MobileNum
Numeric15
Conditional
|
The phone number to send request to.
Constraint(s): With country code; Required if no
Email provided.
|
|
Email
Alphanumeric65
Conditional
|
The email address to send the request to.
Constraint(s): Required if no
MobileNum provided.
|
|
VerificationPin
Numeric8
Required
|
Shared secret for client verification.
Constraint(s): Must be between 4 and 8 digits long.
|
|
PinDescription
Alphanumeric50
Required
|
Description of the VerificationPin.
|
|
Amount
Numeric11
Conditional
|
Base amount for payment, will also display on signature.
Format: Format as you want it to appear ($125.00; £25; 34,95€;), however only USD is supported for payment.
Constraint(s): Required if payment is also requested.
|
|
Description
Alphanumeric160
Conditional
|
Description of what the signature is for. Shows on signature.
Constraint(s): Only required with signature.
|
|
UserId
Alphanumeric65
|
Username or email of the employee sending this request. |
|
MaxPinAttempts
Numeric2
|
Maximum amount of attempts the client is allowed for verification before transaction is locked.
Default: 3
|
|
RequestGeolocation
Boolean5
|
Request the geolocation from the client.
Constraint(s): User can refuse to share location, preventing capture.
Valid value(s):
TRUE, FALSEDefault: TRUE
|
|
TimeoutMinutes
Numeric6
|
Number of minutes client has to complete the transaction before it expires.
Default: 2.5
|
|
RedirectLink
Alphanumeric65
|
Link to direct client to, after signature is complete. |
|
CustomMessage
AlphaNumeric320
|
Freeform text to display at the end of the transaction. |
|
Version
Numeric3
|
The version of the service being used.
Valid value(s):
1.0, 1.4, 1.5, 1.6Default: 1.0
|
|
CustomFields
ObjectN/A
|
Name/Value passthrough values.
Constraint(s): See object definition below.
|
|
PaymentData
ObjectN/A
|
Data for payment processing.
Constraint(s): See object definition below.
|
|
DocumentData
ObjectN/A
|
Data for document presentation.
Constraint(s): See object definition below.
|
|
PaymentFeeAmount
Numeric11
|
A fee to be applied to the payment and shown on the signature.
Format: Format as you want it to appear ($125.00; £25; 34,95€;), however only USD is supported for payment.
Default: 0.00
|
|
SignatureRequested
Boolean5
|
Whether signature is desired or not.
Valid value(s):
TRUE, FALSEDefault: TRUE
|
|
FlowOrder
ObjectN/A
|
The order the pages will appear for the client.
Constraint(s): See object definition below.
|
|
ImageUploadData
ObjectN/A
|
Information for image upload.
Constraint(s): See object definition below.
|
PrepareSendLinkResponse
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/psl
| Attribute | Description |
|---|---|
|
RequestedTimestamp
DateTime25
|
Date and time the transaction was requested
Format: 2017-01-06 10:15:51-0700
|
|
TransId
Numeric20
|
Unique id for the transaction. |
|
StorageResult
Alpha3
|
Result of transaction.
Valid value(s):
OK, ERR |
|
ResultMessage
AlphanumericN/A
|
Message relating to a failed request.
Constraint(s): Only populated if
StorageResult is ERR.
|
|
DocumentId
Numeric20
|
Id for document that was uploaded. Can be sent in future requests to reuse document without uploading it again. |
|
CustomFields
ObjectN/A
|
Custom fields that were passed in for passthrough.
Constraint(s): See object definition below.
|
|
ValidationErrorList
ObjectN/A
|
Object that holds list of validation errors.
Constraint(s): See object definition below.
|
|
ImageUploadId
Numeric20
|
Id for the image that was uploaded by the client. Can be used to retrieve uploaded image. |
Retrieve Signatures
test wsdl:
https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/signatureretrievalservices/signatureretrievalservice.wsdl
live wsdl:
https://wssignature.pdc4u.com/AuthSignatureService/ws/signatureretrievalservices/signatureretrievalservice.wsdlnamespace:
http://www.pdc4u.com/authsig/message/pdc_v1/sigrmethod:
SignatureRetrieval
Retrieve a signature image, previously uploaded document or client-uploaded image
SignatureRetrievalRequest
| Attribute | Description |
|---|---|
|
TransId
Numeric20
Required
|
The id of the signature to be retrieved. |
|
Version
Numeric3
|
The version of the service being used.
Valid value(s):
1.0, 1.4, 1.5, 1.6Default: 1.0
|
|
DocumentId
Numeric20
|
The id of the document to be retrieved. |
|
ImageUploadId
Numeric20
|
The id of the image upload to be retrieved. |
SignatureRetrievalResponse
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/sigr
| Attribute | Description |
|---|---|
|
ErrorCode
Alpha3
|
On error, this code will represent the error. |
|
ErrorMessage
Alphanumeric160
|
On error, this will be a description of the error which occurred. |
|
Latitude
Numeric32
|
The latitude recorded when the client signed the request, if available.
Format: 51.1789
|
|
Longitude
Numeric32
|
The longitude recorded when the client signed the request, if available.
Format: -1.8262
|
|
Signature
Base64N/A
|
Base64 encoded signature image.
Format: .gif
|
|
DocumentRetrievalData
ObjectN/A
|
Data pertaining to document that was retrieved.
Constraint(s): See object definition below.
|
|
ValidationErrorList
ObjectN/A
|
Object that holds list of validation errors.
Constraint(s): See object definition below.
|
|
ReceivedGeolocation
Boolean5
|
Whether the location of the signer was received.
Valid value(s):
TRUE, FALSE |
|
ImageUploadRetrievalData
ObjectN/A
|
Data pertaining to the image upload that was retrieved.
Constraint(s): See object definition below.
|
Reporting
SignatureReportRequest
test wsdl:
https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/signaturereportservices/signaturereportservice.wsdl
live wsdl:
https://wssignature.pdc4u.com/AuthSignatureService/ws/signaturereportservices/signaturereportservice.wsdlnamespace:
http://www.pdc4u.com/authsig/message/pdc_v1/srrmethod:
SignatureReport
Retrieve a report on signatures uploaded during a specified date range or by a combination of attributes in the following table.
| Attribute | Description |
|---|---|
|
StartDate
DateTime20
|
Requests after this date will be retrieved.
Format: ISO-8601 (YYYY-MM-DDTHH:mm:ss)
Default: 2013-01-01T00:00:00
|
|
EndDate
DateTime20
|
Requests before this date will be retrieved.
Format: ISO-8601 (YYYY-MM-DDTHH:mm:ss)
Default: Current date
|
|
FirstName
Alpha45
|
Requests sent to people with this first name will be retrieved. |
|
LastName
Alpha45
|
Requests sent to people with this last name will be retrieved. |
|
RecordStart
Numeric20
|
If defined, which record in date range to start with. In conjunction with RecordCount, if 3000 transactions were pulled, RecordCount is 1,000, RecordStart at 1,000 will return transactions 1,000-2,000.
Default: 0
|
|
RecordCount
Numeric4
|
Total amount of records to be returned in single request. The max value is 5000.
Default: 2000
|
|
RetrieveOnlyCompletedRequests
Boolean5
|
Whether to return ONLY requests that have been completed.
Valid value(s):
TRUE, FALSEDefault: FALSE
|
|
ReportType
Alpha15
|
Type of report to be retrieved.
Valid value(s):
ALLSIGNATURE - requests that had signaturesALLDOCUMENTS - only requests with documentsSINGLEDOCUMENT - all requests with DocumentIdACHPAYMENT - all requests with an ACH paymentCCPAYMENT - all requests with a CC paymentALLPAYMENT - all requests with any paymentDETAIL - detail report for provided SignatureId
Default: ALL
|
|
DocumentId
Numeric20
Conditional
|
Document Id to filter search by.
Constraint(s): Required for
ReportType SINGLEDOCUMENT.
|
|
SignatureId
Numeric20
Conditional
|
Signature Id to retrieve DETAIL report for.
Constraint(s): Required for
ReportType DETAIL.
|
|
UserId
Alphanumeric65
|
Only requests sent by this user will be retrieved. |
|
Version
Numeric3
|
The version of the service being used.
Valid value(s):
1.0, 1.4, 1.5, 1.6Default: 1.0
|
SignatureReportResponse
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/srr
| Attribute | Description |
|---|---|
|
SignatureReportGeneralDatas
ObjectN/A
|
Object containing a list of SignatureReportGeneralData.
Constraint(s): See object definition below.
|
|
SignatureReportDetailData
ObjectN/A
|
Single SignatureReportDetailData.
Constraint(s): See object definition below.
|
|
ValidationErrorList
ObjectN/A
|
Object that holds list of validation errors.
Constraint(s): See object definition below.
|
SignatureReportGeneralData
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/srd
| Attribute | Description |
|---|---|
|
TransactionId
Numeric20
|
Unique id for the transaction. |
|
FirstName
Alpha45
|
First Name of the person the request was sent to. |
|
LastName
Alpha45
|
Last Name of the person the request was sent to. |
|
SentDate
DateTime25
|
The date and time the request was sent.
Format: ISO-8601 (2017-05-22T10:54:10-0600)
|
|
EmailAddressTo
Alphanumeric65
|
Email address the request was sent to. |
|
PhoneNumberTo
Numeric15
|
Phone number the request was sent to. |
|
Username
Alphanumeric65
|
Username of the employee who sent the request. |
|
PaymentType
Alpha3
|
Payment type associated with transaction.
Valid value(s):
CC, ACH |
|
DocumentId
Numeric20
|
Id for document that was uploaded with this transaction. |
|
ImageUploadId
Numeric20
|
Id for the image that was uploaded by the client. |
|
WasSignatureRequested
Boolean5
|
Whether a signature was requested with this transaction.
Valid value(s):
TRUE, FALSE |
|
SignatureCompletionDate
DateTime25
|
The date and time the signature was completed.
Format: ISO-8601 (2017-05-22T10:54:10-0600)
|
|
IsFlowClosed
Boolean5
|
Whether all parts of the transaction were completed or an error occurred and the transaction was closed.
Valid value(s):
TRUE, FALSE |
|
ErrorCode
Alpha3
|
An error code if the transaction was closed due to an error. |
|
ErrorMessage
Alphanumeric160
|
An explanation message for an error that occurred. |
SignatureReportDetailData
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/srd
| Attribute | Description |
|---|---|
|
SignatureReportGeneralData
ObjectN/A
|
Object containing the SignatureReportGeneralData for the transaction.
Constraint(s): See object definition above.
|
|
ACHReportData
ObjectN/A
|
Object containing the ACHReportData for the transaction.
Constraint(s): See object definition below.
|
|
ImageUploadRetrievalData
ObjectN/A
|
Data pertaining to the image upload that was retrieved.
Constraint(s): See object definition below.
|
|
PaymentTransactionId
Numeric20
|
Payment Transaction id tied to this transaction. |
|
AccountNumber
Alphanumeric45
|
Account number associated with payment in this transaction. |
|
AccountDirective
Numeric10
|
The Account directive used for the payment in this transaction. |
|
PaymentCreationDate
DateTime25
|
The date and time the payment was entered for processing.
Format: ISO-8601 (2017-05-22T10:54:10-0600)
|
|
DateProcessed
DateTime25
|
The date the payment was processed.
Format: ISO-8601 (2017-05-22T10:54:10-0600)
|
|
PaymentAmount
Numeric11
|
The payment amount for this transaction.
Format: XXXX.XX
|
|
FeeAmount
Numeric11
|
The fee amount for this transaction.
Format: XXXX.XX
|
|
TotalAmount
Numeric11
|
The total amount processed for this transaction. |
|
Address
Alphanumeric80
|
The address associated with the payment. |
|
City
Alphanumeric45
|
The city associated with the payment. |
|
State
Alphanumeric2
|
The state abbreviation associated with the payment. |
|
Zip
Numeric9
|
The zip code associated with the payment. |
|
CustomFields
ObjectN/A
|
Custom fields that were passed in for passthrough.
Constraint(s): See object definition below.
|
Modify Signatures
test wsdl:
https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/signaturemodificationservices/signaturemodificationservice.wsdl
live wsdl:
https://wssignature.pdc4u.com/AuthSignatureService/ws/signaturemodificationservices/signaturemodificationservice.wsdlnamespace:
http://www.pdc4u.com/authsig/message/pdc_v1/smrmethod:
SignatureModification
Modify a previously uploaded signature request
SignatureModificationRequest
| Attribute | Description |
|---|---|
|
TransId
Numeric20
Required
|
The id of the signature to be modified. |
|
UserId
Alphanumeric65
Required
|
Username or email of the employee making the modification. |
|
Command
Alpha5
Required
|
The modification to make on the transaction.
Valid value(s):
CLOSE |
|
Version
Numeric3
|
The version of the service being used.
Valid value(s):
1.5, 1.6Default: 1.5
|
SignatureModificationResponse
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/smr
| Attribute | Description |
|---|---|
|
Result
Alpha3
|
Result of the modification request.
Valid value(s):
OK, ERR |
|
ErrorMessage
AlphanumericN/A
|
An explanation message for an error that occurred. |
|
ValidationErrorList
ObjectN/A
|
Object that holds list of validation errors.
Constraint(s): See object definition below.
|
Object Definitions
ACHReportData
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/achr
| Attribute | Description |
|---|---|
|
ACHStatusData
ObjectN/A
|
Object that holds a list of status datas for ACH transaction.
Constraint(s): See object definition below.
|
|
BankRoutingNumber
Numeric9
|
The bank routing number used for the transaction. |
|
BankAccountNumberLastFour
Numeric4
|
The last four of the bank account number used for the transaction. |
|
CheckNumber
Numeric10
|
The check number used for the transaction. |
|
AccountType
Alpha8
|
The type of account that was used for the transaction.
Valid value(s):
CHECKING, SAVINGS |
ACHStatusData
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/achs
| Attribute | Description |
|---|---|
|
ACHStatus
Alpha12
|
The status of the ACH transaction.
Valid value(s):
WAITING - transaction will be included in next batchSUBMITTED - transaction has been submitted for processingACKNOWLEDGED - transaction has been accepted for processingFUNDED - money has been deposited into your accountDEDUCTION - money has been taken from your accountVOID - transaction was cancelled prior to submission for processingRETURNED - an exception occured while processing transactionCORRECTION - transaction was automatically corrected during processingERROR - an unknown error occured while processing transaction
|
|
ACHReturnCode
Alpha3
|
Code representing a failed or corrected transaction. ACHReturnMessage will describe this code.
Format:
R01, X05, C02, etc |
|
ACHReturnMessage
AlphanumericN/A
|
Explanation of the ACHReturnCode.
|
|
ACHStatusChangeDate
DateTime25
|
Date and time this ACH status was recorded.
Format: ISO-8601 (YYYY-MM-DDTHH:mm:ss)
|
CustomFields
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/cfl
| Attribute | Description |
|---|---|
|
CustomFields
ObjectN/A
|
Object that holds a list of custom fields. These are passthrough values.
Constraint(s): See object definition below.
|
CustomField
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/cfl
| Attribute | Description |
|---|---|
|
FieldName
Alphanumeric75
|
The name of the Name/Value passthrough. |
|
FieldValue
Alphanumeric75
|
The value of the Name/Value passthrough. |
DocumentRetrievalData
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/docr
| Attribute | Description |
|---|---|
|
OriginalUploadDate
DateTime25
|
The date and time the document was originally uploaded.
Format: ISO-8601 (YYYY-MM-DDTHH:mm:ss)
|
|
DocumentData
ObjectN/A
|
Object that holds all the data for the document.
Constraint(s): See object definition below.
|
DocumentData
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/docr
| Attribute | Description |
|---|---|
|
DocumentName
Alphanumeric36
|
The name given for the document when it was originally uploaded.
Constraint(s): Name must be unique for each uploaded document.
|
|
DocumentBase64String
Base64N/A
|
The document as a Base64 encoded string. |
|
DocumentId
Numeric20
|
Id for document that was uploaded. Can be sent in future requests to reuse document without uploading it again. |
FlowOrder
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/ord
| Attribute | Description |
|---|---|
|
FlowPage
ObjectN/A
|
Object that holds a list of FlowPage objects to define the order.
Constraint(s): See object definition below.
|
FlowPage
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/ord
| Attribute | Description |
|---|---|
|
FlowPage
Alpha6
|
An enum to define pages. List pages in desired order to define order that client will see the pages in.
Constraint(s): Only requested functionality can be included.
Valid value(s):
PG_DOC, PG_IMG, PG_SIG, PG_PAY
Default:
|
ImageUploadData
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/imu
| Attribute | Description |
|---|---|
|
ImageUploadRequested
Boolean5
|
Whether to request an image upload from the client.
Valid value(s):
TRUE, FALSEDefault: FALSE
|
|
ImageDescription
Alphanumeric160
|
A description for what type of image for the client to upload.
Default: ‘Upload Image’
|
ImageUploadRetrievalData
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/imur
| Attribute | Description |
|---|---|
|
ImageDescription
Alphanumeric160
|
A description for what type of image for the client to upload. |
|
ImageUploadId
Numeric20
|
Id for the image that was uploaded by the client. |
|
UploadSuccessful
Boolean5
|
Whether the upload was successful or not.
Valid value(s):
TRUE, FALSE |
|
ImageBase64
Base64N/A
|
Base64 encoded value of the uploaded image.
Format: .png
|
|
ErrorCode
Alpha3
|
Code for error that may have occurred with image upload. |
|
ErrorMessage
Alphanumeric160
|
An explanation message for an error that occurred. |
PaymentData
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/pay
| Attribute | Description |
|---|---|
|
PaymentType
Alpha3
|
Type of payment to include in the request.
Valid value(s):
ACH, CC |
|
AccountDirective
Numeric10
|
The account directive to be used for the payment. |
|
BankAccountType
Alpha8
|
The type of bank account.
Constraint(s): Will be preloaded on form for client, though they will be able to edit it.
Valid value(s):
CHECKING, SAVINGS |
|
BankAccountNumber
Numeric20
|
The payor’s bank account number for ACH transaction.
Constraint(s): Will be preloaded on form for client, though they will be able to edit it.
|
|
BankRoutingNumber
Numeric9
|
The payor’s bank routing number for ACH transaction.
Constraint(s): Will be preloaded on form for client, though they will be able to edit it.
|
|
AccountNumber
Alphanumeric45
|
The payor’s account number.
Constraint(s): Will be preloaded on form for client; they will NOT be able to edit it.
|
|
CheckNumber
Numeric10
|
The payor’s check number for transaction.
Constraint(s): Will be preloaded on form for client, though they will be able to edit it.
|
|
CreditCardToken
Alphanumeric16
|
Credit card token as generated by PDCflow. An actual credit card number will fail validation.
Constraint(s): Will be preloaded on form for client, though they will be able to edit it or enter a different card number.
|
|
CreditCardExpirationMonth
Numeric2
|
Expiration month of the payor’s credit card.
Constraint(s): Will be preloaded on form for client, though they will be able to edit it.
|
|
CreditCardExpirationYear
Numeric4
|
Expiration year of the payor’s credit card.
Constraint(s): Will be preloaded on form for client, though they will be able to edit it.
|
ValidationErrorList
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/val
| Attribute | Description |
|---|---|
|
ValidationErrors
ObjectN/A
|
Object that holds a list of validation errors.
Constraint(s): See object definition below.
|
ValidationErrors
namespace:
http://www.pdc4u.com/authsig/message/pdc_v1/val
| Attribute | Description |
|---|---|
|
ErrorCode
Alpha3
|
Error code for failed validation. |
|
ErrorMessage
AlphanumericN/A
|
An explanation message for the validation error that occurred. |
Sample Code
Web Service Security
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-2" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:Username>SomeSecretUsername</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">SomeEvenMoreSecretPassword</wsse:Password>
<wsu:Created>2014-05-07T20:33:48.015Z</wsu:Created>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
........
Each SOAP request submitted to PDCflow must contain a security header as part of the message. This header is based on an established standard: Web Services Security - UsernameToken Profile 1.1. An example of this header is shown to the right.
See: http://docs.oasis-open.org/wss-m/wss/v1.1.1/os/wss-UsernameTokenProfile-v1.1.1-os.html
Sample Code - Send
Send a signature request
<?php
//special handling to create a WSSE-compliant header
class WsseAuthHeader extends SoapHeader {
private $wss_ns = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd';
function __construct($user, $pass) {
$auth = new stdClass();
$auth->Username = new SoapVar($user, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$auth->Password = new SoapVar($pass, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$username_token = new stdClass();
$username_token->UsernameToken = new SoapVar($auth, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns);
$security_sv = new SoapVar(
new SoapVar($username_token, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns),
SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'Security', $this->wss_ns);
parent::__construct($this->wss_ns, 'Security', $security_sv, true);
}
}
$params = [
'PayorFirstName' => 'Adam',
'PayorLastName' => 'Test',
'MobileNum' => '',
'Email' => 'adamemail@pdcflow.com',
'VerificationPin' => '1234',
'PinDescription' => 'Test description',
'Amount' => '1.00',
'Description' => 'Approve $1 charge',
'UserId' => '',
'MaxPinAttempts' => '',
'RequestGeolocation' => '',
'TimeoutMinutes' => '',
'RedirectLink' => '',
'CustomMessage' => '',
'Version' => '1.6',
'CustomFields' => [],
'PaymentData' => [
'PaymentType' => '',
'AccountDirective' => ''
],
'DocumentData' => [
'DocumentName' => '',
'DocumentBase64String' => '',
'DocumentId' => ''
],
'PaymentFeeAmount' => '',
'SignatureRequested' => 'TRUE',
'FlowOrigin' => 'EXT',
'FlowOrder' => [
],
'ImageUploadData' => [
'ImageUploadRequested' => '',
'ImageDescription' => ''
]
];
$url = 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl';
$namespace = 'http://www.pdc4u.com/authsig/message/pdc_v1/psl';
$method = 'PrepareSendLink';
$wsse_header = new WsseAuthHeader('SomeSecretUsername', 'SomeSecretPassword');
$client = new SoapClient($url);
$client->__setSoapHeaders([$wsse_header]);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
}
catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
use File::Slurp;
use MIME::Base64;
my $soap = SOAP::Lite
->readable(1) # nice for debugging
->autotype(0)
# Extract the targetNamespace from the .wsdl definitions for the desired method
->default_ns( 'http://www.pdc4u.com/authsig/message/pdc_v1/psl' )
->proxy( 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl' );
my $username = 'SomeSecretUsername';
my $password = 'SomeSecretPassword';
my $security = SOAP::Header->name("wsse:Security")->attr({
'xmlns:wsse' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'
});
my $userToken =SOAP::Header->name("wsse:UsernameToken" =>
\SOAP::Header->value(
SOAP::Header->name('wsse:Username')->value($username)->type(''),
SOAP::Header->name('wsse:Password')->value($password)->type('')->attr(
{'Type'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText'}))
)->attr({'xmlns:wsu'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'});
my %params = (
'PayorFirstName' => 'Adam',
'PayorLastName' => 'Test',
'MobileNum' => '',
'Email' => 'adamemail@pdcflow.com',
'VerificationPin' => '1234',
'PinDescription' => 'Test description',
'Amount' => '',
'Description' => 'Approve $1 charge',
'UserId' => '',
'MaxPinAttempts' => '',
'RequestGeolocation' => '',
'TimeoutMinutes' => '',
'RedirectLink' => '',
'CustomMessage' => '',
'Version' => '1.6',
'CustomFields' => {},
'PaymentData' => {
'PaymentType' => '',
'AccountDirective' => ''
},
'DocumentData' => {
'DocumentName' => '',
'DocumentBase64String' => '',
'DocumentId' => ''
},
'PaymentFeeAmount' => '',
'SignatureRequested' => 'TRUE',
'FlowOrigin' => 'EXT',
'FlowOrder' => {
},
'ImageUploadData' => {
'ImageUploadRequested' => '',
'ImageDescription' => ''
}
);
my @data;
foreach my $key ( keys %params ) {
my %xmlns_map = (
'CustomFields' => 'http://www.pdc4u.com/authsig/message/pdc_v1/cfl',
'PaymentData' => 'http://www.pdc4u.com/authsig/message/pdc_v1/pay',
'DocumentData' => 'http://www.pdc4u.com/authsig/message/pdc_v1/doc',
'FlowOrder' => 'http://www.pdc4u.com/authsig/message/pdc_v1/ord',
'ImageUploadData' => 'http://www.pdc4u.com/authsig/message/pdc_v1/imu',
);
push @data, SOAP::Data->name( $key => $params{$key} )
->attr({xmlns => $xmlns_map{$key}});
}
print $soap->call( 'PrepareSendLinkRequest', $security->value(\$userToken), @data )->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
params = {
'PayorFirstName' => 'Adam',
'PayorLastName' => 'Test',
'MobileNum' => '',
'Email' => 'adamemail@pdcflow.com',
'VerificationPin' => '1234',
'PinDescription' => 'Test description',
'Amount' => '1.00',
'Description' => 'Approve $1 charge',
'UserId' => '',
'MaxPinAttempts' => '',
'RequestGeolocation' => '',
'TimeoutMinutes' => '',
'RedirectLink' => '',
'CustomMessage' => '',
'Version' => '1.6',
'CustomFields' => {},
'PaymentData' => {
'PaymentType' => '',
'AccountDirective' => ''
},
'DocumentData' => {
'DocumentName' => '',
'DocumentBase64String' => '',
'DocumentId' => ''
},
'PaymentFeeAmount' => '',
'SignatureRequested' => 'TRUE',
'FlowOrigin' => 'EXT',
'FlowOrder' => {
},
'ImageUploadData' => {
'ImageUploadRequested' => '',
'ImageDescription' => ''
}
}
response = client.call(:prepare_send_link, message: params) do |locals|
locals.wsse_auth "SomeSecretUsername", "SomeSecretPassword"
end
puts response
rescue
puts "Caught: #$!\n"
end
The URL to use for a signature request is:
https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl
The namespace to use is:
http://www.pdc4u.com/authsig/message/pdc_v1/psl
The method to use is:
PrepareSendLink
Send a document request
<?php
//special handling to create a WSSE-compliant header
class WsseAuthHeader extends SoapHeader {
private $wss_ns = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd';
function __construct($user, $pass) {
$auth = new stdClass();
$auth->Username = new SoapVar($user, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$auth->Password = new SoapVar($pass, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$username_token = new stdClass();
$username_token->UsernameToken = new SoapVar($auth, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns);
$security_sv = new SoapVar(
new SoapVar($username_token, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns),
SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'Security', $this->wss_ns);
parent::__construct($this->wss_ns, 'Security', $security_sv, true);
}
}
//read and encode pdf to upload
$pdfDocument = 'mydoc.pdf';
$handle = fopen($pdfDocument, "r");
$pdfContents = fread($handle, filesize($pdfDocument));
fclose($handle);
$documentData = base64_encode($pdfContents);
$params = [
'PayorFirstName' => 'Adam',
'PayorLastName' => 'Test',
'MobileNum' => '',
'Email' => 'adamemail@pdcflow.com',
'VerificationPin' => '1234',
'PinDescription' => 'Test description',
'Amount' => '',
'Description' => 'Approve this document',
'UserId' => '',
'MaxPinAttempts' => '',
'RequestGeolocation' => '',
'TimeoutMinutes' => '',
'RedirectLink' => '',
'CustomMessage' => '',
'Version' => '1.6',
'CustomFields' => [],
'PaymentData' => [
'PaymentType' => '',
'AccountDirective' => ''
],
'DocumentData' => [
'DocumentName' => 'My unique document name',
'DocumentBase64String' => $documentData,
'DocumentId' => ''
],
'PaymentFeeAmount' => '',
'SignatureRequested' => 'FALSE',
'FlowOrigin' => 'EXT',
'FlowOrder' => [
],
'ImageUploadData' => [
'ImageUploadRequested' => '',
'ImageDescription' => ''
]
];
$url = 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl';
$namespace = 'http://www.pdc4u.com/authsig/message/pdc_v1/psl';
$method = 'PrepareSendLink';
$wsse_header = new WsseAuthHeader('SomeSecretUsername', 'SomeSecretPassword');
$client = new SoapClient($url);
$client->__setSoapHeaders([$wsse_header]);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
}
catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
use File::Slurp;
use MIME::Base64;
my $soap = SOAP::Lite
->readable(1) # nice for debugging
->autotype(0)
# Extract the targetNamespace from the .wsdl definitions for the desired method
->default_ns( 'http://www.pdc4u.com/authsig/message/pdc_v1/psl' )
->proxy( 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl' );
my $username = 'SomeSecretUsername';
my $password = 'SomeSecretPassword';
my $security = SOAP::Header->name("wsse:Security")->attr({
'xmlns:wsse' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'
});
my $userToken =SOAP::Header->name("wsse:UsernameToken" =>
\SOAP::Header->value(
SOAP::Header->name('wsse:Username')->value($username)->type(''),
SOAP::Header->name('wsse:Password')->value($password)->type('')->attr(
{'Type'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText'}))
)->attr({'xmlns:wsu'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'});
# read and encode pdf to upload
my $pdfDocument = 'mydoc.pdf';
my $pdfContents = read_file( $pdfDocument );
my $documentData = encode_base64($pdfContents, ""); # encode without newlines
my %params = (
'PayorFirstName' => 'Adam',
'PayorLastName' => 'Test',
'MobileNum' => '',
'Email' => 'adamemail@pdcflow.com',
'VerificationPin' => '1234',
'PinDescription' => 'Test description',
'Amount' => '',
'Description' => 'Approve this document',
'UserId' => '',
'MaxPinAttempts' => '',
'RequestGeolocation' => '',
'TimeoutMinutes' => '',
'RedirectLink' => '',
'CustomMessage' => '',
'Version' => '1.6',
'CustomFields' => {},
'PaymentData' => {
'PaymentType' => '',
'AccountDirective' => ''
},
'DocumentData' => {
'DocumentName' => 'My unique document name',
'DocumentBase64String' => $documentData,
'DocumentId' => ''
},
'PaymentFeeAmount' => '',
'SignatureRequested' => 'FALSE',
'FlowOrigin' => 'EXT',
'FlowOrder' => {
},
'ImageUploadData' => {
'ImageUploadRequested' => '',
'ImageDescription' => ''
}
);
my @data;
foreach my $key ( keys %params ) {
my %xmlns_map = (
'CustomFields' => 'http://www.pdc4u.com/authsig/message/pdc_v1/cfl',
'PaymentData' => 'http://www.pdc4u.com/authsig/message/pdc_v1/pay',
'DocumentData' => 'http://www.pdc4u.com/authsig/message/pdc_v1/doc',
'FlowOrder' => 'http://www.pdc4u.com/authsig/message/pdc_v1/ord',
'ImageUploadData' => 'http://www.pdc4u.com/authsig/message/pdc_v1/imu',
);
push @data, SOAP::Data->name( $key => $params{$key} )
->attr({xmlns => $xmlns_map{$key}});
}
print $soap->call( 'PrepareSendLinkRequest', $security->value(\$userToken), @data )->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
require 'base64'
begin
# create a client for the service
client = Savon.client(wsdl: 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
# read and encode pdf to upload
pdfDocument = 'mydoc.pdf'
file = File.open(pdfDocument, "rb")
contents = file.read
file.close
documentData = Base64.strict_encode64(contents) # encodes without newlines
params = {
'PayorFirstName' => 'Adam',
'PayorLastName' => 'Test',
'MobileNum' => '',
'Email' => 'adamemail@pdcflow.com',
'VerificationPin' => '1234',
'PinDescription' => 'Test description',
'Amount' => '',
'Description' => 'Approve this document',
'UserId' => '',
'MaxPinAttempts' => '',
'RequestGeolocation' => '',
'TimeoutMinutes' => '',
'RedirectLink' => '',
'CustomMessage' => '',
'Version' => '1.6',
'ins1:CustomFields' => {},
'ins2:PaymentData' => {
'ins2:PaymentType' => '',
'ins2:AccountDirective' => ''
},
'ins3:DocumentData' => {
'ins3:DocumentName' => 'My unique document name',
'ins3:DocumentBase64String' => documentData,
'ins3:DocumentId' => ''
},
'PaymentFeeAmount' => '',
'SignatureRequested' => 'FALSE',
'FlowOrigin' => 'EXT',
'ins4:FlowOrder' => {
},
'ins5:ImageUploadData' => {
'ins5:ImageUploadRequested' => '',
'ins5:ImageDescription' => ''
}
}
response = client.call(:prepare_send_link, message: params) do |locals|
locals.wsse_auth "SomeSecretUsername", "SomeSecretPassword"
end
puts response
rescue
puts "Caught: #$!\n"
end
The URL to use for a signature request is:
test wsdl:
https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl
live wsdl:
https://wssignature.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl
The namespace to use is:
http://www.pdc4u.com/authsig/message/pdc_v1/psl
The method to use is:
PrepareSendLink
Send a payment request
<?php
//special handling to create a WSSE-compliant header
class WsseAuthHeader extends SoapHeader {
private $wss_ns = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd';
function __construct($user, $pass) {
$auth = new stdClass();
$auth->Username = new SoapVar($user, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$auth->Password = new SoapVar($pass, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$username_token = new stdClass();
$username_token->UsernameToken = new SoapVar($auth, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns);
$security_sv = new SoapVar(
new SoapVar($username_token, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns),
SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'Security', $this->wss_ns);
parent::__construct($this->wss_ns, 'Security', $security_sv, true);
}
}
$params = [
'PayorFirstName' => 'Adam',
'PayorLastName' => 'Test',
'MobileNum' => '',
'Email' => 'adamemail@pdcflow.com',
'VerificationPin' => '1234',
'PinDescription' => 'Test description',
'Amount' => '1.00',
'Description' => 'Approve this payment',
'UserId' => '',
'MaxPinAttempts' => '',
'RequestGeolocation' => '',
'TimeoutMinutes' => '',
'RedirectLink' => '',
'CustomMessage' => '',
'Version' => '1.6',
'CustomFields' => [],
'PaymentData' => [
'PaymentType' => 'ACH',
'AccountDirective' => 'XX-X'
],
'DocumentData' => [
'DocumentName' => '',
'DocumentBase64String' => '',
'DocumentId' => ''
],
'PaymentFeeAmount' => '0.50',
'SignatureRequested' => 'FALSE',
'FlowOrigin' => 'EXT',
'FlowOrder' => [
],
'ImageUploadData' => [
'ImageUploadRequested' => '',
'ImageDescription' => ''
]
];
$url = 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl';
$namespace = 'http://www.pdc4u.com/authsig/message/pdc_v1/psl';
$method = 'PrepareSendLink';
$wsse_header = new WsseAuthHeader('SomeSecretUsername', 'SomeSecretPassword');
$client = new SoapClient($url);
$client->__setSoapHeaders([$wsse_header]);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
}
catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
use File::Slurp;
use MIME::Base64;
my $soap = SOAP::Lite
->readable(1) # nice for debugging
->autotype(0)
# Extract the targetNamespace from the .wsdl definitions for the desired method
->default_ns( 'http://www.pdc4u.com/authsig/message/pdc_v1/psl' )
->proxy( 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl' );
my $username = 'SomeSecretUsername';
my $password = 'SomeSecretPassword';
my $security = SOAP::Header->name("wsse:Security")->attr({
'xmlns:wsse' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'
});
my $userToken =SOAP::Header->name("wsse:UsernameToken" =>
\SOAP::Header->value(
SOAP::Header->name('wsse:Username')->value($username)->type(''),
SOAP::Header->name('wsse:Password')->value($password)->type('')->attr(
{'Type'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText'}))
)->attr({'xmlns:wsu'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'});
my %params = (
'PayorFirstName' => 'Adam',
'PayorLastName' => 'Test',
'MobileNum' => '',
'Email' => 'adamemail@pdcflow.com',
'VerificationPin' => '1234',
'PinDescription' => 'Test description',
'Amount' => '',
'Description' => 'Approve this payment',
'UserId' => '',
'MaxPinAttempts' => '',
'RequestGeolocation' => '',
'TimeoutMinutes' => '',
'RedirectLink' => '',
'CustomMessage' => '',
'Version' => '1.6',
'CustomFields' => {},
'PaymentData' => {
'PaymentType' => 'ACH',
'AccountDirective' => 'XX-X'
},
'DocumentData' => {
'DocumentName' => '',
'DocumentBase64String' => '',
'DocumentId' => ''
},
'PaymentFeeAmount' => '0.50',
'SignatureRequested' => 'FALSE',
'FlowOrigin' => 'EXT',
'FlowOrder' => {
},
'ImageUploadData' => {
'ImageUploadRequested' => '',
'ImageDescription' => ''
}
);
my @data;
foreach my $key ( keys %params ) {
my %xmlns_map = (
'CustomFields' => 'http://www.pdc4u.com/authsig/message/pdc_v1/cfl',
'PaymentData' => 'http://www.pdc4u.com/authsig/message/pdc_v1/pay',
'DocumentData' => 'http://www.pdc4u.com/authsig/message/pdc_v1/doc',
'FlowOrder' => 'http://www.pdc4u.com/authsig/message/pdc_v1/ord',
'ImageUploadData' => 'http://www.pdc4u.com/authsig/message/pdc_v1/imu',
);
push @data, SOAP::Data->name( $key => $params{$key} )
->attr({xmlns => $xmlns_map{$key}});
}
print $soap->call( 'PrepareSendLinkRequest', $security->value(\$userToken), @data )->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl',
log_level: :debug,
log: false,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
params = {
'PayorFirstName' => 'Adam',
'PayorLastName' => 'Test',
'MobileNum' => '',
'Email' => 'adamemail@pdcflow.com',
'VerificationPin' => '1234',
'PinDescription' => 'Test description',
'Amount' => '1.00',
'Description' => 'Approve this payment',
'UserId' => '',
'MaxPinAttempts' => '',
'RequestGeolocation' => '',
'TimeoutMinutes' => '',
'RedirectLink' => '',
'CustomMessage' => '',
'Version' => '1.6',
'ins1:CustomFields' => {},
'ins2:PaymentData' => {
'ins2:PaymentType' => 'ACH',
'ins2:AccountDirective' => 'XX-X'
},
'ins3:DocumentData' => {
'ins3:DocumentName' => '',
'ins3:DocumentBase64String' => '',
'ins3:DocumentId' => ''
},
'PaymentFeeAmount' => '0.50',
'SignatureRequested' => 'FALSE',
'FlowOrigin' => 'EXT',
'ins4:FlowOrder' => {
},
'ins5:ImageUploadData' => {
'ins5:ImageUploadRequested' => '',
'ins5:ImageDescription' => ''
}
}
response = client.call(:prepare_send_link, message: params) do |locals|
locals.wsse_auth "SomeSecretUsername", "SomeSecretPassword"
end
puts response
rescue
puts "Caught: #$!\n"
end
The URL to use for a signature request is:
test wsdl:
https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl
live wsdl:
https://wssignature.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl
The namespace to use is:
http://www.pdc4u.com/authsig/message/pdc_v1/psl
The method to use is:
PrepareSendLink
Send an image request
<?php
//special handling to create a WSSE-compliant header
class WsseAuthHeader extends SoapHeader {
private $wss_ns = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd';
function __construct($user, $pass) {
$auth = new stdClass();
$auth->Username = new SoapVar($user, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$auth->Password = new SoapVar($pass, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$username_token = new stdClass();
$username_token->UsernameToken = new SoapVar($auth, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns);
$security_sv = new SoapVar(
new SoapVar($username_token, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns),
SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'Security', $this->wss_ns);
parent::__construct($this->wss_ns, 'Security', $security_sv, true);
}
}
$params = [
'PayorFirstName' => 'Adam',
'PayorLastName' => 'Test',
'MobileNum' => '',
'Email' => 'adamemail@pdcflow.com',
'VerificationPin' => '1234',
'PinDescription' => 'Test description',
'Amount' => '',
'Description' => 'Approve this image',
'UserId' => '',
'MaxPinAttempts' => '',
'RequestGeolocation' => '',
'TimeoutMinutes' => '',
'RedirectLink' => '',
'CustomMessage' => '',
'Version' => '1.6',
'CustomFields' => [],
'PaymentData' => [
'PaymentType' => '',
'AccountDirective' => ''
],
'DocumentData' => [
'DocumentName' => '',
'DocumentBase64String' => '',
'DocumentId' => ''
],
'PaymentFeeAmount' => '',
'SignatureRequested' => 'FALSE',
'FlowOrigin' => 'EXT',
'FlowOrder' => [
],
'ImageUploadData' => [
'ImageUploadRequested' => 'TRUE',
'ImageDescription' => 'Take a picture of yourself'
]
];
$url = 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl';
$namespace = 'http://www.pdc4u.com/authsig/message/pdc_v1/psl';
$method = 'PrepareSendLink';
$wsse_header = new WsseAuthHeader('SomeSecretUsername', 'SomeSecretPassword');
$client = new SoapClient($url);
$client->__setSoapHeaders([$wsse_header]);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
}
catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
use File::Slurp;
use MIME::Base64;
my $soap = SOAP::Lite
->readable(1) # nice for debugging
->autotype(0)
# Extract the targetNamespace from the .wsdl definitions for the desired method
->default_ns( 'http://www.pdc4u.com/authsig/message/pdc_v1/psl' )
->proxy( 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl' );
my $username = 'SomeSecretUsername';
my $password = 'SomeSecretPassword';
my $security = SOAP::Header->name("wsse:Security")->attr({
'xmlns:wsse' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'
});
my $userToken =SOAP::Header->name("wsse:UsernameToken" =>
\SOAP::Header->value(
SOAP::Header->name('wsse:Username')->value($username)->type(''),
SOAP::Header->name('wsse:Password')->value($password)->type('')->attr(
{'Type'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText'}))
)->attr({'xmlns:wsu'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'});
my %params = (
'PayorFirstName' => 'Adam',
'PayorLastName' => 'Test',
'MobileNum' => '',
'Email' => 'adamemail@pdcflow.com',
'VerificationPin' => '1234',
'PinDescription' => 'Test description',
'Amount' => '',
'Description' => 'Approve this image',
'UserId' => '',
'MaxPinAttempts' => '',
'RequestGeolocation' => '',
'TimeoutMinutes' => '',
'RedirectLink' => '',
'CustomMessage' => '',
'Version' => '1.6',
'CustomFields' => {},
'PaymentData' => {
'PaymentType' => '',
'AccountDirective' => ''
},
'DocumentData' => {
'DocumentName' => '',
'DocumentBase64String' => '',
'DocumentId' => ''
},
'PaymentFeeAmount' => '',
'SignatureRequested' => 'FALSE',
'FlowOrigin' => 'EXT',
'FlowOrder' => {
},
'ImageUploadData' => {
'ImageUploadRequested' => 'TRUE',
'ImageDescription' => 'Take a picture of yourself'
}
);
my @data;
foreach my $key ( keys %params ) {
my %xmlns_map = (
'CustomFields' => 'http://www.pdc4u.com/authsig/message/pdc_v1/cfl',
'PaymentData' => 'http://www.pdc4u.com/authsig/message/pdc_v1/pay',
'DocumentData' => 'http://www.pdc4u.com/authsig/message/pdc_v1/doc',
'FlowOrder' => 'http://www.pdc4u.com/authsig/message/pdc_v1/ord',
'ImageUploadData' => 'http://www.pdc4u.com/authsig/message/pdc_v1/imu',
);
push @data, SOAP::Data->name( $key => $params{$key} )
->attr({xmlns => $xmlns_map{$key}});
}
print $soap->call( 'PrepareSendLinkRequest', $security->value(\$userToken), @data )->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
params = {
'PayorFirstName' => 'Adam',
'PayorLastName' => 'Test',
'MobileNum' => '',
'Email' => 'adamemail@pdcflow.com',
'VerificationPin' => '1234',
'PinDescription' => 'Test description',
'Amount' => '',
'Description' => 'Approve this image',
'UserId' => '',
'MaxPinAttempts' => '',
'RequestGeolocation' => '',
'TimeoutMinutes' => '',
'RedirectLink' => '',
'CustomMessage' => '',
'Version' => '1.6',
'ins1:CustomFields' => {},
'ins2:PaymentData' => {
'ins2:PaymentType' => '',
'ins2:AccountDirective' => ''
},
'ins3:DocumentData' => {
'ins3:DocumentName' => '',
'ins3:DocumentBase64String' => '',
'ins3:DocumentId' => ''
},
'PaymentFeeAmount' => '',
'SignatureRequested' => 'FALSE',
'FlowOrigin' => 'EXT',
'ins4:FlowOrder' => {
},
'ins5:ImageUploadData' => {
'ins5:ImageUploadRequested' => 'TRUE',
'ins5:ImageDescription' => 'Take a picture of yourself'
}
}
response = client.call(:prepare_send_link, message: params) do |locals|
locals.wsse_auth "SomeSecretUsername", "SomeSecretPassword"
end
puts response
rescue
puts "Caught: #$!\n"
end
The URL to use for a signature request is:
test wsdl:
https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl
live wsdl:
https://wssignature.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl
The namespace to use is:
http://www.pdc4u.com/authsig/message/pdc_v1/psl
The method to use is:
PrepareSendLink
Send a signature, document, payment, and image request with modified order and custom fields
<?php
//special handling to create a WSSE-compliant header
class WsseAuthHeader extends SoapHeader {
private $wss_ns = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd';
function __construct($user, $pass) {
$auth = new stdClass();
$auth->Username = new SoapVar($user, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$auth->Password = new SoapVar($pass, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$username_token = new stdClass();
$username_token->UsernameToken = new SoapVar($auth, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns);
$security_sv = new SoapVar(
new SoapVar($username_token, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns),
SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'Security', $this->wss_ns);
parent::__construct($this->wss_ns, 'Security', $security_sv, true);
}
}
//read and encode pdf to upload
$pdfDocument = 'mydoc.pdf';
$handle = fopen($pdfDocument, "r");
$pdfContents = fread($handle, filesize($pdfDocument));
fclose($handle);
$documentData = base64_encode($pdfContents);
$params = [
'PayorFirstName' => 'Adam',
'PayorLastName' => 'Test',
'MobileNum' => '',
'Email' => 'adamemail@pdcflow.com',
'VerificationPin' => '1234',
'PinDescription' => 'Test description',
'Amount' => '1.00',
'Description' => 'Approve all of this',
'UserId' => '',
'MaxPinAttempts' => '',
'RequestGeolocation' => '',
'TimeoutMinutes' => '',
'RedirectLink' => '',
'CustomMessage' => '',
'Version' => '1.6',
'CustomFields' => [
['FieldName' => 'OS', 'FieldValue' => 'Windows'],
['FieldName' => 'Browser', 'FieldValue' => 'Firefox']
],
'PaymentData' => [
'PaymentType' => 'ACH',
'AccountDirective' => 'XX-X'
],
'DocumentData' => [
'DocumentName' => '',
'DocumentBase64String' => $documentData,
'DocumentId' => ''
],
'PaymentFeeAmount' => '0.50',
'SignatureRequested' => 'TRUE',
'FlowOrigin' => 'EXT',
'FlowOrder' => [
'FlowPage' => [
'PG_SIG',
'PG_IMG',
'PG_DOC',
'PG_PAY'
]
],
'ImageUploadData' => [
'ImageUploadRequested' => 'TRUE',
'ImageDescription' => 'Take a picture of yourself'
]
];
$url = 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl';
$namespace = 'http://www.pdc4u.com/authsig/message/pdc_v1/psl';
$method = 'PrepareSendLink';
$wsse_header = new WsseAuthHeader('SomeSecretUsername', 'SomeSecretPassword');
$client = new SoapClient($url);
$client->__setSoapHeaders([$wsse_header]);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
}
catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
use File::Slurp;
use MIME::Base64;
my $soap = SOAP::Lite
->readable(1) # nice for debugging
->autotype(0)
# Extract the targetNamespace from the .wsdl definitions for the desired method
->default_ns( 'http://www.pdc4u.com/authsig/message/pdc_v1/psl' )
->proxy( 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl' );
my $username = 'SomeSecretUsername';
my $password = 'SomeSecretPassword';
my $security = SOAP::Header->name("wsse:Security")->attr({
'xmlns:wsse' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'
});
my $userToken =SOAP::Header->name("wsse:UsernameToken" =>
\SOAP::Header->value(
SOAP::Header->name('wsse:Username')->value($username)->type(''),
SOAP::Header->name('wsse:Password')->value($password)->type('')->attr(
{'Type'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText'}))
)->attr({'xmlns:wsu'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'});
# read and encode pdf to upload
my $pdfDocument = 'mydoc.pdf';
my $pdfContents = read_file( $pdfDocument );
my $documentData = encode_base64($pdfContents, ""); # encode without newlines
my %params = (
'PayorFirstName' => 'Adam',
'PayorLastName' => 'Test',
'MobileNum' => '',
'Email' => 'adamemail@pdcflow.com',
'VerificationPin' => '1234',
'PinDescription' => 'Test description',
'Amount' => '1.00',
'Description' => 'Approve all of this',
'UserId' => '',
'MaxPinAttempts' => '',
'RequestGeolocation' => '',
'TimeoutMinutes' => '',
'RedirectLink' => '',
'CustomMessage' => '',
'Version' => '1.6',
'CustomFields' => [
{'FieldName' => 'OS', 'FieldValue' => 'Windows'},
{'FieldName' => 'Browser', 'FieldValue' => 'Firefox'}
],
'PaymentData' => {
'PaymentType' => 'ACH',
'AccountDirective' => 'XX-X'
},
'DocumentData' => {
'DocumentName' => '',
'DocumentBase64String' => $documentData,
'DocumentId' => ''
},
'PaymentFeeAmount' => '0.50',
'SignatureRequested' => 'TRUE',
'FlowOrigin' => 'EXT',
'FlowOrder' => {
'FlowPage' => [
'PG_SIG',
'PG_IMG',
'PG_DOC',
'PG_PAY'
]
},
'ImageUploadData' => {
'ImageUploadRequested' => 'TRUE',
'ImageDescription' => 'Take a picture of yourself'
}
);
my @data;
foreach my $key ( keys %params ) {
my %xmlns_map = (
'CustomFields' => 'http://www.pdc4u.com/authsig/message/pdc_v1/cfl',
'PaymentData' => 'http://www.pdc4u.com/authsig/message/pdc_v1/pay',
'DocumentData' => 'http://www.pdc4u.com/authsig/message/pdc_v1/doc',
'FlowOrder' => 'http://www.pdc4u.com/authsig/message/pdc_v1/ord',
'ImageUploadData' => 'http://www.pdc4u.com/authsig/message/pdc_v1/imu',
);
push @data, SOAP::Data->name( $key => $params{$key} )
->attr({xmlns => $xmlns_map{$key}});
}
print $soap->call( 'PrepareSendLinkRequest', $security->value(\$userToken), @data )->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
require 'base64'
begin
# create a client for the service
client = Savon.client(wsdl: 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
# read and encode pdf to upload
pdfDocument = 'mydoc.pdf'
file = File.open(pdfDocument, "rb")
contents = file.read
file.close
documentData = Base64.strict_encode64(contents) # encode without newlines
params = {
'PayorFirstName' => 'Adam',
'PayorLastName' => 'Test',
'MobileNum' => '',
'Email' => 'adamemail@pdcflow.com',
'VerificationPin' => '1234',
'PinDescription' => 'Test description',
'Amount' => '1.00',
'Description' => 'Approve all of this',
'UserId' => '',
'MaxPinAttempts' => '',
'RequestGeolocation' => '',
'TimeoutMinutes' => '',
'RedirectLink' => '',
'CustomMessage' => '',
'Version' => '1.6',
'CustomFields' => [
{'FieldName' => 'OS', 'FieldValue' => 'Windows'},
{'FieldName' => 'Browser', 'FieldValue' => 'Firefox'}
],
'PaymentData' => {
'PaymentType' => 'ACH',
'AccountDirective' => 'XX-X'
},
'DocumentData' => {
'DocumentName' => '',
'DocumentBase64String' => $documentData,
'DocumentId' => ''
},
'PaymentFeeAmount' => '0.50',
'SignatureRequested' => 'TRUE',
'FlowOrigin' => 'EXT',
'FlowOrder' => {
'FlowPage' => [
'PG_SIG',
'PG_IMG',
'PG_DOC',
'PG_PAY'
]
},
'ImageUploadData' => {
'ImageUploadRequested' => 'TRUE',
'ImageDescription' => 'Take a picture of yourself'
}
}
response = client.call(:prepare_send_link, message: params) do |locals|
locals.wsse_auth "SomeSecretUsername", "SomeSecretPassword"
end
puts response
rescue
puts "Caught: #$!\n"
end
The URL to use for a signature request is:
test wsdl:
https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl
live wsdl:
https://wssignature.pdc4u.com/AuthSignatureService/ws/preparesendlinkservices/preparesendlinkservice.wsdl
The namespace to use is:
http://www.pdc4u.com/authsig/message/pdc_v1/psl
The method to use is:
PrepareSendLink
Sample Code - Retrieve
Retrieve a completed signature
<?php
//special handling to create a WSSE-compliant header
class WsseAuthHeader extends SoapHeader {
private $wss_ns = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd';
function __construct($user, $pass) {
$auth = new stdClass();
$auth->Username = new SoapVar($user, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$auth->Password = new SoapVar($pass, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$username_token = new stdClass();
$username_token->UsernameToken = new SoapVar($auth, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns);
$security_sv = new SoapVar(
new SoapVar($username_token, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns),
SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'Security', $this->wss_ns);
parent::__construct($this->wss_ns, 'Security', $security_sv, true);
}
}
$params = [
'TransId' => '1',
'Version' => '',
'DocumentId' => '',
'ImageUploadId' => ''
];
$url = 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/signatureretrievalservices/signatureretrievalservice.wsdl';
$namespace = 'http://www.pdc4u.com/authsig/message/pdc_v1/sigr';
$method = 'SignatureRetrieval';
$wsse_header = new WsseAuthHeader('SomeSecretUsername', 'SomeSecretPassword');
$client = new SoapClient($url);
$client->__setSoapHeaders([$wsse_header]);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
}
catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
my $soap = SOAP::Lite
->readable(1) # nice for debugging
->autotype(0)
# Extract the targetNamespace from the .wsdl definitions for the desired method
->default_ns( 'http://www.pdc4u.com/authsig/message/pdc_v1/sigr' )
->proxy( 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/signatureretrievalservices/signatureretrievalservice.wsdl' );
my $username = 'SomeSecretUsername';
my $password = 'SomeSecretPassword';
my $security = SOAP::Header->name("wsse:Security")->attr({
'xmlns:wsse' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'
});
my $userToken =SOAP::Header->name("wsse:UsernameToken" =>
\SOAP::Header->value(
SOAP::Header->name('wsse:Username')->value($username)->type(''),
SOAP::Header->name('wsse:Password')->value($password)->type('')->attr(
{'Type'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText'}))
)->attr({'xmlns:wsu'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'});
my %params = (
'TransId' => '1',
'Version' => '',
'DocumentId' => '',
'ImageUploadId' => ''
);
my @data;
foreach my $key ( keys %params ) {
push @data, SOAP::Data->name( $key => $params{$key} );
}
print $soap->call( 'SignatureRetrievalRequest', $security->value(\$userToken), @data )->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/signatureretrievalservices/signatureretrievalservice.wsdl',
log_level: :debug,
log: false,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
params = {
'TransId' => '1',
'Version' => '',
'DocumentId' => '',
'ImageUploadId' => ''
}
response = client.call(:signature_retrieval, message: params) do |locals|
locals.wsse_auth "SomeSecretUsername", "SomeSecretPassword"
end
puts response
rescue
puts "Caught: #$!\n"
end
The URL to use for a signature retrieval request is:
test wsdl:
https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/signatureretrievalservices/signatureretrievalservice.wsdl
live wsdl:
https://wssignature.pdc4u.com/AuthSignatureService/ws/signatureretrievalservices/signatureretrievalservice.wsdl
The namespace to use is:
http://www.pdc4u.com/authsig/message/pdc_v1/sigr
The method to use is:
SignatureRetrieval
Sample Code - Report
Retrieve details for signature id
<?php
//special handling to create a WSSE-compliant header
class WsseAuthHeader extends SoapHeader {
private $wss_ns = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd';
function __construct($user, $pass) {
$auth = new stdClass();
$auth->Username = new SoapVar($user, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$auth->Password = new SoapVar($pass, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$username_token = new stdClass();
$username_token->UsernameToken = new SoapVar($auth, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns);
$security_sv = new SoapVar(
new SoapVar($username_token, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns),
SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'Security', $this->wss_ns);
parent::__construct($this->wss_ns, 'Security', $security_sv, true);
}
}
$params = [
'StartDate' => '',
'EndDate' => '',
'FirstName' => '',
'LastName' => '',
'RecordStart' => '',
'RecordCount' => '',
'RetrieveOnlyCompletedRequests' => '',
'ReportType' => 'DETAIL',
'DocumentId' => '',
'SignatureId' => 'X',
'UserId' => '',
'Version' => '',
];
$url = 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/signaturereportservices/signaturereportservice.wsdl';
$namespace = 'http://www.pdc4u.com/authsig/message/pdc_v1/srr';
$method = 'SignatureReport';
$wsse_header = new WsseAuthHeader('SomeSecretUsername', 'SomeSecretPassword');
$client = new SoapClient($url);
$client->__setSoapHeaders([$wsse_header]);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
}
catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
my $soap = SOAP::Lite
->readable(1) # nice for debugging
->autotype(0)
# Extract the targetNamespace from the .wsdl definitions for the desired method
->default_ns( 'http://www.pdc4u.com/authsig/message/pdc_v1/srr' )
->proxy( 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/signaturereportservices/signaturereportservice.wsdl' );
my $username = 'SomeSecretUsername';
my $password = 'SomeSecretPassword';
my $security = SOAP::Header->name("wsse:Security")->attr({
'xmlns:wsse' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'
});
my $userToken =SOAP::Header->name("wsse:UsernameToken" =>
\SOAP::Header->value(
SOAP::Header->name('wsse:Username')->value($username)->type(''),
SOAP::Header->name('wsse:Password')->value($password)->type('')->attr(
{'Type'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText'}))
)->attr({'xmlns:wsu'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'});
my %params = (
'StartDate' => '',
'EndDate' => '',
'FirstName' => '',
'LastName' => '',
'RecordStart' => '',
'RecordCount' => '',
'RetrieveOnlyCompletedRequests' => '',
'ReportType' => 'DETAIL',
'DocumentId' => '',
'SignatureId' => 'X',
'UserId' => '',
'Version' => '',
);
my @data;
foreach my $key ( keys %params ) {
push @data, SOAP::Data->name( $key => $params{$key} );
}
print $soap->call( 'SignatureReportRequest', $security->value(\$userToken), @data )->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/signaturereportservices/signaturereportservice.wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
params = {
'StartDate' => '',
'EndDate' => '',
'FirstName' => '',
'LastName' => '',
'RecordStart' => '',
'RecordCount' => '',
'RetrieveOnlyCompletedRequests' => '',
'ReportType' => 'DETAIL',
'DocumentId' => '',
'SignatureId' => 'X',
'UserId' => '',
'Version' => '',
};
response = client.call(:signature_report, message: params) do |locals|
locals.wsse_auth "SomeSecretUsername", "SomeSecretPassword"
end
puts response
rescue
puts "Caught: #$!\n"
end
The URL to use for a signature report request is:
test wsdl:
https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/signaturereportservices/signaturereportservice.wsdl
live wsdl:
https://wssignature.pdc4u.com/AuthSignatureService/ws/signaturereportservices/signaturereportservice.wsdl
The namespace to use is:
http://www.pdc4u.com/authsig/message/pdc_v1/srr
The method to use is:
SignatureReport
Sample Code - Modify
Cancel a signature request that was sent
<?php
//special handling to create a WSSE-compliant header
class WsseAuthHeader extends SoapHeader {
private $wss_ns = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd';
function __construct($user, $pass) {
$auth = new stdClass();
$auth->Username = new SoapVar($user, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$auth->Password = new SoapVar($pass, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$username_token = new stdClass();
$username_token->UsernameToken = new SoapVar($auth, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns);
$security_sv = new SoapVar(
new SoapVar($username_token, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns),
SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'Security', $this->wss_ns);
parent::__construct($this->wss_ns, 'Security', $security_sv, true);
}
}
$params = [
'TransId' => 'X',
'UserId' => 'usernameOfPersonClosingThis',
'Command' => 'CLOSE',
'Version' => '1.6'
];
$url = 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/signaturemodificationservices/signaturemodificationservice.wsdl';
$namespace = 'http://www.pdc4u.com/authsig/message/pdc_v1/smr';
$method = 'SignatureModification';
$wsse_header = new WsseAuthHeader('SomeSecretUsername', 'SomeSecretPassword');
$client = new SoapClient($url);
$client->__setSoapHeaders([$wsse_header]);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
}
catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
my $soap = SOAP::Lite
->readable(1) # nice for debugging
->autotype(0)
# Extract the targetNamespace from the .wsdl definitions for the desired method
->default_ns( 'http://www.pdc4u.com/authsig/message/pdc_v1/smr' )
->proxy( 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/signaturemodificationservices/signaturemodificationservice.wsdl' );
my $username = 'SomeSecretUsername';
my $password = 'SomeSecretPassword';
my $security = SOAP::Header->name("wsse:Security")->attr({
'xmlns:wsse' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'
});
my $userToken =SOAP::Header->name("wsse:UsernameToken" =>
\SOAP::Header->value(
SOAP::Header->name('wsse:Username')->value($username)->type(''),
SOAP::Header->name('wsse:Password')->value($password)->type('')->attr(
{'Type'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText'}))
)->attr({'xmlns:wsu'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'});
my %params = (
'TransId' => 'X',
'UserId' => 'usernameOfPersonClosingThis',
'Command' => 'CLOSE',
'Version' => '1.6'
);
my @data;
foreach my $key ( keys %params ) {
push @data, SOAP::Data->name( $key => $params{$key} );
}
print $soap->call( 'SignatureModificationRequest', $security->value(\$userToken), @data )->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/signaturemodificationservices/signaturemodificationservice.wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
params = {
'TransId' => 'X',
'UserId' => 'usernameOfPersonClosingThis',
'Command' => 'CLOSE',
'Version' => '1.6'
}
response = client.call(:signature_modification, message: params) do |locals|
locals.wsse_auth "SomeSecretUsername", "SomeSecretPassword"
end
puts response
rescue
puts "Caught: #$!\n"
end
The URL to use for a signature modification request is:
test wsdl:
https://wssignaturedemo.pdc4u.com/AuthSignatureService/ws/signaturemodificationservices/signaturemodificationservice.wsdl
live wsdl:
https://wssignature.pdc4u.com/AuthSignatureService/ws/signaturemodificationservices/signaturemodificationservice.wsdl
The namespace to use is:
http://www.pdc4u.com/authsig/message/pdc_v1/smr
The method to use is:
SignatureModification
Credit Card API
The credit card API allows you to easily process credit cards, tokenize a card number for future use, and run payments exclusively from a tokenized card.
API Request
userInfo
The following table describes the individual elements of the userInfo object.
| Attribute | Description |
|---|---|
|
customerID
Numeric4
Required
|
A four digit customer ID that together with the securityKey uniquely identifies the customer processing credit cards.
|
|
securityKey
Alphanumeric128
Required
|
A password that together with the customerId uniquely identifies the customer processing credit cards.
|
|
accountSet
Numeric4
Required
|
Code to determine what account to deposit funds.
Format: Always 4 digits (0001, 0012, 0104, etc)
|
|
testMode
Deprecated
|
This element is deprecated. Do not include in request. |
|
userName
Alphanumeric75
|
The user who submitted the transaction. |
creditCard
The following table describes the individual elements of the creditCard object.
| Attribute | Description |
|---|---|
|
cardHolderFirstName
Alpha45
Required
|
First name of card holder. |
|
cardHolderLastName
Alpha45
Required
|
Last name of card holder. |
|
cardHolderStreetAddress1
Alphanumeric80
|
Card holder street address line 1. |
|
cardHolderStreetAddress2
Alphanumeric45
|
Card holder street address line 2. |
|
cardHolderCity
Alphanumeric45
|
Card holder city. |
|
cardHolderState
Alpha2
|
Card holder state.
Format: two character abbreviation (UT, CA, MI, etc)
|
|
cardHolderZipCode
Alpha10
|
Card holder zip code. |
|
cardHolderCountry
Deprecated
|
This element is deprecated. Do not include in request. |
|
cardHolderEmailAddress
Alphanumeric75
|
Email address where a receipt will be sent at the completion of the transaction. |
|
cardHolderPhoneNumber
Alphanumeric12
|
Card holder telephone number.
Format: XXX-XXX-XXXX
|
|
cardHolderPhoneNumberType
Deprecated
|
This element is deprecated. Do not include in request. |
|
accountReference
Alphanumeric45
Required
|
Reference/ID value. This is often the customer account number from your system. |
|
memoInformation
Alphanumeric50
|
Memo information for the explanation of the transaction. |
|
cardMagStripeData
AlphanumericN/A
Conditional
|
Mag Stripe data read from card using a PDCFlow approved card scanner.
Constraint(s): Required when using scanner.
|
|
cardNumber
Alphanumeric16
Conditional
|
Credit card number.
Constraint(s): Required for all transactions, except for
CREDIT or VOID that were originally scanned through an approved PDCFlow scanner.
See Test Credit Cards in the Appendix for values and expected results. |
|
cardExpirationMonth
Numeric2
Conditional
|
Credit expiration month.
Format: 2 digit month, such as 01, 08, 12, etc.
Constraint(s): Required for all transactions, except for
CREDIT or VOID that were originally scanned through an approved PDCFlow scanner.
|
|
cardExpirationYear
Numeric2
Conditional
|
Card expiration year.
Format: 2 digit year, such as 17.
Constraint(s): Required for all transactions, except for
CREDIT or VOID that were originally scanned through an approved PDCFlow scanner.
|
|
cardCvv2
Numeric4
|
Card CVV2 number. This will be 3 digits for Visa, MasterCard, and Discover, and 4 digits for American Express cards. |
|
chargeAmount
Numeric11
Conditional
|
The net dollar amount paid by the payer.
Format: XXXX.XX
Do not use any formatting symbols such as currency symbols ($), commas etc.
Constraint(s): Required for all transactions, except when storing a card using the
storeCard method.
|
|
convenienceFee
Numeric11
Conditional
|
Transaction fee amount. Fee amount to be added to the charge amount. If no fee is to be added to this transaction a value of zero (0) still needs to be provided.
Format: XXXX.XX
Do not use any formatting symbols such as currency symbols ($), commas etc.
Constraint(s): Required for all transactions, except when storing a card using the storeCard method.
|
|
currencyType
Alpha3
Required
|
As an integrator, this must be set to EXT.
Valid value(s):
EXT |
|
processingCommand
Alpha6
Required
|
Indicates how the card is to be processed.
Valid value(s):
SALE, VOID, CREDIT |
|
secondaryTrace
Alphanumeric50
|
Location information about a company. |
|
originalOrderNumber
Numeric20
Conditional
|
When issuing a CREDIT or VOID, the original order number should be provided here.
Constraint(s): Required with
processingCommand of CREDIT or VOID.
|
|
originalAmount
Deprecated
|
This element is deprecated. Do not include in request. |
vaultInfo
The following table describes the individual elements of the vaultInfo object.
| Attribute | Description |
|---|---|
|
vaultKey
Alphanumeric20
Conditional
|
The token for a card. This token should have been previously stored. Passing in this token will only automatically populate the card number and the card expiration date for processing.
Constraint(s): Required when using the
processStoredCreditCardTransaction method.
|
API Result
-- Sample success XML --
<return>
<processingResult><processing-results><result>OK</result></processing-results></processingResult>
<gatewayResponseData><![CDATA[<?xml version="1.0" ?><com.pdc4u.webservices.gps.TransactionResponse><requestResultStatus>APPROVED</requestResultStatus><cardTransactionResult><transactionId>23608</transactionId><cardToken>removedFromSample</cardToken><authorizationCode>095242</authorizationCode><cvv2ResultCode>M</cvv2ResultCode><roundTripNVPS></roundTripNVPS></cardTransactionResult><checkTransactionResult></checkTransactionResult><checkStatusUpdateResult><newStatus></newStatus><transactionId></transactionId><roundTripNVPS></roundTripNVPS></checkStatusUpdateResult><requestErrors><requestError></requestError></requestErrors></com.pdc4u.webservices.gps.TransactionResponse>]]></gatewayResponseData>
<orderNumber>23608</orderNumber>
<authorizationCode>095242</authorizationCode>
<softwareVersion/>
<state>OK</state>
</return>
-- Sample error XML --
<return>
<processingResult><![CDATA[<processing-results><result>Error</result><error>Field Card Expiration Year is required.</error><error>Field Card Expiration Month is required.</error></processing-results>]]></processingResult>
<gatewayResponseData><![CDATA[<?xml version="1.0" ?><com.pdc4u.webservices.gps.TransactionResponse><requestResultStatus>ERROR</requestResultStatus><cardTransactionResult><transactionId></transactionId><authorizationCode></authorizationCode><cvv2ResultCode></cvv2ResultCode><roundTripNVPS></roundTripNVPS></cardTransactionResult><checkTransactionResult><roundTripNVPS></roundTripNVPS></checkTransactionResult><checkStatusUpdateResult><newStatus></newStatus><transactionId></transactionId><roundTripNVPS></roundTripNVPS></checkStatusUpdateResult><requestErrors><requestError><com.pdc4u.webservices.gps.RequestError><code>10001</code><description>Field Card Expiration Year is required.</description></com.pdc4u.webservices.gps.RequestError><com.pdc4u.webservices.gps.RequestError><code>10001</code><description>Field Card Expiration Month is required.</description></com.pdc4u.webservices.gps.RequestError></requestError></requestErrors></com.pdc4u.webservices.gps.TransactionResponse>]]></gatewayResponseData>
<orderNumber/>
<authorizationCode/>
<softwareVersion/>
<state>ERROR</state>
<transactionProcessingMessages>
<message>Field Card Expiration Year is required.</message>
<xmlTag>error</xmlTag>
</transactionProcessingMessages>
<transactionProcessingMessages>
<message>Field Card Expiration Month is required.</message>
<xmlTag>error</xmlTag>
</transactionProcessingMessages>
</return>
The following table describes the individual elements in a response. Sample success and failure examples are listed to the right.
| Attribute | Description |
|---|---|
|
processingResult
XMLN/A
|
Result of the transaction. |
|
gatewayResponseData
XMLN/A
|
Similar to processingResult, but contains additional information, such as a card token, cvv2 result, and customizable round-trip name/value pairs.
|
|
orderNumber
Numeric20
|
Order/Confirmation number of transaction. Returned in conjunction with authorizationCode when a transaction is successfully processed through the gateway.
|
|
authorizationCode
Alphanumeric75
|
Returned in conjunction with orderNumber when a transaction is successfully processed through the gateway. This value will be blank when issuing a VOID.
|
|
softwareVersion
Alphanumeric20
|
The version number of the the CreditCard SOAP Service. |
|
state
Alpha10
|
The result of a request. A successful request will have a state of OK. Attribute not present when using storeCard.
|
|
transactionProcessingMessages
XMLN/A
|
Error messages from a request. This attribute will not be present on a successful request, but can exist one or more times with an error. See example to the right for structure of attribute. |
API Fault
Generally, the only time a fault should be thrown is if you can’t connect to our system, or if the soap package is malformed. Verify you can access our WSDL and that all required elements listed above are present in your request.
Credit Card Vault
PDCFlow also offers a Credit Card Vault for even more secure credit card processing, particularly in the event of a recurring payment or other multiple transactions. The Vault is fully PCI-DSS compliant and allows you to process transactions without the risk of passing actual credit card information in a live environment. There are two distinct web services in the package. The first is to set up the key that will apply to the credit card number and then a second service to process a transaction based on the key.
The WSDL for the Vault and the Credit Card Processing are nearly identical. It will require the same core input as listed in the previous chart for the Credit Card transaction WSDL. The primary difference is that you will “Store” the card number in the Vault and the Vault will do any future processing of that card. When you store the card in the Vault, it will return a “cardStorageResult” as opposed to a card processing result. This element will also return a unique “authorizationKey”. You will need to save and store this key. When you wish to process a charge to the credit card, you will use the Key as a reference for the card number that is inside the Vault.
A stored card transaction uses the same basic information as for a normal credit card transaction. For the new charge, you will need to send the new transaction information that includes the processingCommand and the chargeAmount/convenienceFee.
Sample Code
This section offers some client implementation examples in different languages. Keep in mind, these are only minimalistic examples used to demonstrate the Credit Card Services API and are not meant for production use.
Process a basic credit card transaction
<?php
// Get customer-specific information
$userInformation = [
'accountSet' => '0001',
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'userName' => 'frontenduser@pdc4u.com'
];
// Payment-specific information
$creditCardInformation = [
'cardHolderFirstName' => 'Adam',
'cardHolderLastName' => 'Test',
'cardHolderStreetAddress1' => '1234 Main St.',
'cardHolderStreetAddress2' => 'Apt. 7B',
'cardHolderCity' => 'Ogden',
'cardHolderState' => 'UT',
'cardHolderZipCode' => '84404',
'cardHolderEmailAddress' => 'adamemail@pdc4u.com',
'cardHolderPhoneNumber' => '777-777-7777',
'accountReference' => 'AB1234',
'memoInformation' => 'December payment',
'cardMagStripeData' => '',
'cardNumber' => '4000100011112224',
'cardExpirationMonth' => '09',
'cardExpirationYear'=> '22',
'cardCvv2' => '123',
'chargeAmount' => '5.00',
'convenienceFee' => '0.50',
'currencyType' => 'EXT',
'processingCommand' => 'SALE',
'secondaryTrace' => '',
'originalOrderNumber' => ''
];
$url = 'https://cclegacydemo.pdc4u.com/CreditCardServices/CreditCardTransactionProcessor?wsdl';
$namespace = 'http://transaction.webservices.pdc4u.com';
$method = 'processCreditCardTransaction';
$params = [
'creditCard' => $creditCardInformation,
'userInfo'=> $userInformation
];
$client = new SoapClient($url);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
}
catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
my $soap = SOAP::Lite
->readable(1)
->autotype(0)
->ns( 'http://transaction.webservices.pdc4u.com/', "ns1" )
->proxy( 'https://cclegacydemo.pdc4u.com/CreditCardServices/CreditCardTransactionProcessor?wsdl' );
my %userInformation = (
'pdcAccountSet' => '01',
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'userName' => 'frontenduser@pdc4u.com'
);
# Payment-specific information
my %creditCardInformation = (
'cardHolderFirstName' => 'Adam',
'cardHolderLastName' => 'Test',
'cardHolderStreetAddress1' => '1234 Main St.',
'cardHolderStreetAddress2' => 'Apt. 7B',
'cardHolderCity' => 'Ogden',
'cardHolderState' => 'UT',
'cardHolderZipCode' => '84404',
'cardHolderEmailAddress' => 'adamemail@pdc4u.com',
'cardHolderPhoneNumber' => '777-777-7777',
'accountReference' => 'AB1234',
'memoInformation' => 'December payment',
'cardMagStripeData' => '',
'cardNumber' => '4000100011112224',
'cardExpirationMonth' => '09',
'cardExpirationYear'=> '22',
'cardCvv2' => '123',
'chargeAmount' => '5.00',
'convenienceFee' => '0.50',
'currencyType' => 'EXT',
'processingCommand' => 'SALE',
'secondaryTrace' => '',
'originalOrderNumber' => ''
);
print $soap->call( 'processCreditCardTransaction',
SOAP::Data->name('creditCard' => \%creditCardInformation),
SOAP::Data->name('userInfo' => \%userInformation)
)->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://cclegacydemo.pdc4u.com/CreditCardServices/CreditCardTransactionProcessor?wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
# Get customer-specific information
userInformation = {
'accountSet' => '0001',
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'userName' => 'frontenduser@pdc4u.com'
}
# Payment-specific information
creditCardInformation = {
'cardHolderFirstName' => 'Adam',
'cardHolderLastName' => 'Test',
'cardHolderStreetAddress1' => '1234 Main St.',
'cardHolderStreetAddress2' => 'Apt. 7B',
'cardHolderCity' => 'Ogden',
'cardHolderState' => 'UT',
'cardHolderZipCode' => '84404',
'cardHolderEmailAddress' => 'adamemail@pdc4u.com',
'cardHolderPhoneNumber' => '777-777-7777',
'accountReference' => 'AB1234',
'memoInformation' => 'December payment',
'cardMagStripeData' => '',
'cardNumber' => '4000100011112224',
'cardExpirationMonth' => '09',
'cardExpirationYear'=> '22',
'cardCvv2' => '123',
'chargeAmount' => '5.00',
'convenienceFee' => '0.50',
'currencyType' => 'EXT',
'processingCommand' => 'SALE',
'secondaryTrace' => '',
'originalOrderNumber' => ''
}
params = {
'creditCard' => creditCardInformation,
'userInfo'=> userInformation
}
response = client.call(:process_credit_card_transaction, message: params)
puts response
rescue
puts "Caught: #$!\n"
end
General transactions will use this method. It will simply accept credit card details, and process the card.
The URL to process a credit card is:
test wsdl:
https://cclegacydemo.pdc4u.com/CreditCardServices/CreditCardTransactionProcessor?wsdl
live wsdl:
https://cclegacy.pdc4u.com/CreditCardServices/CreditCardTransactionProcessor?wsdl
The namespace to use is:
http://transaction.webservices.pdc4u.com
The method to use is:
processCreditCardTransaction
Store a credit card in the vault
<?php
// Get customer-specific information
$userInformation = [
'accountSet' => '0001',
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'userName' => 'frontenduser@pdc4u.com'
];
// Payment-specific information
$creditCardInformation= [
'cardHolderFirstName' => 'Adam',
'cardHolderLastName' => 'Test',
'cardHolderStreetAddress1' => '1234 Main St.',
'cardHolderStreetAddress2' => 'Apt. 7B',
'cardHolderCity' => 'Ogden',
'cardHolderState' => 'UT',
'cardHolderZipCode' => '84404',
'cardHolderEmailAddress' => 'adamemail@pdc4u.com',
'cardHolderPhoneNumber' => '777-777-7777',
'accountReference' => 'AB1234',
'memoInformation' => 'December payment',
'cardMagStripeData' => '',
'cardNumber' => '4000100011112224',
'cardExpirationMonth' => '09',
'cardExpirationYear'=> '22',
'cardCvv2' => '',
'chargeAmount' => '',
'convenienceFee' => '',
'currencyType' => 'EXT',
'processingCommand' => 'SALE',
'secondaryTrace' => '',
'originalOrderNumber' => ''
];
$url = 'https://cclegacydemo.pdc4u.com/CreditCardServices/CardVault?wsdl';
$namespace = 'http://transaction.webservices.pdc4u.com';
$method = 'storeCard';
$params = [
'creditCard' => $creditCardInformation,
'userInfo'=> $userInformation
];
$client = new SoapClient($url);
try {
$response = $client->__soapCall(
$method,
[$parms, $namespace]
);
print_r($response);
}
catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
my $soap = SOAP::Lite
->readable(1)
->autotype(0)
->ns( 'http://transaction.webservices.pdc4u.com/', "ns1" )
->proxy( 'https://cclegacydemo.pdc4u.com/CreditCardServices/CardVault?wsdl' );
my %userInformation = (
'pdcAccountSet' => '01',
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'userName' => 'frontenduser@pdc4u.com'
);
# Payment-specific information
my %creditCardInformation = (
'cardHolderFirstName' => 'Adam',
'cardHolderLastName' => 'Test',
'cardHolderStreetAddress1' => '1234 Main St.',
'cardHolderStreetAddress2' => 'Apt. 7B',
'cardHolderCity' => 'Ogden',
'cardHolderState' => 'UT',
'cardHolderZipCode' => '84404',
'cardHolderEmailAddress' => 'adamemail@pdc4u.com',
'cardHolderPhoneNumber' => '777-777-7777',
'accountReference' => 'AB1234',
'memoInformation' => 'December payment',
'cardMagStripeData' => '',
'cardNumber' => '4000100011112224',
'cardExpirationMonth' => '09',
'cardExpirationYear'=> '22',
'cardCvv2' => '123',
'chargeAmount' => '',
'convenienceFee' => '',
'currencyType' => 'EXT',
'processingCommand' => 'SALE',
'secondaryTrace' => '',
'originalOrderNumber' => ''
);
print $soap->call( 'storeCard',
SOAP::Data->name('creditCard' => \%creditCardInformation),
SOAP::Data->name('userInfo' => \%userInformation)
)->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://cclegacydemo.pdc4u.com/CreditCardServices/CardVault?wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
# Get customer-specific information
userInformation = {
'accountSet' => '0001',
#'customerID' => '0000',
#'securityKey' => 'SomeSecurityKey',
'customerID' => '6299',
'securityKey' => '31819d62fe0161d307defb1737b74ba4',
'userName' => 'frontenduser@pdc4u.com'
}
# Payment-specific information
creditCardInformation= {
'cardHolderFirstName' => 'Adam',
'cardHolderLastName' => 'Test',
'cardHolderStreetAddress1' => '1234 Main St.',
'cardHolderStreetAddress2' => 'Apt. 7B',
'cardHolderCity' => 'Ogden',
'cardHolderState' => 'UT',
'cardHolderZipCode' => '84404',
'cardHolderEmailAddress' => 'adamemail@pdc4u.com',
'cardHolderPhoneNumber' => '777-777-7777',
'accountReference' => 'AB1234',
'memoInformation' => 'December payment',
'cardMagStripeData' => '',
'cardNumber' => '4000100011112224',
'cardExpirationMonth' => '09',
'cardExpirationYear'=> '22',
'cardCvv2' => '',
'chargeAmount' => '',
'convenienceFee' => '',
'currencyType' => 'EXT',
'processingCommand' => 'SALE',
'secondaryTrace' => '',
'originalOrderNumber' => ''
}
params = {
'creditCard' => creditCardInformation,
'userInfo'=> userInformation
}
response = client.call(:store_card, message: params)
puts response
rescue
puts "Caught: #$!\n"
end
Tokenize card details (card number, card expiration month, card expiration year) to be used later, generally in conjunction with the next code sample, the processStoredCreditCardTransaction method. This will only store a card, it will not process a transaction. Transaction details are generally not required at this point, as you are only storing card information. The cvv2 is also not necessary, as this piece of data can not be stored.
The URL to test the vault storage service is:
test wsdl:
https://cclegacydemo.pdc4u.com/CreditCardServices/CardVault?wsdl
live wsdl:
https://cclegacy.pdc4u.com/CreditCardServices/CardVault?wsdl
The namespace to use is:
http://transaction.webservices.pdc4u.com
The method to use is:
storeCard
Process a credit card transaction from the vault
<?php
// Get customer-specific information
$userInformation = [
'accountSet' => '0001',
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'userName' => 'frontenduser@pdc4u.com'
];
// Payment-specific information
$creditCardInformation = [
'cardHolderFirstName' => 'Adam',
'cardHolderLastName' => 'Test',
'cardHolderStreetAddress1' => '1234 Main St.',
'cardHolderStreetAddress2' => 'Apt. 7B',
'cardHolderCity' => 'Ogden',
'cardHolderState' => 'UT',
'cardHolderZipCode' => '84404',
'cardHolderEmailAddress' => 'adamemail@pdc4u.com',
'cardHolderPhoneNumber' => '777-777-7777',
'accountReference' => 'AB1234',
'memoInformation' => 'December payment',
'cardMagStripeData' => '',
'cardNumber' => '',
'cardExpirationMonth' => '',
'cardExpirationYear'=> '',
'cardCvv2' => '',
'chargeAmount' => '5.00',
'convenienceFee' => '0.50',
'currencyType' => 'EXT',
'processingCommand' => 'SALE',
'secondaryTrace' => '',
'originalOrderNumber' => ''
];
//Tokenized card from vault to use
$vaultInformation = [
'vaultKey' => 'abc123'
];
$url = 'https://cclegacydemo.pdc4u.com/CreditCardServices/StoredCreditCardTransactionProcessor?wsdl';
$namespace = 'http://transaction.webservices.pdc4u.com';
$method = 'processStoredCreditCardTransaction';
$params = [
'creditCard' => $creditCardInformation,
'userInfo'=> $userInformation,
'vaultInfo' => $vaultInformation
];
$client = new SoapClient($url);
try {
$response = $client->__soapCall(
$method,
[$parms, $namespace]
);
print_r($response);
}
catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
my $soap = SOAP::Lite
->readable(1)
->autotype(0)
->ns( 'http://transaction.webservices.pdc4u.com/', "ns1" )
->proxy( 'https://cclegacydemo.pdc4u.com/CreditCardServices/StoredCreditCardTransactionProcessor?wsdl' );
my %userInformation = (
'pdcAccountSet' => '01',
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'userName' => 'frontenduser@pdc4u.com'
);
# Payment-specific information
my %creditCardInformation = (
'cardHolderFirstName' => 'Adam',
'cardHolderLastName' => 'Test',
'cardHolderStreetAddress1' => '1234 Main St.',
'cardHolderStreetAddress2' => 'Apt. 7B',
'cardHolderCity' => 'Ogden',
'cardHolderState' => 'UT',
'cardHolderZipCode' => '84404',
'cardHolderEmailAddress' => 'adamemail@pdc4u.com',
'cardHolderPhoneNumber' => '777-777-7777',
'accountReference' => 'AB1234',
'memoInformation' => 'December payment',
'cardMagStripeData' => '',
'cardNumber' => '',
'cardExpirationMonth' => '',
'cardExpirationYear'=> '',
'cardCvv2' => '',
'chargeAmount' => '5.00',
'convenienceFee' => '0.50',
'currencyType' => 'EXT',
'processingCommand' => 'SALE',
'secondaryTrace' => '',
'originalOrderNumber' => ''
);
# Tokenized card from vault to use
my %vaultInformation = (
'vaultKey' => 'abc123'
);
print $soap->call( 'processStoredCreditCardTransaction',
SOAP::Data->name('creditCard' => \%creditCardInformation),
SOAP::Data->name('userInfo' => \%userInformation),
SOAP::Data->name('vaultInfo' => \%vaultInformation)
)->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://cclegacydemo.pdc4u.com/CreditCardServices/StoredCreditCardTransactionProcessor?wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
# Get customer-specific information
userInformation = {
'accountSet' => '0001',
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'userName' => 'frontenduser@pdc4u.com'
};
# Payment-specific information
creditCardInformation = {
'cardHolderFirstName' => 'Adam',
'cardHolderLastName' => 'Test',
'cardHolderStreetAddress1' => '1234 Main St.',
'cardHolderStreetAddress2' => 'Apt. 7B',
'cardHolderCity' => 'Ogden',
'cardHolderState' => 'UT',
'cardHolderZipCode' => '84404',
'cardHolderEmailAddress' => 'adamemail@pdc4u.com',
'cardHolderPhoneNumber' => '777-777-7777',
'accountReference' => 'AB1234',
'memoInformation' => 'December payment',
'cardMagStripeData' => '',
'cardNumber' => '',
'cardExpirationMonth' => '',
'cardExpirationYear'=> '',
'cardCvv2' => '',
'chargeAmount' => '5.00',
'convenienceFee' => '0.50',
'currencyType' => 'EXT',
'processingCommand' => 'SALE',
'secondaryTrace' => '',
'originalOrderNumber' => ''
}
# Tokenized card from vault to use
vaultInformation = {
'vaultKey' => 'abc123'
}
params = {
'creditCard' => creditCardInformation,
'userInfo'=> userInformation,
'vaultInfo' => vaultInformation
}
response = client.call(:process_stored_credit_card_transaction, message: params)
puts response
rescue
puts "Caught: #$!\n"
end
A vault key should have been stored previously. Generally, you would use the previous code example to generate the vault key (storeCard method). Using that key, you can now process a card without having to resubmit the card information. A tokenized card will only auto-populate the card number and the card expiration date. No other previous transaction information will be used in this transaction.
The URL for testing the processing on a card that is already in the vault is:
test wsdl:
https://cclegacydemo.pdc4u.com/CreditCardServices/StoredCreditCardTransactionProcessor?wsdl
live wsdl:
https://cclegacy.pdc4u.com/CreditCardServices/StoredCreditCardTransactionProcessor?wsdl
The namespace to use is:
http://transaction.webservices.pdc4u.com
The method to use is:
processStoredCreditCardTransaction
ECheck API
This document describes the different objects and methods required to use the PDCFlow ECheckServices SOAP services.
The PDCFlow ECheck API consists of a few web services:
- Transaction Processing - Submit an ACH transaction to the PDCFlow ACH system.
- Transaction Inquiry - Retrieve the status details of a transaction you have previously submitted.
- Transaction Status Inquiry - Retrieve a list of all status changes for all transactions since your last request.
- Transaction Updating - Update the status of a previously submitted transaction. Currently, the only allowed method is to void a transaction. This will keep the transaction from being sent into the ACH network.
- ACH Recurring - This service is deprecated. Do not use it.
Transaction Processing
Submit an ACH transaction to the PDCFlow ACH system. A transaction can be processed one at a time, or in a batch mode. The objects required are the same. See the sample code below for how to send one transaction vs multiple transactions.
API Processing Request
userInfo
The following table describes the individual elements of the userInfo object.
| Attribute | Description |
|---|---|
|
customerID
Numeric4
Required
|
A four digit customer ID that together with the securityKey uniquely identifies the customer processing ACH transactions.
|
|
securityKey
Alphanumeric128
Required
|
A password that together with the customerID uniquely identifies the customer processing ACH transactions.
|
|
pdcAccountSet
Numeric2
Required
|
Code to determine what account to deposit funds.
Format: 01, 02, 10, etc.
|
|
userName
Alphanumeric50
|
The user who submitted the transaction. |
|
groupID
Deprecated
|
This element is deprecated. Do not include in request. |
|
interLevelBillingCode
Deprecated
|
This element is deprecated. Do not include in request. |
API Processing Request
achTransaction
The following table describes the individual elements of the achTransaction object.
| Attribute | Description |
|---|---|
|
payorFirstName
Alpha45
Required
|
Payor first name. |
|
payorLastName
Alpha45
Required
|
Payor last name. |
|
payorStreetAddress1
Alphanumeric45
|
The first line of the street/mailing address of the payor. |
|
payorStreetAddress2
Alphanumeric45
|
The second line of the street/mailing address of the payor. |
|
payorCity
Alpha45
|
Payor city. |
|
payorState
Alphanumeric2
|
Payor state.
Format: two character abbreviation (UT, CA, MI, etc)
|
|
payorZip
Numeric10
|
Payor zip code. |
|
transactionEmailAddress
Alphanumeric75
|
Email address where a receipt will be sent at the completion of the transaction. |
|
payorPhoneNumber
Numeric15
|
Payor telephone number.
Format: XXX-XXX-XXXX
|
|
payorPhoneNumberType
Deprecated
|
This element is deprecated. Do not include in request. |
|
payorAccountReference
Numeric20
Required
|
Reference/ID value. This is often the customer account number from your system. |
|
payorMemoInformation
Alphanumeric50
|
Memo information for the explanation of the transaction. |
|
payorBankRoutingNumber
Numeric9
Required
|
Payor bank routing number. |
|
payorBankAccountNumber
Numeric20
Required
|
Payor bank account number. |
|
payorCheckNumber
Numeric10
|
Check number to appear on any printed check representing this transaction. |
|
payorAccountType
Alpha1
Required
|
Account type of the payor, Checking or Savings.
Valid value(s):
C, S |
|
chargeAmount
Numeric11
Required
|
The net dollar amount paid by the payor.
Format: XXXX.XX
Do not use any formatting symbols such as currency symbols ($), commas etc. |
|
feeAmount
Numeric11
Required
|
Transaction fee amount. Fee amount to be added to the charge amount.
Format: XXXX.XX
Do not use any formatting symbols such as currency symbols ($), commas etc.
Constraint(s): If no fee is to be added to this transaction a value of zero “0” still needs to be submitted.
|
|
transactionOrigin
Alpha3
Required
|
The origin of the transaction.
Valid value(s):
EXT |
|
payorTransactionType
Alpha1
Required
|
Type of transaction, Debit or Credit.
Valid value(s):
D, C |
|
achEntryCode
Alpha3
Required
|
The NACHA/ACH SEC code for how payment authorization was received. Options and descriptions can be found in the appendix. |
|
processingDate
Date10
Required
|
This element represents the date the payment should be submitted to the ACH payment system.
Format: YYYY-MM-DD
|
|
secondaryTrace
Alphanumeric50
|
Location information about a company. |
API Processing Result
processACHTransactionResponse
The following table describes the individual elements of the processACHTransactionResponse object. This object represents the results of a processed transaction.
| Attribute | Description |
|---|---|
|
processingResult
Alpha5
|
The result of the transaction request.
Valid value(s):
OK - The transaction was processed successfully.ERROR - The transaction failed.
|
|
resultMessage
Alpha256
|
Detailed explanation of the result of the processed transaction. If processingResult was ERROR this field will provide details about why the transaction processing failed.
|
|
transactionID
Numeric20
|
Order/Confirmation number to transaction. This is used as a reference to a particular transaction after submission to the PDCFlow system. |
|
achTransaction
ObjectN/A
|
The transaction details that were contained in your original request. |
API Processing Fault
Generally, the only time a fault should be thrown is if you can’t connect to our system, or if the soap package is malformed. Verify you can access our wsdl and that all required elements listed above are present in your request.
Transaction Inquiry
Retrieve the status details of a transaction you have previously submitted.
API Inquiry Request
echeckInquiryData
The following table describes the individual elements of the echeckInquiryData object.
| Attribute | Description |
|---|---|
|
customerID
Numeric4
Required
|
A four digit customer ID that together with the securityKey uniquely identifies the customer requesting ACH transaction information.
|
|
securityKey
Alphanumeric128
Required
|
A password that together with the customerID uniquely identifies the customer requesting ACH transaction information.
|
|
primaryTrace
Numeric20
Required
|
Order/Confirmation number of the transaction being inquired upon. If following up on a transaction submitted using the standard transaction processing, this would be the transactionID.
|
API Inquiry Result
getECheckDataResponse
The following table describes the individual elements of the getECheckDataResponse object. An ACH transaction can have more than one status message at a time, so these values can have more than one instance in a response.
| Attribute | Description |
|---|---|
|
status
Alpha12
|
Current state of check in the ACH payment cycle.
Valid value(s):
WAITING - transaction will be included in next batchSUBMITTED - transaction has been submitted for processingACKNOWLEDGED - transaction has been accepted for processingFUNDED - money has been deposited into your accountDEDUCTION - money has been taken from your accountVOID - transaction was cancelled prior to submission for processingRETURNED - an exception occurred while processing transactionCORRECTION - transaction was automatically corrected during processingERROR - an unknown error occurred while processing transaction
|
|
statusDate
DateTime21
|
The date and time the check was submitted to PDCFlow.
Format: YYYY-MM-DD HH:mm:SS.S
|
|
statusDescription
Alpha256
|
Extended description of the status |
|
secondaryTrace
Alphanumeric32
|
Location information about a company. |
API Inquiry Fault
Generally, the only time a fault should be thrown is if you can’t connect to our system, or if the soap package is malformed. Verify you can access our wsdl and that all required elements listed above are present in your request.
Transaction Status Inquiry
Retrieve a list of all status changes for all transactions since your last request.
API Update Inquiry Request
getECheckDataUpdates
The following table describes the individual elements of the getECheckDataUpdates object.
| Attribute | Description |
|---|---|
|
customerID
Numeric4
Required
|
A four digit customer ID that together with the securityKey uniquely identifies the customer requesting ACH status information.
|
|
securityKey
Alphanumeric128
Required
|
A password that together with the customerID uniquely identifies the customer requesting ACH status information.
|
API Update Inquiry Result
getECheckDataUpdatesResponse
The following table describes the individual elements of the getECheckDataUpdatesResponse object.
| Attribute | Description |
|---|---|
|
id
Numeric20
|
The transactionID
|
|
status
Alpha12
|
Current state of check in the ACH payment cycle.
Valid value(s):
WAITING - transaction will be included in next batchSUBMITTED - transaction has been submitted for processingACKNOWLEDGED - transaction has been accepted for processingFUNDED - money has been deposited into your accountDEDUCTION - money has been taken from your accountVOID - transaction was cancelled prior to submission for processingRETURNED - an exception occurred while processing transactionCORRECTION - transaction was automatically corrected during processingERROR - an unknown error occurred while processing transaction
|
|
statusDate
DateTime21
|
The date and time the check was submitted to PDCFlow.
Format: YYYY-MM-DD HH:mm:SS.SM
|
|
statusDescription
Alpha256
|
Extended description of the status |
|
secondaryTrace
Alphanumeric32
|
Location information about a company. |
API Update Inquiry Fault
Generally, the only time a fault should be thrown is if you can’t connect to our system, or if the soap package is malformed. Verify you can access our wsdl and that all required elements listed above are present in your request.
Transaction Updating
Update the status of a previously submitted transaction. Currently, the only allowed method is to void a transaction. This will keep the transaction from being sent into the ACH network.
API Updating Request
eCheckUpdateData
The following table describes the individual elements of the eCheckUpdateData object.
| Attribute | Description |
|---|---|
|
customerID
Numeric4
Required
|
A four digit customer ID that together with the securityKey uniquely identifies the customer requesting the update.
|
|
securityKey
Alphanumeric128
Required
|
A password that together with the customerID uniquely identifies the customer requesting the update.
|
|
primaryTrace
Numeric20
Required
|
Order/Confirmation number of the transaction being inquired upon. If following up on a transaction submitted using the standard transaction processing, this would be the transactionID.
|
|
newStatus
Alpha4
Required
|
New status to assign to the transaction.
Valid value(s):
VOID |
API Updating Result
updateStatusResponse
The following table describes the individual elements of the updateStatusResponse object.
| Attribute | Description |
|---|---|
|
status
Alpha5
|
The status of the transaction.
Valid value(s):
OK - The transaction was processed successfully.ERROR - The transaction failed.
|
|
resultMessage
Alpha256
|
Result of attempted update. |
API Updating Fault
Generally, the only time a fault should be thrown is if you can’t connect to our system, or if the soap package is malformed. Verify you can access our wsdl and that all required elements listed above are present in your request. Common pieces to watch for are an incorrect namespace, missing one of the required 4 elements, or an element that is missing a value.
Sample Code
This section offers some client implementation examples in different languages. Keep in mind, these are only minimalistic examples used to demonstrate the Credit Card Services API and are not meant for production use.
processACHTransaction - Transaction Processing - individual transaction
<?php
// Get customer-specific information
$userInformation = [
'pdcAccountSet' => '01',
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'userName' => 'frontenduser@pdc4u.com'
];
// Payment-specific information
$achInformation = [
'payorFirstName' => 'Adam',
'payorLastName' => 'Test',
'payorStreetAddress1' => '1234 Main St.',
'payorStreetAddress2' => 'Apt. 7B',
'payorCity' => 'Ogden',
'payorState' => 'UT',
'payorZip' => '84404',
'transactionEmailAddress' => 'adamemail@pdc4u.com',
'payorPhoneNumber' => '777-777-7777',
'payorAccountReference' => 'AB1234',
'payorMemoInformation' => 'December payment',
'payorBankRoutingNumber' => '124001545',
'payorBankAccountNumber' => '123456',
'payorCheckNumber' => '9999',
'payorAccountType' => 'C',
'chargeAmount' => '5.00',
'feeAmount' => '0.50',
'transactionOrigin' => 'EXT',
'payorTransactionType' => 'D',
'achEntryCode' => 'WEB',
'processingDate' => '2017-05-31',
'secondaryTrace' => ''
];
$url = 'https://achlegacydemo.pdc4u.com/ECheckServices/ACHTransactionProcessor?wsdl';
$namespace = 'http://transaction.webservices.pdc4u.com';
$method = 'processACHTransaction';
$params = [
'achTransaction' => $achInformation,
'userInfo'=> $userInformation
];
$client = new SoapClient($url);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
} catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
my $soap = SOAP::Lite
->readable(1)
->autotype(0)
->ns( 'http://transaction.webservices.pdc4u.com/', "ns1" )
->proxy( 'https://achlegacydemo.pdc4u.com/ECheckServices/ACHTransactionProcessor?wsdl' );
my %userInformation = (
'pdcAccountSet' => '01',
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'userName' => 'frontenduser@pdc4u.com'
);
# Payment-specific information
my %achInformation = (
'payorFirstName' => 'Adam',
'payorLastName' => 'Test',
'payorStreetAddress1' => '1234 Main St.',
'payorStreetAddress2' => 'Apt. 7B',
'payorCity' => 'Ogden',
'payorState' => 'UT',
'payorZip' => '84404',
'transactionEmailAddress' => 'adamemail@pdc4u.com',
'payorPhoneNumber' => '777-777-7777',
'payorAccountReference' => 'AB1234',
'payorMemoInformation' => 'December payment',
'payorBankRoutingNumber' => '124001545',
'payorBankAccountNumber' => '123456',
'payorCheckNumber' => '9999',
'payorAccountType' => 'C',
'chargeAmount' => '5.00',
'feeAmount' => '0.50',
'transactionOrigin' => 'EXT',
'payorTransactionType' => 'D',
'achEntryCode' => 'WEB',
'processingDate' => '2017-05-31',
'secondaryTrace' => ''
);
my @transaction;
foreach my $key ( keys %achInformation ) {
push @transaction, SOAP::Data->name( $key => $achInformation{$key} );
}
# userInfo
my @userInfo;
foreach my $key ( keys %userInformation ) {
push @userInfo, SOAP::Data->name( $key => $userInformation{$key} );
}
print $soap->call( 'processACHTransaction',
SOAP::Data->name('achTransaction' => \SOAP::Data->value(@transaction)),
SOAP::Data->name('userInfo' => \SOAP::Data->value(@userInfo))
)->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://achlegacydemo.pdc4u.com/ECheckServices/ACHTransactionProcessor?wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
# Get customer-specific information
userInformation = {
'pdcAccountSet' => '01',
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'userName' => 'frontenduser@pdc4u.com'
}
# Payment-specific information
achInformation = {
'payorFirstName' => 'Adam',
'payorLastName' => 'Test',
'payorStreetAddress1' => '1234 Main St.',
'payorStreetAddress2' => 'Apt. 7B',
'payorCity' => 'Ogden',
'payorState' => 'UT',
'payorZip' => '84404',
'transactionEmailAddress' => 'adamemail@pdc4u.com',
'payorPhoneNumber' => '777-777-7777',
'payorAccountReference' => 'AB1234',
'payorMemoInformation' => 'December payment',
'payorBankRoutingNumber' => '124001545',
'payorBankAccountNumber' => '123456',
'payorCheckNumber' => '9999',
'payorAccountType' => 'C',
'chargeAmount' => '5.00',
'feeAmount' => '0.50',
'transactionOrigin' => 'EXT',
'payorTransactionType' => 'D',
'achEntryCode' => 'WEB',
'processingDate' => '2017-05-31',
'secondaryTrace' => ''
}
# Build the parameters
params = {
'achTransaction' => achInformation,
'userInfo' => userInformation
};
response = client.call(:process_ach_transaction, message: params)
puts response
rescue
puts "Caught: #$!\n"
end
General transactions will use this method. It will simply accept ach details, and process the transaction.
The URL to process a check is:
test wsdl:
https://achlegacydemo.pdc4u.com/ECheckServices/ACHTransactionProcessor?wsdl
live wsdl:
https://achlegacy.pdc4u.com/ECheckServices/ACHTransactionProcessor?wsdl
The namespace to use is:
http://transaction.webservices.pdc4u.com
The method to use is:
processACHTransaction
processACHTransactionBatch - Transaction Processing - batch of transactions
<?php
// Get customer-specific information
$userInformation = [
'pdcAccountSet' => '01',
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'userName' => 'frontenduser@pdc4u.com'
];
// Payment-specific information
$achInformation = [
'payorFirstName' => 'Adam',
'payorLastName' => 'Test',
'payorStreetAddress1' => '1234 Main St.',
'payorStreetAddress2' => 'Apt. 7B',
'payorCity' => 'Ogden',
'payorState' => 'UT',
'payorZip' => '84404',
'transactionEmailAddress' => 'adamemail@pdc4u.com',
'payorPhoneNumber' => '777-777-7777',
'payorAccountReference' => 'AB1234',
'payorMemoInformation' => 'December payment',
'payorBankRoutingNumber' => '124001545',
'payorBankAccountNumber' => '123456',
'payorCheckNumber' => '9999',
'payorAccountType' => 'C',
'chargeAmount' => '5.00',
'feeAmount' => '0.50',
'transactionOrigin' => 'EXT',
'payorTransactionType' => 'D',
'achEntryCode' => 'WEB',
'processingDate' => '2017-05-31',
'secondaryTrace' => ''
];
//Payment-specific information for tran 2
$achInformation2 = $achInformation;
$achInformation2['payorFirstName'] = 'Adam2';
$url = 'https://achlegacydemo.pdc4u.com/ECheckServices/ACHTransactionProcessor?wsdl';
$namespace = 'http://transaction.webservices.pdc4u.com';
$method = 'processACHTransactionBatch';
$params = [
'achTransactionBatchItems' => [
$achInformation,
$achInformation2
],
'userInfo'=> $userInformation
];
$client = new SoapClient($url);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
} catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
my $soap = SOAP::Lite
->readable(1)
->autotype(0)
->ns( 'http://transaction.webservices.pdc4u.com/', "ns1" )
->proxy( 'https://achlegacydemo.pdc4u.com/ECheckServices/ACHTransactionProcessor?wsdl' );
my %userInformation = (
'pdcAccountSet' => '01',
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'userName' => 'frontenduser@pdc4u.com'
);
# Payment-specific information
my %achInformation = (
'payorFirstName' => 'Adam',
'payorLastName' => 'Test',
'payorStreetAddress1' => '1234 Main St.',
'payorStreetAddress2' => 'Apt. 7B',
'payorCity' => 'Ogden',
'payorState' => 'UT',
'payorZip' => '84404',
'transactionEmailAddress' => 'adamemail@pdc4u.com',
'payorPhoneNumber' => '777-777-7777',
'payorAccountReference' => 'AB1234',
'payorMemoInformation' => 'December payment',
'payorBankRoutingNumber' => '124001545',
'payorBankAccountNumber' => '123456',
'payorCheckNumber' => '9999',
'payorAccountType' => 'C',
'chargeAmount' => '5.00',
'feeAmount' => '0.50',
'transactionOrigin' => 'EXT',
'payorTransactionType' => 'D',
'achEntryCode' => 'WEB',
'processingDate' => '2017-05-31',
'secondaryTrace' => ''
);
my @batch1;
foreach my $key ( keys %achInformation ) {
push @batch1, SOAP::Data->name( $key => $achInformation{$key} );
}
# Payment-specific information for tran 2
my %achInformation2 = %achInformation;
$achInformation2{'payorFirstName'} = 'Adam2';
my @batch2;
foreach my $key ( keys %achInformation2 ) {
push @batch2, SOAP::Data->name( $key => $achInformation2{$key} );
}
# userInfo
my @userInfo;
foreach my $key ( keys %userInformation ) {
push @userInfo, SOAP::Data->name( $key => $userInformation{$key} );
}
print $soap->call( 'processACHTransactionBatch',
SOAP::Data->name('achTransactionBatchItems' => \SOAP::Data->value(@batch1)),
SOAP::Data->name('achTransactionBatchItems' => \SOAP::Data->value(@batch2)),
SOAP::Data->name('userInfo' => \SOAP::Data->value(@userInfo))
)->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://achlegacydemo.pdc4u.com/ECheckServices/ACHTransactionProcessor?wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
# Get customer-specific information
userInformation = {
'pdcAccountSet' => '01',
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'userName' => 'frontenduser@pdc4u.com'
}
# Payment-specific information
achInformation = {
'payorFirstName' => 'Adam',
'payorLastName' => 'Test',
'payorStreetAddress1' => '1234 Main St.',
'payorStreetAddress2' => 'Apt. 7B',
'payorCity' => 'Ogden',
'payorState' => 'UT',
'payorZip' => '84404',
'transactionEmailAddress' => 'adamemail@pdc4u.com',
'payorPhoneNumber' => '777-777-7777',
'payorAccountReference' => 'AB1234',
'payorMemoInformation' => 'December payment',
'payorBankRoutingNumber' => '124001545',
'payorBankAccountNumber' => '123456',
'payorCheckNumber' => '9999',
'payorAccountType' => 'C',
'chargeAmount' => '5.00',
'feeAmount' => '0.50',
'transactionOrigin' => 'EXT',
'payorTransactionType' => 'D',
'achEntryCode' => 'WEB',
'processingDate' => '2017-05-31',
'secondaryTrace' => ''
}
# Payment-specific information for tran 2
achInformation2 = achInformation;
achInformation2['payerFirstName'] = 'Adam2';
# Build the parameters
params = {
'achTransactionBatchItems' => [
achInformation,
achInformation2
],
'userInfo' => userInformation
};
response = client.call(:process_ach_transaction_batch, message: params)
puts response
rescue
puts "Caught: #$!\n"
end
You can also submit check transactions as a batch by providing a list of transactions.
The URL to process a check batch is:
test wsdl:
https://achlegacydemo.pdc4u.com/ECheckServices/ACHTransactionProcessor?wsdl
live wsdl:
https://achlegacy.pdc4u.com/ECheckServices/ACHTransactionProcessor?wsdl
The namespace to use is:
http://transaction.webservices.pdc4u.com
The method to use is:
processACHTransactionBatch
getECheckData - Transaction Inquiry - get details about processed transactions
<?php
// Get customer and transaction information
$updateInformation = [
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'primaryTrace' => 'SomeTransactionID'
];
$url = 'https://achlegacydemo.pdc4u.com/ECheckServices/ECheckInquiry?wsdl';
$namespace = 'http://inquiry.webservices.pdc4u.com';
$method = 'getECheckData';
$params = [
'echeckInquiryData'=> $updateInformation
];
$client = new SoapClient($url);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
} catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
my $soap = SOAP::Lite
->readable(1)
->autotype(0)
->ns( 'http://inquiry.webservices.pdc4u.com/', "ns1" )
->proxy( 'https://achlegacydemo.pdc4u.com/ECheckServices/ECheckInquiry?wsdl' );
# Get customer and transaction information
my %updateInformation = (
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'primaryTrace' => 'SomeTransactionID'
);
print $soap->call( 'getECheckData',
SOAP::Data->name('eCheckInquiryData' => \%updateInformation)
)->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://achlegacydemo.pdc4u.com/ECheckServices/ECheckInquiry?wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
# Get customer and transaction information
updateInformation = {
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'primaryTrace' => 'SomeTransactionID'
}
# Build the parameters
params = {
'echeckInquiryData' => updateInformation
}
response = client.call(:get_e_check_data, message: params)
puts response
rescue
puts "Caught: #$!\n"
end
Gather information about a specific transaction.
The URL to check a transaction is:
test wsdl:
https://achlegacydemo.pdc4u.com/ECheckServices/ECheckInquiry?wsdl
live wsdl:
https://achlegacy.pdc4u.com/ECheckServices/ECheckInquiry?wsdl
The namespace to use is:
http://inquiry.webservices.pdc4u.com
The method to use is:
getECheckData
getECheckDataUpdates - Transaction Status Inquiry - get status changes since last request
<?php
// Get customer and transaction information
$updateInformation = [
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
];
$url = 'https://achlegacydemo.pdc4u.com/ECheckServices/ECheckUpdateInquiry?wsdl';
$namespace = 'http://inquiry.webservices.pdc4u.com';
$method = 'getECheckDataUpdates';
$params = [
'echeckInquiryData'=> $updateInformation
];
$client = new SoapClient($url);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
} catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
my $soap = SOAP::Lite
->readable(1)
->autotype(0)
->ns( 'http://inquiry.webservices.pdc4u.com/', "ns1" )
->proxy( 'https://achlegacydemo.pdc4u.com/ECheckServices/ECheckUpdateInquiry?wsdl' );
# Get customer and transaction information
my %updateInformation = (
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
);
print $soap->call( 'getECheckDataUpdates',
SOAP::Data->name('echeckInquiryData' => \%updateInformation)
)->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://achlegacydemo.pdc4u.com/ECheckServices/ECheckUpdateInquiry?wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
# Get customer and transaction information
updateInformation = {
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
}
# Build the parameters
params = {
'echeckInquiryData' => updateInformation
}
response = client.call(:get_e_check_data_updates, message: params)
puts response
rescue
puts "Caught: #$!\n"
end
Get details about all transactions since last request. It is recommended to use the Transaction Inquiry API rather than this method.
The URL to get status changes is:
test wsdl:
https://achlegacydemo.pdc4u.com/ECheckServices/ECheckUpdateInquiry?wsdl
live wsdl:
https://achlegacy.pdc4u.com/ECheckServices/ECheckUpdateInquiry?wsdl
The namespace to use is:
http://inquiry.webservices.pdc4u.com
The method to use is:
getECheckDataUpdates
updateStatus - Transaction Updating - change the status of a transaction
<?php
// Get customer and transaction information
$updateInformation = [
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'primaryTrace' => 'SomeTransactionID',
'newStatus' => 'VOID'
];
$url = 'https://achlegacydemo.pdc4u.com/ECheckServices/ECheckStatusUpdate?wsdl';
$namespace = 'http://update.webservices.pdc4u.com';
$method = 'updateStatus';
$params = [
'eCheckUpdateData'=> $updateInformation
];
$client = new SoapClient($url);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
} catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
my $soap = SOAP::Lite
->readable(1)
->autotype(0)
->ns( 'http://update.webservices.pdc4u.com/', "ns1" )
->proxy( 'https://achlegacydemo.pdc4u.com/ECheckServices/ECheckStatusUpdate?wsdl' );
# Get customer and transaction information
my %updateInformation = (
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'primaryTrace' => 'SomeTransactionID',
'newStatus' => 'VOID'
);
print $soap->call( 'updateStatus',
SOAP::Data->name('eCheckUpdateData' => \%updateInformation)
)->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://achlegacydemo.pdc4u.com/ECheckServices/ECheckStatusUpdate?wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
# Get customer and transaction information
updateInformation = {
'customerID' => '0000',
'securityKey' => 'SomeSecurityKey',
'primaryTrace' => 'SomeTransactionID',
'newStatus' => 'VOID'
}
# Build the parameters
params = {
'eCheckUpdateData' => updateInformation
}
response = client.call(:update_status, message: params)
puts response
rescue
puts "Caught: #$!\n"
end
Change the status of a previously submitted transaction. In particular, VOID the transaction.
The URL to update a transaction is:
test wsdl:
https://achlegacydemo.pdc4u.com/ECheckServices/ECheckStatusUpdate?wsdl
live wsdl:
https://achlegacy.pdc4u.com/ECheckServices/ECheckStatusUpdate?wsdl
The namespace to use is:
http://update.webservices.pdc4u.com
The method to use is:
updateStatus
GW Authentication API
This service allows you to obtain a JWT or an API key.
- Authentication JWT - Obtain an authenticated JWT for use as authorization with other PDCFlow services.
- API Key - Manage API keys to be used when tokenizing cards.
Authentication JWT
API Request
test wsdl:
https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/authentication
live wsdl:
https://authentication.pdc4u.com/GWAuthentication/api/v1_0/authentication
Use a username and password to obtain an authenticated JWT for use as authorization with other PDCFlow services.
This API requires a a Base64 encoded username:password, passed in through the BASIC Http Authorization Header. Besides the authorization header, no further attributes are required. An example is provided below.
Each response includes a DepreciaterefreshToken which is no longer used.
API Response
| Attribute | Description |
|---|---|
|
accessToken
AlphanumericN/A
|
The JSON Web Token for use as authorization in other PDCFlow services. Valid for 30 minutes. |
|
refreshToken
Base64N/A
|
Deprecated |
Tokenizing API Key
Use a username and password to manage API keys. These keys will be used to tokenize cards. You can retrieve a list of existing keys, create a new key, or revoke an existing key.
Retrieve list of existing keys
test wsdl:
https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/apikeys
live wsdl:
https://authentication.pdc4u.com/GWAuthentication/api/v1_0/apikeys
GET to retrieve a full list of all active and revoked API keys. No additional parameters are required. View example request.
API Response
| Attribute | Description |
|
apiKeyList
ListN/A
|
A list of apiKeyList objects containing details about each key.
See object definition below. |
Create new key
test wsdl:
https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/apikeys
live wsdl:
https://authentication.pdc4u.com/GWAuthentication/api/v1_0/apikeys
POST to have a new key created. No additional parameters are required. View example request.
API Response
| Attribute | Description |
|
ObjectN/A
|
Details about the created key.
See object definition below. |
Revoke existing key
test wsdl:
https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/apikeys
live wsdl:
https://authentication.pdc4u.com/GWAuthentication/api/v1_0/apikeys
PUT to revoke an existing key. The key revoked will no longer be able to be used, effective immediately. The companyCredentialApiKeyId should be used as the numeric id submitted to revoke an apiKey. No additional parameters are required. If the key to specified to be revoked is the last active key, it will not be revoked and an Http Response Code 409 will be returned. View example request.
API Response
| Attribute | Description |
|
ObjectN/A
|
Details about the revoked key.
See object definition below. |
API key object
| Attribute | Description |
|---|---|
|
companyCredentialApiKeyId
Alphanumeric8
|
The id of the API key. This would be used if you wanted to revoke access to a key. |
|
companyId
Numeric8
|
The id of the company that owns the key. This will be your company id. |
|
createDateTime
Datetime19
|
The date the key was created. |
|
revokeDateTime
Datetime19
|
The date the key was revoked. No value if the key is still active. |
|
lastUsedDateTime
Datetime19
|
The date when this key was last used to tokenize a card. This is useful if you aren’t sure if one of your keys is in use or not. |
|
apiKey
Alphanumeric64
|
The API key to be used when attempting to tokenize a card. |
Sample Code
This section offers some client implementation examples in different programming languages. Keep in mind, these are only minimalistic examples used to demonstrate the Signature Service REST API and are not meant for production use.
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 '409':
Description = 'Conflict. The resource could not be modified.'
Status '500':
Description = 'An internal error has occurred.'
Sample Retrieve new JWT
<?php
$url = 'https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/authentication';
$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "someSecretUsername:someSecretPassword");
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://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/authentication");
my $req = HTTP::Request->new( 'GET', $uri );
$req->authorization_basic( 'SomeSecretUsername', 'SomeSecretPassword' );
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
url = "https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/authentication"
c = Curl::Easy.new( url )
c.http_auth_types = :basic
c.username = 'SomeSecretUsername'
c.password = 'SomeSecretPassword'
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
Creates a new JWT accessToken and refreshToken.
Send an HTTP GET request to:
test wsdl:
https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/authentication
live wsdl:
https://authentication.pdc4u.com/GWAuthentication/api/v1_0/authentication
Sample Refresh JWT
<?php
$url = 'https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/authentication/refreshedToken?';
$accessToken = 'previously_acquired_access_token';
$authorization = "Authorization: Bearer " . $accessToken;
$params = [
'companyId' => '1234',
'grantType' => 'refreshToken',
'refreshToken' => 'previously_acquired_refresh_token'
];
$urlParams = http_build_query($params);
$url .= $urlParams;
$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://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/authentication/refreshedToken");
$params = {
'companyId' => '1234',
'grantType' => 'refreshToken',
'refreshToken' => 'previously_acquired_refresh_token'
}
$uri->query_form($reportParams);
my $jwt = 'jwt_from_gwauthenticationservice';
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
params = {
'companyId' => '1234',
'grantType' => 'refreshToken',
'refreshToken' => 'previously_acquired_refresh_token'
}
jwt = 'jwt_from_gwauthenticationservice'
url = "https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/authentication/refreshedToken?#{Curl::postalize(params)}"
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
Creates a new JWT accessToken.
A valid accessToken is required for authentication (even if it is expired).
Send an HTTP GET request to:
test wsdl:
https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/authentication/refreshedToken
live wsdl:
https://authentication.pdc4u.com/GWAuthentication/api/v1_0/authentication/refreshedToken
Sample List API keys
<?php
$url = 'https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/apikeys';
$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "someSecretUsername:someSecretPassword");
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://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/apikeys");
my $req = HTTP::Request->new( 'GET', $uri );
$req->authorization_basic( 'SomeSecretUsername', 'SomeSecretPassword' );
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
url = "https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/apikeys"
c = Curl::Easy.new( url )
c.http_auth_types = :basic
c.username = 'SomeSecretUsername'
c.password = 'SomeSecretPassword'
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
Retrieve a list of existing API keys.
Send an HTTP GET request to:
test wsdl:
https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/apikeys
live wsdl:
https://authentication.pdc4u.com/GWAuthentication/api/v1_0/apikeys
Sample Add API key
<?php
$url = 'https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/apikeys';
$curl = curl_init();
curl_setopt($curl, CURLOPT_POST, 1);
$data = json_encode([], JSON_UNESCAPED_SLASHES);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Content-Length: 0']
);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "someSecretUsername:someSecretPassword");
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
use File::Slurp;
use MIME::Base64;
eval {
my $data = {};
$data = JSON::XS->new->utf8->encode ($data);
my $url = 'https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/apikeys';
my $req = HTTP::Request->new( 'POST', $url );
$req->authorization_basic( 'SomeSecretUsername', 'SomeSecretPassword' );
$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 $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 = {}
c = Curl::Easy.new
c.url = 'https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/apikeys';
c.http_auth_types = :basic
c.username = 'SomeSecretUsername'
c.password = 'SomeSecretPassword'
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
Add a new API key.
Send an HTTP POST request to:
test wsdl:
https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/apikeys
live wsdl:
https://authentication.pdc4u.com/GWAuthentication/api/v1_0/apikeys
Sample Revoke API key
<?php
$companyCredentialApiKeyId = 1;
$url = 'https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/apikeys/'.$companyCredentialApiKeyId;
$curl = curl_init();
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
$data = json_encode([], JSON_UNESCAPED_SLASHES);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Content-Length: ' . strlen($data)]
);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "someSecretUsername:someSecretPassword");
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
use File::Slurp;
use MIME::Base64;
eval {
my $companyCredentialApiKeyId = 1;
my $url = "https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/apikeys/$companyCredentialApiKeyId";
my $data = {};
$data = JSON::XS->new->utf8->encode ($data);
my $req = HTTP::Request->new( 'PUT', $url );
$req->authorization_basic( 'SomeSecretUsername', 'SomeSecretPassword' );
$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
# companyCredentialApiKeyId = 1;
companyCredentialApiKeyId = 2560;
url = "https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/apikeys/#{companyCredentialApiKeyId}"
data = {}
c = Curl::Easy.new
c.url = url
c.http_auth_types = :basic
c.username = 'SomeSecretUsername'
c.password = 'SomeSecretPassword'
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_put(payload)
#puts JSON.parse c.body_str
puts c.body_str
if c.response_code == 200 then
puts "Success " + c.status
else
puts "Error " + c.status
end
rescue
puts "Caught: #$!\n"
end
Revoke an existing API key.
Send an HTTP PUT request to:
test wsdl:
https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/apikeys
live wsdl:
https://authentication.pdc4u.com/GWAuthentication/api/v1_0/apikeys
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 GWAuthenticationService.
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_gwauthenticationservice';
$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_gwauthenticationservice';
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_gwauthenticationservice'
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_gwauthenticationservice';
$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_gwauthenticationservice';
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_gwauthenticationservice'
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
Portal API
The payment portal is the easiest way for you to accept online payments. We provide two ways to integrate, either through a standard url or by embedding it within an iframe on your website. For a more advanced integration, you can send PDC information to prepopulate the payment form (see Prepopulate Integration) and use Postback Integration to get the details back into your system. This form allows you to seamlessly integrate to a PCI compliant payment portal.
Configure Portal
Portal Configuration URL:
test url: https://app-demo.pdcflow.com
live url: https://app.pdcflow.com
Since the payment portal is a feature of PDC’s FlowUI, all configuration of the payment portal needs to be done within our UI. Once you are signed in, go to Configure -> Portal. This will give you the ability to create any number of portals. Within each portal, you have the ability to configure multiple settings such as:
- Set custom portal name. This is used as part of the url you provide to your customers.
- Set the payment accounts for processing. If you have multiple bank accounts, this option would allow each portal to go to a different bank account.
- Default fee amount. All payments will have this fee amount added.
- Notification settings, such as automatic notifications and custom receipt text.
- Ability to hide fields you don’t need. For example, if you don’t want to collect a physical address for the payer, you can hide all address fields from the form.
- Ability to require fields. You can make any field required. For example, if you need a zip code to get a lower card processing rate, you can require that field.
- Set fields to be readonly. If using the integration below, you can pass values to pre-fill the form, and then use this setting to make sure the value isn’t changed by your customer. Warning: If you mark a field as readonly and don’t send a value, your customer will not be able to submit the payment.
- Override the company name on file. For example, if your company is named ‘The Company A’, but the portal you are configuring is so you can take payments for a company with the name 'Best Company’, this setting would allow the listed name on the portal screen and on all receipts to use 'Best Company’.
- Set a url to redirect to after the payment is complete
- Set a url to have transaction details sent to after a payment is complete (see Postback Integration)
- Change field labels. All fields can be given custom labels. For example, the default 'Account Number’ field could be renamed to 'Member ID’ if that is what you call your id.
- Apply custom styling to the form. This includes colors, fonts, and spacing.
While this page gives a basic overview of portal setup, additional help can be found next to each setting on the configuration screen. Look for the purple question marks for a description of each setting.
Prepopulate Integration
One of the main features available to integrators is the ability to prepopulate a payment form. This is accomplished by handling all lookups within your existing system, and then posting that information into a PDC Portal.
The following table describes the individual elements that can receive a prepopulate value. If during the portal configuration any field is set to be hidden, a prepopulate value for that field will be ignored.
| Attribute | Description |
|---|---|
|
firstName
Alpha45
|
First name of person paying. |
|
lastName
Alpha45
|
Last name of person paying. |
|
streetAddressOne
Alphanumeric80
|
Street address line 1. |
|
streetAddressTwo
Alphanumeric45
|
Street address line 2. |
|
city
Alphanumeric45
|
The city of the payor. |
|
state
Alpha2
|
The state of the payor.
Format: two character abbreviation (UT, CA, MI, etc)
|
|
country
Alpha2
|
The country of the payor. The only reason to set this parameter is if the payor is outside of the United States.
Format: two character abbreviation (US, DE, GB, etc)
Default: US
|
|
zip
Numeric5
|
The zip code of the payor. |
|
zipPlusFour
Numeric4
|
Additional 4 digits of zip code. |
|
emailAddress
Alphanumeric75
|
Email address where a receipt will be sent at the completion of the transaction (if enabled in portal configuration). |
|
phoneNumber
Alphanumeric10
|
Telephone number. All formatting should be removed, as only the first 10 digits will be used in the field.
Format: XXXXXXXXXX
|
|
accountNumber
Alphanumeric45
|
Reference/ID value. This is often the customer account number from your system. |
|
memo
Alphanumeric50
|
Memo information for the explanation of the transaction. |
|
paymentAmount
Numeric11
|
The payment amount.
Format: XXXX.XX
Do not use any formatting symbols such as currency symbols ($), commas etc. |
|
roundTrip
Alphanumeric75
|
This can be used to pass custom key/value pairs with each payment. For example, if you need to track the office a payment was processed through, that can be submitted as a roundTrip, and it will be included with the payment information at the end of processing. You may send up to 3. They should be passed as an html array. The key can be up to 75 characters, and the value can be up to 75 characters. In the example below, the keys are level and office, and the values are A and Scranton.
Format:
<input type=“hidden” name=“roundTrip[level]” value=“A” /> <input type=“hidden” name=“roundTrip[office]” value=“Scranton” /> |
Postback Integration
If a url is set within Configure Portal, all details about a transaction can be posted back to your system. The attribute name will match the name used when attempting to prepopulate. The content will always come as JSON, and as POST.
If something goes wrong when attempting to postback to your system, PDC will automatically retry on the following schedule.
- First attempt: immediately following a successful payment
- Second attempt: 5 minutes after receiving payment
- Third attempt: 15 minutes after receiving payment
- Fourth attempt: 1 hour after receiving payment
- Fifth/Final attempt: 24 hours after receiving payment
To be considered successful, we expect your server to return a status 200. Once that is received or after the fifth attempt at 24 hours, we will no longer try to post the data back to you.
| Attribute | Description |
|---|---|
|
transactionId
Numeric20
|
The PDC transaction id. Use this to pull further details on a payment, check the status, issue a CREDIT, etc. |
|
firstName
Alpha45
|
First name of person paying. |
|
lastName
Alpha45
|
Last name of person paying. |
|
streetAddressOne
Alphanumeric80
|
Street address line 1. |
|
streetAddressTwo
Alphanumeric45
|
Street address line 2. |
|
city
Alphanumeric45
|
The city of the payor. |
|
state
Alpha2
|
The state of the payor.
Format: two character abbreviation (UT, CA, MI, etc)
|
|
country
Alpha2
|
The country of the payor. The only reason to set this parameter is if the payor is outside of the United States.
Format: two character abbreviation (US, DE, GB, etc)
Default: US
|
|
zip
Numeric5
|
The zip code of the payor. |
|
zipPlusFour
Numeric4
|
Additional 4 digits of zip code. |
|
emailAddress
Alphanumeric75
|
Email address entered by user. |
|
phoneNumber
Alphanumeric10
|
Phone number entered by user.
Format: XXXXXXXXXX
|
|
accountNumber
Alphanumeric45
|
Reference/ID value. This is often the customer account number from your system. |
|
memo
Alphanumeric50
|
Memo information for the explanation of the transaction. |
|
paymentAmount
Numeric11
|
The payment amount.
Format: XXXX.XX
|
|
feeAmount
Numeric11
|
Transaction fee amount.
Format: XXXX.XX
|
|
totalAmount
Numeric11
|
The total charged amount. This is calculated by adding paymentAmount to feeAmount.
Format: XXXX.XX
|
|
serviceType
Alpha5
|
The method of payment.
Valid value(s):
CARD, CHECK |
|
transactionType
Alpha6
|
The type of payment.
Valid value(s):
CREDIT, DEBIT, SALE, VOID |
|
accountDirective
Alphanumeric10
|
The underlying financial account that was used to process the payment. |
|
cardNumberLastFour
Numeric4
|
Last four digits of the card number.
Constraint(s): Only present when
serviceType is CARD.
|
|
cardType
Alpha16
|
The card type.
Constraint(s): Only present when
serviceType is CARD.
Valid value(s):
AMERICAN EXPRESS, DISCOVER, MASTERCARD, VISA |
|
cardMonth
Numeric2
|
Card expiration month.
Constraint(s): Only present when
serviceType is CARD.
|
|
cardYear
Numeric2
|
Card expiration year.
Constraint(s): Only present when
serviceType is CARD.
|
|
securityCodeResult
Alpha1
|
Result of the CVV2/CVC2/CID verification system.
Constraint(s): Only present when
serviceType is CARD.
Valid value(s):
M - MatchN - No matchP - Not processedS - Should be on card but not so indicatedU - Issuer not certifiedX - No response from association(blank) - No CVV2/CVC data available for transaction
|
|
bankAccountNumberLastFour
Alphanumeric4
|
The last four of the bank account number.
Constraint(s): Only present when
serviceType is CHECK.
|
|
bankAccountType
Alpha16
|
The type of account the payment will be made from.
Constraint(s): Only present when
serviceType is CHECK.
Valid value(s):
CHECKING, SAVINGS |
|
bankRoutingNumber
Numeric9
|
The routing number of the bank/credit union.
Constraint(s): Only present when
serviceType is CHECK.
|
|
bankName
Alphanumeric16
|
The name of the bank/credit union.
Constraint(s): Only present when
serviceType is CHECK.
|
|
checkNumber
Numeric10
|
The check number.
Constraint(s): Only present when
serviceType is CHECK.
|
|
dateCreated
Date19
|
The date and time the transaction was received by our system.
Format: YYYY-MM-DD HH:mm:SS
|
|
dateProcessed
Date19
|
The date and time the transaction was sent for processing by our system.
Format: YYYY-MM-DD HH:mm:SS
|
|
dateScheduled
Date19
|
The date and time the transaction is scheduled to be processed by our system. This can be in the future if a CHECK is post-dated.
Constraint(s): This will only have a value when
serviceType is CHECK.
Format: YYYY-MM-DD HH:mm:SS
|
|
currentStatus
Alpha12
|
Current state of check in the ACH payment cycle. With the postback, this will generally be WAITING.
Valid value(s):
WAITING - transaction will be included in next batchSUBMITTED - transaction has been submitted for processingACKNOWLEDGED - transaction has been accepted for processingFUNDED - money has been deposited into your accountDEDUCTION - money has been taken from your accountVOID - transaction was cancelled prior to submission for processingRETURNED - an exception occured while processing transactionCORRECTION - transaction was automatically corrected during processingERROR - an unknown error occured while processing transaction
|
|
allowDuplicate
Numeric1
|
Flag stating if person paying was warned transaction may be a duplicate. For payment to have been processed after warning is displayed, they must acknowledge that they want to proceed. 1 means warning was shown, 0 means transaction was not flagged as a duplicate.
Valid value(s):
1, 0 |
|
relatedId
Numeric20
|
If this payment is a VOID or CREDIT, this will contain the transactionId of that original SALE/DEBIT.
|
|
roundTrip
ListN/A
|
JSON object of key/value pairs. Each key has a max length of 75 characters, and each value has a max length of 75 characters. |
Postback Error
Although rare, it is possible that an error could occur when gathering the transaction details to post. In that case, a different response would be given.
| Attribute | Description |
|---|---|
|
error
Alphanumeric200
|
If this element is present, no other elements will be. Sample message: “Unable to retrieve details for CHECK transaction id 28539. Use Transaction Service API to recover.” |
Sample Code
Prepopulate information
<form action="https://app-demo.pdcflow.com/customerID" method="post">
<input type="submit" value="Payment by credit card" />
<input type="hidden" name="firstName" value="Adam" />
<input type="hidden" name="lastName" value="Test" />
<input type="hidden" name="accountNumber" value="AB1234" />
<input type="hidden" name="paymentAmount" value="5.00" />
<input type="hidden" name="roundTrip[office]" value="Scranton" />
</form>
Use standard hidden fields to submit your information to PDC. This should always be sent as a POST request.
Postback Sample Success
{"transactionId":"28550","firstName":"My","lastName":"Test","accountNumber":"1234","paymentAmount":"1.00","feeAmount":"","memo":"","phoneNumber":"","emailAddress":"blake@pdc4u.com","dateScheduled":"","dateProcessed":"2017-12-11 12:19:00","dateCreated":"2017-12-11 12:19:00","accountDirective":"888-1","totalAmount":"1.00","transactionType":"SALE","securityCodeResult":"M","relatedId":"","cardNumberLastFour":"2228","cardType":"VISA","streetAddressOne":"","streetAddressTwo":"","city":"","state":"","zip":"","zipPlusFour":"","country":"US","serviceType":"CARD","roundTrip":{"flowUiPortalId":"5"},"cardMonth":"02","cardYear":"19","allowDuplicate":"1"}
Postback Sample Failure
{"error":"Unable to retrieve details for CHECK transaction id 28539. Use Transaction Service API to recover."}
Schedule Service API
The Schedule and Recurring service allows easy integration for creating, modifying, and retrieving of Schedule and Recurring information. Requests are made through GET, POST, PATCH, and PUT requests.
Authentication and authorization for the ScheduleService will be done by JWT in the HTTP Authorization Header. This JWT can be obtained by passing a valid username and password to the GWAuthenticationService.
In general, fields will only be returned if their value is not null or empty.
Schedule
test urls:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedules
live urls:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/schedules
POST to create a new schedule record.
PUT to modify a previous schedule. This will ALWAYS regenerate the payment list based on the updated request parameters. All original values will be overwritten with the updated parameters.
PATCH to modify a previous schedule. This will NEVER regenerate the payment list and will only modify specified parameters. Passing in an empty value for a parameter will remove the stored value for that parameter.
DELETE to delete a previous schedule that does not have a payment attempt.
GET to get a list of schedules. The READONLY fields will only be present on this endpoint
| Attribute | Description |
|
status
Alpha15
|
The passed in value will only be DRAFT
Valid value(s):
DRAFT - Schedule is not yet activeACTIVE - Schedule is activeCOMPLETED - Schedule is completeINACTIVE - Schedule is inactive |
|
settingId
Numeric
Required
|
The id of the schedule setting. |
|
paymentMethod
Alpha
Conditional
|
Valid value(s):
CARDCHECKRequired if requestPaymentData is False
|
|
requestPaymentData
Boolean
|
If this is True a flow request will be sent requesting the payment information. The accountDirective for all allowed payment types is required if this is set to True.A valid emailAddress or phoneNumber is required when set to True. |
|
firstName
Alphanumeric45
Required
|
The first name of the person associated to this schedule |
|
lastName
Alphanumeric45
Required
|
The last name of the person associated to this schedule |
|
accountNumber
Alphanumeric45
Required
|
The accountNumber |
|
numberOfPayments
Numeric
|
The Number of Payments used for creation of the Schedule. If this is provided the paymentAmount cannot be provided. If the number of payments is too great an error message will be provided that indicates the maximum value. If this is changed during a PUT call, then the SchedulePayments will be regenerated. Only returns if not zero on POST or PUT requests.
|
|
paymentAmount
Numeric
|
This is the amount that will be charged for each scheduled payment. If this is provided the numberOfPayments cannot be provided. If the payment amount is too small an error message will be provided that indicates the minimum value. If this is changed during a PUT call, then the SchedulePayments will be regenerated. Only returns if not zero on POST or PUT requests.
|
|
memo
Alphanumeric50
|
The memo associated to the schedule |
|
emailAddress
Alphanumeric75
|
An email address to associate with the schedule. Reminders will be sent to this email address prior to payments being processed, according to the cardReminderDays or checkReminderDays in the Setting for this schedule.
If sendAuthorizationRequest is true, the authorization request will be sent to this email address.
If requestPaymentData is true, the request will be sent to this email address.Either the emailAddress or phoneNumber is required if sendAuthorizationRequest or requestPaymentData is true.
|
|
sendReceiptToEmailAddress
Boolean
Required
|
Toggle the sending of email receipts. A valid emailAddress is required when set to True.
|
|
phoneNumber
Numeric10
Conditional
|
A phone number to associate with the schedule. If sendAuthorizationRequest is true, the authorization request will be sent to this phone number via text message.If requestPaymentData is true, the request will be sent to this phone number via text message.Either the emailAddress or phoneNumber is required if sendAuthorizationRequest or requestPaymentData is true.
|
|
sendAuthorizationRequest
Boolean5
Conditional
|
Whether an authorization request will be sent to the included emailAddress and/or phoneNumber. Required if the status of the schedule is set to ACTIVE, AUTHORIZE or UNAUTHORIZED.
An authorization request will only be sent if the status of the schedule is ACTIVE, AUTHORIZE or UNAUTHORIZED.
When an authorization request is sent, the schedule will be set to a status of AUTHORIZE until the account holder has completed the authorization request. When the authorization request is successfully completed, the status of the schedule will be set to ACTIVE.If sendAuthorizationRequest is true, the Authorization object is required, along with either the emailAddress or phoneNumber.
|
|
authorization
AuthorizationN/A
Conditional
|
The phone number |
|
addressOne
Alphanumeric80
|
Address One |
|
addressTwo
Alphanumeric45
|
Address Two |
|
city
Alphanumeric45
|
City |
|
state
Alphanumeric2
|
State |
|
zip
Alphanumeric5
|
Zip |
|
zipPlusFour
Alphanumeric4
|
The four digit zip code extension. |
|
country
Alphanumeric2
|
Country |
|
origin
Alphanumeric3
|
This should always be set to “EXT” |
|
locationId
Alphanumeric75
|
The locationId for a branch of a company (if configured, typically this will be blank) |
|
recurrenceRule
Alphanumeric255
|
This is the recurrence rule that you want the schedule to calculate the payments against. Passing in a recurrence rule here will override the recurrence that was saved as part of the Setting referenced by the settingId.
This follows the ICal RRule standard, with the exception that DTSTART will only accept yyyyMMdd format. Any timestamp included as part of DTSTART will be ignored.
Restrictions on which frequencies are allowed are stored in the Setting object.
This will restrict the allowed frequencies.
There is no need to start a rule with “RRULE=”. The DTSTART value cannot be in the past or more than 13 months in the future and needs to be formatted “yyyyMMdd”.
The INTERVAL has the following valid ranges: MONTHLY 1-12, WEEKLY 1-5, DAILY 1-31.
Example valid rule “FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=1;”. If this is changed during a PUT call, then the SchedulePayments will be regenerated.
|
|
username
Alphanumeric75
Required
|
This value is used as the createUser and/or updateUser.
|
|
createUser
Alphanumeric75
|
The user who created the Schedule. READONLY
|
|
updateUser
Alphanumeric75
|
The user who last modified the Schedule. READONLY
|
|
createDate
Date
|
Date the Schedule was created. READONLY
Format: URL Encoded ISO-8601
|
|
updateDate
Date
|
Date the Schedule was last updated. READONLY
Format: URL Encoded ISO-8601
|
|
owedAmount
Numeric11
Required
|
The original amount, or the amount owed by the debtor. If this is changed during a PUT call, then the SchedulePayments will be regenerated. Only returns if not zero on POST or PUT requests.
|
|
initialPaymentAmount
Numeric11
|
An amount collected before the schedule is created. This will be deducted from the owedAmount. Only returns if not zero on POST or PUT requests.
|
|
adjustmentAmount
Numeric11
|
An amount to be deducted from the owedAmount. Only returns if not zero on POST or PUT requests.
|
|
pendingAmount
Numeric
|
The total pending amount that is still owed. READONLY |
|
nextPaymentAmount
Numeric
|
The payment amount of the next scheduled payment. READONLY |
|
collectedAmount
Numeric
|
The total amount that has been paid. READONLY |
|
unsuccessfulAmount
Numeric
|
The sum of the paymentAmounts of all failed payments. READONLY |
|
totalExpectedAmount
Numeric
|
The total amount of all payments on the schedule regardless of status, failed, successful or pending. READONLY |
|
nextPaymentDate
DateTime
|
Date the next payment is scheduled. READONLY
Format: URL Encoded ISO-8601
|
|
pendingCount
Numeric
|
The total number of payments that are still waiting to be collected. READONLY |
|
collectedCount
Numeric
|
The total number of payments that have been collected successfully. READONLY |
|
unsuccessfulCount
Numeric
|
The total number of payments that have been unsuccessful. READONLY |
|
totalExpectedCount
Numeric
|
The total number of payments associated with the schedule, regardless of current status. READONLY |
|
billingLastFour
Alphanumeric
4
|
The last four digits of the credit card number or the bank account number. From the active payment method. READONLY |
|
billingCard
Object
Conditional
|
BillingCard object. This is ONLY returned when paymentMethod is CARD
and when a single Schedule object is returned.Required if paymentMethod = CARD
Only the accountDirective field in the billingCard object is required if requestPaymentData is True and CARD is an accepted payment type.
|
|
billingCheck
Object
Conditional
|
BillingCheck object. This is ONLY returned when paymentMethod is CHECK
and when a single Schedule object is returned.Required if paymentMethod = CHECK
Only the accountDirective field in the billingCheck object is required if requestPaymentData is True and CHECK is an accepted payment type.
|
|
payments
List
|
List of SchedulePayment objects. This will be returned when a single Schedule is returned and cannot be modified through the schedules endpoint
Description: See object definition below.
|
Search Parameters
| Attribute | Description |
|---|---|
|
createStartDate
DateTime
|
Date the Schedule was created formatted “yyyy-MM-dd HH:mm:ss”. This filters the records by looking for schedules with a createDate newer than or equal to the date provided
Format: URL Encoded ISO-8601
|
|
createEndDate
DateTime
|
Date the Schedule was created formatted “yyyy-MM-dd HH:mm:ss”. This filters the records by looking for schedules with a createDate older than or equal to the date provided
Format: URL Encoded ISO-8601
|
|
updateStartDate
DateTime
|
Date the Schedule was created formatted “yyyy-MM-dd HH:mm:ss”. This filters the records by looking for schedules with an updateDate newer than or equal to the date provided
Format: URL Encoded ISO-8601
|
|
updateEndDate
DateTime
|
Date the Schedule was created formatted “yyyy-MM-dd HH:mm:ss”. This filters the records by looking for schedules with an updateDate older than or equal to the date provided
Format: URL Encoded ISO-8601
|
|
firstName
Alphanumeric
|
First name of the associated with the Schedule |
|
lastName
Alphanumeric
|
Last name of the associated with the Schedule |
|
accountNumber
Alphanumeric
|
Account Number associated with the Schedule |
|
paymentType
Alphanumeric
|
If empty then both values will be used
Valid value(s):
CARDCHECK |
|
origin
List
|
Origin associated with the Schedule. You can pass in an alphanumeric list of Origin values. |
|
createUser
Alphanumeric
|
User who created the record |
|
updateUser
Alphanumeric
|
User who last modified the record |
|
billingLastFour
Alphanumeric4
|
The last four of the card number or bank account number |
|
status
ListN/A
|
The status of the Schedule. You can pass in a list of values.
Valid value(s):
DRAFTACTIVEINACTIVECOMPLETED |
Schedule Request Examples
Request
GET to retrieve single schedule by its id
test endpoint:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedules/{id}
live endpoint:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/schedules/{id}
Response
Schedule object
Request
GET to retrieve list of schedules by SearchParameters if no SearchParameters are provided, it will search for all records
test endpoint:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedules?{SearchParameters}
live endpoint:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/schedules?{SearchParameters}
Response
List of Schedule objects
Payment
test urls:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedulepayments
live urls:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/schedulepayments
Request
PUT to modify a previous schedule payment. This will overwrite all previous data (except previously processed payments) with the new data passed in. Any change in payment amount or payment method will cause regeneration of the payments and require re-authorization from the client.
test endpoint:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedules/{id}
live endpoint:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/schedules/{id}
Response
The newly updated Schedule object
Request
DELETE to delete a previous schedule payment that does not have a payment attempt.
test endpoint:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedulepayments/{id}
live endpoint:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/schedulepayments/{id}
Response
Status code 200 - Successful
Status code 404 - Record could not be found or is invalid
Status code 409 - Could not be deleted as there has been a payment attempt.
Request
GET to get a SchedulePayment object
test endpoint:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedulepayments/{id}
live endpoint:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/schedulepayments/{id}
Response
SchedulePayment Object
Status code 200 - Successful
Status code 404 - Record could not be found or is invalid
Request
POST to create a new SchedulePayment
test endpoint:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedulepayments
live endpoint:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/schedulepayments
Response
SchedulePayment Object
Status code 200 - Successful
Status code 404 - Record could not be found or is invalid
Request
PUT to update a previous SchedulePayment that has not been used.
test endpoint:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedulepayments/{id}
live endpoint:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/schedulepayments/{id}
Response
SchedulePayment Object
Status code 200 - Successful
Status code 404 - Record could not be found or is invalid
SchedulePayment
| Attribute | Description |
|---|---|
|
paymentId
Numeric20
|
Id for the payment record |
|
scheduleId
Numeric10
|
Id for the parent schedule object |
|
status
Alpha13
|
The status of the last payment attempt.
Valid value(s): PENDING,
WAITING,
PULLED,
ACKNOWLEDGED,
REJECTED,
SUBMITTED,
VOID,
PAID,
FUNDED,
NSF,
RETURNED,
NSF_DEDUCTION,
DECLINED,
CORRECTION,
ERROR,
RETRY,
CANCELLED,
SKIPPED
|
|
paymentAmount
Numeric11
|
Payment amount |
|
paymentDate
Date19
|
Date the payment is scheduled to post formatted “yyyy-MM-dd”
Format: URL Encoded ISO-8601
|
|
arrivalId
Numeric11
|
The arrivalId of the last payment attempt. This will only exist if a payment has been attempted. |
|
transactionId
Numeric20
|
The transaction id of the last payment. This will only exist if a payment has been attempted. |
Billing Card
| Attribute | Description |
|---|---|
|
cardToken
Alphanumeric
16
Conditional
|
The credit card token. This must be a token, and not a raw credit card number. Required if requestPaymentData is False.
|
|
expirationMonth
Numeric
2
Conditional
|
The credit card expiration month. Required if requestPaymentData is False.
|
|
expirationYear
Numeric
2
Conditional
|
The credit card expiration year. Required if requestPaymentData is False.
|
|
accountDirective
Alphanumeric
10
Required
|
The credit card processing account directive. |
Billing Check
| Attribute | Description |
|---|---|
|
routingNumber
Numeric
9
Conditional
|
The bank routing number. Required if requestPaymentData is False.
|
|
bankAccountNumber
Alphanumeric
20
Conditional
|
The bank account number. Required if requestPaymentData is False.
|
|
bankAccountType
Alpha
Conditional
|
Valid values:CHECKINGSAVINGSRequired if requestPaymentData is False.
|
|
accountDirective
Alphanumeric
10
Required
|
The ACH processing account directive. |
Schedule History
Request
{scheduleId} represents the schedule to get or post history for.
GET Get a list of history records related to a schedule.
Optional Parameter: eventType - Type of history event to search for
POST Add a history entry to this schedule.
test endpoint:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedules/{scheduleId}/histories
live endpoint:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/schedules/{scheduleId}/histories
| Attribute | Description |
|---|---|
|
scheduleId
Numeric
Required
|
Schedule ID to add history to. |
|
event
Alpha
Required
|
Valid value(s):
CREATE,
SCHEDULE_MODIFY,
SCHEDULE_STATUS,
TERMS_MODIFY,
BILLING_MODIFY,
PAYMENT_SKIP,
PAYMENT_ATTEMPT,
PAYMENT_REVERSAL,
AUTHORIZATION,
AUTHORIZATION_COMPLETE,
|
|
data
Alphanumeric 255
Required
|
Free form text description of the event. |
|
date
Date19
Required
|
The date the history was added.
Format: ISO-8601 (YYYY-MM-DD HH:mm:ss)
|
|
user
Alphanumeric75
Required
|
User that is adding the history. |
|
eventType
Object
Required
|
The data related to the EVENT
For PAYMENT_ATTEMPT, See object definition below.
For AUTHORIZATION_COMPLETE, See object definition below.
|
EventData Object - PAYMENT_ATTEMPT
| Attribute | Description |
|---|---|
|
arrivalId
Numeric
Required
|
The arrivalId of a transaction
|
|
transactionId
Numeric
Conditional
|
The transactionId of a payment. This is required if the paymentAttempt has a status of PAID, WAITING, SUBMITTED, ACKNOWLEDGED, FUNDED, CORRECTION, VOID, NSF, NSF_DEDUCTION, RETURNED, PULLED, REJECTED.
|
|
paymentId
Numeric
Conditional
|
Schedule payment id. Required to relate this attempt to a scheduled payment. |
|
status
Alpha
Required
|
Valid value(s):
PENDING,
WAITING,
PULLED,
ACKNOWLEDGED,
REJECTED,
SUBMITTED,
VOID,
PAID,
FUNDED,
NSF,
RETURNED,
NSF DEDUCTION,
DECLINED,
CORRECTION,
ERROR,
RETRY,
CANCELLED,
SKIPPED
|
EventData Object - AUTHORIZATION_COMPLETE
| Attribute | Description |
|---|---|
|
flowId
Numeric
Required
|
The id of the related authorization request. |
|
status
Alpha
Required
|
Valid value(s):
PENDING,
EXPIRED,
COMPLETED,
FAILED
|
|
statusDate
Date19
|
The date the flow status was updated.
Format: ISO-8601 (YYYY-MM-DD HH:mm:ss)
|
Schedule Settings
Request
GET to retrieve list of schedule settings
test endpoint:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/settings
live endpoint:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/settings
Response
List of ScheduleSetting objects
Request
GET to retrieve single schedule setting by settingId
test endpoint:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/settings/{id}
live endpoint:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/settings/{id}
Response
Single ScheduleSetting object
Request
GET to retrieve single schedule setting by name
test endpoint:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/settings/names/{name}
live endpoint:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/settings/names/{name}
Response
Single ScheduleSetting object
Request
PUT to save single schedule setting by settingId
test endpoint:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/settings/{id}
live endpoint:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/settings/{id}
Response
Single ScheduleSetting object
Request
POST to save new schedule setting
test endpoint:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/settings
live endpoint:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/settings
Response
Single ScheduleSetting object
ScheduleSetting Object
| Attribute | Description |
|
settingId
Numeric
|
The id of the schedule setting. |
|
name
Alpha 75
|
The name of the schedule setting. |
|
description
Alphanumeric 255
|
Description of the schedule setting. |
|
recurSetting
JSON
|
The recurring schedule settings recurSetting
|
|
date
Date19
|
The date the schedule setting was updated.
Format: ISO-8601 (YYYY-MM-DD HH:mm:ss)
|
|
user
Alphanumeric 75
|
The user that last updated the schedule setting. |
recurSetting Object
| Attribute | Description |
|
paymentTypes
Alpha5
|
The schedule payment types in a list.
Valid value(s):
CHECK - check transaction will be processedCARD - card transaction will be processed |
|
minimumPaymentAmount
Numeric
|
The minimum payment allowed on a schedule. This value must be between 1 and 10000. |
|
allowedFrequencies
Alpha10
|
The allowed payment frequencies in a list.
Valid value(s):
MONTHLY - once per monthBI_MONTHLY - 2 times per monthBI_WEEKLY - once every 2 weeksWEEKLY - once per weekDAILY - once per day |
|
checkReminderDays
Numeric
|
The number of days prior to payment date to send a reminder. This value must be between 3 and 14. |
|
cardReminderDays
Numeric
|
The number of days prior to payment date to send a reminder. This value must be between 3 and 14. |
|
recurrenceRule
Alphanumeric255
|
This is the recurrence rule that you want the schedules using this setting to calculate the payments against. This follows the ICal RRule standard, with the exception that DTSTART will only accept yyyyMMdd format. Any timestamp included as part of DTSTART will be ignored. There is also no need to start a rule with “RRULE=” Example valid rule “FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=1;”. The DTSTART value cannot be in the past or more than 13 months in the future and needs to be formatted “yyyyMMdd”. The INTERVAL has the following valid ranges: MONTHLY 1-12, WEEKLY 1-5, DAILY 1-31. |
Recurring Term
test urls:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/settings/recurringterms
live urls:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/settings/recurringterms
POST to create a new recurring term record.
PUT to modify an existing recurring term.
DELETE to delete an exiting recurring term.
GET to get a list of recurring terms or an individual term.
| Attribute | Description |
|---|---|
|
id
Numeric
|
Id for the recurring term |
|
maximumAmount
Numeric
|
Maximum amount for the term. This value must be unique. Leaving the amount blank will make the record unbounded. |
|
termMonth
AlphaNumeric3
Required
|
The maximum amount of months a schedule with an owedAmount within the maximumAmount can run
|
|
date
Date
Format: URL Encoded ISO-8601
|
Date the term was last modified |
|
user
AlphaNumeric75
Required
|
User creating or modifying the record |
|
maximumPayments
Numeric
|
The maximum amount of payments that can be created with this term and the specified recurrenceRule. Only returns when an amount and recurrenceRule are specified in the URL. READONLY
|
Request
GET while passing in an amount in the URL to specify the amount you are trying to use to get a list of one recurringTerm.
test urls:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/settings/recurringterms?amount=5000.00
live urls:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/settings/recurringterms?amount=5000.00
GET while passing in amount and recurrenceRule will calculate the maximum number of payments that can be generated using the appropriate term and the specified recurrenceRule.
test urls:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/settings/recurringterms?amount=5000.00&recurrenceRule=FREQ=WEEKLY;INTERVAL=1;
live urls:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/settings/recurringterms?amount=5000.00&recurrenceRule=FREQ=WEEKLY;INTERVAL=1;
GET while passing in a settingId will take into consideration the minimumPaymentAmount from the recurSetting object to calculate the maximum number of payments that can be generated using the appropriate term and the specified recurrenceRule. If a recurrenceRule is not specified, but a settingId is, it will use the recurrenceRule from the recurSetting object.
test urls:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/settings/recurringterms?amount=5000.00&settingId=2&recurrenceRule=FREQ=WEEKLY;INTERVAL=1;
live urls:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/settings/recurringterms?amount=5000.00&settingId=2&recurrenceRule=FREQ=WEEKLY;INTERVAL=1;
Response
List of RecurringTerm objects.
Schedule Preview
test urls:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedules/previews
live urls:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/schedules/previews
POST to create a preview of a schedule. This preview will not be saved until the schedules endpoint is called with a POST or a PUT request to save the schedule.
| Attribute | Description |
|---|---|
|
owedAmount
Numeric11
Required
|
The original amount, or the amount owed by the debtor. |
|
initialPaymentAmount
Numeric11
|
An amount collected before the schedule is created. This will be deducted from the owedAmount.
|
|
adjustmentAmount
Numeric11
|
An amount to be deducted from the owedAmount.
|
|
numberOfPayments
Numeric
|
The number of payments desired for the schedule. If this is provided the paymentAmount cannot be provided. If the number of payments requested is too great, causing each payment to be less than the minimumPaymentAmount, an error message will be provided that indicates the maximum number of payments.
|
|
paymentAmount
Numeric
|
This is the amount that will be charged for each scheduled payment. If this is provided the numberOfPayments cannot be provided. If the payment amount is too small, causing the schedule length to exceed the termMonth for this amount, an error message will be provided that indicates the minimum value.
|
|
settingId
Numeric
Required
|
The id of the schedule setting to be used to generate the schedule preview. |
|
recurrenceRule
Alphanumeric255
|
This is the recurrence rule that you want the schedule to calculate the payments against. Passing in a recurrence rule here will override the recurrence that was saved as part of the ScheduleSetting referenced by the settingId.
This follows the ICal RRule standard, with the exception that DTSTART will only accept yyyyMMdd format. Any timestamp included as part of DTSTART will be ignored.
Restrictions on which frequencies are allowed are stored in the ScheduleSetting object.
There is no need to start a rule with “RRULE=”. The DTSTART value cannot be in the past or more than 13 months in the future and needs to be formatted “yyyyMMdd”.
The INTERVAL has the following valid ranges: MONTHLY 1-12, WEEKLY 1-5, DAILY 1-31.
Example valid rule “FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=1;”.
|
|
payments
List
|
List of SchedulePayment objects. Each SchedulePayment will include only a paymentAmount and paymentDate.
Description: See object definition above.
|
Schedule Patch
test urls:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedules/{scheduleId}
live urls:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/schedules/{scheduleId}
PATCH to update the specified Schedule with the requested parameters. This will not regenerate the list of payments.
| Attribute | Description |
|
status
Alpha15
|
This value cannot be modified to be empty. Use this field to ACTIVATE a schedule draft. A Schedule may only be ACTIVATED if there is at least one future payment on the Schedule. When a Schedule is ACTIVATED, any past PENDING payments will be marked as SKIPPED.
Valid value(s):
DRAFT - Schedule is not yet activeACTIVE - Schedule is activeCOMPLETED - Schedule is completeINACTIVE - Schedule is inactive |
|
paymentMethod
Alpha
|
This value cannot be modified to be empty, unless requestPaymentData is set to True.
Valid value(s):
CARDCHECK |
|
requestPaymentData
Boolean
|
If this is True a flow request will be sent requesting the payment information. The accountDirective for all allowed payment types is required if this is set to True.A valid emailAddress or phoneNumber is required when set to True.
|
|
firstName
Alphanumeric45
|
The first name of the person associated to this schedule. This value cannot be modified to be empty. |
|
lastName
Alphanumeric45
|
The last name of the person associated to this schedule. This value cannot be modified to be empty. |
|
accountNumber
Alphanumeric45
|
The accountNumber. This value cannot be modified to be empty. |
|
memo
Alphanumeric50
|
The memo associated to the schedule. |
|
emailAddress
Alphanumeric75
|
An email address to associate with the schedule. Reminders will be sent to this email address prior to payments being processed, according to the cardReminderDays or checkReminderDays in the Setting for this schedule.
If sendAuthorizationRequest is true, the authorization request will be sent to this email address.
If requestPaymentData is true, the request will be sent to this email address.Either the emailAddress or phoneNumber is required if sendAuthorizationRequest or requestPaymentData is true.
|
|
sendReceiptToEmailAddress
Boolean
|
Toggle the sending of email receipts. A valid emailAddress is required when set to True.
|
|
phoneNumber
Numeric10
Conditional
|
A phone number to associate with the schedule. If sendAuthorizationRequest is true, the authorization request will be sent to this phone number via text message.If requestPaymentData is true, the request will be sent to this phone number via text message.Either the emailAddress or phoneNumber is required if sendAuthorizationRequest or requestPaymentData is true.
|
|
sendAuthorizationRequest
Boolean5
Required
|
Whether an authorization request will be sent to the included emailAddress and/or phoneNumber. Required if the new or the current status of the schedule is set to ACTIVE, AUTHORIZE or UNAUTHORIZED.
An authorization request will only be sent if the status of the schedule is ACTIVE, AUTHORIZE or UNAUTHORIZED.
When an authorization request is sent, the schedule will be set to a status of AUTHORIZE until the account holder has completed the authorization request. When the authorization request is successfully completed, the status of the schedule will be set to ACTIVE.If sendAuthorizationRequest is true, the Authorization object is required, along with either the emailAddress or phoneNumber.
|
|
authorization
AuthorizationN/A
Conditional
|
The phone number. |
|
addressOne
Alphanumeric80
|
Address One. |
|
addressTwo
Alphanumeric45
|
Address Two. |
|
city
Alphanumeric45
|
City. |
|
state
Alphanumeric2
|
State. |
|
zip
Alphanumeric5
|
Zip. |
|
zipPlusFour
Alphanumeric4
|
The four digit zip code extension. |
|
country
Alphanumeric2
|
Country. |
|
origin
Alphanumeric3
|
This should always be set to “EXT” and cannot be modified to be empty. |
|
locationId
Alphanumeric75
|
The locationId for a branch of a company (if configured, typically this will be blank). |
|
username
Alphanumeric75
Required
|
This value is used as the updateUser.
|
Schedule Render
test urls:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedules/render
live urls:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/schedules/render
POST to create an HTML representation of the schedule. The service will also email the schedule if at least one valid recipient is provided. If there were validation or processing errors, this object will have a list of RequestError objects.
| Attribute | Description |
|---|---|
|
scheduleId 10
Numeric
Required
|
The id of the schedule to create the HTML for. |
|
includeSignatureImage 5
Boolean
|
Whether the schedule HTML render should include the signature from the corresponding authorization request. This image will only be available if the authorization request has been signed and completed. |
|
scheduleHtml
AlphanumericN/A
|
The HTML representation of the schedule. READONLY |
|
emailTo
ListN/A
|
A list of TO email addresses. Each address can be up to 75 characters. |
|
emailCC
ListN/A
|
A list of CC email addresses. Each address can be up to 75 characters. |
|
emailBCC
ListN/A
|
A list of BCC email addresses. Each address can be up to 75 characters. |
|
requestErrorList
ListN/A
|
A list of RequestError objects containing errors.
Constraint(s): Only returned when validation or processing errors occur.
|
Sample Code
This section offers some client implementation examples in different languages. Keep in mind, these are only minimalistic examples used to demonstrate the Transaction Service REST API and are not meant for production use.
A Jason Web Token (JWT) is required to process all requests through the ScheduleService. You can request a JWT through the GWAuthenticationService, using your company’s username and password, as shown below.
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 '500':
Description = 'An internal error has occurred.'
Sample JWT Request
<?php
$url = 'https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/authentication';
$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "someSecretUsername:someSecretPassword");
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);
General JWT retrieval will use this method. A new JWT will be created for use and valid for 30 minutes.
Send an HTTP GET request to:
test url:
https://authenticationdemo.pdc4u.com/GWAuthentication/api/v1_0/authentication
live url:
https://authentication.pdc4u.com/GWAuthentication/api/v1_0/authentication
Sample SchedulePreview request
<?php
$url = 'https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedules/previews';
$jwt = 'jwt_from_gwauthenticationservice';
$authorization = "Authorization: Bearer " . $jwt;
$schedulePreview = [
'owedAmount' => '2000.00',
'initialPaymentAmount' => '500.00',
'adjustmentAmount' => '100.00',
'numberOfPayments' => '0',
'paymentAmount' => '50.00',
'settingId' => '16',
'recurrenceRule' => 'FREQ=WEEKLY;INTERVAL=1;BYMONTHDAY=1;DTSTART=20201116Y000000',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_POST, 1);
$data = json_encode($schedulePreview, JSON_UNESCAPED_SLASHES);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Content-Length: ' . strlen($data),
$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);
This will create a SchedulePreview. SchedulePayments generated through this method will contain only a paymentAmount and paymentDate and will not be saved until the schedules endpoint is called with a POST or PUT request.
Send an HTTP POST request to:
test url:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedules/previews
live url:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/schedules/previews
Sample Schedule Patch request
<?php
$scheduleIdToPatch = 2;
$url = 'https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedules/'.$scheduleIdToPatch;
$jwt = 'jwt_from_gwauthenticationservice';
$authorization = "Authorization: Bearer " . $jwt;
$schedulePatch = [
'status' => 'ACTIVE',
'firstName' => 'Test',
'lastName' => 'Testing',
'accountNumber' => '123455',
'origin' => 'EXT',
'username' => 'user',
'memo' => '', //This will clear the current value of memo
'emailAddress' => 'no_email@pdc4u.com',
'phoneNumber' => '4654654654',
'addressOne' => '', //This will clear the current value of addressOne
'addressTwo' => '', //This will clear the current value of addressTwo
'city' => 'Montezuma',
'state' => 'MI',
'zip' => '84404',
'zipPlusFour' => '4564',
'country' => 'US',
'paymentMethod' => 'CARD',
'billingCard' => [
'cardToken' => 'aSampleToken4444',
'expirationMonth' => '12',
'expirationYear' => '24',
'accountDirective' => '1111'
]
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PATCH');
$data = json_encode($schedulePatch, JSON_UNESCAPED_SLASHES);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Content-Length: ' . strlen($data),
$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);
This will update a Schedule. Parameters passed in empty will clear the previous value. If change on a field is undesired, do not pass in that parameter. The Schedule will be returned with the newly updated values.
Send an HTTP PATCH request to:
test url:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedules/{scheduleId}
live url:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/schedules/{scheduleId}
Sample Render Schedule Request
<?php
$url = 'https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedules/render';
$scheduleIdToRender = 4;
$render = [
'scheduleId' => $scheduleIdToRender,
'includeSignatureImage' => true
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_POST, 1);
$data = json_encode($render, JSON_UNESCAPED_SLASHES);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Content-Length: ' . strlen($data)
]);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "someSecretUsername:someSecretPassword");
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
use File::Slurp;
use MIME::Base64;
eval {
my $scheduleToRender = 42;
my $data = {
'scheduleId' => $scheduleToRender,
'includeSignatureImage' => true
};
$data = JSON::XS->new->utf8->encode ($data);
my $url = 'https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedules/render';
my $req = HTTP::Request->new( 'POST', $url );
$req->authorization_basic( 'SomeSecretUsername', 'SomeSecretPassword' );
$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 $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
# read and encode pdf to upload
scheduleToRender = 55
data = {
'scheduleId' => scheduleToRender,
'includeSignatureImage' => true
}
c = Curl::Easy.new
c.url = 'https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedules/render'
c.http_auth_types = :basic
c.username = 'SomeSecretUsername'
c.password = 'SomeSecretPassword'
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
This will create an HTML representation of the requested Schedule.
Send an HTTP POST request to:
test url:
https://scheduledemo.pdc4u.com/ScheduleService/api/v1_0/schedules/render
live url:
https://schedule.pdc4u.com/ScheduleService/api/v1_0/schedules/render
Scoring Service API
Scoring Overview
Step 1: A PDCFlow integrator submits batch records to be scored via SOAP request. These records may be submitted by using a base64 encoded file or through a ScoringInputRecords object. Supported file formats are:
- Microsoft Excel (Note: Only XLS files are supported and not XLSX)
- Comma-Separated-Variable (CSV)
Step 2: At regular intervals, PDCFlow gathers the submitted batch records, prepares them, and sends the batch to the credit bureau. Once there, the bureau process will pick up the batch file and process or score each submitted record.
Step 4: Once the receiving bureau has processed/scored the batch, the credit bureau notifies PDCFlow the batch is ready to be picked up and delivered. PDCFlow then picks up the scored batch and persists the batch information to a database for later consumption.
Step 5: Once the batch information has been updated on the PDCFlow server, integrators are then able to inquire on any of the previously submitted records.
The following tables describe the different elements making up a Scoring SOAP request.
API Request
All elements must be present in the request, even if they are not essential to the ProcessingCommand action being performed. If an element is not required, just leave it blank. See the Sample Code.
ScoringRequest
ScoringRequest is the parent/top-level element of the incoming SOAP message.
| Attribute | Description |
|---|---|
|
MessageControl
|
Determines how the message information is handled upon receipt.
Constraint(s): See object definition below.
|
|
ScoringInputRecords
|
A list or array of ScoringInputRecord objects. When submitting a ScoringRequest, either ScoringInputRecords OR ScoringInputFile may be used to submit records.
|
|
ScoringInputFile
|
Embedded file within the SOAP message that holds records to be processed. When submitting a ScoringRequest, either ScoringInputRecords OR ScoringInputFile may be used to submit records.
Constraint(s): See object definition below.
|
MessageControl
The MessageControl element determines how the message information is handled upon receipt. All elements must be present.
| Attribute | Description |
|---|---|
|
ProcessingCommand
Alpha3
Required
|
Describes the type of request being made to the scoring service.
Valid value(s):
DWN - Requests a previously scored batch to be downloaded. STR - Requests a status of a previously uploaded batch. UPL - Upload a batch of records for scoring processing. TST - Requests validation of uploaded records only. No processing other than validation will be performed.
|
|
BureauReportType
Alphanumeric6
Required
|
Describes the type of scoring information to be returned for a particular batch.
TransUnion valid value(s) -
TRU001 Experian valid value(s) - EXP001, EXP002, EXP003, EXP004, EXP005, EXP006, EXP007 Note: These enumerations describe the different report options available from either TransUnion or Experian. For a more detailed description about what each report offers see documentation from the respective bureau. |
|
ReturnFileFormat
Alpha3
Conditional
|
Format that the batch download will be returned in.
Valid value(s):
XML
Constraint(s): Used when requesting a download
DWN request, left blank otherwise.
|
|
BatchID
Numeric18
Conditional
|
The batch ID.
Constraint(s): Used when requesting a download
DWN or a status STR request.
|
|
BatchOrigin
Alpha3
Required
|
Describes the origin of the batch of records to be scored by the bureau.
Valid value(s):
EXT |
|
DwnRecordStart
Date19
|
Used to control the starting record download point of the scored batch. Used in conjunction with the ProcessingCommand DWN.
Format: YYYY-MM-DD HH:mm:SS
|
|
DwnRecordCount
Date19
|
Used to control the ending record download point of the scored batch. Used in conjunction with the ProcessingCommand DWN.
Format: YYYY-MM-DD HH:mm:SS
|
ScoringInputRecord
This element is populated when uploading a scoring batch. Either this group of elements is used or the ScoringInputFile element is populated when uploading a batch, but NOT both.
| Attribute | Description |
|---|---|
|
LastName
Alpha32
Required
|
Last name of the individual. |
|
FirstName
Alpha32
Required
|
First name of the individual. |
|
Address1
Alphanumeric35
Required
|
Street address of the individual. |
|
Address2
Alphanumeric35
|
Extended address of the individual. |
|
City
Alpha32
Required
|
Name of the city. |
|
State
Alpha2
Required
|
Name of the state.
Format: two character abbreviation (UT, CA, MI, etc)
|
|
ZipCode
Numeric10
Required
|
Zip code.
Format: XXXXX or XXXXX-XXXX
|
|
Spouse
Deprecated
|
This element is deprecated. Though the element is not used, it must still be present in the request. |
|
SocialSecurityNumber
Numeric11
|
Social security number. While not required, this field is highly recommended to get valid information back from the bureau.
Format: XXXXXXXXX or XXX-XX-XXXX
|
|
AmountOwing
Numeric10
|
Amount owing.
Format: XXXX.XX
Do not use any formatting symbols such as the currency symbols ($), commas, etc. |
|
DateOfService
Date10
Required
|
Date of service.
Format: YYYYMMDD or YYYY-MM-DD
|
|
AccountReferenceNumber
Alphanumeric50
Required
|
Reference/ID value. This is often the customer account number from your system. |
ScoringInputFile
This element is used when submitting an XLS or CSV file as part of the ScoringRequest. Either this element is populated or the ScoringInputRecord group is used when uploading a batch, but NOT both.
| Attribute | Description |
|---|---|
|
FileName
AlphanumericN/A
|
Name of file with extension. |
|
FileContents
Base64N/A
Required
|
Base64 encoded batch file contents. |
Input file format
This section describes the file format when employing the ScoringInputFile upload model. The following table details and describes the columns of the XLS/CSV.
| Attribute | Description |
|---|---|
|
LAST_NAME
Alpha32
Required
|
Last name of the individual. |
|
FIRST_NAME
Alpha32
Required
|
First name of the individual. |
|
ADDRESS_1
Alphanumeric30
Required
|
Street address of the individual. |
|
ADDRESS_2
Alphanumeric30
|
Extended address of the individual. |
|
CITY
Alpha30
Required
|
Name of the city. |
|
STATE
Alpha2
Required
|
Name of the state.
Format: two character abbreviation (UT, CA, MI, etc)
|
|
ZIP
Numeric10
Required
|
Zip code. Format: XXXXX or XXXXX-XXXX
|
|
SPOUSE
Deprecated
|
This element is deprecated. The column must still be present, but left blank. |
|
SSN
Numeric11
|
Social security number. While not required, this field is highly recommended to get valid information back from the bureau.
Format: XXXXXXXXX or XXX-XX-XXXX
|
|
AMOUNT_OWING
Numeric10
|
Amount owing.
Format: XXXX.XX
Do not use any formatting symbols such as the currency symbols ($), commas, etc. |
|
DATE_OF_SERVICE
Date10
Required
|
Date of service.
Format: YYYYMMDD or YYYY-MM-DD
|
|
ACCT_REF_NUMBER
Alphanumeric50
Required
|
Reference/ID value. This is often the customer account number from your system. |
An OPTIONAL header row is allowed to be submitted along with the batch of records. If included, the column values must be named as follows:
- LAST_NAME
- FIRST_NAME
- ADDRESS_1
- ADDRESS_2
- CITY
- STATE
- ZIP
- SPOUSE - Though deprecated, this column must still be present.
- SSN
- AMOUNT_OWING
- DATE_OF_SERVICE
- ACCT_REF_NUMBER
API Result
ScoringResponse
The following table describes the different elements making up a ScoringResponse.
| Attribute | Description |
|---|---|
|
ScoringReturnFile
|
Populated with returned scoring file as received from the bureau.
Constraint(s): Returned in conjunction with the
ProcessingCommand DWN. When not using the ProcessingCommand DWN this element will be empty.
|
|
ValidationErrorList
Deprecated
|
This response object has been deprecated and will be returned empty. |
|
ExperianScoredRecords
|
Collection of Experian scored records returned in the SOAP return message. For information on Experian scoring results, please contact a developer on the API Forum. |
|
TransUnionScoredRecords
|
Collection of TransUnion scored records returned in the SOAP return message. For information on TransUnion scoring results, please contact a developer on the API Forum. |
|
BatchUploadResults
|
The results of the batch upload. |
|
BatchStatusResults
|
Shows the current status information of the batch. |
BatchUploadResults
This section describes the values returned when a ProcessingCommand of UPL is issued to the web service.
| Attribute | Description |
|---|---|
|
BatchID
Numeric18
|
Batch identification value assigned by PDCFlow when a batch is initially uploaded. This BatchID will be required when issuing a ProcessingCommand of STR or DWN
|
|
TotalRecordsSubmitted
Numeric11
|
Total number of records submitted. |
|
TotalRecordsAccepted
Numeric11
|
Total number of records accepted for processing. |
|
TotalRecordsRejected
Numeric11
|
Total number of records rejected due to validation errors. |
|
BatchArrivalDateTime
Date19
|
Timestamp when the batch was originally uploaded.
Format: YYYY-MM-DD HH:mm:SS
|
|
ValidationErrorList
Deprecated
|
This element has been deprecated, and will be returned empty. |
|
RejectedRecords
ObjectN/A
|
Collection of RejectedRecord objects. |
BatchStatusResults
This section describes the values returned when a ProcessingCommand of STR is issued to the web service.
| Attribute | Description |
|---|---|
|
BatchID
Numeric18
|
Batch identification value assigned by PDCFlow when a batch is initially uploaded. |
|
CompanyID
Numeric8
|
Company ID value previously assigned by PDCFlow. |
|
BureauType
Alphanumeric6
|
Describes the type of scoring information to be returned for a particular batch. |
|
BatchArrivalDateTime
Date19
|
Timestamp when the batch was originally uploaded.
Format: YYYY-MM-DD HH:mm:SS
|
|
TotalRecordsSubmitted
Numeric11
|
Total number of records submitted. |
|
TotalRecordsAccepted
Numeric11
|
Total numbers of records accepted for processing. |
|
TotalRecordsRejected
Numeric11
|
Total number of records rejected due to validation errors. |
|
BureauSubmissionDateTime
Date19
|
Timestamp when the batch was submitted by PDCFlow to the processing bureau.
Format: YYYY-MM-DD HH:mm:SS
|
|
BureauReturnedDateTime
Date19
|
Timestamp when the batch was received.
Format: YYYY-MM-DD HH:mm:SS
|
|
BatchCancelDateTime
Date19
|
Timestamp when the batch was canceled prior to bureau submission.
Format: YYYY-MM-DD HH:mm:SS
|
RejectedRecord
This section describes any rejected records discovered during batch validation. This is essentially a mirror of the uploaded record with the addition of a RecordErrors element used to supply detailed exception information.
| Attribute | Description |
|---|---|
|
LastName
Alpha32
|
Last name of the individual. |
|
FirstName
Alpha32
|
First name of the individual. |
|
Address1
Alphanumeric35
|
Street address of the individual. |
|
Address2
Alphanumeric35
|
Extended address of the individual. |
|
City
Alpha32
|
Name of the city. |
|
State
Alpha2
|
Name of the state.
Format: two character abbreviation (UT, CA, MI, etc)
|
|
ZipCode
Numeric10
|
Zip code.
Format: XXXXX or XXXXXXXXX
|
|
Spouse
Deprecated
|
This element is deprecated and will be returned empty. |
|
SocialSecurityNumber
Numeric11
|
Social security number.
Format: XXXXXXXXX
|
|
AmountOwing
Numeric10
|
Amount owing. Format: XXXX.XX
|
|
DateOfService
Date10
|
Date of service. Format: YYYY-MM-DD
|
|
AccountReferenceNumber
Alphanumeric50
|
This is often the customer account number from your system. |
|
RecordErrors
ObjectN/A
|
Collection of RecordError elements. |
RecordError
Object used to describe why a individual scoring record was rejected.
| Attribute | Description |
|---|---|
|
ErrorCode
Numeric4
|
PDCFlow error code representing the error. This will be described by ErrorDescription.
|
|
ErrorDescription
Alphanumeric172
|
Description of the validation error. |
Sample Code
Web Service Security
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-2" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:Username>SomeSecretUsername</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">SomeEvenMoreSecretPassword</wsse:Password>
<wsu:Created>2014-05-07T20:33:48.015Z</wsu:Created>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
........
Each SOAP scoring request submitted to PDCFlow must contain a security header as part of the message. This header is based on an established standard: Web Services Security - UsernameToken Profile 1.1. An example of this header is shown to the right.
See: http://docs.oasis-open.org/wss-m/wss/v1.1.1/os/wss-UsernameTokenProfile-v1.1.1-os.html
Upload a scoring batch via ScoringInputFile
<?php
//special handling to create a WSSE-compliant header
class WsseAuthHeader extends SoapHeader {
private $wss_ns = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd';
function __construct($user, $pass) {
$auth = new stdClass();
$auth->Username = new SoapVar($user, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$auth->Password = new SoapVar($pass, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$username_token = new stdClass();
$username_token->UsernameToken = new SoapVar($auth, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns);
$security_sv = new SoapVar(
new SoapVar($username_token, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns),
SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'Security', $this->wss_ns);
parent::__construct($this->wss_ns, 'Security', $security_sv, true);
}
}
// Get information for elements
$MessageControl = [
'ProcessingCommand' => 'TST',
'BureauReportType' => 'EXP001',
'ReturnFileFormat' => '',
'BatchID' => '',
'BatchOrigin' => 'EXT',
'DwnRecordStart' => '',
'DwnRecordCount' => ''
];
// Example CSV format file
$scoringFile = 'LAST_NAME,FIRST_NAME,ADDRESS_1,ADDRESS_2,CITY,STATE,ZIP,SPOUSE,SSN,AMOUNT_OWING,DATE_OF_SERVICE,ACCT_REF_NUMBER
Test,Adam,1234 Main St.,Apt. 7B,Ogden,UT,84404,,111-22-3333,5.5,2016-01-25,D123456ADBD12
Test II,Adam,1234 Main St.,Apt. 7B,Ogden,UT,84404,,222-33-4444,6.5,2016-01-25,D123456ADBD13
Test III,Adam,1234 Main St.,Apt. 7B,Ogden,UT,84404,,333-44-5555,7.5,2016-01-25,D123456ADBD14';
/*
* If uploading from a XLS file....
* $handle = fopen($_FILES["file"]["tmp_name"], "r"); // Open the temp file
* $scoringFile = fread($handle, filesize($_FILES["file"]["tmp_name"])); // Read the temp file
* fclose($handle);
*/
$ScoringInputFile = [
'FileName' => 'scoringUploadFile.csv',
'FileContents' => $scoringFile
];
//Request Parameters
$params = [
'MessageControl' => $MessageControl,
'ScoringInputRecords' => '',
'ScoringInputFile' => $ScoringInputFile
];
$url = 'https://wsscoringdemo.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl';
$namespace = 'http://www.pdc4u.com/scoring/ws/message/pdc-v1';
$method = 'Scoring';
$auth_header = new WsseAuthHeader('SomeSecretUsername', 'SomeSecretPassword');
$client = new SoapClient($url);
$client->__setSoapHeaders([$auth_header]);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
}
catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
use File::Slurp;
use MIME::Base64;
my $soap = SOAP::Lite
->readable(1) # nice for debugging
->autotype(0)
# Extract the targetNamespace from the .wsdl definitions for the desired method
->default_ns( 'http://www.pdc4u.com/scoring/ws/message/pdc-v1' )
->proxy( 'https://wsscoringdemo.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl' );
my $username = 'SomeSecretUsername';
my $password = 'SomeSecretPassword';
my $security = SOAP::Header->name("wsse:Security")->attr({
'xmlns:wsse' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'
});
my $userToken =SOAP::Header->name("wsse:UsernameToken" =>
\SOAP::Header->value(
SOAP::Header->name('wsse:Username')->value($username)->type(''),
SOAP::Header->name('wsse:Password')->value($password)->type('')->attr(
{'Type'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText'}))
)->attr({'xmlns:wsu'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'});
# Get information for elements
my %MessageControl = (
'ProcessingCommand' => 'TST',
'BureauReportType' => 'EXP001',
'ReturnFileFormat' => '',
'BatchID' => '',
'BatchOrigin' => 'EXT',
'DwnRecordStart' => '',
'DwnRecordCount' => ''
);
# Example CSV format file
my $scoringFile = 'LAST_NAME,FIRST_NAME,ADDRESS_1,ADDRESS_2,CITY,STATE,ZIP,SPOUSE,SSN,AMOUNT_OWING,DATE_OF_SERVICE,ACCT_REF_NUMBER
Test,Adam,1234 Main St.,Apt. 7B,Ogden,UT,84404,,111-22-3333,5.5,2016-01-25,D123456ADBD12
Test II,Adam,1234 Main St.,Apt. 7B,Ogden,UT,84404,,222-33-4444,6.5,2016-01-25,D123456ADBD13
Test III,Adam,1234 Main St.,Apt. 7B,Ogden,UT,84404,,333-44-5555,7.5,2016-01-25,D123456ADBD14';
# If uploading from a XLS file....
# my $xlsDocument = 'mydoc.xls';
# my $scoringFile = read_file( $xlsDocument );
my %ScoringInputFile = (
'FileName' => 'scoringUploadFile.csv',
'FileContents' => encode_base64($scoringFile, "") # encode without newlines
);
my %params = (
'MessageControl' => \%MessageControl,
'ScoringInputFile' => \%ScoringInputFile,
'ScoringInputRecords' => ''
);
my @data;
foreach my $key ( keys %params ) {
push @data, SOAP::Data->name( $key => $params{$key} );
}
print $soap->call( 'ScoringRequest', $security->value(\$userToken), @data )->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://wsscoringdemo.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
# Get information for elements
messageControl = {
'ins0:ProcessingCommand' => 'TST',
'ins0:BureauReportType' => 'EXP001',
'ins0:ReturnFileFormat' => '',
'ins0:BatchID' => '',
'ins0:BatchOrigin' => 'EXT',
'ins0:DwnRecordStart' => '',
'ins0:DwnRecordCount' => ''
};
# Example CSV format file
scoringFile = 'LAST_NAME,FIRST_NAME,ADDRESS_1,ADDRESS_2,CITY,STATE,ZIP,SPOUSE,SSN,AMOUNT_OWING,DATE_OF_SERVICE,ACCT_REF_NUMBER
Test,Adam,1234 Main St.,Apt. 7B,Ogden,UT,84404,,111-22-3333,5.5,2016-01-25,D123456ADBD12
Test II,Adam,1234 Main St.,Apt. 7B,Ogden,UT,84404,,222-33-4444,6.5,2016-01-25,D123456ADBD13
Test III,Adam,1234 Main St.,Apt. 7B,Ogden,UT,84404,,333-44-5555,7.5,2016-01-25,D123456ADBD14';
# If uploading from a XLS file....
# xlsDocument = 'mydoc.xls'
# file = File.open(xlsDocument, "rb")
# contents = file.read
# file.close
scoringInputFile = {
'ins0:FileName' => 'scoringUploadFile.csv',
'ins0:FileContents' => Base64.strict_encode64(scoringFile)
}
# Request Parameters
params = {
'ins0:MessageControl' => messageControl,
'ins0:ScoringInputRecords' => '',
'ins0:ScoringInputFile' => scoringInputFile
}
response = client.call(:scoring, message: params) do |locals|
locals.wsse_auth "SomeSecretUsername", "SomeSecretPassword"
end
puts response
rescue
puts "Caught: #$!\n"
end
This is an example on how to upload a batch to be scored using an XLS/CSV file.
Please note that the TST ProcessingCommand is used in place of UPL in the example code. If UPL is used, a batch will be scheduled to be scored an no more testing can be done until it has been scored.
The wsdl to use for sending a scoring request is:
test wsdl:
https://wsscoringdemo.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl
live wsdl:
https://wsscoring.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl
The namespace to use is:
http://www.pdc4u.com/scoring/ws/message/pdc-v1
The method to use is:
Scoring
Upload a scoring batch via ScoringInputRecords
<?php
//special handling to create a WSSE-compliant header
class WsseAuthHeader extends SoapHeader {
private $wss_ns = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd';
function __construct($user, $pass) {
$auth = new stdClass();
$auth->Username = new SoapVar($user, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$auth->Password = new SoapVar($pass, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$username_token = new stdClass();
$username_token->UsernameToken = new SoapVar($auth, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns);
$security_sv = new SoapVar(
new SoapVar($username_token, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns),
SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'Security', $this->wss_ns);
parent::__construct($this->wss_ns, 'Security', $security_sv, true);
}
}
// Get information for elements
$MessageControl = [
'ProcessingCommand' => 'TST',
'BureauReportType' => 'EXP001',
'ReturnFileFormat' => '',
'BatchID' => '',
'BatchOrigin' => 'EXT',
'DwnRecordStart' => '',
'DwnRecordCount' => ''
];
// For ScoringInputRecords
$ScoringInputRecord1 = [
'LastName' => 'Test',
'FirstName' => 'Adam',
'Address1' => '1234 Main St.',
'Address2' => 'Apt. 7B',
'City' => 'Ogden',
'State' => 'UT',
'ZipCode' => '84404',
'Spouse' => '',
'SocialSecurityNumber' => '111-22-3333',
'AmountOwing' => '5.50',
'DateOfService' => '2016-11-23',
'AccountReferenceNumber' => 'D173492343F'
];
$ScoringInputRecord2 = [
'LastName' => 'Test II',
'FirstName' => 'Adam',
'Address1' => '1234 Main St.',
'Address2' => 'Apt. 7B',
'City' => 'Ogden',
'State' => 'UT',
'Spouse' => '',
'ZipCode' => '84404',
'SocialSecurityNumber' => '222-33-4444',
'AmountOwing' => '6.50',
'DateOfService' => '2016-11-23',
'AccountReferenceNumber' => 'D173492343F'
];
$ScoringInputRecord3 = [
'LastName' => 'Test III',
'FirstName' => 'Adam',
'Address1' => '1234 Main St.',
'Address2' => 'Apt. 7B',
'City' => 'Ogden',
'State' => 'UT',
'Spouse' => '',
'ZipCode' => '84404',
'SocialSecurityNumber' => '333-44-5555',
'AmountOwing' => '7.50',
'DateOfService' => '2016-11-23',
'AccountReferenceNumber' => 'D17349233423F'
];
// Assemble all the individual scoring records into a list
$ScoringInputRecords = [
$ScoringInputRecord1,
$ScoringInputRecord2,
$ScoringInputRecord3
];
//Request Parameters
$params = [
'MessageControl' => $MessageControl,
'ScoringInputRecords' => $ScoringInputRecords,
'ScoringInputFile' => [
'FileName' => '',
'FileContents' => ''
]
];
$url = 'https://wsscoringdemo.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl';
$namespace = 'http://www.pdc4u.com/scoring/ws/message/pdc-v1';
$method = 'Scoring';
$auth_header = new WsseAuthHeader('SomeSecretUsername', 'SomeSecretPassword');
$client = new SoapClient($url);
$client->__setSoapHeaders([$auth_header]);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
}
catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
use File::Slurp;
my $soap = SOAP::Lite
->readable(1) # nice for debugging
->autotype(0)
# Extract the targetNamespace from the .wsdl definitions for the desired method
->default_ns( 'http://www.pdc4u.com/scoring/ws/message/pdc-v1' )
->proxy( 'https://wsscoringdemo.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl' );
my $username = 'SomeSecretUsername';
my $password = 'SomeSecretPassword';
my $security = SOAP::Header->name("wsse:Security")->attr({
'xmlns:wsse' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'
});
my $userToken =SOAP::Header->name("wsse:UsernameToken" =>
\SOAP::Header->value(
SOAP::Header->name('wsse:Username')->value($username)->type(''),
SOAP::Header->name('wsse:Password')->value($password)->type('')->attr(
{'Type'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText'}))
)->attr({'xmlns:wsu'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'});
# Get information for elements
my %MessageControl = (
'ProcessingCommand' => 'TST',
'BureauReportType' => 'EXP001',
'ReturnFileFormat' => '',
'BatchID' => '',
'BatchOrigin' => 'EXT',
'DwnRecordStart' => '',
'DwnRecordCount' => ''
);
# For ScoringInputRecords
my %ScoringInputRecord1 = (
'LastName' => 'Test',
'FirstName' => 'Adam',
'Address1' => '1234 Main St.',
'Address2' => 'Apt. 7B',
'City' => 'Ogden',
'State' => 'UT',
'ZipCode' => '84404',
'Spouse' => '',
'SocialSecurityNumber' => '111-22-3333',
'AmountOwing' => '5.50',
'DateOfService' => '2016-11-23',
'AccountReferenceNumber' => 'D173492343F'
);
my %ScoringInputRecord2 = (
'LastName' => 'Test II',
'FirstName' => 'Adam',
'Address1' => '1234 Main St.',
'Address2' => 'Apt. 7B',
'City' => 'Ogden',
'State' => 'UT',
'Spouse' => '',
'ZipCode' => '84404',
'SocialSecurityNumber' => '222-33-4444',
'AmountOwing' => '6.50',
'DateOfService' => '2016-11-23',
'AccountReferenceNumber' => 'D173492343F'
);
my %ScoringInputRecord3 = (
'LastName' => 'Test III',
'FirstName' => 'Adam',
'Address1' => '1234 Main St.',
'Address2' => 'Apt. 7B',
'City' => 'Ogden',
'State' => 'UT',
'Spouse' => '',
'ZipCode' => '84404',
'SocialSecurityNumber' => '333-44-5555',
'AmountOwing' => '7.50',
'DateOfService' => '2016-11-23',
'AccountReferenceNumber' => 'D17349233423F'
);
# Request Parameters
my %params = (
'MessageControl' => \%MessageControl,
'ScoringInputRecords' => \SOAP::Data->value(
SOAP::Data->name('ScoringInputRecord' => \%ScoringInputRecord1),
SOAP::Data->name('ScoringInputRecord' => \%ScoringInputRecord2),
SOAP::Data->name('ScoringInputRecord' => \%ScoringInputRecord3),
),
'ScoringInputFile' => {
'FileName' => '',
'FileContents' => ''
}
);
my @data;
foreach my $key ( keys %params ) {
push @data, SOAP::Data->name( $key => $params{$key} );
}
print $soap->call( 'ScoringRequest', $security->value(\$userToken), @data )->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://wsscoringdemo.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
# Get information for elements
messageControl = {
'ins0:ProcessingCommand' => 'TST',
'ins0:BureauReportType' => 'EXP001',
'ins0:ReturnFileFormat' => '',
'ins0:BatchID' => '',
'ins0:BatchOrigin' => 'EXT',
'ins0:DwnRecordStart' => '',
'ins0:DwnRecordCount' => ''
}
# For ScoringInputRecords
scoringInputRecord1 = {
'ins0:LastName' => 'Test',
'ins0:FirstName' => 'Adam',
'ins0:Address1' => '1234 Main St.',
'ins0:Address2' => 'Apt. 7B',
'ins0:City' => 'Ogden',
'ins0:State' => 'UT',
'ins0:ZipCode' => '84404',
'ins0:Spouse' => '',
'ins0:SocialSecurityNumber' => '111-22-3333',
'ins0:AmountOwing' => '5.50',
'ins0:DateOfService' => '2016-11-23',
'ins0:AccountReferenceNumber' => 'D173492343F'
}
scoringInputRecord2 = {
'ins0:LastName' => 'Test II',
'ins0:FirstName' => 'Adam',
'ins0:Address1' => '1234 Main St.',
'ins0:Address2' => 'Apt. 7B',
'ins0:City' => 'Ogden',
'ins0:State' => 'UT',
'ins0:Spouse' => '',
'ins0:ZipCode' => '84404',
'ins0:SocialSecurityNumber' => '222-33-4444',
'ins0:AmountOwing' => '6.50',
'ins0:DateOfService' => '2016-11-23',
'ins0:AccountReferenceNumber' => 'D173492343F'
}
scoringInputRecord3 = {
'ins0:LastName' => 'Test III',
'ins0:FirstName' => 'Adam',
'ins0:Address1' => '1234 Main St.',
'ins0:Address2' => 'Apt. 7B',
'ins0:City' => 'Ogden',
'ins0:State' => 'UT',
'ins0:Spouse' => '',
'ins0:ZipCode' => '84404',
'ins0:SocialSecurityNumber' => '333-44-5555',
'ins0:AmountOwing' => '7.50',
'ins0:DateOfService' => '2016-11-23',
'ins0:AccountReferenceNumber' => 'D17349233423F'
}
# Request Parameters
params = {
'ins0:MessageControl' => messageControl,
'ins0:ScoringInputRecords' => {
'ins0:ScoringInputRecord' => [
scoringInputRecord1,
scoringInputRecord2,
scoringInputRecord3
],
},
'ins0:ScoringInputFile' => {
'ins0:FileName' => '',
'ins0:FileContents' => ''
}
}
response = client.call(:scoring, message: params) do |locals|
locals.wsse_auth "SomeSecretUsername", "SomeSecretPassword"
end
puts response
rescue
puts "Caught: #$!\n"
end
This is an example on how to upload a batch to be scored using a collection of ScoringInputRecord objects.
Please note that the TST ProcessingCommand is used in place of UPL in the example code. If UPL is used, a batch will be scheduled to be scored an no more testing can be done until it has been scored.
The wsdl to use for sending a scoring request is:
test wsdl:
https://wsscoringdemo.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl
live wsdl:
https://wsscoring.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl
The namespace to use is:
http://www.pdc4u.com/scoring/ws/message/pdc-v1
The method to use is:
Scoring
Check the status of a previously uploaded batch file
<?php
//special handling to create a WSSE-compliant header
class WsseAuthHeader extends SoapHeader {
private $wss_ns = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd';
function __construct($user, $pass) {
$auth = new stdClass();
$auth->Username = new SoapVar($user, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$auth->Password = new SoapVar($pass, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$username_token = new stdClass();
$username_token->UsernameToken = new SoapVar($auth, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns);
$security_sv = new SoapVar(
new SoapVar($username_token, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns),
SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'Security', $this->wss_ns);
parent::__construct($this->wss_ns, 'Security', $security_sv, true);
}
}
// Get information for elements
$MessageControl = [
'ProcessingCommand' => 'STR',
'BureauReportType' => 'EXP001',
'ReturnFileFormat' => '',
'BatchID' => '00001234.012345678',
'BatchOrigin' => 'EXT',
'DwnRecordStart' => '',
'DwnRecordCount' => ''
];
$params = [
'MessageControl' => $MessageControl,
'ScoringInputFile' => '',
'ScoringInputRecords' => ''
];
$url = 'https://wsscoringdemo.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl';
$namespace = 'http://www.pdc4u.com/scoring/ws/message/pdc-v1';
$method = 'Scoring';
$auth_header = new WsseAuthHeader('SomeSecretUsername', 'SomeSecretPassword');
$client = new SoapClient($url);
$client->__setSoapHeaders([$auth_header]);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
}
catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
my $soap = SOAP::Lite
->readable(1) # nice for debugging
->autotype(0)
# Extract the targetNamespace from the .wsdl definitions for the desired method
->default_ns( 'http://www.pdc4u.com/scoring/ws/message/pdc-v1' )
->proxy( 'https://wsscoringdemo.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl' );
my $username = 'SomeSecretUsername';
my $password = 'SomeSecretPassword';
my $security = SOAP::Header->name("wsse:Security")->attr({
'xmlns:wsse' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'
});
my $userToken =SOAP::Header->name("wsse:UsernameToken" =>
\SOAP::Header->value(
SOAP::Header->name('wsse:Username')->value($username)->type(''),
SOAP::Header->name('wsse:Password')->value($password)->type('')->attr(
{'Type'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText'}))
)->attr({'xmlns:wsu'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'});
# Get information for elements
my %MessageControl = (
'ProcessingCommand' => 'STR',
'BureauReportType' => 'EXP001',
'ReturnFileFormat' => '',
'BatchID' => '00001234.012345678',
'BatchOrigin' => 'EXT',
'DwnRecordStart' => '',
'DwnRecordCount' => ''
);
my %params = (
'MessageControl' => \%MessageControl,
'ScoringInputFile' => '',
'ScoringInputRecords' => ''
);
my @data;
foreach my $key ( keys %params ) {
push @data, SOAP::Data->name( $key => $params{$key} );
}
print $soap->call( 'ScoringRequest', $security->value(\$userToken), @data )->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://wsscoringdemo.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
# Get information for elements
messageControl = {
'ins0:ProcessingCommand' => 'STR',
'ins0:BureauReportType' => 'EXP001',
'ins0:ReturnFileFormat' => '',
'ins0:BatchID' => '00001234.012345678',
'ins0:BatchOrigin' => 'EXT',
'ins0:DwnRecordStart' => '',
'ins0:DwnRecordCount' => ''
}
params = {
'ins0:MessageControl' => messageControl,
'ins0:ScoringInputFile' => '',
'ins0:ScoringInputRecords' => ''
}
response = client.call(:scoring, message: params) do |locals|
locals.wsse_auth "SomeSecretUsername", "SomeSecretPassword"
end
puts response
rescue
puts "Caught: #$!\n"
end
This is an example on how to check the status of a previously uploaded batch.
A batch is identified by the BatchID that was returned in the BatchUploadResults object.
The wsdl to use for sending a scoring request is:
test wsdl:
https://wsscoringdemo.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl
live wsdl:
https://wsscoring.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl
The namespace to use is:
http://www.pdc4u.com/scoring/ws/message/pdc-v1
The method to use is:
Scoring
Download
<?php
//special handling to create a WSSE-compliant header
class WsseAuthHeader extends SoapHeader {
private $wss_ns = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd';
function __construct($user, $pass) {
$auth = new stdClass();
$auth->Username = new SoapVar($user, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$auth->Password = new SoapVar($pass, XSD_STRING, NULL, $this->wss_ns, NULL, $this->wss_ns);
$username_token = new stdClass();
$username_token->UsernameToken = new SoapVar($auth, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns);
$security_sv = new SoapVar(
new SoapVar($username_token, SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'UsernameToken', $this->wss_ns),
SOAP_ENC_OBJECT, NULL, $this->wss_ns, 'Security', $this->wss_ns);
parent::__construct($this->wss_ns, 'Security', $security_sv, true);
}
}
// Get information for elements
$MessageControl = [
'ProcessingCommand' => 'DWN',
'BureauReportType' => 'EXP002',
'ReturnFileFormat' => 'XML',
'BatchID' => '00001234.012345678',
'BatchOrigin' => 'EXT',
'DwnRecordStart' => '',
'DwnRecordCount' => ''
];
$params = [
'MessageControl' => $MessageControl,
'ScoringInputFile' => '',
'ScoringInputRecords' => ''
];
$url = 'https://wsscoringdemo.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl';
$namespace = 'http://www.pdc4u.com/scoring/ws/message/pdc-v1';
$method = 'Scoring';
$auth_header = new WsseAuthHeader('SomeSecretUsername', 'SomeSecretPassword');
$client = new SoapClient($url);
$client->__setSoapHeaders([$auth_header]);
try {
$response = $client->__soapCall(
$method,
[$params, $namespace]
);
print_r($response);
}
catch (SoapFault $fault) {
print_r($fault);
}
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
my $soap = SOAP::Lite
->readable(1) # nice for debugging
->autotype(0)
# Extract the targetNamespace from the .wsdl definitions for the desired method
->default_ns( 'http://www.pdc4u.com/scoring/ws/message/pdc-v1' )
->proxy( 'https://wsscoringdemo.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl' );
my $username = 'SomeSecretUsername';
my $password = 'SomeSecretPassword';
my $security = SOAP::Header->name("wsse:Security")->attr({
'xmlns:wsse' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'
});
my $userToken =SOAP::Header->name("wsse:UsernameToken" =>
\SOAP::Header->value(
SOAP::Header->name('wsse:Username')->value($username)->type(''),
SOAP::Header->name('wsse:Password')->value($password)->type('')->attr(
{'Type'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText'}))
)->attr({'xmlns:wsu'=>'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'});
# Get information for elements
my %MessageControl = (
'ProcessingCommand' => 'DWN',
'BureauReportType' => 'EXP002',
'ReturnFileFormat' => 'XML',
'BatchID' => '00001234.012345678',
'BatchOrigin' => 'EXT',
'DwnRecordStart' => '',
'DwnRecordCount' => ''
);
my %params = (
'MessageControl' => \%MessageControl,
'ScoringInputFile' => '',
'ScoringInputRecords' => ''
);
my @data;
foreach my $key ( keys %params ) {
push @data, SOAP::Data->name( $key => $params{$key} );
}
print $soap->call( 'ScoringRequest', $security->value(\$userToken), @data )->result;
#!/usr/bin/ruby
require 'savon' # version 2.0
begin
# create a client for the service
client = Savon.client(wsdl: 'https://wsscoringdemo.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl',
log_level: :debug,
log: true,
pretty_print_xml: true)
puts "Available operations: "
client.operations.each { |x| puts " #{x}", "\n" } # find which operations are supported
# Get information for elements
messageControl = {
'ins0:ProcessingCommand' => 'DWN',
'ins0:BureauReportType' => 'EXP002',
'ins0:ReturnFileFormat' => 'XML',
'ins0:BatchID' => '00001234.012345678',
'ins0:BatchOrigin' => 'EXT',
'ins0:DwnRecordStart' => '',
'ins0:DwnRecordCount' => ''
}
params = {
'ins0:MessageControl' => messageControl,
'ins0:ScoringInputFile' => '',
'ins0:ScoringInputRecords' => ''
}
response = client.call(:scoring, message: params) do |locals|
locals.wsse_auth "SomeSecretUsername", "SomeSecretPassword"
end
puts response
rescue
puts "Caught: #$!\n"
end
This is an example on how to request a scored batch and have it returned in the form of XML.
A batch is identified by the BatchID that was returned in the BatchUploadResults object.
The wsdl to use for sending a scoring request is:
test wsdl:
https://wsscoringdemo.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl
live wsdl:
https://wsscoring.pdc4u.com/pdcscoring/scoringwebservices/scoringService/scoring.wsdl
The namespace to use is:
http://www.pdc4u.com/scoring/ws/message/pdc-v1
The method to use is:
Scoring
Secure Overlay API
The Secure Overlay is a way for PDCflow customers/partners to easily process credit card payments from their own sites/software without PCI Compliance concerns.
It provides a tight integration between account management software and PDCflow’s Payment Processing Products and takes the core software platform out of PCI Scope. Enter payment information (credit card data) from within your software system using our secure overlay form. The sensitive credit and/or debit card data fields reside on our secure, PCI Level 1 Certified servers, and overlays the data entry field on the core software’s payment page.
Sensitive Card Data is encrypted, tokenized, and stored in a secure vault. The token is then returned to your software system through the webservices, eliminating your transmission of any PCI relevant data.
Implementation
Your HTML page
The secure overlay uses the HTML5 postMessage() protocol. This allows messages to be posted from the parent website (your page) to the iframe and back. Thus, when the Credit Card number, entered on our page, can be tokenized and the token can be returned to your page.
Add the javascript to the bottom of your HTML.
Add an <iframe> element in the <body> of your HTML that will contain the secure input field. The src of the iframe will be “https://wsdemo.pdc4u.com/SecureOverlay/” for testing. Live integration will be “https://ws.pdc4u.com/SecureOverlay/”
<script type="text/javascript">
...
window.addEventListener("message", receiveMessage, false);
function receiveMessage(event) {
//Here we want to confirm that any messages received originate from the iframe
if (event.origin !== "https://wsdemo.pdc4u.com") {
return;
}
switch (event.data.function) {
case "PRELOAD":
//Handle any preload data (if you already have a token, pass it here)
break;
case "RESPONSE":
//Handle the response from tokenizing the credit card
break;
}
}
function postRequiredData() {
var requiredData = {};
...
document.getElementById("iframeId").contentWindow.postMessage(requiredData, "https://wsdemo.pdc4u.com");
}
...
</script>
Add a listener to listen for messages posted from the iframe, and the function to call when these messages are received. These posts will be from the domain “https://wsdemo.pdc4u.com” (testing) or from “https://ws.pdc4u.com” (live). Also, add the function to post the required data to the iframe. If you are receiving an error similar to “Cookies must be turned on to process a payment.”, verify that you are allowing cookies to be set from these two domains.
Script Variable Definitions
| Attribute | Description |
|---|---|
|
preloadData
JSONN/A
|
Will preload the input field with whatever data is returned in the token field. Also allows basic style options. See object definition below.
|
|
processData
JSONN/A
|
The data and command to tokenize, posted to the iframe. See object definition below. |
|
clear
JSONN/A
|
Will clear all characters in the input field. See object definition below. |
|
preloadReceival
|
The iframe will post a message when it is ready to receive a preload message. See object definition below. |
|
responseReceival
|
The iframe will post a message with the reponse data when it has finished tokenizing the card. See object definition below. |
Preload Data
| Attribute | Description |
|---|---|
|
backgroundColor
AlphanumericN/A
|
Set the background color of the input field using a CSS color.
Format: Text (red, blue), Hexadecimal (#RRGGBB), RGB (rgb(255,0,0))
|
|
fontSize
AlphanumericN/A
|
Set the size of the font in the input box. Append the unit to the font size (12px, 2em, 12pt, etc).
Format: 12px
|
|
token
Alphanumeric16
|
An existing token to prepopulate the field with. |
|
focus
Boolean5
|
Whether or not to set focus to the input field on page load. If you preload the token, it is not recommended that you focus on the field, as that will clear the preloaded token.
Valid value(s):
true, false |
|
function
Alpha7
|
The function to be performed by the remote javascript.
Valid value(s): PRELOAD
|
Process Data
| Attribute | Description |
|---|---|
|
apiKey
AlphanumericN/A
|
Your PDCFlow APIKey for tokenizing data.
|
|
companyId
Numeric8
|
Your PDCFlow Company Id. |
|
dataType
Alpha3
|
The type of data you are tokenizing.
Valid value(s): CCN
|
|
ccExpMonth
Numeric2
|
The expiration month of the card.
Format: MM
|
|
ccExpYear
Numeric4
|
The expiration year of the card.
Format: YYYY
|
|
function
Alpha7
|
The function to be performed by the remote javascript.
Valid value(s): PROCESS
|
Clear
| Attribute | Description |
|---|---|
|
function
Alpha5
|
The function to be performed by the remote javascript.
Valid value(s): CLEAR
|
Post Message Receival
These are the definitions of the objects the integrated website can expect to receive in a posted message.
Preload Receival
| Attribute | Description |
|---|---|
|
function
Alpha7
|
The function that should be handled by the integrating website. When this message is received, the iframe is loaded and ready to handle a postMessage with the preloadData.
Valid value(s): PRELOAD
|
Error Receival
| Attribute | Description |
|---|---|
|
errorMsg
AlphanumericN/A
|
The error message pertaining to a failed tokenization request. |
|
function
Alpha8
|
The function to be performed by the remote javascript.
Valid value(s):
ERROR |
Response Receival
| Attribute | Description |
|---|---|
|
token
Alphanumeric16
|
The token that represents the encrypted data in the PDCFlow system. |
|
cardType
Alpha15
|
The type of card number that was tokenized.
Valid value(s): VISA, MASTERCARD, DISCOVERY, AMERICAN_EXPRESS, UNKNOWN
|
|
mask
Numeric10
|
The mask for the card number that was tokenized. This consists of the first 6 numbers and the last 4 numbers of the card. |
|
result
Alpha7
|
The result of the tokenization request. PRELOAD will be returned only if an existing token was preloaded and was not overwritten with a new card number.
Valid value(s): OK, ERROR, PRELOAD
|
|
errorMsg
AlphanumericN/A
|
The error message pertaining to a failed tokenization request. |
|
function
Alpha8
|
The function to be performed by the remote javascript.
Valid value(s): RESPONSE
|
Sample Code
<!DOCTYPE html>
<html lang="en">
<head>
<title>Payment</title>
<meta charset="utf-8"/>
</head>
<body>
<div class="container">
<div class="ccPayment">
<iframe id="iframeId" src="https://wsdemo.pdc4u.com/SecureOverlay/"></iframe>
<input type="tel" id="expMonth" placeholder="Expiration Month" />
<input type="tel" id="expYear" placeholder="Expiration Year" />
<button id="nextButton" onclick="processPayment()">Process</button>
</div>
</div>
<script type="text/javascript">
window.addEventListener("message", receiveMessage, false);
var remoteDomain = "https://wsdemo.pdc4u.com";
function receiveMessage(event) {
if (event.origin !== remoteDomain) {
return;
}
switch (event.data.function) {
case "PRELOAD":
var styleOptions = {};
styleOptions.backgroundColor = "#ccc";
styleOptions.fontSize="14px";
styleOptions.function = "PRELOAD";
document.getElementById("iframeId").contentWindow.postMessage(styleOptions, remoteDomain);
break;
case "RESPONSE":
if (event.data.errorMsg) {
alert("error: " + event.data.errorMsg);
}
console.log("token: " + event.data.token);
case "ERROR":
if (event.data.errorMsg) {
alert("error: " + event.data.errorMsg);
}
console.log("error: " + event.data.errorMsg);
break;
}
}
function processPayment() {
var data = {};
data.dataType = "CCN";
data.ccExpMonth = document.getElementById("expMonth").value;
data.ccExpYear = document.getElementById("expYear").value;
data.apiKey = "replaceWithRealApiKeyForTest";
data.companyId = "replaceWithRealCompanyId";
data.function = "PROCESS";
document.getElementById("iframeId").contentWindow.postMessage(data, remoteDomain);
}
</script>
</body>
</html>
Here is a sample HTML page that has all of the code required to interact with the Secure Overlay API. It contains the complete Javascript code as well as a test form that includes additional fields other than the Secure Overlay field.
Signature Service API
The signature service allows easy integration of sending requests for signatures, payments, documents, and image uploads. Integrators are also able to retrieve previously sent signatures and create transaction reports on previous requests. All requests are made through common HTTP POST, GET, PUT requests.
Authentication will be done with a Base64 encoded username:password, passed in through the BASIC HTTP Authorization Header.
If the request cannot be delivered by the requested method (email or text message), the integrator will receive an HTTP error 500 with a RequestErrorList containing an ERR type RequestError. The request will thus be treated as a failed request and will not be stored for future reporting or retrieval.
Signature
test endpoint: https://wssignaturedemo.pdc4u.com/SignatureService/api/v2_0/signatures
live endpoint: https://wssignature.pdc4u.com/SignatureService/api/v2_0/signatures
POST to the signature endpoint to send a request though email, text, or both.
GET to retrieve a previous signature.
PUT to modify a previous signature.
| Attribute | Description |
|
signatureId
Numeric20
|
The id of the signature request. |
|
firstName
Alphanumeric45
Required
|
The first name of your client. |
|
lastName
Alphanumeric45
Required
|
The last name of your client. |
|
emailAddress
Alphanumeric65
|
The email address to send the request to. Sending both emailAddress and mobileNumber will send the request to both.
|
|
mobileNumber
Numeric15
|
The phone number to send request to. Sending both emailAddress and mobileNumber will send the request to both.
Format: With country code
|
|
username
Alphanumeric65
Conditional
|
Username or email of the employee sending this request.
Constraint(s): Required for modification (
PUT) requests.
|
|
description
Alphanumeric160
Conditional
|
Description of what the signature is for. Will show with the signature.
Constraint(s): Only required with standalone signature.
|
|
verificationPin
Numeric8
Required
|
Shared secret for client verification.
Constraint(s): Must be between 4 and 8 digits long.
|
|
pinDescription
Alphanumeric50
Required
|
Description of the verificationPin.
|
|
maxPinAttempts
Numeric2
|
Maximum amount of attempts the client is allowed for verification before transaction is locked.
Default: 3
|
|
requestGeolocation
Boolean5
|
Request the geolocation from the client.
Constraint(s): Client can refuse to share location, preventing capture.
Valid value(s):
true, falseDefault: true
|
|
timeoutMinutes
Numeric6
|
Number of minutes client has to complete the transaction before it expires.
Default: 2 if a payment is included, otherwise 3
|
|
redirectLink
URL65
|
A URL link to direct client to, after signature is complete. |
|
customMessage
AlphaNumeric320
|
Free form text to display at the end of the transaction. |
|
payment
PaymentN/A
|
Data for payment request.
Constraint(s): See object definition below.
|
|
document
DocumentN/A
|
Data for document presentation.
Constraint(s): Document must be uploaded through
POST to Document endpoint, then resultant documentId specified here. See object definition below.
|
|
imageUpload
ImageUploadN/A
|
Information for image upload.
Constraint(s): See object definition below.
|
|
companyOverride
CompanyOverrideN/A
|
Data for overriding company information.
Constraint(s): See object definition below.
|
|
standaloneSignatureRequested
Boolean5
|
Whether standalone signature is desired or not.
Valid value(s):
true, falseDefault: true
|
|
transactionOrigin
String3
|
The origin of the transaction request.
Valid value(s):
EXT |
|
templateName
String50
|
The name of the template used for this request. Can be used to associate similar requests together. |
|
completionDate
Date25
|
The date and time the full request was completed.
Format: ISO-8601 (YYYY-MM-DD HH:mm:ss)
|
|
signatureReceivedDate
Date25
|
The date and time the signature was stored on our system.
Format: ISO-8601 (YYYY-MM-DD HH:mm:ss)
|
|
signatureReceivedTimezone
Numeric5
|
The timezone in which the signature was signed.
Format: GMT Offset
|
|
signatureClosed
Boolean5
|
Whether or not a the transaction was closed. Either all parts of the transaction were completed or an error occurred.
Valid value(s):
true, false |
|
modificationCode
Alpha5
Required
|
The modification to make on the transaction.
Valid value(s):
CLOSE |
|
postbackUrl
URL500
|
A URL to POST completed signature data to.
Constraint(s): Must be SSL (HTTPS)
POSTed data may include:signatureId, completionDate, errorCode, errorMessage |
|
customSmsMessage
AlphaNumeric640
|
A message to send in the text request, along with the signature link. If this is part of the request, ONLY this text and the signature link will be sent to the mobileNumber.
|
|
customEmailBody
AlphaNumeric60,000
Conditional
|
Text to include in the email request, above the signature link. If this is part of the request, ONLY this text, the signature link, and the customEmailFooter will be sent to the emailAddress.
Constraint(s): Required if the
customEmailFooter is also requested.
|
|
customEmailFooter
AlphaNumeric60,000
|
Text to include in the email request, below the signature link. If this is part of the request, ONLY the customEmailBody, the signature link, and this text will be sent to the emailAddress. |
|
errorCode
Alpha3
|
Code if an error occurred with the signature. |
|
errorMessage
Alphanumeric160
|
An explanation message for the error that occurred.
Constraint(s): Will only show if an
errorCode is present.
|
|
roundTripNVPS
ListN/A
|
List of roundTripNVP objects. These are Name/Value pass-through values.
Constraint(s): Max of 10
roundTripNVP objects per request. See object definition below.
|
|
pageOrder
List-AlphaN/A
|
A list of page enum values to define the order in which the receiver will view the pages of the request.
Constraint(s): Only pages for requested functionality can be included.
Valid value(s):
PG_DOC, PG_IMG, PG_SIG, PG_PAYDefault: PG_DOC, PG_IMG, PG_SIG, PG_PAY
|
|
requestedDate
Date25
|
Date and time the transaction was requested.
Format: ISO-8601 (YYYY-MM-DD HH:mm:ss)
|
|
expirationDate
Date25
|
Date and time the transaction will expire. Based on the requestedDate and timeoutMinutes.
Format: ISO-8601 (YYYY-MM-DD HH:mm:ss)
|
|
signatureImage
Base64N/A
|
Base64 encoded signature image in .png format. |
|
textSuccessful
Boolean5
|
Whether the text was successfully sent to the client.
Valid value(s):
true, false |
|
emailSuccessful
Boolean5
|
Whether the email was successfully sent to the client.
Valid value(s):
true, false |
|
signatureUrl
Alphanumeric160
|
The URL sent to the recipient to complete the signature request. |
|
status
Alpha9
|
The current status of the request. For requests sent prior to June 2019, this field may be empty.
Valid value(s):
PENDING - The request has been sent.OPEN - A valid PIN has been entered on the request, but the request has not been completed.COMPLETED - The request has been successfully completed.FAILED - The request has failed. This can be due to the document being denied, the request being manually closed, etc. An errorCode and errorMessage will provide the reason for the failure.EXPIRED - The request has exceeded the timeoutMinutes and cannot be completed. |
|
statusDate
Date25
|
The date that the current status happened. For an EXPIRED status, this will be the date the request expired. For requests sent prior to June 2019, this field may be empty.
Format: ISO-8601 (YYYY-MM-DD HH:mm:ss)
|
|
componentList
ListN/A
|
List of related Component objects. See object definition below. READONLY
|
|
emailAttemptList
ListN/A
|
List of related EmailAttempt objects. See object definition below. READONLY
|
ReportParameters
test endpoint: https://wssignaturedemo.pdc4u.com/SignatureService/api/v2_0/signatures
live endpoint: https://wssignature.pdc4u.com/SignatureService/api/v2_0/signatures
GET to retrieve a list of signature transactions. URL encode all values for request.
| Attribute | Description |
|
startDate
Date25
|
The starting date for the report range.
Format: URL Encoded ISO-8601
Default: 2016-01-01+00:00:00
|
|
endDate
Date25
|
The ending date for the report range.
Format: URL Encoded ISO-8601
Default: Current Date
|
|
firstName
Alpha45
|
The first name to filter the report results by. Adding a “%” to the end of the name will allow wildcard search. |
|
lastName
Alpha45
|
The last name to filter the report results by. Adding a “%” to the end of the name will allow wildcard search. |
|
recordStart
Numeric20
|
The record count to start on.
Default: 0
|
|
recordCount
Numeric4
|
How many records to return.
Default: 2000
Maximum: 5000
|
|
retrieveOnlyCompletedRequests
Boolean5
|
Whether to retrieve only signature requests that have been closed.
Valid value(s):
true, falseDefault: false
|
|
reportType
Alpha14
Required
|
What type of report to retrieve.
Valid value(s):
ALL - Retrieve all signature requests.SIGNATURE - Retrieve only requests with that include a signature.ALLDOCUMENTS - Retrieve only requests with attached documents.SINGLEDOCUMENT - Retrieve only requests with the specified documentId attached.ACHPAYMENT - Retrieve only requests with an attached ACH payment.CCPAYMENT - Retrieve only requests with an attached Credit Card payment.ALLPAYMENT - Retrieve only requests with an attached payment. |
|
documentId
Numeric20
Conditional
|
The document Id to filter SINGLEDOCUMENT type reports.
|
|
userId
Alphanumeric65
|
The user Id to filter reports by. |
SignatureList
| Attribute | Description |
|
signatureList
ListN/A
|
A list of Signature objects returned from a report request. Result parameters (For a detailed explanation of each response parameter, see Signature):signatureId
firstName
lastName
emailAddress
mobileNumber
username
payment (if applicable)
– paymentTransactionId
– paymentType
– totalAmount
document (if applicable)
– documentId
imageUpload (if applicable)
– imageUploadId
standaloneSignatureRequested
completionDate
signatureClosed
errorCode
errorMessage
requestedDate
expirationDate
signatureURL
|
Payment
| Attribute | Description |
|
paymentTransactionId
Numeric20
|
The confirmation id of the payment. |
|
accountNumber
Alphanumeric45
|
Account number associated with payment in this transaction. |
|
accountDirective
Deprecated
|
This element is deprecated. Use the accountDirective within AchTransaction and CreditCardTransaction.
|
|
dateCreated
Date25
|
The date and time the payment was entered for processing.
Format: ISO-8601 (YYYY-MM-DD HH:mm:ss)
|
|
dateProcessed
Date25
|
The date and time the payment was processed.
Format: ISO-8601 (YYYY-MM-DD HH:mm:ss)
|
|
paymentAmount
NumericString11
|
The payment amount for this transaction. This attribute also serves as the maximum payment amount. The payer will not be allowed to pay more than the submitted amount, even if editablePaymentAmount is set to true.
Format: XXXXXXXX.XX
|
|
editablePaymentAmount
Boolean5
|
Whether or not the paymentAmount is editable by the payer.
Valid value(s):
true, falseDefault: false
|
|
minimumAmount
NumericString11
|
If the payer is able to edit the paymentAmount, this is the minimum they can pay.
Format: XXXXXXXX.XX
|
|
feeAmount
NumericString11
|
The fee amount for this transaction.
Format: XXXXXXXX.XX
Constraint(s): Cannot be present if
feePercentage is present
|
|
feePercentage
Numeric9
|
The percentage of the payment amount that will be charged as a fee. Presented as a percentage, not a decimal
Format: XXX.XXXXXX
Constraint(s):
-Cannot be present if feeAmount is present -Cannot be greater than 4 |
|
totalAmount
NumericString11
|
The total amount for this transaction.
Format: XXXXXXXX.XX
|
|
address
Alphanumeric80
|
The address associated with the payment. |
|
city
Alphanumeric45
|
The city associated with the payment. |
|
state
Alphanumeric2
|
The state abbreviation associated with the payment. |
|
zip
NumericString9
|
The zip code associated with the payment. |
|
paymentType
Alpha3
|
Type of payment to include in the request.
Constraint(s): Required for payment.
Valid value(s):
ACH, CC, ALL |
|
achTransaction
ObjectN/A
|
Data to preload for ACH payment request.
Constraint(s): See object definition below.
|
|
ccTransaction
ObjectN/A
|
Data to preload for credit card payment request.
Constraint(s): See object definition below.
|
AchTransaction
| Attribute | Description |
|
achStatusData
ListN/A
|
List of achStatusData objects for this ach transaction.
Constraint(s): See object definition below.
|
|
accountDirective
Alphanumeric10
|
The account directive if an ach payment is processed.
Format: XXX-X
|
|
bankAccountNumber
Numeric20
|
The payer’s bank account number for ACH transaction.
Constraint(s): Will be preloaded on form for client, though they will be able to edit it.
|
|
bankRoutingNumber
NumericString9
|
The payer’s bank routing number for ACH transaction.
Constraint(s): Will be preloaded on form for client, though they will be able to edit it.
|
|
bankAccountNumberLastFour
NumericString20
|
The last four numbers of the payer’s bank account number. |
|
checkNumber
NumericString9
|
The payer’s check number for transaction.
Constraint(s): Will be preloaded on form for client, though they will be able to edit it.
|
|
bankAccountType
Alpha8
|
The type of bank account.
Constraint(s): Will be preloaded on form for client, though they will be able to edit it.
Valid value(s):
CHECKING, SAVINGS |
AchStatusData
| Attribute | Description |
|
status
Alpha12
|
The status of the ACH transaction
Valid value(s):
WAITING - transaction will be included in next batchSUBMITTED - transaction has been submitted for processingACKNOWLEDGED - transaction has been accepted for processingFUNDED - money has been deposited into your accountDEDUCTION - money has been taken from your accountVOID - transaction was cancelled prior to submission for processingRETURNED - an exception occurred while processing transactionCORRECTION - transaction was automatically corrected during processingERROR - an unknown error occurred while processing transaction
|
|
returnCode
Alpha8
|
The return code for the ACH transaction, if applicable. |
|
returnMessage
AlphanumericN/A
|
Explanation of the returnCode. |
|
statusChangeDate
Date25
|
Date and time this ACH status was recorded.
Format: ISO-8601 (YYYY-MM-DD HH:mm:ss)
|
CreditCardTransaction
| Attribute | Description |
|
accountDirective
Alphanumeric10
|
The account directive if a card payment is processed.
Format: XXX-X
|
|
creditCardExpirationMonth
Numeric2
|
Expiration month of the payer’s credit card.
Constraint(s): Will be preloaded on form for client, though they will be able to edit it.
|
|
creditCardExpirationYear
Numeric4
|
Expiration year of the payer’s credit card.
Constraint(s): Will be preloaded on form for client, though they will be able to edit it.
|
|
creditCardToken
Alphanumeric16
|
Credit card token as generated by PDC4U. An actual credit card number will fail validation.
Constraint(s): Will be preloaded on form for client, though they will be able to edit it or enter a different card number.
See the Store a credit card in the vault example in the Credit Card API for help generating the token. |
|
creditCardType
Alpha50
|
The type of the payer’s credit card. |
|
authorizationCode
Alphanumeric75
|
The authorization code for the processed transaction |
Document
test endpoint: https://wssignaturedemo.pdc4u.com/SignatureService/api/v2_0/documents
live endpoint: https://wssignature.pdc4u.com/SignatureService/api/v2_0/documents
POST to document endpoint to upload a document.
GET to retrieve a previously uploaded document.
| Attribute | Description |
|
documentName
Alphanumeric36
|
The name given for the document. |
|
documentBase64String
Base64N/A
|
The document as a Base64 encoded string. |
|
documentId
Numeric20
|
Id for document that was uploaded. Can be sent in future requests to reuse document without uploading it again. |
|
documentUrl
Alphanumeric160
|
The URL to retrieve the information, through a GET request, for this document.
|
|
originalUploadDate
Date25
|
The date and time the document was originally uploaded.
Format: ISO-8601 (YYYY-MM-DD HH:mm:ss)
|
|
overlayId
Numeric20
|
The id of an uploaded overlay to apply to this document in the request. |
ImageUpload
test endpoint: https://wssignaturedemo.pdc4u.com/SignatureService/api/v2_0/imageUploads
live endpoint: https://wssignature.pdc4u.com/SignatureService/api/v2_0/imageUploads
GET to retrieve an image from a previous signature request.
| Attribute | Description |
|
imageUploadRequested
Boolean5
|
Whether to request an image upload from the client.
Valid value(s):
true, falseDefault: false
|
|
imageUploadId
Numeric20
|
Id for the image that was uploaded by the client. |
|
signatureId
Numeric20
|
The id of the transaction request this image is tied to. |
|
imageUploadSuccessful
Boolean5
|
Whether the upload was successful or not.
Valid value(s):
true, false |
|
imageUploadDescription
Alphanumeric160
|
A description of the image for the client to upload.
Default: Upload Image
|
|
ImageUploadBase64
Base64N/A
|
Base64 encoded value of the .png format uploaded image. |
|
signatureUrl
Alphanumeric160
|
The URL to retrieve the information, through a GET request, for this transaction.
|
|
imageUploadUrl
Alphanumeric160
|
The URL to retrieve the information, through a GET request, for this image upload.
|
CompanyOverride
| Attribute | Description |
|
companyName
Alphanumeric45
|
The company name to display on the signature, if different than the company sending the request. If this value is included in the request, the configured company logo will not show for this request. |
|
emailFromName
Alphanumeric50
|
The name to display on from field of the signature email request.
Default: The sending Company’s Name (or provided overrideCompanyName) will be used
|
|
subject
Alphanumeric50
|
The subject to display on the signature email request.
Default: The sending Company’s Name (or provided overrideCompanyName) will be used
|
|
linkText
Alphanumeric25
|
The text to display on the clickable URL in the signature email request.
Default: Complete Transaction
|
Component
| Attribute | Description |
|
componentType
Alpha24
|
The type of this component.
Valid value(s):
SCHEDULE |
|
relatedId
Alphanumeric24
Conditional
|
The id of the object represented by this component. Required if componentType is SCHEDULE
|
|
data
ObjectN/A
Conditional
|
Component Data. Required if componentType is SCHEDULE
Constraint(s): See object definition below.
|
Component Data
| Attribute | Description |
|
requestPaymentData
Boolean5
Required
|
Boolean stating if the Flow should Request Payment Data for this componentType
|
|
requestAuthorization
Boolean5
Required
|
Boolean stating if the Flow should Request Authorization for this componentType
|
|
paymentTypes
ListN/A
Conditional
|
Allowed Payment Types for this componentType. Required if requestPaymentData is true
Valid value(s):
CARD, CHECK |
EmailAttempt
| Attribute | Description |
|
attemptDate
Date25
|
The date and time the Email was attempted to send. READONLY
Format: ISO-8601 (YYYY-MM-DD HH:mm:ss)
|
|
attemptResult
Alphanumeric10
|
The result status of the sending Attempt. READONLY
Valid value(s):
SENT = email was successfully sent to the email provider
FAILED = email was sent to the email provider, but rejected and will not be retried
RETRY = email was not able to send to the email provider, but will be retried
|
|
emailDeliveryResultList
ListN/A
|
List of related EmailDeliveryResult objects. See object definition below. READONLY
|
EmailDeliveryResult
| Attribute | Description |
|
result
Alphanumeric30
|
Delivery Result for a SENT Email attempt. READONLY
Valid value(s):
SEND = email provider acknowledged they received the email
DELIVERY = email provider successfully delivered the email
BOUNCED = email provider was not able to deliver the email
OPEN = email was opened by recipient
CLICK = an email link was clicked by recipient
COMPLAINT = email was reported as spam/abuse by recipient
|
|
resultDate
Date25
|
The date and time of the Email delivery result. READONLY
Format: ISO-8601 (YYYY-MM-DD HH:mm:ss)
|
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. |
TransactionReport
test endpoint: https://wssignaturedemo.pdc4u.com/SignatureService/api/v2_0/transactionReports
live endpoint: https://wssignature.pdc4u.com/SignatureService/api/v2_0/transactionReports
GET to retrieve a transaction report for a signature transaction. If this flow is an authorization request for a schedule, the schedule will be included in this report, along with the signature if the authorization request was completed.
| Attribute | Description |
|
signatureId
Numeric20
Required
|
The id of the transaction request to retrieve a report for. |
|
reportType
Alpha7
|
The desired type of the transaction report. FULL will return the full transaction report. RECEIPT will return a report with the signature image, any related payment information and any attached document.
Valid value(s):
FULL, RECEIPTDefault: FULL
|
|
emailAddress
Alphanumeric65
|
An email address to send the transaction report to. |
|
reportData
Base64N/A
|
The full transaction report pdf as a Base64 encoded value. |
|
closedOrExpired
Boolean5
|
Whether the request has been closed or expired or not.
Valid value(s):
true, false |
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 Use Case
While the signature service offers many different types of functionality, knowing how to tie them all together can be a bit tricky. Below are some potential work-flows that you may encounter, and the API components that should be used. The components can be used separately, or as a group.
Get signatures on a mortgage document and image of some form of identification
<?php
$data = [
'document' => [
'documentId' => 'ID_FROM_STEP_1',
'overlayId' => ''
],
'imageUpload' => [
'imageUploadDescription' => 'Take a picture of some form of identification',
'imageUploadRequested' => 'true'
],
'standaloneSignatureRequested' => 'true'
];
my $data = {
'document' => {
'documentId' => 'ID_FROM_STEP_1',
'overlayId' => ''
},
'imageUpload' => {
'imageUploadDescription' => 'Take a picture of some form of identification',
'imageUploadRequested' => 'true'
},
'standaloneSignatureRequested' => 'true'
};
data = {
'document' => {
'documentId' => 'ID_FROM_STEP_1',
'overlayId' => ''
},
'imageUpload' => {
'imageUploadDescription' => 'Take a picture of some form of identification',
'imageUploadRequested' => 'true'
},
'standaloneSignatureRequested' => 'true'
};
Components required: Signature, Document, ImageUpload
- Step 1: Upload the mortgage document. The
documentIdreturned will be used in the next step. - Step 2: Send a Signature Request. You would set
standaloneSignatureRequestedtotrueand add theimageUploadblock. Thedocumentblock would also be submitted, wheredocumentIdhas the value from step 1. See sample code block to the right. - Step 3: Once the request has been completed by the end user, you would use the Transaction Report Retrieval to see the signed document and photo they uploaded for identification.
Get a signature on a recurring payment schedule
<?php
$data = [
'document' => [
'documentId' => 'ID_FROM_STEP_1',
'overlayId' => ''
],
'standaloneSignatureRequested' => 'true'
];
my $data = {
'document' => {
'documentId' => 'ID_FROM_STEP_1',
'overlayId' => ''
},
'standaloneSignatureRequested' => 'true'
};
data = {
'document' => {
'documentId' => 'ID_FROM_STEP_1',
'overlayId' => ''
},
'standaloneSignatureRequested' => 'true'
};
Components required: Signature, Document
- Step 1: Upload a PDF of the recurring schedule. The
documentIdreturned will be used in the next step. - Step 2: Send a Signature Request. You would set
standaloneSignatureRequestedtotrue. Thedocumentblock would also be submitted, wheredocumentIdhas the value from step 1. See sample code block to the right. - Step 3: Once the request has been completed by the end user, you would use the Transaction Report Retrieval to see the signed document.
Sample Code
This section offers some client implementation examples in different languages. Keep in mind, these are only minimalistic examples used to demonstrate the Signature Service REST API and are not meant for production use.
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 '500':
Description = 'An internal error has occurred.'
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.
Send Signature Request
<?php
$paymentType = 'CARD';
$payment = [
'accountNumber' => 'YourAccountNumber',
'paymentAmount' => '$125.00',
'feeAmount' => '$5.00',
'feePercentage' => 0,
'accountDirective' => '0000',
'editablePaymentAmount' => 'true',
'minimumAmount' => '100.00'
];
if($paymentType == 'CARD') {
$payment['paymentType'] = 'CC';
$payment['ccTransaction'] = [
'creditCardExpirationMonth' => '09',
'creditCardExpirationYear' => '2022',
'creditCardToken' => 'CardTokenFromPDC'
];
}
else if($paymentType == 'CHECK') {
$payment['paymentType'] = 'ACH';
$payment['achTransaction'] = [
'bankAccountNumber' => '123456',
'bankAccountNumberLastFour' => '3456',
'bankAccountType' => 'CHECKING',
'bankRoutingNumber' => '124001545',
'checkNumber' => '1'
];
}
$roundTripList = [];
$roundTripList[] = [
'rtName' => 'personalIdNumber',
'rtValue' => '1234Number'
];
$data = [
'customMessage' => 'Thank you for buying!',
'description' => 'Agreement for mortgage.',
'emailAddress' => 'frontenduser@pdc4u.com',
'firstName' => 'Adam',
'lastName' => 'Test',
'maxPinAttempts' => '2',
'mobileNumber' => '7777777777',
'pinDescription' => 'Last four of your social security number',
'redirectLink' => 'https://www.pdcflow.com',
'requestGeolocation' => 'true',
'roundTripNVPS' => $roundTripList,
'payment' => $payment,
'companyOverride' => [
'companyName' => 'Our Child Company'
],
'document' => [
'documentId' => '1',
'overlayId' => ''
//Specify to include an overlay
],
'imageUpload' => [
'imageUploadDescription' => 'Upload photo id',
'imageUploadRequested' => 'true',
],
'standaloneSignatureRequested' => 'true',
'templateName' => 'SignatureOnly',
'timeoutMinutes' => '4.5',
'transactionOrigin' => 'EXT',
'username' => 'someuser@pdc4u.com',
'verificationPin' => '1235',
'customSmsMessage' => 'We are trying to collect some debt. Click the following link to authorize this payment.',
'postbackUrl' => 'https://www.testpostbackaddress.com'
];
$url = 'https://wssignaturedemo.pdc4u.com/SignatureService/api/v2_0/signatures';
$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, [
'Content-Type: application/json',
'Content-Length: ' . strlen($data)
]);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "someSecretUsername:someSecretPassword");
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 $paymentType = 'CARD';
my %payment = (
'accountNumber' => 'YourAccountNumber',
'paymentAmount' => '$125.00',
'feeAmount' => '$5.00',
'feePercentage' => '0',
'accountDirective' => '0000',
'editablePaymentAmount' => 'true',
'minimumAmount' => '100.00'
);
if($paymentType eq 'CARD') {
$payment{'paymentType'} = 'CC';
$payment{'ccTransaction'} = {
'creditCardExpirationMonth' => '09',
'creditCardExpirationYear' => '2022',
'creditCardToken' => 'CardTokenFromPDC'
};
}
elsif ($paymentType == 'CHECK'){
$payment{'paymentType'} = 'ACH';
$payment{'achTransaction'} = {
'bankAccountNumber' => '123456',
'bankAccountNumberLastFour' => '3456',
'bankAccountType' => 'CHECKING',
'bankRoutingNumber' => '124001545'