Developer FAQs

General

Can Payment Express handle multiple simultaneous transactions?

Yes, we can. However each transaction needs to be processed by an electronic merchant number given to us by the merchant. So, how many simultaneous transactions we can accept depends on how many electronic merchant numbers you have.

Can transactions be performed using a specified currency?

Yes. Current banks that can provide multi-currency services can be found here. Component references will have the parameter and currency code that needs to be specified with each transaction.

Can we get our money from the cards deposited to an account other than own bank account? Can we set it up so that that all proceeds are deposited to an account other than our own - our suppliers bank account for example?

Yes. Settlement may be made to a bank account other than your own. The "Merchant" relationship remains between yourself and your bank though. Contact your bank for further details.

Do you have any products that do not need Payment Express or 3rd party software?

PX Post is our platform independent product, which is an XML interface at our host. All you need to be able to do is send us XML, which you can wrap in the language of your choice.

Does my application need to retain the original card number in order to process a completion or refund transaction?

NO. Do not store card or expiry details, rather store just DPSTxnRef returned by the original transaction.

How does Payment Express handle Refund Transactions?

A refund transaction transfers (refunds) money from the Merchant account to a cardholder account. This transaction is used for example, when goods are returned or in other circumstances at the discretion of the merchant. Refunds need to be matched with their original purchase/complete transaction, which is returned its response as DpsTxnRef. Each component reference has a section on doing refund transactions. Also merchants have access to the Payment Manager to handle refunds manually, if they do not wish to build their own interface.

How long does it take to authorise a transaction?

Transactions are normally processed within 3-5 seconds.

How can we generate a declined transaction for testing?

This can be done using one of the test cards below:

Expired Card (ReCo 54) - 4999999999999996

Card with Insufficient Funds (ReCo 51) - 5431111111111228

Timeout (ReCo U9) - 4999999999999202

Using the card number 4999999999999202 will result in a declined transaction and set the retry flag to "1" for interfaces that support it.

Is Cardholder name field validated?

No, the cardholder name is not validated. Only the card number and expiry date are verified by your bank. Also CVC and 3D authentication if you are enabled for those

Is there a message that I can use to reassure my customers that their transaction will be secure?

Our privacy policy (http://www.paymentexpress.com/privacypolicy.htm) should be linked on your payment page.

There is no input field/property to allow the card type to be specified, Visa, MasterCard etc?

You do not need to specify the card type. Payment Express is online to the acquirer and the card type is determined from the card number. Card type used is returned for successful transactions in the Cardname property.

What is the difference between the Transaction Date and the DateSettlement?

Transaction date is the date of authorisation, date settlement is the date that the transaction is applied to the merchant bank account.

What programming languages do you support?

Developers can use virtually any programming language to interface into the Payment Express payment gateway. Common examples that are being used are PHP, CF, ASP, Perl, Java & .NET, which we generally have samples for.

Ecommerce NonHosted

DPS AuthS COM object

A 32 error message appeared during the COM object installation and I need to know what to do to resolve the problem.

Most error messages that occur during installation are related to the presence of previous versions. It is important to uninstall these programs before installing or use the current version installed if it is current.

I am testing my integration with your gateway and am receiving back a response code of D2 and response text of declined. What am I doing wrong?

You should contact Payment Express to confirm your Post Username and Password are correct, as the ones you are using are not authenticating.

I am testing my integration with your gateway and am receiving back a response code of D5 and response text of declined. What am I doing wrong?

You should contact Payment Express to confirm your Post Password is correct, as the one you are using are not authenticating.

The only response I receive when testing transactions is 99. Why is that?

Your payments aren't reaching the Payment Express gateway. This is usually because you are being blocked by your firewall or proxy server. Get the output of the TraceData property for a better understanding of what is blocking you.

What field do I use to set the currency?

Currency

What ports does my firewall need to be able to access?

The standard ports (80 and 443) for https posts and hosting a web site.

DPS AuthS Java Bean

Can you clarify whether the Javabean is an enterprise Javabean, or just for use in a standalone Java application.

The AuthSSL Java bean is a standalone java application which needs JRE 1.4 or above to run, can be embedded in any Java application, stand alone or Java servlet.

For the Auth SSL Java Bean, the configuration states details for a proxy, what do we do if we do not have a proxy?

The proxy server is the proxy server of the local network, which is used to connect to the Internet rather than the Payment Express gateway server. The java bean will connect to Payment Express gateway server via the local proxy server.

I am testing my integration with your gateway and am receiving back a response code of D5 and response text of declined. What am I doing wrong?

You should contact Payment Express to confirm your Post Password are correct, as the one you are using are not authenticating.

I am testing transactions to your gateway with 20 simultaneous connections, but I am getting exception errors in the Java Bean. Can you explain why?

The Java Bean has been limited to 10 concurrent connections, as in a real world scenario this would be the maximum ever needed. You would need 10 electronic terminal numbers with your bank to process 10 simultaneous transactions at once as well.

What field do I use to set the currency?

Currency

What ports does my firewall need to be able to access?

The standard ports (80 and 443) for https posts and hosting a web site.

PxPost

What is the difference between PX Post and PX XML?

Although both products use an XML interface, PX XML needs to connect to PX Server/Daemon, whereas PX Post connects directly to our host.

What field do I use to set the currency?

In order to send/post a transaction, an SSL socket must be open between our system and your gateway. My question is whether, once that socket is open, we can do multiple interleaved transactions (socket write/read operations). Some gateway servers shut down a connection after a single transaction is processed or expect the client to close the connection. Other servers permit the connection to remain open and support interleaved transactions. How does your server work?

You can keep the SSL connection by specifying header information: Connection: Keep-Alive\r\n. Our PXPost server is a standard HTTPS server. You may need to specify header information every time before you post a transaction.

I am testing my integration with your gateway and am receiving back a response code of D2 and response text of declined. What am I doing wrong?

You should contact Payment Express to confirm your Post Username and Password are correct, as the ones you are using are not authenticating.

I am testing my integration with your gateway and am receiving back a response code of D5 and response text of declined. What am I doing wrong?

You should contact Payment Express to confirm your Post Password are correct, as the one you are using are not authenticating.

What ports does my firewall need to be able to access?

The standard ports (80 and 443) for https posts and hosting a web site.

Ecommerce Hosted

Hosted payment page (general)

I am testing on my local machine and I am not receiving your background post, only the redundant response when I click next. Why is that?

Your web site needs to be a publicly accessible domain name/I.P and on the normal web publishing port (80), as the Payment Express Host needs to be able to find this address on the internet. However, when the user clicks "Next" the response is returned by the browser.

What is the difference between PX Post/PX Toolkit and the Hosted Payments Page?

The difference is that PX Post takes payment on your secure payment page and you get the response given back to you in the post, whereas the hosted payments page takes payment on our secure servers after being forwarded from your site with the order details and we send you back the response to your insecure pages etc.

How do I get my logo to show on the Payments Page and change the titles for TxnData1,2 and 3 fields?

You can send any changes to these fields by sending [email protected] the changes and images you would like made.

I have set the response pages URLs in my transaction request form, but I'm not getting redirected back to the pages i asked for.

You need to use a fully qualified address for example http://www.yourwebsite.com/response.xxx. You cannot just use response.xxx etc.

What field do I use to set the currency?

CurrencyInput

What happens if a customer doesn't click "Next" on the payment result page and/or closes their window?

This is where Fail Proof Result Notification (FPRN) comes in. A background message is sent from the Payment Express server to the merchant's nominated Success/Failure page as soon as a transaction is processed. This feature is enabled by default for all Payment Express Hosted accounts. The merchant's website should be able to handle multiple responses for a transaction.

What ports does my firewall need to be able to access?

Only the standard port 80 for http posts.

Why can't Internet Explorer display my success or failure pages?

Internet Explorer limits URLs to 2083 characters, above which it will display a page stating that 'Internet Explorer cannot display the webpage'. The lengths of the query strings used on the payment pages and of those appended to the success and failure URLs can sometimes cause the URLs to exceed the maximum allowable in Internet Explorer. This will generally only occur when large amounts of transaction data are being passed to Payment Express' and are subsequently encrypted and become part of the query string. Please contact the Payment Express support team to ask about URL compression or reduce the amount of transaction data being passed in optional fields.

Why do amounts like $2,500 come out as $2 on the payment page?

This is due to a formatting error of the amount string. The amount cannot have commas or dollar signs in the string. The amount should instead be in the following format: 2500.00

Back to top

Why do I get an error page stating that the 'Root element is missing'?

When the URL is provided as part of an XML document certain characters such as the ampersand must be escaped in order to maintain the integrity of the document. Before directing the browser to the URL provided the escaped charaters should be unescaped.

Why do I see an error screen when I redirect to the payment page?

Please see this page for details on the error codes provided.

Why is Payment Express calling my success/fail url TWICE in succession?

This is deliberate redundancy - see http://www.paymentexpress.com/blue.asp?id=d_pxaccess, under "Fail Proof Result Notification". By doing this when a customer submits a credit card for processing your site is guaranteed to receive notification of the transaction. Without this feature there would likely be a problem if a cardholder failed to return to the merchant site having submitted a card e.g. he might close his browser. Generally merchants, quite properly, rely on this notification to know when to take action on orders. The two calls we make to the URL are identical, so we advise developers to simply disregard the second post if and when they get it.

Hosted payment page (Linux)

I am currently getting the following web server error message before going to your payment page using PHP. Warning: unpack(): Type H: outside of string in ....

You need the mcrypt library package, if your version of PHP doesn't come with it installed. Have a look at your php.ini. Make sure extension=libmcrypt is there and not commented out.

I am using the PHP version of the Hosted Payments Page and when I try and process a transaction I get an NK error, what is the problem?

If you are just testing your payment page, you might have got the PX Access key wrong. You should contact Payment Express to confirm the key, however if this is not the reason, you should check the code for comments about your PHP version. The current sample changes the code automatically for the php version you are using.

I get the following error when submitting the payment with the PHP PX Access, what would be wrong? Fatal error: Call to undefined function: mcrypt_module_open() in ....

You need the mcrypt library package, if your version of PHP doesn't come with it installed. Have a look at your php.ini. Make sure extension=libmcrypt is there and not commented out.

Why cannot i use a versions below JDK 1.4 for the Hosted Payments Page using Java?

PX Access java can only run native on 1.4 jdk, as no 3des encryption functions on 1.3. However, you can install Java Cryptography Extension (JCE)

Hosted payment page (Windows)

My understanding was that Payment Express would be hosting the payment page for us. Why do i need to install the COM object?

For windows systems the COM object is required to handle the 3DES encryption in the URL string given to our Host and the response given back, which the COM has to decrypt from the response string. It has built in method calls and exception handling, so there is less programming for the merchant to do. If you cannot install any COMs on your host for any reason, you would need to use our platform independent products like PX Post with your own SSL certificate. Exception handling would need to be written by yourselves as well.

Back to top

Is version 1.3.5 of the PX Access Com object compatible with VB and ASP code written for 1.2.2?

The new Com object uses the triple DES encryption, which is a 24 byte session key and 8 byte MAC key to check if the message matches correctly. That greatly improves the channel security. You will need to grab a new 64 digit key from Payment Express to install with the new COM. Additionally your response pages need to set the UserId parameter with the COM to decrypt the response.

Back to top

A 32 error message appeared during the COM object installation and I need to know what to do to resolve the problem.

Most error messages that occur during installation are related to the presence of previous versions. It is important to uninstall these programs before installing or use the current version installed if it is current.

Integrated EFTPOS

PX CL ActiveX COM object

I develop an application using Borland Delphi. How do we integrate this application with Payment Express?

Delphi versions 3.0 or greater support Microsoft ActiveX and COM objects. The ActiveX control is designed to be used for User Interface applications

PX EFTPOS

Do we need the Eftpos Communication Server and Pinpad service installed at anytime during testing?

The software components will only be needed when you are ready to roll out the Eftpos terminals. For integration purposes you can "EnableTestMode" and use the PinPad simulator. A development Pinpad can be purchased however and will be refunded when returned to us, if you need to test in a live environment.

How are refunds carried out by the merchant?

Refunds are done like normal purchase transactions (except TxnType will be "Refund"), where the credit card is keyed in or received by swiping the card (track data). A supervisor card is needed for each terminal in addition to this, which you need to request from your bank.

How do I get a declined response in "EnableTestMode"?

The test to generate a declined response is an amount with any dollars amount and 76 cents; ie 8.76. You should get an approved response if you try any other amount, for example 8.12 etc

How do we test without the PinPad terminal being connected?

How do we test without the PinPad terminal being connected?

I get a "PX offline" error when trying test transactions. What is the cause of this?

The terminal ActiveX control is for the developer to mimic the eftpos transactions without Pinpad and Eftpos communication server environment. You need to set the property EnableTestMode = true to set the activeXControl to test mode, otherwise it will try to connect to Eftpos communication server and will cause a "PX Offline" error message.

I have set EnablePrintReceipt to true (1) should it now print the receipt for me?

The receipt will be printed if the "EnablePrintReceipt" set to true in the live environment. But the receipt printing is controlled by Pinpad server and at the moment you haven't installed the Pinpad server and printer, so there's no receipt printed.

What are the minimum system requirements for EFTPOS?

As the software installs as a service, it will only run on NT platforms. Recommended platforms are currently:

Windows Vista to Windows 7

Recommended minimum RAM : 1GB

Recommended minimum CPU: 2.4GHz single core

You will need administrator access to install the software and permanent write privileges for the user on the system (install volume) for temporary storage of transaction information.

What is the HostId to use?

This should be 001 for live ETSL transactions. If you are using the test host with test ETSL numbers, this will be 541.

What ports do we need open on our external firewall for the Eftpos Communication Server?

The communication server uses port 61 to communicate to the banking network.

What ports do we need open on our internal firewall (LAN/WAN) for communication between the Pinpad services on each terminal to the EFTPOS Communication Server?

Port 62 is used on the internal network and computers.

When I use my Eftpos client/POS, it freezes when it tries to do a transaction. What is the problem?

You need to have write/modify permissions on the EFTPOS installation directory for the system to work, as it needs to store temporary data on the system.

GPRS

Does the completion amount have to be the same as the authorisation amount?

The Completion amount can be different to the authorisation - the auth merely reserves funds prior to the completion.

If we would like to leave merref field empty, what shall we put in?

The MerchantReference may be left empty - it is free text (max 64 character) that appears on merchant reconciliation reports. It could be a tax invoice number (from receipt etc).

In the specification there is mention of an Account field. What should be used here?

This should be left empty, as it is reserved for future use.

We are going to put the version number inside our hello message, will Payment Express system return new software version of our parking machines as soon as finds that newer version was used?

The contents of this message are such that Versions etc can be used for optional features such as new firmware downloading - in this scenario the Payment Express host can detect a software version of an installed vending device and make available a new software release via GPRS. This is an optional feature and for connectivity checks this can be ignored.

What are the benefits of using Auth/ Completion transaction types?

The meter could be programmed to automatically send an auth after the card is inserted and while the user is choosing parking time span, the meter receives the results of the auth (typically 3-4 seconds). This means that when the user has selected the time to park (and the final amount is then known to the meter), the meter already has the results of the authorisation - if a stolen or expired card has been used the transaction does not proceed further, otherwise for an approved authorisation, the meter can proceed to print the ticket and, if no printer malfunction and ticket has been dispensed, the completion can be sent. The cardholder is provided with the impression of an instant issuance of ticket - same speed as coin is most cases. If the ticket cannot be issued, then the completion phase is not sent - the auth does not result in a charge being applied to the cardholder account unless it is followed by an auth complete.

What is this ~123~ from the example?

The 123 is the amount to pre authorise with implied decimal place. - Eg:AUD$1.23.

What shall we send in ConfigChecksum field?

Space, blank or any alphanumeric characters are acceptable.

What shall we send in SwVersion, what is the purpose of this field?

The hello message is optional. It is our experience that certain GPRS modems, for example the GT47 from m2mconnectivity, do not reliably indicate to the RS232 attached device that an established TCP socket has been closed by the remote end or network. This means the vending device does not learn about the connection failure until after a send is attempted. If this a send containing a transaction, a very long period (>14 seconds) may be needed for the device to re-establish connectivity. This would be unsatisfactory for the cardholder. Payment Express would recommend periodic sending of a hello message by the vending device to check that connectivity is available every 30-60 minutes or so. If a hello message fails (no response received), the device can reset the modem as needed. The contents of this message are such as Version etc can be used for optional features such as new firmware downloading - in this scenario the Payment Express host can detect a software version of an installed vending device and make available a new software release via GPRS. This is an optional feature and for connectivity checks can be ignored.

What shall we send in track1 field if it is empty?

Null is recommended ~~ It's only handy to have the track1 info if available) for reporting purposes and to assist in customer queries from cardholders.

Legacy Interfaces

Batch Processor

Do file names matter to the Batch Processor?

File names for batches only matter locally in preventing the batch processor client from processing the same file twice. However, the actual name of the file does not impact upon the operation of the processor.

I am the IT support engineer here and have been installing your PX server and Batch Processor software as per the instructions I was sent. However, I cannot ping the IP address's you have listed.

You actually will not be able to ping us, as we only have a few ports open and the rest are behind a firewall. First you have to see if your own firewalls are letting you communicate outside on port 3007. Please telnet to our host instead on this port.

When using DPSBAT Batch Processor, does the Batch Processor ensure that files are not processed twice or must my application remove processed input files from the directory before starting a new processing run?

The DPSBAT Batch Processor ensures that records are processed once only and includes full power-fail recovery. If power fails during a processing run, processing is resumed after restart at the correct record. DPSBAT will not process files twice as it ignores all files with _OUT as the last part of the filename and files are automatically renamed to have this extension as part of processing.

DPS Auth COM object

A 32 error message appeared during the COM object installation and I need to know what to do to resolve the problem.

Most error messages that occur during installation are related to the presence of previous versions. It is important to uninstall these programs before installing or use the current version installed if it is current.

DPSAuth returns 'Transaction Approved' no matter what of card number is entered.

The DPSAuth control is running in "simulator" mode.

The following error occurs when we try to use the DPSAUTH COM Object: Server object error 'ASP 0193 : 80020009' OnStartPage Failed /TestDPS.asp, line 25 An error occurred in the OnStartPage method of an external object.

This error occurs when Session State is disabled on the web server. To fix this problem either Enable Session State on your web server or upgrade your DPSAUTH COM Object to v2.22+

Using dpsauth.asp Active Server Page with Payment express results in the following error displayed on the browser: Server object error 'ASP 0177 : 800401f3' Server.CreateObject Failed dpsauth.asp, line 19 Invalid class string

The DPSAUTH.DLL COM object is not properly installed on the web server executing the ASP. Reinstall the DPSAUTH.DLL COM Object or use REGSVR32 DPSAUTH.DLL to register the COM object manually.

Using the DPSAuth.DLL COM Object, transactions are failing with ResponseCode "S4" and "S5". Why is this failure occurring?

"S4" and "S5" indicate that DPSAuth.DLL COM object has established a connection to the Payment Express Server installed at the Merchant Site, but that the link upstream from the Payment Express Server to the Payment Express Host is not active or online.

What field do I use to set the currency?

Currency

What ports does my firewall need to be able to access?

The TCP/IP port 3007 needs to be open for the Payment Express server to connect to our host. The DPSAuth COM object needs to have access to port 3004 on the local network.

PX server / daemon

Can i have the Payment Express Server installed on a different machine to my client application?

Yes. You need to check "Enable Second Listener" on the "Local" tab of the PX.EXE control panel. Payment Express will now listen by default on the PC's given IP Address.

How secure is the connection from the PX server to the Payment Express gateway?

The PX server uses a 168bit encrypted tunnel to communicate with the Payment Express Host. This provides more than adequate security and is similar to transacting via an SSL certificate.

We are running a web farm for a number of merchants. How do we use Payment Express to ensure each payment is settled to the appropriate merchant bank account?

The DPSAUTH.DLL COM and the DPSAUTHP Site Server Plug-In expose an "Account" property. This property must be set with the correct merchant account number from 1-9999 prior to starting the transaction. The account is mapped to a unique virtual terminal or group of virtual terminals at the Payment Express Server and the terminal/terminals allow settlement to any bank account. As each new merchant is added to a web farm Payment Express, terminals and a unique account number (unique for a given payment express service) is allocated.

We have upgraded our kernel version on our Linux server and noticed the following error occurring with the Payment Express daemon. 09:31:17 00000420/000002b0>recv() Socket:580 Error:10054 09:31:17 00000420/000002b0>readsocket failed -disconnecting

The PX daemon may not support your kernel version. Only versions up until 2.4.18 are supported. Versions above are best to try our Cross platform product called PXPost, which involves no Payment Express or 3rd party software.

What changes need to be made to the firewall?

The Payment Express Server needs outbound access to port 3007 (http) on the following internet addresses: 219.88.103.203, 219.88.103.202, 210.54.253.165

When I start the Payment Express Service it instantly changes the start up type to DISABLED.

The Payment Express Service is designed to DISABLE itself if it does not connect for 7 straight days. To re enable the service you will need to delete the "LGNTIM" registry string value. This is found in the registry at HKEY_LOCAL_MACHINE\Software\DirectPaymentSolutions\PX\SERVER\LGNTIM. You can now restart the Payment Express Service.

PX XML interface

Can I use http headers or a connection which uses the HTTP protocol for the XML interface?

No, the transaction information needs to be in raw XML when a socket connection is made through to the PX Server.

What field do I use to set the currency?

What is the difference between PX Post and PX XML?

Although both products use an XML interface, PX XML needs to connect to PX Server/Daemon, whereas PX Post connects directly to our host.

Why isn't Payment Express server receiving transactions from my new version of PHP code (4.2 and above)?

If the PX Server is not receiving transactions and you can establish a telnet session or post transactions to the PX Server the explanation is most likely to do with the new version of PHP. Different versions of PHP use different methods to create and write to a socket. Our sample uses fsockopen, fputs, fgets and fclose. But more recent versions of PHP e.g. v4.2.2 + errors occur when trying to use this method. In the past customers have been able to solve this problem by rewriting the example using socket_create, socket_connect, socket_write etc..

3D Secure

How does 3D secure authentication work?

It requires the card holder to enter a password (only if the card holder is enrolled) as an additional step to entering their credit card details that is verified by the issuing bank. Once the issuing bank has verified the password, the user is then redirected back to the merchants web site.

Which Payment Express products support 3D secure authentication?

The Payment Express Hosted Payments Page (where payment is taken on our secure pages) and the Payment Express Webservice are both capable of handling 3D Secure Authentication.

CVC2

Is CVC a required field for transactions?

Yes, CVC/CVC2/CVV2 is now a mandatory field and applies to all electronic commerce merchants. The mandated date may vary from region to region, so please check with your bank if unsure.

Is CVC always validated?

CVC2 may not be validated by all banks/acquirers, if unsure, please check with your bank.

Transaction Types

What is the difference between Purchase and Auth/Complete transaction type payments

Purchase debits the card in real time, if you need to cancel the transaction because you do not have the stock or just not willing to ship the product you need to do a refund. Authorisation on the other hand, transfers no money. It validates the card and guarantees it will be approved for the amount and ties the funds up for seven days. If you do not wish to take money from the client you literally do nothing, and the hold on the money will expire after 7 days. If you wish to take payment you can complete it within 7 days.

Merchants and developers can find answers to some of their commonly asked questions.