PayPoint Integration Best Practices Guide - First Data material presented in this PayPoint...
Transcript of PayPoint Integration Best Practices Guide - First Data material presented in this PayPoint...
PayPoint Integration
Best Practices
Guide
Version: 2.6
6/10/2011
First Data Corporation
Suite 300
11311 Cornell Park Drive
Cincinnati, Ohio 45242
www.firstdata.com
© 2009-2011 First Data Corporation. All Rights Reserved. This document contains
unpublished, confidential and proprietary information of First Data Corporation. You may not
disclose, copy or use any part of this material for any purpose in any medium outside First Data
Corporation without the express written consent of First Data Corporation.
Version 2.6.0 6/10/2011
PayPoint® Integration Best Practices Guide
Table of Contents
Disclaimer ___________________________________________________________________ i
Revision History ______________________________________________________________ i
1.0 Introduction ______________________________________________________________ 1 Document Goals ___________________________________________________________ 1
Assumptions of Knowledge __________________________________________________ 1
2.0 Designing a PayPoint Business Application ____________________________________ 1 2.1 Architecture____________________________________________________________ 1
2.1.1 Single Tier ________________________________________________________ 2
2.1.2 N-Tier ____________________________________________________________ 2
2.2 Make Payment Workflow _________________________________________________ 4
2.3 Code Separation ________________________________________________________ 5
3.0 Interfaces and Languages___________________________________________________ 5 3.1 Interfaces ______________________________________________________________ 5
3.1.1 HTTP ____________________________________________________________ 5
3.1.2 Web Service _______________________________________________________ 6
3.2 Languages _____________________________________________________________ 7
3.2.1 Microsoft .NET (C# and VB.NET) ______________________________________ 7
3.2.2 VB 6 ____________________________________________________________ 10
3.2.3 ASP _____________________________________________________________ 10
3.2.4 PERL ___________________________________________________________ 10
3.2.5 Java ____________________________________________________________ 10
4.0 Coding Practices _________________________________________________________ 11 4.1 Hard Coding __________________________________________________________ 11
4.2 Do Not Assume Timeout Length __________________________________________ 11
4.3 Handling Return Codes __________________________________________________ 11
4.4 Error Handling ________________________________________________________ 14
4.5 Security ______________________________________________________________ 15
4.5.1 What to encrypt ___________________________________________________ 15
4.5.2 How to encrypt ____________________________________________________ 15
4.5.3 What to store _____________________________________________________ 16
4.5.4 What not to store ever! ______________________________________________ 17
5.0 Advanced Application Development _________________________________________ 18 5.1 Asynchronous Requests _________________________________________________ 18
5.2 Avoiding Duplicate Submissions __________________________________________ 18
5.2.1 Checking Payment Status ____________________________________________ 19
5.2.2 Canceling Payments________________________________________________ 19
Version 2.6.0 6/10/2011
PayPoint® Integration Best Practices Guide
5.3 Using Registered Accounts _______________________________________________ 19
5.3.1 Registered Account Common Issues ___________________________________ 20
5.4 Handling multiple payment types (Credit Card, eCheck, Debit, etc) _______________ 20
5.5 Interface suggestions ____________________________________________________ 21
5.6 Version Compatibility ___________________________________________________ 21
6.0 Common Issues __________________________________________________________ 23 6.1 Web Service Reference __________________________________________________ 23
6.2 HTTP API URL Encoding _______________________________________________ 25
7.0 A Simple Payment Application _____________________________________________ 26 7.1 ASP HTTP Application _________________________________________________ 26
7.2 C# ASP.NET Web Service Application _____________________________________ 26
Resources __________________________________________________________________ 27
Version 2.6.0 Page i 6/10/2011
PayPoint® Integration Best Practices Guide
Disclaimer
The material presented in this PayPoint Integration Best Practices Guide is for general guidance
only. First Data Corporation does not represent or warrant that this is the only information
available or the only information that should be considered when deciding to implement an
electronic payment processing solution. First Data Corporation shall not be held liable for any
losses caused by reliance on the accuracy, reliability or timeliness of this information. Portions of
such information may not be useful or applicable to an entity's particular circumstance. Any
person or entity that relies on any information obtained from this Guide does so at his or her own
risk.
Revision History
Date PayPoint
Release
Section Updates
8/28/2007 2.1 All Updated in First Data format.
3/26/2009 2.3 All Update to new First Data Branding
3/26/2009 2.3 3.0 Interfaces and
Languages
(How to reference
the web service in
Visual Studio 2003)
Changed the WSDL reference to:
https://www.govone.com/epay/epaywebservic
e.asmx?WSDL
3/26/2009 2.3 6.0 Common Issues
(Add PayPoint Web
Reference in
Microsoft Visual
Studio 2003)
Changed the WSDL reference to:
https://www.govone.com/epay/epaywebservic
e.asmx?WSDL
10/26/2009 2.4 6.0 Common Issues
(Add PayPoint Web
Reference in
Microsoft Visual
Studio 2003)
Moved ACH Credit from Third Party
Payment Medium directly under
PaymentInfoEFT Object listing.
5/13/2010 2.5 7.0 A Simple
Application
Updated URL for samples:
https://www.govone.com/epayadmin/samples/
Version 2.6.0 Page ii 6/10/2011
PayPoint® Integration Best Practices Guide
paypoint%20samples.zip
6/10/2011 2.6 The guide was reviewed and there are no
updates from 2.6 Release.
Version 2.6.0 Page 1 6/10/2011
PayPoint® Integration Best Practices Guide
1.0 Introduction
Document Goals
This document is intended to help project managers and developers. The document is technical
in nature and targeted at developers, and as such contains several code examples. These
examples are for demonstration purposes only. After reading this guide, and familiarizing
yourself with the Merchant Integration Guide, a developer should be able to design an interface
PayPoint to avoid common design pitfalls and maximizing the customer‟s experience.
Assumptions of Knowledge
This document assumes general familiarity with the PayPoint API, which is available in the
Merchant‟s Guide. It also assumes familiarity with HTML, web communications, and a
programming language. Most code examples are in ASP, Visual Basic, or C#.
2.0 Designing a PayPoint Business Application
The basic PayPoint business application simply requests payment information from the user and
submits the data to PayPoint, then waits for the result message and displays a user friendly
message to the user. A good design assumes these will not succeed 100% of the time for a
variety of reasons. Therefore, it is important to consider all aspects of the application architecture
before you begin coding an interface with PayPoint. For instance, it‟s essential for the business
application to handle all conditions.
2.1 Architecture
The first step in designing an application is choosing whether to use a single tier or n-tier
architecture. Typically, this corresponds to whether the application will be calling PayPoint in a
synchronous or asynchronous manner.
Version 2.6.0 Page 2 6/10/2011
PayPoint® Integration Best Practices Guide
2.1.1 SINGLE TIER
A single tier application is the simplest application to develop and deploy. However, it is also the
least robust and typically cannot scale well. An example of a single tier PayPoint application is a
simple website that accepts payment information and calls PayPoint from the web code. All
business logic exists in the web code, and there is no database to track payments. The application
depends entirely on PayPoint.
ADVANTAGES
Fast development time
Simple architecture
Runs on a single server
DISADVANTAGES
No code separation making maintenance and reuse more difficult
Does not scale
No database to track failed payments or other issues
Limited or no ability to deal with errors in payments
Synchronous calls to PayPoint can hang when network issues occur
2.1.2 N-TIER
An N-Tier architecture consists of the web server as the front end, a middle tier to handle
business logic and calls to PayPoint, and a database back-end to store payment information. The
diagram below demonstrates making a payment in an n-tier environment. This architecture
establishes logical tiers and separation of processing. This allows for distributed processing over
any number of physical servers.
Version 2.6.0 Page 3 6/10/2011
PayPoint® Integration Best Practices Guide
User
MakePayment
Screen
Please Wait
Processing
Payment
Payment
Complete
Database
Web Server
Application
Server
Internet
PayPoint®
1) User submits
payment and is
redirected to wait
page.
2) Web server submits request
to application server which
stores application specific data,
then creates and sends
PayPoint® request.
3) PayPoint®
receives request
and processes
payment.
4) PayPoint® sends
payment response.
5) Application
server receives
PayPoint®
response.
6) Application server stores
PayPoint® confirmation number
and result, then sends response
to web server.
7) Web server
sends user to
payment complete
page.
1
2
3 4
6
5
7
ADVANTAGES
Scalable to multiple web, app, and db servers
Robust error handling and tracking of errors
Asynchronous calls to PayPoint allow better handling of user actions that may take
some time while the payment is being processed.
Code separation of business logic allows better maintenance and reuse
DISADVANTAGES
Longer development time
Higher hardware and deployment costs
Version 2.6.0 Page 4 6/10/2011
PayPoint® Integration Best Practices Guide
2.2 Make Payment Workflow
The most used function in PayPoint is
MakePayment. It is very important that your
application handle all conditions returned by
this function in a user friendly fashion. In order
to handle all possible scenarios, your
application should store transaction status
information locally on transactions sent to
PayPoint. (For
card security
purposes you
should never store
account numbers,
cvv2, or track data
in your database).
For example, your
application should
record when
payments fail
unexpectedly, and
determine
whether they need
to be refunded
automatically.
Here is the
recommended
flow an
application
should
implement when
using
MakePayment.
Submit
Payment for
Processing
Is Data Valid?
Store Payment
in DB
Create Unique
Reference
Code
Create
PayPoint®
Request
Submit
Request to
PayPoint®
Did PayPoint®
return a
response?
Submit Payment
Status Request to
PayPoint®
Using
Reference Code
Did PayPoint®
return
response that
payment
exists?
Contact
PayPoint®
Support
Was payment
successful?
Is the failed
payment due
to bad user
data?
Send Failure
Response to
User
Explaining
Options
User fills out
payment
information
Store Payment
Result in DB
Display
Payment
Confirmation to
User
No
Yes
No
Yes
No
No
Yes
Yes
No
For example, they
entered an invalid
CVV2 code
Version 2.6.0 Page 5 6/10/2011
PayPoint® Integration Best Practices Guide
2.3 Code Separation
It is recommended the actual code that calls PayPoint be separated from the application‟s core
logic (i.e. a separate object or DLL). A separate object will make debugging problems much
easier in both testing and production. In addition this model provides a higher level of reuse
across multiple payment applications.
3.0 Interfaces and Languages
3.1 Interfaces
There are two main interfaces to PayPoint API, HTTP and Web Service. In general, the web
service is the recommended interface because it‟s easier to integrate using modern Interactive
Development Environment tools
3.1.1 HTTP
The HTTP interface allows any web capable application to interface with PayPoint using
standard HTTP requests. It supports either Form or Query String style parameters. This method
has some advantages in cases where older development tools don‟t support web services without
a lot of SOAP level development. A big disadvantage is the use of non-intuitive parameter
naming. This was done to keep the query string as short as possible.
Advantages
Universally supported
Easy to implement
Disadvantages
All query string parameters must be URL encoded
Hard to keep track of parameter keys
Difficult to debug due to non-intuitive parameter keys
Version 2.6.0 Page 6 6/10/2011
PayPoint® Integration Best Practices Guide
3.1.2 WEB SERVICE
The web service interface allows almost all major programming languages to easily interface
with the PayPoint system. The web service exposes the objects used by PayPoint and makes
calling PayPoint functions easy and intuitive.
Advantages
Easy interface
Takes full advantage of programming GUIs
Easier to implement advanced features like asynchronous requests
Easier to debug
Disadvantages
Must use development platform that support web services to gain full advantages
NOTE: When using the GUIs such as Visual Studio to point at the web service WSDL you
will need to take care in defining your WSDL reference. Because PayPoint is behind a
secure firewall, the automatically generated WSDL returns the incorrect non reference-
able web service address. Please see the Common Issues section for details.
Version 2.6.0 Page 7 6/10/2011
PayPoint® Integration Best Practices Guide
3.2 Languages
3.2.1 MICROSOFT .NET (C# AND VB.NET)
Microsoft .NET natively supports web services making it a natural choice for integrating with
PayPoint. Using the web service is as simple as adding a reference to it in your project
HOW TO REFERENCE THE WEB SERVICE IN VISUAL STUDIO 2003
1. In your project, right-click on References in the Solution Explorer window and choose
Add Web Reference…
Enter the address for the PayPoint WSDL.
https://www.govone.com/epay/epaywebservice.asmx?WSDL
2. Rename the web reference something more logical, such as PayPoint and click Add
Reference
3. Highlight the PayPoint reference in the Solution Explorer, the go to the Properties
window
4. Change URL Behavior to Dynamic
CALLING THE WEB SERVICE IN C#
//Create as new Make Payment Request
PayPoint.EPayMakePaymentRequest oPaymentRequest = new
PayPoint.EPayMakePaymentRequest();
//Create header
PayPoint.EPayHeader oHeader = new PayPoint.EPayHeader();
oHeader.ApplicationID = "414";
oHeader.PaymentChannel = PayPoint.EPayPaymentChannel.Web;
oHeader.SecurityKey = "password";
// Attach the header
oPaymentRequest.Header = oHeader;
//Create Credit Card Info
PayPoint.EPayPaymentInfoCC oCC = new PayPoint.EPayPaymentInfoCC();
oCC.CardNumber = "xxxx";
// Fill out all credit card info
//Create Payment Info object
Version 2.6.0 Page 8 6/10/2011
PayPoint® Integration Best Practices Guide
oPaymentRequest.PaymentInfo = new PayPoint.EPayPaymentInfo();
oPaymentRequest.PaymentInfo.PaymentMedium =
PayPoint.EPayPaymentMedium.CreditCard;
//Attach the payment info
oPaymentRequest.PaymentInfo.PaymentInfoCC = oCC;
//Create the web service
PayPoint.EPayWebService oService = new PayPoint.EPayWebService();
//IMPORTANT: Set the web server address, this should not be hardcoded like this
oService.Url = "https://www.govone.com/epay/epaywebservice.asmx";
//Set the timeout
oService.Timeout = 300000; // 5 minutes
try
{
//Call makepayment
PayPoint.EPayMakePaymentResult oResult =
oService.MakePayment(oPaymentRequest);
//Show result
MessageBox.Show(oResult.ReturnCode.ToString());
} catch (Exception ex)
{
MessageBox.Show(ex.Message);
}
CALLING THE WEB SERVICE IN VB.NET
Dim oPaymentRequest As PayPoint.EPayMakePaymentRequest
Dim oHeader As PayPoint.EPayHeader
Dim oCC As PayPoint.EPayPaymentInfoCC
Dim oService As PayPoint.EPayWebService
Dim oResult As PayPoint.EPayMakePaymentResult
'Create as new Make Payment Request
oPaymentRequest = New PayPoint.EPayMakePaymentRequest
'Create header
oHeader = New PayPoint.EPayHeader
oHeader.ApplicationID = "414"
oHeader.PaymentChannel = PayPoint.EPayPaymentChannel.Web
oHeader.SecurityKey = "password"
' Attach the header
oPaymentRequest.Header = oHeader
'Create Credit Card Info
oCC = New PayPoint.EPayPaymentInfoCC
Version 2.6.0 Page 9 6/10/2011
PayPoint® Integration Best Practices Guide
oCC.CardNumber = "xxxx"
' Fill out all credit card info
'Create Payment Info object
oPaymentRequest.PaymentInfo = New PayPoint.EPayPaymentInfo
oPaymentRequest.PaymentInfo.PaymentMedium =
PayPoint.EPayPaymentMedium.CreditCard
'Attach the payment info
oPaymentRequest.PaymentInfo.PaymentInfoCC = oCC
'Create the web service
oService = New PayPoint.EPayWebService
'IMPORTANT: Set the web server address, this should not be hardcoded like this
oService.Url = "https://www.govone.com/epay/epaywebservice.asmx"
'Set the timeout
oService.Timeout = 300000 ' 5 minutes
Try
'Call makepayment
oResult = oService.MakePayment(oPaymentRequest)
'Show result
MsgBox(oResult.ReturnCode.ToString)
Catch ex As Exception
MsgBox(ex.Message)
End Try
Version 2.6.0 Page 10 6/10/2011
PayPoint® Integration Best Practices Guide
3.2.2 VB 6
Visual Basic 6 does not natively support web services. As a result, we expect most applications
using VB will choose the HTTP interface. Microsoft has provided a web service system for VB 6
called the SOAP Toolkit. Unfortunately, it is not as intuitive as the .NET version is. More
information on the SOAP Toolkit can be found here:
http://www.microsoft.com/downloads/details.aspx?familyid=c943c0dd-ceec-4088-9753-
86f052ec8450&displaylang=en
It is recommended when using VB to interface the PayPoint HTTP API, use the WinHTTP v5.1
object. You can see a sample of this in the ASP sample project.
3.2.3 ASP
ASP does not natively support web services. To use PayPoint from ASP, you must use the HTTP
API via a web request object such as WinHTTP. A functional ASP sample is provided as part of
this guide.
3.2.4 PERL
Perl supports web services via the SOAP::Lite library. This library has some limitations that are
beyond the scope of this document. You can find more information about using SOAP::Lite to
call .NET web services here: http://msdn.microsoft.com/library/default.asp?url=/library/en-
us/dnsoap/html/soapliteperl.asp
3.2.5 JAVA
Java supports web services via several of its built-in libraries. Java also provides a web services
toolkit here: http://java.sun.com/webservices/downloads/1.3/index.html
Version 2.6.0 Page 11 6/10/2011
PayPoint® Integration Best Practices Guide
4.0 Coding Practices
4.1 Hard Coding
In general, it is not good practice to hardcode values. For PayPoint, there are several items that
might be tempting to hard code. Values such as application ID and password, or even the web
service URL and timeouts might seem safe to hard code but never should be. Put these values
someplace where they can be changed easily. This will aide in testing as well as prevent
unnecessary code changes in the future. You should also consider security around access to
changing these values such as a database or encrypted configuration file.
4.2 Do Not Assume Timeout Length
A common mistake when calling PayPoint is to assume when PayPoint actions timeout. PayPoint
has several network layers and makes calls to multiple processing gateways. Each processor has
its own timeout specifications, and as a result different transactions can take different lengths of
time. In general you can expect a response in 3 to 5 seconds. However situations can arise that
extend this time period. Your application should wait at least 300 seconds, but it should still
have a mechanism to check whether the payment succeeded. PayPoint transactions normally take
only a few seconds, but network issues can occasionally cause very long payments.
The best approach to timeouts is to build a system where payments that time out can be resolved
without user input. Then the timeout in the developed application can be set to one that seems
reasonable. Keep in mind if the timeout in your application is too long, the user might retry
submitting the payment before it‟s completed.
See the Advanced Application Development section for strategies on handling payments that
timeout in your application but succeed in PayPoint, and how to resolve them.
4.3 Handling Return Codes
PayPoint returns a variety of codes in response to requests. The meaning of these codes is
covered in the Merchant Guide under EPayResultCodes. It is important to handle these return
codes properly, especially in the case of MakePayment and CancelPayment as funds may have
been transferred. It is also important to make sure your application can handle unknown return
codes. Future PayPoint upgrades may add new return codes. Your application should contain a
catch all to handle new codes. Generally, you should consider an unknown code an error so that
Version 2.6.0 Page 12 6/10/2011
PayPoint® Integration Best Practices Guide
it gets noted and the code can either be upgraded or left as an error. A simple handler for the
MakePayment call might look like this in C#:
switch (oResponse.ReturnCode)
{
case EPayResultCode.Payment_Success:
case EPayResultCode.Settled:
case EPayResultCode.Partial_Settlement:
case EPayResultCode.Settlement_Pending:
case EPayResultCode.Payment_Pending:
sUserMsg = “Thank you for your payment.”;
break;
case EPayResultCode.Declined:
case EPayResultCode.Verification_Failed:
case EPayResultCode.Unaccepted_Card_Type:
case EPayResultCode.Payment_Exceeds_System_Limit:
case EPayResultCode.Payment_Exceeds_Allowable_Limit:
case EPayResultCode.Undefined_Item:
case EPayResultCode.Account_Invalid:
case EPayResultCode.Post_Date_Too_Large:
sUserMsg = “There was a problem with your payment information: “ +
oResponse.ResultMessage;
break;
default:
sUserMsg = “There were technical difficulties making your payment.”;
// Save actual error for further investigation
myLog.Add(eError, oResponse.ResultMessage);
break;
}
Below is a table indicating how to handle the various return codes from PayPoint when calling
the API. Note that many codes are not returned via the API. That simply means they are used
elsewhere in the PayPoint system.
Version 2.6.0 Page 13 6/10/2011
PayPoint® Integration Best Practices Guide
WebServices API or Batch
EPayResultCode
HTTPS
API
Result
Code
Ma
ke
Pa
ym
en
t
PIN
Le
ss
De
bit
Ch
ec
k
Ca
lcu
late
Co
nv
en
ien
ce
Fe
e
Ca
nc
elP
ay
me
nt
Pa
ym
en
tSta
tus
Re
gis
tra
tio
nC
RD
Re
gis
tra
tio
nIn
qu
iry
Re
gis
tra
tio
n L
oo
ku
p
Re
cu
rrin
gP
aym
en
tCR
D
Re
cu
rrin
gP
aym
en
tIn
qu
iry
Unknown 0 E E E E E E E E E E
Success 1
S
S S S S S S
Payment_Success 2 S
Cancel_Success 3
S
Error 4 E E E E E E E E E E
Declined 5 F
F
Verification_Failed 6 F
F
Communication_Error 7 E E E E E E E E E E
Settled 8 S
S
Settlement_Error 9 E
E
Network_Error 10 E E E E E E E E E E
Processor_Mismatch 11 E
E
CreditCards_Disabled 12 Ec
Ec
Ec
Unaccepted_Card_Type 13 Fcd
Fcd
Payment_Exceeds_System_Limit 14 F
F
Payment_Exceeds_Allowable_Limit 15 F
F
Possible_Duplicate_Payment 16 F
Unresolved_Cancellation 17 E
E
Undefined_Item 18 F F F F F F F F F F
Chargeback 19
Chargeback_Reversal 20
Settlement_Incomplete 21 E
E
Partial_Settlement 22 S
S
Settlement_Pending 23 S
S
eChecks_Disabled 24 Ee
Ee
Ee
Missing_Identification 25 Fe
Fe
Waiting_On_PreNote 26 E
E
PreNote_Failed 27 E
E
Stop_Payment_Issued 28
Non_Sufficient_Funds 29
Version 2.6.0 Page 14 6/10/2011
PayPoint® Integration Best Practices Guide
WebServices API or Batch
EPayResultCode
HTTPS
API
Result
Code
Ma
ke
Pa
ym
en
t
PIN
Le
ss
De
bit
Ch
ec
k
Ca
lcu
late
Co
nv
en
ien
ce
Fe
e
Ca
nc
elP
ay
me
nt
Pa
ym
en
tSta
tus
Re
gis
tra
tio
nC
RD
Re
gis
tra
tio
nIn
qu
iry
Re
gis
tra
tio
n L
oo
ku
p
Re
cu
rrin
gP
aym
en
tCR
D
Re
cu
rrin
gP
aym
en
tIn
qu
iry
Final_Non_Sufficient_Funds 30
Account_Invalid 31
Payment_Pending 32 S
S
Post_Date_Too_Large 33 Fe
Fe
Refund_Settlement_Pending 34
S
Pre_Auth_Success 35 Scd
Eligible 36
Sd
Not_Eligible 37
Fd
PINLessDebit_Disabled 38 Ed
Ed
Ed
PINDebit_Disabled 39 Ed
Ed
Ed
Blank - Status does not pertain to PayPoint method
S - Success, no further action necessary
F - Failure, user should be shown the error status and message
E - Error, user should be given generic error message, specific error from PayPoint should be saved
ResultCodes apply to all payment mediums except where noted:
e - Applies to eCheck Transactions
c - Applies to Credit Card Transactions
d - Applies to Debit Card Transactions
4.4 Error Handling
Error handling is an important part of any application, but it is especially important in dealing
with external API calls such as PayPoint. There are three major types of errors your application
should be able to handle.
The first is an application error that may occur within your application. For example, let‟s
assume the web service call fails due to a networking issue such as your firewall doesn‟t allow
the URL. This is not a PayPoint error, but an error in the application. Generally, you hide the
error from the user and tell the user the application is experiencing technical difficulties.
Version 2.6.0 Page 15 6/10/2011
PayPoint® Integration Best Practices Guide
The second type of error is an unexpected issue in communicating with PayPoint during your
payment process. For example a network device goes down causing a response from PayPoint to
not be received. This is when you never get a response from PayPoint. In this case, the status of
the transaction is unknown, there may or may not have been an error with the payment. As a
result, the transaction should be flagged and later be checked to see if it needs to be refunded. In
these cases, the user should be notified that their payment failed. The application should then
check the original transaction status using the methods described in the Advanced Application
Development section.
The third type of error is a known PayPoint payment error. By “known” we mean error types
such as Invalid Card Number, Verification Failed, etc. These errors mean the payment failed, and
that the user should be notified why. These errors are safe to show the user.
4.5 Security
Any application that deals with payment information must keep security high on the priority list.
It is essential that user data be kept secure. This means encrypting data where necessary and
never storing certain data.
4.5.1 WHAT TO ENCRYPT
Applications should not store customer specific account information. PayPoint is designed to
hold and manage all of this information on your behalf in a highly secured fashion. Various
government and association rules/regulations govern the management of sensitive account
information. PayPoint goes through annual audits to ensure compliance with these rules and
regulations. If the application will store customer data, then that data should be encrypted using
an AES compliant encryption technique. The best protection is to not store the data at all.
Below is a list of data that PayPoint stores in an encrypted format within our databases:
Account Number
Expiration Date
Driver‟s License Number
SSN
Federal Tax ID
4.5.2 HOW TO ENCRYPT
Version 2.6.0 Page 16 6/10/2011
PayPoint® Integration Best Practices Guide
The encryption used should be a minimum of 128bit AES. Most programming languages have
readily available encryption libraries. One important note is that all encryption methods require
an encryption key. This key is needed to decrypt the data. The security of the encrypted values is
only as good as the security of this key. If the key is easily accessible, then anyone with it can
decrypt the information. The application will need decryption methods to read the encrypted
values, and these functions should never be public.
4.5.3 WHAT TO STORE
When using a database to track your applications payments, there are several key pieces of
information you should store.
Unique ID – Each payment should have a completely unique identifier, this unique
identifier can be passed into PayPoint as the reference to make identifying the
payment in PayPoint easier
Amount – The amount is required for refunds
PayPoint Confirmation Number – Each time a payment or refund is made, PayPoint
returns a confirmation number. Note that PayPoint might associate multiple
confirmation numbers with a payment because the original payment and refund
happen at different times. You may want to do the same.
PayPoint Result Message – If PayPoint returns a result message, it may contain
essential information for tracking any issues with payment and should be stored.
Version 2.6.0 Page 17 6/10/2011
PayPoint® Integration Best Practices Guide
4.5.4 WHAT NOT TO STORE EVER!
Credit card regulations strictly prohibit the storage of certain data. It is against regulations to
store the following:
CVV2
PIN
PIN Key
Track Data
It‟s highly recommended that you not store the following information. However if you do it‟s
important to ensure the data is encrypted and protected by multiple layers of security.
Account Number
Expiration Date
Driver‟s License Number
SSN
Federal Tax ID
Version 2.6.0 Page 18 6/10/2011
PayPoint® Integration Best Practices Guide
5.0 Advanced Application Development
A robust implementation of a PayPoint application will require some advanced concepts to be
implemented. This section covers some of those ideas.
5.1 Asynchronous Requests
To properly support payment timeouts, a PayPoint application should consider supporting
asynchronous calls to the PayPoint system. How to make asynchronous requests depends on the
application‟s specific implementation, so this is beyond the scope of this document. However,
the key is that your application should be able to deal with potential errors that may occur such
as timeouts or dropped network connections. An asynchronous request approach can handle the
payment state such as determining if this request needs to be cancelled; otherwise a duplicate
payment may occur.
5.2 Avoiding Duplicate Submissions
Duplicate payments can occur when the user gets impatient and resubmits the payment before
the first one was finished. Both payments end up going through. Duplicate payments may also
occur around timeout or dropped connections due to unexpected conditions. PayPoint might
finish the payment, but the application has no idea of the payment result. The first step in
preventing duplicate payments is to eliminate the ability of the user to submit two payments in
rapid succession. This usually requires taking the user to a wait page, explaining that the
payment is processing, and instructing them not to use the browser‟s back button. This prevents
the more common duplicate payment cause.
A more proactive approach is to build in support for tracking your transactions with indicators
for payments in process and completion. Prior to sending a payment that status can be used to
determine if a previous payment request is in process or complete and provide user the
appropriate feedback related to the status.
In the case of timeouts or dropped connections, the application must do some cleanup behind the
scenes. The application should attempt to check the payment‟s status in PayPoint using the
reference code, then cancel the payment if necessary. Supporting this feature requires that the
application store a minimal amount of information in their database, so that dropped payments
can be tracked and resolved.
Version 2.6.0 Page 19 6/10/2011
PayPoint® Integration Best Practices Guide
5.2.1 CHECKING PAYMENT STATUS
When a payment times out or network connections get dropped, not only doesn‟t the application
know the status but it also has no confirmation number. One approach to getting status under this
situation is to perform a status request using a reference value. However in order for this to work
your application needs to send a unique reference number for all payments. If PaymentStatus
returns that the payment does not exist, then it is safe to assume the payment was unsuccessful.
However, if it indicates the payment was successful, then the application should store the
confirmation number and decide whether to refund the payment or leave it as is.
5.2.2 CANCELING PAYMENTS
To fully support recovering from critical errors like timeouts or network issues, the application
should be able to automatically cancel payments. After PaymentStatus has returned the
confirmation number of the payment, the application may choose to submit a CancelPayment
command. This requires passing the original payment amount and the confirmation number.
After CancelPayment returns a success, the payment is voided and the duplicate payment has
been resolved.
5.3 Using Registered Accounts
PayPoint supports creating registered accounts. Use of registered accounts provides two
benefits. The first benefit is that it can provide a mechanism for applications with repeat
payments for consumers to provide options to the user to store their account information for
future purchases which can streamline the payment process. The second benefit is that this
dramatically reduces security risk for your application because all sensitive account information
is stored and managed by PayPoint which uses a multitude of security technologies to ensure this
information is not compromised. With registered accounts your application only stores a
registration ID provided by PayPoint and all subsequent interactions to display accounts or
update accounts is managed through PayPoint. Making a payment with registered accounts is
simple; simply pass amount and the registered account id.
Version 2.6.0 Page 20 6/10/2011
PayPoint® Integration Best Practices Guide
5.3.1 REGISTERED ACCOUNT COMMON ISSUES
There are some limitations to the registered account system. Only one address and payment
method may be stored per account. Therefore, to support allowing the user to create multiple
payment methods or multiple addresses, the application must create a new registered account for
each combination. For example, a user with two different credit cards would have two accounts
in the PayPoint system. The application would simply store both the Registered Account IDs.
Another common issue is updating accounts. PayPoint allows you to query a registered account,
but it will never return the full account number (i.e. credit card number, bank account). This is
done for security purposes. Your interface will likely want to provide options for the consumer
to update their account information if it has changed. You will always need to ask the consumer
to re-key their full account number and send that full account number with your registration
update request to PayPoint.
5.4 Handling multiple payment types (Credit Card, eCheck, Debit, etc)
Ideally, the application should be able to handle any type of payment even if initially it will only
support one or two. This makes adding support for new payments easy in the future. Supporting
multiple payment types is relatively simple. PayPoint has defined two primary datasets for
payment information, PaymentInfoCC and PaymentInfoEFT. Other payment types such as
pinless debit and debit simply piggyback onto these datasets. PayPoint relies on the
PaymentMedium property to know which dataset to use. Below is a breakdown of which
PaymentMediums map to which data object.
PaymentInfoCC
CreditCard
CommercialCreditCard
PINlessDebit
Debit
Third Party Data including:
o Cash
o LockBox
o Point of Sale (POS)
o RemoteCapture
Version 2.6.0 Page 21 6/10/2011
PayPoint® Integration Best Practices Guide
PaymentInfoEFT
ACH Credit
eCheck
BusinessCheck
By consolidating the application‟s validation code to focus on these to data objects, it‟s easy to
support all payment types.
5.5 Interface suggestions
When requesting user payment information, it is important to clearly indicate what is required.
Segment out portions of the form interface, for example, separate the payment information from
the address information. This makes it easy to reuse the address entry for credit card versus
eCheck data entry. Use JavaScript validation to provide immediate feedback for missing data
like credit card number. Where possible, don‟t rely on PayPoint to tell the user what data is
missing.
It is also recommended you hide PayPoint error messages from users. If an error occurs, simply
tell the user problems occurred making the payment and they need to try again. If the user‟s card
was rejected due to bad information, present a user friendly version of the message.
5.6 Version Compatibility
The PayPoint Product Team is responsible for enhancing PayPoint‟s feature/functionality
including improvements related to technology advancements, usability, gateway advancements,
etc. These updates are managed through scheduled product releases. Our product team does a
lot of work to ensure that our product releases won‟t break existing applications if they are coded
properly. PayPoint only adds features to the API, meaning existing properties will never be
removed or renamed to ensure backward compatibility with existing integrated applications.
There are some practices that you should follow to provide assurance that your code will always
be compatible with product updates. Never hard code the expected return fields. For example,
PaymentStatus currently returns the payment status and confirmation number. The application
should simply look for these two values and ignore any other data. In a future version, PayPoint
might also return the last four digits of the credit card in the status. Your application would
continue to work properly as long as it ignored this data. Most web service APIs, such as the one
built into Microsoft .NET, automatically handle these situations gracefully and simply ignore the
new fields.
Version 2.6.0 Page 22 6/10/2011
PayPoint® Integration Best Practices Guide
Additionally, due to the nature of the XML data returned via the web service and the key/value
data returned via the HTTP API, do not hardcode the expected order of return values. Your
application should be able to handle the return values in any order.
Version 2.6.0 Page 23 6/10/2011
PayPoint® Integration Best Practices Guide
6.0 Common Issues
6.1 Web Service Reference
A common development issue occurs when adding a reference to the web service using the web
service address. The procedure of adding the reference works fine, but any actual calls to the web
service fail. This is due the way Microsoft automatically generates the WSDL when adding a
reference to the web service. PayPoint is behind a firewall for security, and because of this the
generated WSDL returns the internal address of PayPoint which is inaccessible via the internet.
To get around this issue, PayPoint provides a separate WSDL with the correct address. In
addition, always set the web service URL in code before calling the web service. That ensures
that the URL is easily configurable, and not hard coded in the project.
ADD PAYPOINT WEB REFERENCE IN MICROSOFT VISUAL STUDIO 2003
1) Create new project
2) Right-click on References in the Solution Explorer window and choose Add Web
Reference…
3) Enter the address for the WSDL:
https://www.govone.com/epay/epaywebservice.asmx?WSDL
4) After the PayPoint web service is found, change the Web Reference Name to something
more readable, such as “PayPoint”
5) Click Add Reference
Version 2.6.0 Page 24 6/10/2011
PayPoint® Integration Best Practices Guide
6) In the Properties window for the PayPoint web reference, change the URL Behavior to
Dynamic (this allows the URL to set in code)
7) Finally, remember to set the URL property of the web service in code
//Create the web service
PayPoint.EPayWebService oService = new
PayPoint.EPayWebService();
//IMPORTANT: Set the web server address
oService.Url = (string) Params["PayPoint URL"];
Version 2.6.0 Page 25 6/10/2011
PayPoint® Integration Best Practices Guide
6.2 HTTP API URL Encoding
When passing values to the HTTP API using query string format, a common mistake is
improperly encoded values. Query string parameters are simply key=value pairs, but it is very
important that only the value portion be URL encoded. This means special characters need to be
escaped properly. Take a payment status request as an example. The application ID is „320‟ with
a password of „h3!!o‟, and the payment‟s reference data is „test=yes‟. Following the instructions
in the Merchant Guide, the request should look as follows:
https://www.govone.com/epay/http/ps.aspx?m=r&a=320&s=h3%21%21o&p=1&e=test%3Dyes
Note that only the values are URL encoded. So „h3!!o‟ becomes „h3%21%21o‟, and that the
equal sign in the reference is encoded but the equal signs delimiting keys from values are left
alone. Most languages support URL encoding. For example, in ASP the above string can be
written as follows:
Dim sReq
sReq = “https://www.govone.com/epay/http/ps.aspx?m=r&a=320”
sReq = sReq & “&s=” & Server.URLEncode(“h3!!o”)
sReq = sReq & “&p=1”
sReq = sReq & “&e=” & Server.URLEncode(“test=yes”)
Version 2.6.0 Page 26 6/10/2011
PayPoint® Integration Best Practices Guide
7.0 A Simple Payment Application
This section will describe two different simple PayPoint applications provided with this guide.
They represent the most basic application possible, one that accepts credit card information and
submits it to PayPoint as a payment. These applications are meant as a starting point. They are
not fully realized applications, and as such, do not contain the level of error handling and
security a full production application should contain. These samples can be downloaded from the
PayPoint website: https://www.govone.com/epayadmin/samples/paypoint%20samples.zip
7.1 ASP HTTP Application
This sample is an ASP application that uses the PayPoint HTTP API to submit a payment. It is a
single tier application in that it exists solely on the web server and makes the call to PayPoint
synchronously. It does not separate the call to PayPoint from the ASP code, and in that regard
does not follow the recommended code separation. However, it would be trivial to move the
payment code into a reusable ASP include, or better yet into a DLL.
The application is a single page that requests the user‟s basic credit card information. When the
user submits the page, the code validates the input, constructs the PayPoint request, and finally
uses the WinHTTP DLL to submit the request.
There are two important things to note. First, all parameters are URL encoded which prevent
special characters from causing problems in the request. Second is the use of the WinHTTP
Request timeouts. In rare cases, a network issue can prevent your application from receiving a
response to a request. Without a timeout the page may hang indefinitely. It is important to detect
when a timeout has occurred and record it because the payment may have succeeded and will
need to be refunded later.
This sample can be found under \ASP.
7.2 C# ASP.NET Web Service Application
This sample demonstrates making an asynchronous call to the PayPoint web service from an
ASP.NET application. The ASP.NET code does not call PayPoint directly, but uses a DLL that
contains the essential PayPoint communication code. This allows the DLL to be reused across
several applications if necessary. The DLL uses the web service timeout built into .NET to detect
when payments time out and marks the payments for later cleanup. Since it‟s possible the
Version 2.6.0 Page 27 6/10/2011
PayPoint® Integration Best Practices Guide
payment will complete successfully in PayPoint, it‟s important to clean up (i.e. refund) the timed
out payments so that duplicate payments do not occur.
In order to track payments, the sample uses a simple database to store basic payment
information. Note that it is not necessary to store sensitive data such as credit card numbers to
build an effective PayPoint application.
This sample can be found under \CSharp.
Resources
Microsoft Developer‟s Network (MSDN)
http://msdn.microsoft.com
Open Web Application Security Project (OWASP)
http://www.owasp.org/index.php/Main_Page
SOAP::Lite for Perl
http://soaplite.com/