NAV Navbar

Logo

Introduction

Payment Data Systems - PDS Checkout Documentation

PDS checkout is an embedded payment form for desktop, tablet and mobile devices.
You can accept both Credit/Debit cards and ACH.
Using PDS checkout allows direct site integration and removes PCI concerns.
The experience is customizable with several different themes to match your site.
Web service calls support SOAP, WCF and REST/JSON.

Last updated on, 1/15/2019 © Payment Data Systems.

Change Log

DateAuthorDoc VersionChange Summary
1/15/2019 Tracy Rickman 1.0 Initial web release

Environment

SANDBOX & PRODUCTION https://checkout.securepds.com

Sandbox & Production

https://checkout.securepds.com

Our sandbox and production servers share the same URL.
The correct systems will be chosen based on the credentials submitted.

SOAP/WFC WSDL

https://checkout.securepds.com/checkout/checkout.svc?wsdl

REST/JSON Endpoints and definitions:

https://checkout.securepds.com/checkout/checkout.svc/json/help

Required Parameters in all calls

Parameter NameDescription
MerchantKey Unique checkout key assigned by PDS

Parameter values for Sandbox

Parameter NameTest Value
MerchantKey AEAE82F9-5A34-47C3-A61E-1E8EE37BE3AD

Client Side Integration

Pay Now Button

            
<form action="" method="POST" id="paymentform">
	<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.0/jquery.min.js"></script>
	<script id="checkoutscript"
		src="https://checkout.securepds.com/checkout/checkout2.js"
		pds-key="D6A033D8-A7E6-45C9-BD77-AFB3013BC45A" 
		pds-theme="blue" 
		pds-image="https://yourdomain.com/images/logo.jpg" 
		pds-name="Windy Oaks Apartments" 
		pds-description="Make your rent payment" 
		pds-button="Pay Now" 
		pds-amount="800.00" 
		pds-paymenttypes="" 
		pds-email="" 
		pds-fees="" 
		pds-pinless="true" 
		pds-pinlesscredit="true" > 
	</script>
</form>
			
            

The “pay now” button is used to collect and securely send sensitive payment information to us. Once the information has been validated the script will return a token that can be used with an API call to charge the user. The checkout screen does NOT charge the customer. On success, the script will generate a hidden field on the form with the name/id of pdstoken and submit the form. On iOS devices, it will direct the user to a new page rather than a popup and will return the Token as a querystring parameter. In either scenario, you will need to manage the user submitting the information to the return token with a session variable.

* Tokens recieved from the PDS Checkout widget are single use and will expire after 5 minutes.

Recieving page Sample

Below is a sample ASPX page showing how to capture the returned values
string sToken = Request.Form["pdsToken"];
string sPmtType = Request.Form["pdsPmtType"];
if (sToken == null) { sToken = Request.QueryString["pdsToken"]; }
if (sPmtType == null) { sPmtType = Request.QueryString["pdsPmtType"]; }

if (sToken != null)
{
    //Do API submission here
}

Form Tag Parameters

NameRequiredDescription
Action Required Location that token will be posted to. Leave blank to have it submitted back to calling page. The post back will create two new hidden elements. The first “pdsToken” will contain the token or an error message. The second “pdsPmtType” will return the payment method selected by the user. It will return “cc” for Credit/Debit cards and “ach” for ACH transactions.
Method Required Method for posting form. This must be set to “POST”
ID Required The name of the form. This must be set to “paymentform”

Script Tag Parameters

NameRequiredDescription
ID Required This is the name of the script. This must be set to “checkoutscript”
src Required Source of the script file. This must be set to https://checkout.securepds.com/checkout/checkout2.js
pds-key Required Your unique merchant API key.
pds-theme Required This will select the color theme of the embedded button as well as the checkout form. See table below for values
pds-image Required Full URL to your logo image. Image should be 128x128 pixels.
pds-name Required The name of your company.
pds-description Required A description of the product or service being purchased.
pds-button Required The text that will appear on the integrated button.
pds-amount Required If a valid amount is given then the button on the checkout screen will display “Pay $800.00”. If the amount is left blank the button will display “Pay Now”.
pds-paymenttypes Optional Exclude paramater for both CC/Debit and ACH. Use cconly or achonly to limit selection.
pds-email Optional Exclude parameter if not being used.
Prefilled email address on payment form.
pds-fees Optional Exclude parameter if not being used.
Used to display fees to user.
Fees must contain two decimals split by a |. First list the credit/debit card fee, then list the ACH fee. Fees may be decimals up to 4% or fixed amounts. Anything over 0.04 is considered a fixed amount and anything under is a percentage. Example usage “0.029|1.00” This would charge 2.9% on Credit and $1.00 on ACH.
To calculate fees pds-amount must be set.
pds-pinless Optional Exclude parameter if not being used.
Set to true to use the Pinless Debit Network instead of the Credit Card Network.
pds-pinlesscredit Optional Exclude parameter if not being used.
Will verify that the card entered is a debit card and that it supports the credit operation

Themes

NameButton SampleForm Sample
blue
darkblue
aqua
green
yellow
orange
red
fuchsia
purple
gray
black

Mobile UI

POST https://checkout.securepds.com/checkout/checkout.svc/JSON/GenerateToken

            
{
	"MerchantKey": "string",
	"PaymentType": "string",
	"EmailAddress": "string",
	"CardNumber": "string",
	"ExpDate": "string",
	"CVV": "string",
	"BankRouting": "string",
	"BankAccountNumber": "string",
	"BankAccountType": "string"	
}
                
            

The above command returns the following JSON structure:

            
{
	"Status": "string",
	"Message": "string",
	"Confirmation": "string"
}
                
            

This method can be called from a mobile application to generate a payment token.
This would take the place of the Web UI and allow you to send the card or bank informaiton directly to PDS rather than passing it through your server. This removes many of the PCI requirements.

* Tokens recieved from the the mobile API call are single use and will expire after 5 minutes.

Important Information

All fields are required int the JSON object. If you are submitting a credit card, then use empty strings for the ACH fields. If you are submitting ACH information, then use empty strings for the credit card fields.

HTTP Request

POST https://checkout.securepds.com/checkout/checkout.svc/JSON/GenerateToken

Parameters

NameTypeRequiredLengthDescription
MerchantKey string Required Max 50 PDS Provided Checkout Key
PaymentType string Required 2-10 “cc” for Credit Card,
“ach” for bank account,
“db” for Pinless Debit Card,
“dbcredit” for Pinless Debit Card Credit Operations
EmailAddress string Required 2-39 Customer email address
CardNumber string Required 14-17 Credit/Debit Card Number
ExpDate string Required 5 Expiration Date (MM/YY)
CVV string Required 3-4 CVC/CVV Number
BankRoutingNumber string Required 9 Bank Routing Number
BankAccountNumber string Required 2-19 Bank Account Number
BankAccountType string Required Max 10 "checking" or "savings"

Response

NameTypeDescription
Status string "success" or "failure"
Message string On failure will contain the error description
Confirmation string On success will contain the transaction confirmation ID

API Integration

Single Payment

POST https://checkout.securepds.com/checkout/checkout.svc/json/SinglePayment

            
{
	"MerchantKey": "string",
	"Token": "string",	
	"Amount": "string",
	"FirstName": "string",
	"LastName": "string",
	"Address1": "string",
	"Address2": "string",
	"City": "string",
	"State": "string",
	"Zip": "string",	
	"AdditionalSearch": "string",
	"AccountCode1": "string",
	"AccountCode2": "string",
	"AccountCode3": "string",
	"VerStr": "string"
}
                
            

The above command returns the following JSON structure:

            
{
	"Status": "string",
	"Message": "string",
	"Confirmation": "string"
}
                
            

This method is used to generate a Credit Card, Pinless Debit Cards, or ACH payment with a token provided by PDS Checkout.

* Tokens recieved from the PDS Checkout widget or mobile API call are single use and will expire after 5 minutes.

Important Information

All fields are required in the JSON object.
If you do not have data for one of the fields you may send an empty string.

HTTP Request

POST https://checkout.securepds.com/checkout/checkout.svc/json/SinglePayment

Parameters

NameTypeRequiredLengthDescription
MerchantKey string Required Max 50 Merchant Identification Number
Token string Required Max 50 Token provided by PDS Checkout widget or mobile API call.
Amount string Required max 8 Amount of Transaction (#0.00)
FirstName string Required 2-19 Customer first name
LastName string Required 2-19 Customer last name
Address1 string Required 2-39 Customer address 1
Address2 string Required 2-39 Customer address 2
City string Required 2-39 Customer city
State string Required 2 Customer state code
Zip string Required 4-10 Customer zip code (international supported)
AdditionalSearch string Required max 20 Optional reporting field
AccountCode1 string Required max 20 Optional reporting field
AccountCode2 string Required max 20 Optional reporting field
AccountCode3 string Required max 20 Optional reporting field
VerStr string Required 1 Set to "N" to check ACH Negative accounts table

Response

NameTypeDescription
Status string "success" or "failure"
Message string On failure will contain the error description
Confirmation string On success will contain the transaction confirmation ID

Convenience Fee Payment

POST https://checkout.securepds.com/checkout/checkout.svc/json/ConvPayPayment

            
{
	"MerchantKey": "string",
	"Token": "string",	
	"Amount": "string",
	"FirstName": "string",
	"LastName": "string",
	"Address1": "string",
	"Address2": "string",
	"City": "string",
	"State": "string",
	"Zip": "string",	
	"AdditionalSearch": "string",
	"AccountCode1": "string",
	"AccountCode2": "string",
	"AccountCode3": "string",
	"VerStr": "string"
}
                
            

The above command returns the following JSON structure:

            
{
	"Status": "string",
	"Message": "string",
	"Confirmation": "string"
}
                
            

This method is used to generate a Credit Card, Pinless Debit Cards, or ACH payment with a token provided by PDS Checkout. If you are setup to charge a convenience fee then you would call this method instead of SinglePayment. All convenience fees are setup and calculated internally and are not passed with the request.

* Tokens recieved from the PDS Checkout widget or mobile API call are single use and will expire after 5 minutes.

Important Information

All fields are required in the JSON object.
If you do not have data for one of the fields you may send an empty string.

HTTP Request

POST https://checkout.securepds.com/checkout/checkout.svc/json/ConvPayPayment

Parameters

NameTypeRequiredLengthDescription
MerchantKey string Required Max 50 Merchant Identification Number
Token string Required Max 50 Token provided by PDS Checkout widget or mobile API call.
Amount string Required max 8 Amount of Transaction (#0.00)
FirstName string Required 2-19 Customer first name
LastName string Required 2-19 Customer last name
Address1 string Required 2-39 Customer address 1
Address2 string Required 2-39 Customer address 2
City string Required 2-39 Customer city
State string Required 2 Customer state code
Zip string Required 4-10 Customer zip code (international supported)
AdditionalSearch string Required max 20 Optional reporting field
AccountCode1 string Required max 20 Optional reporting field
AccountCode2 string Required max 20 Optional reporting field
AccountCode3 string Required max 20 Optional reporting field
VerStr string Required 1 Set to "N" to check ACH Negative accounts table

Response

NameTypeDescription
Status string "success" or "failure"
Message string On failure will contain the error description
Confirmation string On success will contain the transaction confirmation ID

Pinless Credits

POST https://checkout.securepds.com/checkout/checkout.svc/json/PinlessCredit

            
{
	"MerchantKey": "string",
	"Login": "string",
	"Password": "string",
	"Token": "string",	
	"Amount": "string",
	"FirstName": "string",
	"LastName": "string",
	"Address1": "string",
	"Address2": "string",
	"City": "string",
	"State": "string",
	"Zip": "string",	
	"AdditionalSearch": "string",
	"AccountCode1": "string",
	"AccountCode2": "string",
	"AccountCode3": "string"
}
                
            

The above command returns the following JSON structure:

            
{
	"Status": "string",
	"Message": "string",
	"Confirmation": "string"
}
                
            

This method is used to send funds (credit) to a Pinless Debit card holder with a token provided by PDS Checkout. To have the ability to send credits please contact our sales department.

* Tokens recieved from the PDS Checkout widget or mobile API call are single use and will expire after 5 minutes.

Important Information

All fields are required in the JSON object.
If you do not have data for one of the fields you may send an empty string.

HTTP Request

POST https://checkout.securepds.com/checkout/checkout.svc/json/PinlessCredit

Parameters

NameTypeRequiredLengthDescription
MerchantKey string Required Max 50 Merchant Identification Number
Login string Required Max 50 API 2.0 Login
Password string Required Max 50 API 2.0 Password
Token string Required Max 50 Token provided by PDS Checkout widget or mobile API call.
Amount string Required max 8 Amount of Transaction (#0.00)
FirstName string Required 2-19 Customer first name
LastName string Required 2-19 Customer last name
Address1 string Required 2-39 Customer address 1
Address2 string Required 2-39 Customer address 2
City string Required 2-39 Customer city
State string Required 2 Customer state code
Zip string Required 4-10 Customer zip code (international supported)
AdditionalSearch string Required max 20 Optional reporting field
AccountCode1 string Required max 20 Optional reporting field
AccountCode2 string Required max 20 Optional reporting field
AccountCode3 string Required max 20 Optional reporting field

Response

NameTypeDescription
Status string "success" or "failure"
Message string On failure will contain the error description
Confirmation string On success will contain the transaction confirmation ID

Additional API Methods

All other features such as creating future payments, voids, refunds, etc. are available in the Payments API 2.0.
https://api.securepds.com/2.0/documentation/

Code Samples

			
curl -X POST \
https://api.securepds.com/2.0/payments.svc/json/endpoint \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
   "MerchantID": "0000000001", 
   "Login": "API0000000001", 
   "Password": "Temp1234!", 
   "additionalData": "1221"  
   }'
			
		
			
WebRequest request = WebRequest.Create("https://api.securepds.com/2.0/payments.svc/json/endpoint");
request.Method = "POST";
request.ContentType = "application/json; charset=utf-8";
request.Timeout = 600000;
string input = "{\"MerchantID\":\"0000000001\",\"login\":\"API0000000001\",
	\"password\":\"Temp1234!\",\"additionalData\":\"values\"}";
//Get the request stream
Stream POSTstream = request.GetRequestStream();
//Write the data bytes in the request stream
byte[] dataByte = Encoding.UTF8.GetBytes(sJSON.ToString());
POSTstream.Write(dataByte, 0, dataByte.Length);
POSTstream.Close();
//Get response from server
WebResponse POSTResponse = request.GetResponse();
StreamReader reader = new StreamReader(POSTResponse.GetResponseStream(), Encoding.UTF8);
string responseJSON = reader.ReadToEnd();
			
		
			
URL url = new URL("https://api.securepds.com/2.0/payments.svc/json/enpoint");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setDoOutput(true);
conn.setRequestMethod("POST");
conn.setRequestProperty("Content-Type", "application/json");

String input = "{\"MerchantID\":\"0000000001\",\"login\":\"API0000000001\",
	\"password\":\"Temp1234!\",\"additionalData\":\"values\"}";

OutputStream os = conn.getOutputStream();
os.write(input.getBytes());
os.flush();

if (conn.getResponseCode() != HttpURLConnection.HTTP_CREATED) {
   throw new RuntimeException("Failed : HTTP error code : " + conn.getResponseCode());
}

BufferedReader br = new BufferedReader(new InputStreamReader((conn.getInputStream())));

String output;
System.out.println("Output from Server .... \n");
while ((output = br.readLine()) != null) {
   System.out.println(output);
}

conn.disconnect();
			
		
			
function CallSingularBillPayAPI() {   
   var xhttp = new XMLHttpRequest();
   xhttp.onreadystatechange = function () {
       if (this.readyState == 4 && this.status == 200) {
           alert(this.responseText);
       }
   };
   xhttp.open("POST", "https://api.securepds.com/2.0/payments.svc/json/endpointName", true);
   xhttp.setRequestHeader("Content-type", "application/json");
   var obj = '{"MerchantID":"0000000001","Login":"API0000000001","Password":"Temp1234!","additionalData":""}';
   xhttp.send(obj);
}
			
		
			
let json: [String: Any] = 
["MerchantID": "0000000001",
"Login": "API0000000001",
"Password": "Temp1234!",
"additionalData": ""]

let jsonData = try? JSONSerialization.data(withJSONObject: json)

let url = URL(string: "https://api.securepds.com/2.0/payments.svc/json/endpoint")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.httpBody = jsonData
 
let task = URLSession.shared.dataTask(with: request) { data, response, error in
   guard let data = data, error == nil else {
      print(error?.localizedDescription ?? "No data")
      return
   }
   let responseJSON = try? JSONSerialization.jsonObject(with: data, options: [])
   if let responseJSON = responseJSON as? [String: Any] {
      print(responseJSON)
   }
}
 
task.resume()
			
		
			
function callAPI($method, $url, $data){
   $curl = curl_init();
   curl_setopt($curl, CURLOPT_POST, 1);
   curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
   // OPTIONS:
   curl_setopt($curl, CURLOPT_URL, $url);
   curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
   curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
   curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);

   // EXECUTE:
   $result = curl_exec($curl);
   if(!$result){die("Connection Failure");}
   curl_close($curl);
   return $result;
}

$data_array =  array(
   "merchantID" => "0000000001",
   "login" => "API0000000001",
   "password" => "Temp1234!",
   "additionalData" => "values"
   ),
);

$make_call = callAPI('POST', 'https://api.securepds.com/2.0/payments.svc/json/enpoint', json_encode($data_array));
$response = json_decode($make_call, true);
$errors   = $response['response']['errors'];
$data     = $response['response']['data'][0];

			
		
			
use REST::Client;
 
my $client = REST::Client->new();

$client->addHeader('Content-Type', 'application/json');
$client->addHeader('charset', 'UTF-8');
$client->addHeader('Accept', 'application/json');

$req = '{
	"MerchantID" : "0000000001",
	"Login" : "API0000000001",
	"Password" : "Temp1234!",
	"additionalData" : "",
	}';

$url="https://api.securepds.com/2.0/payments.svc/json/endpoint"; 

$client->POST($url, $req);
print $client->responseContent();
			
		
			
require 'net/http'

url = 'https://api.securepds.com/2.0/payments.svc/json/endpoint'
params = {
  merchantID => '0000000001',
  login => 'API0000000001',
  password => 'Temp1234!',
  additionalData => 'values'
}

resp = Net::HTTP.post_form(url, params)

resp_text = resp.body
			
		
			
import requests
import json

def main():
   data = {}
   data[MerchantID] = '000000000001'
   data[Login] = 'API0000000001'
   data[Password] = 'Temp1234!'
   data[additionalData] = ''
   json = json.dumps(data)

   req = requests.post('https://api.securepds.com/2.0/payments.svc/json/endpoint', data=None, json=None)
   print("HTTP Status Code: " + str(req.status_code))
   print(req.headers)
   json_response = json.loads(req.content)
   print(json_response)

if __name__ == '__main__':
   main()
			
		
			
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    jsonData := map[string]string{
      "MerchantID": "0000000001", 
      "Login": "API0000000001", 
      "password": "Temp234!", 
      "additionalData": "values"}
    jsonValue, _ := json.Marshal(jsonData)
    response, err := http.Post("https://api.securepds.com/2.0/payments.svc/json/endpoint", 
	   "application/json", 
	   bytes.NewBuffer(jsonValue))
    if err == nil {
        data, _ := ioutil.ReadAll(response.Body)
		fmt.Println(data)
    }
}
			
		

In the right hand pannel we have provided code samples in several of the most popular programming languages.
You will find code for cURL, C#, JAVA, Javascript, Swift, PHP, Perl, Ruby, Python, and Go.
In addition to REST/JSON, we also support REST/XML, SOAP, and WCF calls.

For additional help and support during your integration please contact us at integrations@paymentdata.com

References

Test Account Numbers

Following account numbers can be used for testing

Account TypeAccount NumberRouting Number
Credit Card 4111111111111111
Debit Card 5489221100112235
ACH 123456789 555555550

PDS Response Codes

PDS will return 5000 series response codes for errors that occur within our system. Most of these errors are for improper formatting of data

CodeDescription
5000 Security Violation
5001 System Failure
5002 Unspecified Network Issue
5003 Unable To Parse Response
5004 Unable to Load Merchant Details
5005 Invalid Gateway Setup
5006 Transaction Limits Exceeded
5007 State Not Supported
5008 Prefunding Amount Exceeded
5009 Pinless Credits Cannot Be Returned
5010 Invalid Transaction Code
5011 Operation Not Valid On This Card
5012 Operation Not Available On This Transaction Type
5020 Invalid Confirmation ID
5030 Unable to locate record
5031 Unable to get gateway token
5050 Invalid Amount
5051 Invalid Credit Card Track Data
5052 Invalid Credit Card Track Data Method
5053 Invalid Email Address
5054 Invalid First Name
5055 Invalid Last Name
5056 Invalid Address
5057 Invalid Address 2
5058 Invalid City
5059 Invalid State
5060 Invalid Zip Code
5061 Invalid International Province
5062 Invalid Country
5063 Invalid Card Number
5064 Invalid Credit Card Type
5065 Invalid Expiration Date
5066 Invalid CVV
5067 Invalid Merchant Pay Account
5068 Invalid Office ID
5069 Invalid User ID
5070 Invalid Additional Search
5071 Invalid Account Code 1
5072 Invalid Account Code 2
5073 Invalid Account Code 3
5074 Invalid Convenience Fee Amount
5075 Unable to Void Authorizations
5076 Invalid Payment Date
5077 Invalid Phone Number
5078 Invalid Account Number
5079 Invalid Routing Number
5080 Invalid Check Number
5081 Invalid Merchant Name
5082 Invalid Bank Name