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.

http://www.firstdata.com/

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


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


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/

https://www.govone.com/epay/epaywebservice.asmx?WSDL




https://www.govone.com/epayadmin/samples/paypoint%20samples.zip

Version 2.6.0 Page ii 6/10/2011


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


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


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


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


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


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


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


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.


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


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


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


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

http://www.microsoft.com/downloads/details.aspx?familyid=c943c0dd-ceec-4088-9753-86f052ec8450&displaylang=en

http://www.microsoft.com/downloads/details.aspx?familyid=c943c0dd-ceec-4088-9753-86f052ec8450&displaylang=en

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnsoap/html/soapliteperl.asp

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnsoap/html/soapliteperl.asp

http://java.sun.com/webservices/downloads/1.3/index.html

Version 2.6.0 Page 11 6/10/2011


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


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


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


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


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


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


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


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


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


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


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


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


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:


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


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


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”)

https://www.govone.com/epay/http/ps.aspx?m=r&a=320&s=h3%21%21o&p=1&e=test%3Dyes

Version 2.6.0 Page 26 6/10/2011


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


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/

http://msdn.microsoft.com/

http://www.owasp.org/index.php/Main_Page

http://soaplite.com/

PayPoint Integration Best Practices Guide - First Data material presented in this PayPoint...

Documents

Transcript of PayPoint Integration Best Practices Guide - First Data material presented in this PayPoint...