WebServices_API_1.0

8/12/2019 WebServices_API_1.0

1/180

API Reference Guidefor Web Services

February 2014

Version 1.0


2/180

This manualandaccompanying electronic media are proprietary products of Optimal Payments plc. They are to be used onlyby licensed users of the product.

19992014 Optimal Payments plc. All rights reserved.

The information within this document is subject to change without notice. The software described in this document is provid-ed under a license agreement, and may be used or copied only in accordance with this agreement. No part of this manual maybe reproduced or transferred in any form or by any means without the express written consent of Optimal Payments plc.

All other names, trademarks, and registered trademarks are the property of their respective owners.Optimal Payments plc makes no warranty, either express or implied, with respect to this product, its merchantability or fitnessfor a particular purpose, other than as expressly provided in the license agreement of this product. For further information,please contact Optimal Payments plc.

International Head Office3500 de Maisonneuve W., Suite 700Montreal, Quebec H3Z 3C1Canada

Tel.: (514) 380-2700Fax: (514) 380-2760

Email: [email protected] support: [email protected]

Web: www.optimalpayments.com

U.K. OfficeCompass House, Vision ParkChivers Way, HistonCambridge CB24 9ADUnited Kingdom

Email: [email protected] Support: [email protected]: www.netbanx.com

U.S. Office1209 Orange StreetWilmington, DE 19801

Gatineau Office75 Promenade du PortageGatineau, Quebec J8X 2J9Canada


3/180

API Reference Guide for Web Services 1.0 III

Contents

1 NETBANX Web ServicesWhat are NETBANX Web Services? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Web Services supported for Direct Debit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1Web Services supported for credit cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2Web Services supported for Information Lookup Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

Accessing the NETBANX WSDLs and links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Direct Debit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Credit card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Information Lookup Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

Testing NETBANX Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Security features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

AVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4CVD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5Negative database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-63D Secure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6

Using this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6Functionality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7

2 Direct Debit TransactionsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

.NET example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Building charge, verify, or credit requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3charge example C#. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3ddCheckRequestV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5ddCheckRequestV1 elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6

Special considerations for Direct Debit elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12

Building updateShippingInfo requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12

updateShippingInfo example C# . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13ddShippingRequestV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14ddShippingRequestV1 elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15

Building lookup requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16lookup example C#. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16ddLookupRequestV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18ddLookupRequestV1 elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18

Building mandate requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20


4/180


5/180

February 2014

API Reference Guide for Web Services 1.0 V

Building Authentication requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-45Authentication example C#. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-46ccAuthenticateRequestV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-46ccAuthenticateRequestV1 elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-47

Processing the response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-49detail tag/value pairs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-55addendumResponse tag/value pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-55Currency codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-56

4 Information Lookup Service TransactionsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

NETBANX ILS WSDLs and links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

.NET example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Building ILS requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3ILS C#. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3

ilsLookupRequestV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5ilsLookupRequestV1 elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6

Processing the response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8ilsLookupResponseV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9Response element contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12

Authorizations response details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13Settlements response details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13Credits response details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14Chargebacks response details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14Direct Debit response details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15

Reason codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16Chargeback reason codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16Retrieval request reason codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17Discover chargeback and retrieval request reason codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18

A Using the HTTP Post MethodIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Direct Debit requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1charge/verify/credit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

HTML example charge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2updateShippingInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4

HTML example updateShippingInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4ddLookupRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6HTML example lookupRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6

Mandate request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7HTML example mandate request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8

Change status request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9HTML example change status request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10

Credit card requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10


6/180

February 2014

VI

Purchase/Authorization/Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10HTML example Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-12

Authorization Reversal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-14HTML example Authorization Reversal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-14

Settlement/Credit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-15HTML example Settlement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-16

Stored Data Authorization/Purchase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-17HTML example Stored Data Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-17

Cancel Settle/Credit/Payment/Independent Credit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-18HTML example Cancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-19

Payment request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-20HTML example Payment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-21

Credit card Information Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-22HTML example Information Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-23

Enrollment Lookup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-24HTML example Enrollment Lookup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-24

Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-25HTML example Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-26

Information Lookup Service requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-27HTML example - ILS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-27

Sample HTTP Post . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-28Sample HTTP Post responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-29

B Response CodesOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

Response codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1Action codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-18

Return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-18

C Geographical CodesProvince codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1

State codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-2

Country codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3


7/180

API Reference Guide for Web Services 1.0 1-1

CHAPTER1

NETBANX Web Services

What are NETBANX Web Services?Web Services are a technology that allows applications to communicate with each other in a plat-form- and programming languageindependent manner. A Web Service is a software interfacethat describes a collection of operations that can be accessed over the network through standard-ized XML messaging. It uses protocols based on the XML language to describe an operation toexecute or data to exchange with another Web Service. Web Services are built on open standardssuch as SOAP and WSDL.

NETBANX Web Services offer the following benefits:

Merchants can integrate easily with the Web Service API, using their favourite platform andlanguage.

Merchants can automate operation and avoid manually keying in information via the NET-BANX Web page.

Merchants can operate independently of changes and updates to the NETBANX Web site.

Web Services supported for Direct DebitNETBANX currently supports the following Web Services for Direct Debit:

Table 1-1: Direct Debit Operations

Operation Description

Verify Allows you to confirm that a customers bank account is in good standing, without actually transfer-ring money out of that account.

Charge Allows you to transfer money from a customers bank account to your merchant account. This trans-action is completed in real time, though the banking network takes 35 days to transfer the funds.

Credit Allows you to transfer money from your merchant account directly to a customers bank account.This transaction is completed in real time, though the banking network takes 35 days to transferthe funds.

Update Shipping Info Allows you to send shipping information, including a tracking number, once you have shippedgoods for which you previously processed a chargetransaction.

Information Lookup Allows you to run a report through the API over a date range you specify to return data on DirectDebit chargeand credittransactions processed through your merchant account.

Mandate Request Allows you to create a mandate for a customers UK bank account and lodge it at their bank, whichpermits you to transfer money from the customers bank account to your merchant account. Thebanking network typically takes 5 days to process the mandate.

Change Status Allows you to change the status of a charge, credit, or mandate transaction.

Availability of Direct Debit operation types is allotted on a merchant-by-merchant basis, since not allmerchant banks support all operations. If you have any questions, contact your account manager.


8/180

NETBANX Web Services February 2014

1-2

Web Services supported for credit cardsNETBANX currently supports the following Web Services for credit cards:

Web Services supported for Information Lookup ServiceNETBANX currently supports the following Web Service:

Table 1-2: Credit Card Operations


Authorization Allows you to confirm that a credit card exists and has sufficient funds to cover a Purchase, but withoutsettling the funds to your merchant account.

Purchase Both authorizes and settles a requested amount against a credit card.

Verification Allows you to run an AVS and/or CVD check on a credit card without processing a charge against thatcard.

AuthorizationReversal

Allows you to reverse all or part of an existing authorization, provided no settlements (either full or par-tial) have been processed against that authorization. This transaction type does notfunction with pur-chase transactions, but only with authorizations.

Credit Allows you to issue a credit for an amount that was previously settled.

Settlement Allows you to Settle the amount of an existing Authorization, crediting the authorized amount from the

credit card to your merchant account.

Stored DataAuthorization

Allows you to authorize an amount on a customers credit card using customer data that is stored in ourdatabase. You provide only a minimum of information, saving you time and effort.

Stored DataPurchase

Allows you to both authorize and settle an amount on a customers credit card using customer data thatis stored in our database. You provide only a minimum of information, saving you time and effort.

Cancel Allows you to cancel a Credit, Settlement, Payment, or Independent Credit transaction. You can cancelone of these transactions as long as it is in a Pending state, which typically is before midnight of the daythat it is requested. In some cases, you may find older Credit transactions in a Pending state.

Payment Allows you to credit an amount to a customers credit card. The Payment transaction is not associatedwith a previously existing authorization, so the amount of the transaction is not restricted in this way.

IndependentCredit Allows you to credit an amount to a customers credit card. The Independent Credit transaction is notassociated with a previously existing authorization, so the amount of the transaction is not restricted inthis way.

InformationLookup

Allows you to run a report through the API over a date range you specify to return data on credit cardtransactions processed through your merchant account.

EnrollmentLookup

Allows you to determine whether a customers credit card is enrolled in the 3D Secure program.

Authentication Allows you to send an Authentication request in order for a cardholder enrolled in 3D Secure toauthenticate their card with the Card Issuer before you process an Authorization.

Availability of credit card operation types is allotted on a merchant-by-merchant basis, since not all mer-chant banks support all operations. If you have any questions, contact your account manager.


9/180

February 2014 System requirements


System requirementsThe SOAP API has been tested with the following client environments:

For more information:

J2SE or J2EE 1.3.1 or newer (1.4.X recommended) Sun Microsystems, Inc.http://java.sun.com/downloads/index.html

Apache Axis 1.4, The Apache Software Foundationhttp://www.apache.org/dyn/closer.cgi/ws/axis/1_4

Apache Axis2, 1.2, The Apache Software Foundationhttp://ws.apache.org/axis2/1_2/contents.html

Microsoft .NET Framework Version 1.1/2.0 Microsoft Corporation

http://www.microsoft.com/net

Accessing the NETBANX WSDLs and links

Direct DebitWSDL:

https://webservices.optimalpayments.com/directdebitWS/DirectDebitService/v1?wsdl

Web Service:

https://webservices.optimalpayments.com/directdebitWS/DirectDebitService/v1

HTTP Post:

https://webservices.optimalpayments.com/directdebitWS/DirectDebitServlet/v1

Table 1-3: Information Lookup Service Operation


Information Lookup Service Allows you to run a report through the API over a date range you specify toreturn data on Authorizations, Settlements, Credits, and Chargebacks pro-cessed through a merchant account.

Table 1-4: Client Environments

SOAP Client Programming Environment Operating Environment

Microsoft .NET 1.1 and 2.0Framework

Microsoft Visual Studio .NET 2003 Microsoft Windows Server 2003 and Windows XP

Apache Axis 1.4 Java (J2SE 1.4.X and higher) Linux and Microsoft Windows XP, Server 2003

Apache Axis 2.0 Java (J2SE 1.4.X and 1.5.X) Linux and Microsoft Windows XP, Server 2003

Regardless of which SOAP client you adopt, it must support document-style messaging.
http://java.sun.com/downloads/index.htmlhttp://www.apache.org/dyn/closer.cgi/ws/axis/1_4http://ws.apache.org/axis2/1_2/contents.htmlhttp://www.microsoft.com/net/https://webservices.optimalpayments.com/directdebitWS/DirectDebitService/v1?wsdlhttps://webservices.optimalpayments.com/directdebitWS/DirectDebitService/v1https://webservices.optimalpayments.com/directdebitWS/DirectDebitServlet/v1http://www.apache.org/dyn/closer.cgi/ws/axis/1_4https://webservices.optimalpayments.com/directdebitWS/DirectDebitServlet/v1https://webservices.optimalpayments.com/directdebitWS/DirectDebitService/v1https://webservices.optimalpayments.com/directdebitWS/DirectDebitService/v1?wsdlhttp://www.microsoft.com/net/http://java.sun.com/downloads/index.htmlhttp://ws.apache.org/axis2/1_2/contents.html


10/180


1-4

Credit cardWSDL:

https://webservices.optimalpayments.com/creditcardWS/CreditCardService/v1?wsdl

Web Service:

https://webservices.optimalpayments.com/creditcardWS/CreditCardService/v1HTTP Post:

https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1

Information Lookup ServiceWSDL:

https://webservices.optimalpayments.com/ilsWS/IlsService/v1?wsdl

Web Service:

https://webservices.optimalpayments.com/ilsWS/IlsService/v1

HTTP Post:

https://webservices.optimalpayments.com/ilsWS/IlsServlet/v1

Testing NETBANX Web ServicesOnce you have configured your Web Servicesenabled application, please contact our TechnicalSupport team for instructions on how to test your API calls.

Email [email protected]

Telephone 888-709-8753

Security featuresFor some transactions (e.g., Purchase) NETBANX provides additional features to protect the mer-chant from fraudulent card usage.

Address verification system (AVS)

Card validation data (CVD)

Negative database

3D Secure

AVS NETBANX supports address verification checks (AVS) wherever the issuing bank supports thisfeature. AVS verifies whether the address supplied by the customer using a card matches the bill-ing address associated with that card at the issuing bank. This makes it more difficult to use thecard fraudulently, since in order to use a stolen card someone must also know the billing addressassociated with it. In addition, if goods are to be shipped, the merchant can require that they beshipped to the billing address associated with the card.
https://webservices.optimalpayments.com/creditcardWS/CreditCardService/v1?wsdlhttps://webservices.optimalpayments.com/creditcardWS/CreditCardService/v1https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1https://webservices.optimalpayments.com/ilsWS/IlsService/v1?wsdlhttps://webservices.optimalpayments.com/ilsWS/IlsService/v1https://webservices.optimalpayments.com/ilsWS/IlsServlet/v1mailto:[email protected]:[email protected]://webservices.optimalpayments.com/ilsWS/IlsServlet/v1https://webservices.optimalpayments.com/ilsWS/IlsService/v1https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1https://webservices.optimalpayments.com/creditcardWS/CreditCardService/v1mailto:[email protected]://webservices.optimalpayments.com/ilsWS/IlsService/v1?wsdlhttps://webservices.optimalpayments.com/creditcardWS/CreditCardService/v1?wsdl


11/180

February 2014 CVD


Within NETBANX, each payment method is configured with the acceptable set of AVS returncodes. If the bank returns a code that is not acceptable for the payment method, then the requestis rejected with an Authorization Failed error. If you get an Authorization Failed error in responseto a transaction request, and an Authorization number is returned in the response, then the fail-ure was caused by the AVS check. You can look at the AVS code returned to determine exactlywhy the AVS check failed. NETBANX returns the following codes, in the avsResponseelement, to

the merchant application in response to a transaction request, with A, N, and Eindicating AVSfailure:

When you registered with NETBANX, your account was set up to automatically apply AVSchecks. NETBANX accepts only transactions for which the allowable AVS return codes arereturned.

AVS has three limitations, which may affect the decisions you make with regard to failed AVSchecks:

AVS is not always reliable. Bad results can be returned if someone has moved, for instance,or because some people report five-digit zip codes and some report nine-digit zip codes.

AVS does only limited support internationally. If you decide, therefore, to ship only toaddresses that return good AVS results, you may exclude otherwise valid transactions.

AVS is supported by many U.S. issuing banks, but not all. So even if you only serve U.S. cus-tomers, you may not always be able to depend on AVS being available.

CVDThe CVD value is a 3- or 4-digit number printed on the credit card, but which is not present onthe magnetic strip. Therefore, the value is not printed on receipts or statements, reducing theprobability of fraud from imprint information. The CVD feature, intended specifically for trans-

Table 1-5: AVS Codes

Code Letter Explanation

A Address matches, but zip code does not.

B AVS not performed for international transaction. Either the postal code has invalid formator address information not provided.

E AVS not supported for this industry.

M For international transaction, address and postal code match.

N No part of the address matches.

Q Unknown response from issuer/banknet switch.

R Retry. System unable to process.

S AVS not supported.

U Address information is unavailable.

W Nine-digit zip code matches, but address does not.

X Exact. Nine-digit zip code and address match.

Y Yes. Five-digit zip code and address match.

Z Five-digit zip code matches, but address does not.


12/180


1-6

actions where a card is not present, is a requirement of NETBANX. We support the CVD featurewherever the issuing banks do.

When customers enter their card and cardholder information, the CVD value is requested at thesame time. One of four indicators flag the status of a CVD request:

Not provided The customer did not provide the CVD value.

Provided The customer provided the CVD value. When this indicator is selected, the CVDvalue is provided.

Illegible The customer claims the CVD value is illegible.

Not present The customer claims the CVD value is not on the card.

Negative databaseNETBANX administers a negative database that provides additional protection against misuse ofcards and inappropriate transaction requests. Card numbers and email addresses are enteredinto the negative database for the following reasons:

A chargeback associated with the card number or email address has occurred.

The card number or email address was involved in, or suspected to have been involved in,fraudulent activity.

Your account is configured to automatically implement this security feature, and any transactionrequest that attempts to use either a card number or email address that is in the negative data-base will not be processed.

3D SecureNETBANX supports 3D Secure, an online cardholder authentication program designed to makeInternet purchase transactions safer by authenticating a cardholder's identity at the time of pur-chase, before the merchant submits an authorization request. It is currently supported by severalcard brands, including Visa (Verified by Visa), MasterCard (SecureCode), and JCB (J/Secure).

Authorizations processed using 3D Secure are guaranteed against most common types of charge-back disputes.

Using this guideThis user guide details major system functions. Each section provides an overview of functions,which are then broken down into procedures with steps to be followed.

AudienceThis users guide is intended for NETBANX merchants using our Web Services API to processtransaction requests with NETBANX.

FunctionalityThis guide may document some features to which you do not have access. Access to such func-tionality is allotted on a merchant-by-merchant basis. If you have any questions, contact youraccount manager.


13/180

February 2014 Symbols


SymbolsThis user guide uses the following symbols to bring important items to your attention:

Table 1-6: Symbols

Symbol Description

This noteicon denotes a hint or tip to help you use the transaction processing application more efficiently.

This warningicon alerts you about actions you might take that could have important consequences.


14/180


1-8


15/180


CHAPTER2

Direct Debit Transactions

IntroductionThis chapter describes how to process Direct Debit transactions via the NETBANX Web Service.The following operations are supported:

The verify, charge, and creditoperations accept a ddCheckRequestV1document object.

The updateShippingInfo operation accepts a ddShippingRequestV1document object.

The lookup operation accepts a ddLookupRequestV1document object.

The mandate requestoperation accepts a ddMandateRequestdocument object.

The change statusoperation accepts a ddChangeStatusRequestdocument object.

Table 2-1: Supported Operations

Operation Description Request Type

Verify Allows you to confirm that a customers bank account is ingood standing, without actually transferring money out ofthat account.

See Building charge, verify, orcredit requests on page 2-3.

Charge Allows you to transfer money from a customers bankaccount to your merchant account. This transaction is com-pleted in real time, though the banking network takes 35days to transfer the funds.

Credit Allows you to transfer money from your merchant accountdirectly to a customers bank account. This transaction iscompleted in real time, though the banking network takes35 days to transfer the funds.

Update Shipping Info Allows you to send shipping information, including a trackingnumber, once you have shipped goods for which you previ-ously processed a chargetransaction.

See Building updateShippingInforequests on page 2-12.

Information Lookup Allows you to run a report through the API over a date range

you specify to return data on Direct Debit chargeand credittransactions processed through your merchant account.

See Building lookup requests on

page 2-16.

Mandate Request Allows you to create a mandate for a customers UK bankaccount and lodge it at their bank, which permits you totransfer money from the customers bank account to yourmerchant account. The banking network typically takes 5days to process the mandate.

See Building mandate requests onpage 2-20.

Change Status Allows you to change the status of a charge, credit, or man-date transaction.

See Building change statusrequests on page 2-26.

Availability of Direct Debit operation types is allotted on a merchant-by-merchant basis, since not all

merchant banks support all operations. If you have any questions, contact your account manager.


16/180


17/180

February 2014 Building charge, verify, or credit requests


The Web client is now built.

4. Build a Direct Debit request and process response.

See Building charge, verify, or credit requests on page 2-3

See Building updateShippingInfo requests on page 2-12

See Processing the response on page 2-29

Building charge, verify, or credit requestsCharge, verify, and creditrequests require the ddCheckRequestV1document object. This sectiondescribes the structure of a ddCheckRequestV1and how to construct one. See Table 2-2:ddCheckRequestV1 Elements on page 2-6for details on elements required.

charge example C#The following is a chargeexample in C#.


18/180

Direct Debit Transactions February 2014

2-4

// Prepare the call to the Direct Debit Web ServiceDDCheckRequestV1 ddCheckRequest = new DDCheckRequestV1();

ddCheckRequest.amount = "10.00";MerchantAccountV1 merchantAccount = new MerchantAccountV1();merchantAccount.accountNum = "12345678";merchantAccount.storeID = "myStoreID";merchantAccount.storePwd = "myStorePWD";ddCheckRequest.merchantAccount = merchantAccount;CheckV1 check = new CheckV1();check.routingNum = "123456789";check.accountNum = "987654321";check.accountType = BankAccountTypeV1.PC;check.bankName = "Chase";check.checkNum = 12;check.payee = "ACME Inc.";ddCheckRequest.check = check;

BillingDetailsV1 billingDetails = new BillingDetailsV1();billingDetails.firstName = "Jane";billingDetails.lastName = "Jones";billingDetails.street = "123 Main Street";billingDetails.city = "LA";billingDetails.country = CountryV1.US;billingDetails.zip = "90210";billingDetails.phone = "555-555-5555";billingDetails.checkPayMethod = CheckPayMethodV1.WEB;ddCheckRequest.billingDetails = billingDetails;//Perform the Web Services call to process the chargeDirectDebitServiceV1 ddService = new DirectDebitServiceV1();DDCheckResponseV1 ddTxnResponse = ddService.charge(ddCheckRequest);

// Print out the resultString responseTxt = ddTxnResponse.code + " - " + ddTxnResponse.decision +

" - " + ddTxnResponse.description;responseTxt += "Details:" + Environment.NewLine;if (ddTxnResponse.detail != null){

for (int i = 0; i < ddTxnResponse.detail.Length; i++){

responseTxt += " - " + ddTxnResponse.detail[i].tag + " - " +ddTxnResponse.detail[i].value + Environment.NewLine;

}}responseTxt = responseTxt.Replace("\n", Environment.NewLine);System.Console.WriteLine(responseTxt);if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision)){

System.Console.WriteLine("Transaction Successful.");}else{

System.Console.WriteLine("Transaction Failed with decision: " +ddTxnResponse.decision);

}

To make this a creditor verifyrequest, just modify the value charge (underlined below) to credit orverify, respectively.


19/180

February 2014 ddCheckRequestV1 schema


ddCheckRequestV1 schemaA ddCheckRequestV1document object has the following structure:


20/180


2-6

ddCheckRequestV1 elementsThe ddCheckRequestV1document object may contain the following elements:

Table 2-2: ddCheckRequestV1 Elements

Element Child Element Required Type Description

merchantAccount accountNum Yes StringMax = 10

This is the merchant account number.

storeID Yes String

Max = 80

This is the NETBANX store identifier, used toauthenticate the request. It is defined byNETBANX and provided to the merchant aspart of the integration process.

storePwd Yes String

Max = 20

This is the NETBANX store password, usedto authenticate the request. It is defined byNETBANX and provided to the merchant aspart of the integration process.

merchantRefNum Conditional String

Max = 255

This is the unique ID number associated

with the original request. The value is cre-ated by the merchant and submitted as partof the original request. This is returned onlyin response to a lookup request.

amount Yes StringMax =999999999.99

This is amount of the transaction request.


21/180

February 2014 ddCheckRequestV1 elements


check accountType Yes Enumeration This is the type of checking account used forthe transaction. Possible values are: PC (Personal Checking)

PS (Personal Savings) PL (Personal Loan) BC (Business Checking) BS (Business Savings) BL (Business Loan)

bankName Yes StringMax = 40

This is the name of the customers bank, towhich this transaction is posted.

checkNum Yes Long

Max = 8

This is the check serial number, provided atthe time of the transaction request.NOTE:The checkNumelement is requiredfor the verifyoperation, where it serves as aunique transaction ID, even though no

money is transferred between accounts forthis operation.

accountNum Yes StringMax = 17

This is the customers bank account number

routingNum Yes StringMin = 6Max = 9

For USD accounts, this is the 9-digit routingnumber of the customers bank.For British pound accounts, this is the 6-digitsort code of the customers bank.For Canadian dollar accounts, this is a com-bination of the 3-digit institution ID fol-lowed bythe 5-digit transit number of thecustomers bank branch. They must be

entered in this order. Do not include spacesor dashes.

payee Conditional StringMax = 81

This is the descriptor that will appear on thecustomers bank account. It is required onlyfor creditand verifytransactions.If you provide a value for this field, this valuewill be used as the statement descriptor. Ifyou do notprovide a value for this field, adefault value configured for the merchantaccount will be used.

bankCountry Conditional Enumeration This is the country in which the bank islocated. See Country codes on page C-3for

correct codes to use. This is a required ele-ment only for certain countries.

bankCity Conditional StringMax = 40

This is the city in which the bank is located.This is a required element only for certaincountries.

Table 2-2: ddCheckRequestV1 Elements (Continued)



22/180


2-8

check(continued)

mandateReference Conditional StringMax = 10

This is the mandate reference that allows theU.K. account to be charged. This is the valuereturned for the confirmationNumber

parameter in the response to addMandateRequestV1.

billingDetails checkPayMethod Yes Enumeration This is the payment type.Possible values are: WEB (Personal Check Only) TEL (Personal Check Only) PPD (Personal Check Only) CCD (Business Check Only)

firstName Conditional StringMax = 40

This is the customers first name.Required if checkPayMethodis set to WEBor TEL.

lastName Conditional String

Max = 40

This is the customers last name.

Required if checkPayMethodis set to WEBor TEL.

companyName Conditional StringMax = 50

This is the companys name.Required if checkPayMethodis a businesscheck.

street Yes StringMax = 50

This is the first line of the customers streetaddress.

street2 Optional StringMax = 50

This is the second line of the customersstreet address.

city Yes StringMax = 40

This is the city in which the customerresides.

state/region Conditional If state, thenEnumerationIf region, thenstringMax = 40

This is the state/province/region in which thecustomer resides.Providestateif within U.S./Canada. Provideregionif outside of U.S./Canada.SeeAppendix C: Geographical Codesforcorrect codes to use.

country Yes Enumeration This is the country in which the customerresides. See Country codes on page C-3forcorrect codes to use.

zip Optional StringMax = 10

This is the customers ZIP code if in the U.S.;otherwise, this is the customers postal code.

phone Optional String

Max = 40

This is the customers telephone number.

email Optional StringMax = 100

This is the customers email address.




23/180



personalID idNumber Optional StringMax = 20

This is the number of the ID provided for theidTypeelement.

idType Optional Enumeration This is the type of ID used to identify theowner of the bank account.Possible values are: DL (Drivers License) SS (Government ID) MI (Military ID) GN (Generic ID)

state/region Optional If state, thenEnumeration

If region, thenstringMax = 40

This is the state/province/region in which theID was issued.

Providestateif within U.S./Canada. Provideregionif outside of U.S./Canada.SeeAppendix C: Geographical Codesforcorrect codes to use.

country Optional StringLength = 2

This is the country in which the ID wasissued. Possible values are: CA (Canada) US (United States)

expiry Optional The expirychild element has three furtherchild elements.

Child Element of expiry

day Optional IntLength = 2

This is the day the ID expires.

month Optional Int

Length = 2

This is the month the ID expires.

year Conditional IntLength = 4

This is the year the ID expires.This element is required if the expiryele-ment is included.

socialSecurityNumber Optional StringMax = 12

This is the customers Social SecurityNumber.

dateOfBirth Optional This is the customers date of birth.

year Conditional StringMax = 419009999

This is the customers year of birth.

month Conditional StringMax = 12

This is the customers month of birth.

day Conditional String

Max = 31

This is the customers day of birth.




24/180


2-10

shippingDetails carrier Optional Enumeration This is the shipment carrier.Possible values are: APC = APC Overnight

APS = AnPost CAD = Canada Postal Service DHL FEX = Fedex RML = Royal Mail UPS = United Parcel Service USPS = United States Postal Service OTHER

trackingNumber Optional String

Max = 50

This is the shipping tracking number pro-vided by the carrier.

shipMethod Optional Enumeration This is the method of shipment.Possible values are: N = Next Day/Overnight T = Two-Day Service C = Lowest Cost O = Other

firstName Optional StringMax = 40

This is the recipientss first name.

lastName Optional StringMax = 40

This is the recipients last name.

street Optional StringMax = 50

This is the first line of the recipients streetaddress.


This is the second line of the recipientsstreet address.

city Optional StringMax = 40

This is the city in which the recipient resides.

state/region Optional If state,EnumerationIf region, thenstringMax = 40

This is the state/province/region in which therecipient resides.Providestateif within U.S./Canada. Provideregionif outside of U.S./Canada.SeeAppendix C: Geographical Codesforcorrect codes to use.

country Optional Enumeration This is the country in which the recipient

resides. See Country codes on page C-3forcorrect codes to use.

zip Optional String

Max = 10

This is the recipients ZIP code if in the U.S.;otherwise, this is the recipients postal code.

phone Optional StringMax = 40

This is the recipients phone number.


This is the recipients email address.




25/180



customerIP Optional StringMax = 50

This is the customers IP address.

productType Optional Enumeration This is the type of product sold.Possible values are: P (Physical Goods) D (Digital Goods) C (Digital Content) G (Gift Certificate/Digital Cash) S (Shareware) M (Both Digital and Physical) R (Account Replenish)

txnAppliedTo No This element is not applicable for DirectDebit transactions.

confirmationNumber Conditional StringMax = 20

This is the confirmation number returned byNETBANX in response to the original charge

request.Include this element only if you are using theddCheckRequestV1to process a creditrequest.

targetVirtualAccount No This element is not applicable for DirectDebit transactions.

checkRiskService No This element is not applicable for DirectDebit transactions.

txnDate Optional dateTime This is the date and time that the transactiontook place.For a chargeor credit, or for a

ddMandateRequestV1, this can be the futuredate and time when the transaction will takeplace.

sdk version Conditional String

Max = 20

This is the version of the SDK used, if any.

Required ifsdkelement is provided.

platform Conditional String

Max = 10

This is the integration language of the SDKused (e.g., Java, .NET).Required ifsdkelement is provided.

provider Conditional StringMax = 20

This is the author of the SDK used. Set tovalue op when the SDK is provided byNETBANX.

Required ifsdkelement is provided.

origin Optional Enumeration The is the origin of the request.Possible values are: Wireless Wireline




26/180


2-12

Special considerations for Direct Debit elements

Some merchants are integrated with downsteam processors that have different requirements formandatory Direct Debit elements. In such cases, the following holds.

Building updateShippingInfo requests

addendumData tag Optional StringMax = 30

This is additional data that the merchant caninclude with the transaction request.

value Optional StringMax = 1024 This is additional data that the merchant caninclude with the transaction request.

Table 2-3: Additional Direct Debit Element Requirements

Element For Regular Transactions For Guaranteed Transactions

billingDetails.firstName Required Required

billingDetails.lastName Required RequiredbillingDetails.state Required Required

billingDetails.zip Required Required

billingDetails.phone Required Required

billingDetails.email Optional Required

customerIP Optional Required

dateOfBirth.year Optional Required

dateOfBirth.month Optional Required

dateOfBirth.day Optional RequiredpersonalID.idNumber Optional Required

personalID.state Optional Required

socialSecurityNumber Optional Required

Your account manager will inform you 1) if you are integrated with this type of downstream processorand 2) if you are eligible for guaranteed Direct Debit processing.

All optional elements that take non-nullable data types (e.g., intor enum) must have their specifiedattribute set to truewhen setting values for those elements. See the shipMethodelement in the examplebelow.




27/180

February 2014 updateShippingInfo example C#


The updateShippingInforequest requires the ddShippingRequestV1document object. This sectiondescribes the structure of a ddShippingRequestV1and how to construct one. See Table 2-4:ddShippingRequestV1 Elements on page 2-15for details on elements required.

updateShippingInfoexample C#

The following is an updateShippingInfoexample in C#.// Prepare the call to the Direct Debit Web ServiceDDShippingRequestV1 ddShippingRequest = new DDShippingRequestV1();MerchantAccountV1 merchantAccount = new MerchantAccountV1();merchantAccount.accountNum = "12345678";merchantAccount.storeID = "myStoreID";merchantAccount.storePwd = "myStorePwd";ddShippingRequest.merchantAccount = merchantAccount;ddShippingRequest.confirmationNumber = "123456"; // A valid confirmation numberfrom a previous settle auth or purchaseddShippingRequest.carrier = CarrierV1.FEX; // FedexddShippingRequest.shipMethod = ShipMethodV1.T;ddShippingRequest.shipMethodSpecified = true;ddShippingRequest.trackingNumber = "555666888999";

ddShippingRequest.firstName = "Jane";ddShippingRequest.lastName = "Jones";ddShippingRequest.street = "123 Main Street";ddShippingRequest.city = "LA";ddShippingRequest.country = CountryV1.US;ddShippingRequest.countrySpecified = true;ddShippingRequest.zip = "90210";ddShippingRequest.email = "[email protected]"; // optional email address

//Perform the Web Services call to update the shipping infoDirectDebitServiceV1 ddService = new DirectDebitServiceV1();DDCheckResponseV1 ddTxnResponse =ddService.updateShippingInfo(ddShippingRequest);// Print out the result

String responseTxt = ddTxnResponse.code + " - " + ddTxnResponse.decision + " - " +ddTxnResponse.description;

responseTxt += "Details:" + Environment.NewLine;if (ddTxnResponse.detail != null){



}}responseTxt = responseTxt.Replace("\n", Environment.NewLine);System.Console.WriteLine(responseTxt);if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision))

{System.Console.WriteLine("Transaction Successful.");

}else{


}


28/180


2-14

ddShippingRequestV1 schemaA ddShippingRequestV1document object has the following structure:


29/180

February 2014 ddShippingRequestV1 elements


ddShippingRequestV1 elementsThe ddShippingRequestV1document object may contain the following elements:

Table 2-4: ddShippingRequestV1 Elements




storeID Yes String

Max = 20


storePwd Yes String

Max = 20


carrier Yes Enumeration This is the shipment carrier.

Possible values are: APC = APC Overnight APS = AnPost CAD = Canada Postal Service DHL FEX = Fedex RML = Royal Mail UPS = United Parcel Service USPS = United States Postal Service OTHER

trackingNumber Yes StringMax = 50

This is the shipping tracking number pro-vided by the carrier.

confirmationNumber Yes StringMax = 20

This is the confirmation number returned byNETBANX.

shipMethod Optional Enumeration This is the method of shipment.Possible values are: N = Next Day/Overnight T = Two-Day Service C = Lowest Cost O = Other

firstName Optional StringMax = 40

This is the customers first name.

lastName Optional StringMax = 40

This is the customers last name.

street Optional StringMax = 50

This is the first line of the customers streetaddress.




30/180


2-16

Building lookup requestsThe Direct Debit lookup request allows you to run a report, over a date range you specify, toreturn data on Direct Debit charge andcredittransactions processed through your merchantaccount.

lookup example C#The following is a ddLookupRequest example in C#.

// Prepare the call to the Direct Debit Web ServiceDDLookupRequestV1 ddLookupRequest = new DDLookupRequestV1();MerchantAccountV1 merchantAccount = new MerchantAccountV1();merchantAccount.accountNum = "12345678";merchantAccount.storeID = "myStoreID";merchantAccount.storePwd = "myStorePWD";ddLookupRequest.merchantAccount = merchantAccount;ddLookupRequest.confirmationNumber = "123456789";DateV1 startDate = new DateV1();startDate.year = "2012";startDate.month = "08";startDate.day = "15";startDate.hour = "11";startDate.minute = "00";startDate.second = "00";ddLookupRequest.startDate = startDate;ddLookupRequest.startDateSpecified = true;DateV1 endDate = new DateV1();endDate.year = "2012";endDate.month = "08";



state/region Optional If state, thenEnumerationIf region, thenstringMax = 40

This is the state/province/region in which thecustomer resides.Providestateif within U.S./Canada. Provideregionif outside of U.S./Canada.SeeAppendix C: Geographical Codesforcorrect codes to use.

country Optional Enumeration This is the country in which the customerresides. See Country codes on page C-3forcorrect codes to use.


This is the customers ZIP code if in the U.S.;otherwise, this is the customers postal code.




This is the customers email address.

Table 2-4: ddShippingRequestV1 Elements (Continued)



31/180

February 2014 lookup example C#


endDate.day = "15";endDate.hour = "14";endDate.minute = "00";endDate.second = "00";ddLookupRequest.endDate = endDate;ddLookupRequest.endDateSpecified = true;

//Perform the Web Services call to process the chargeDirectDebitServiceV1 ddService = new DirectDebitServiceV1();DDCheckResponseV1 ddCheckResponse = ddService.lookup(ddLookupRequest);// Print out the resultString responseTxt = ddCheckResponse.code + " - " + ddCheckResponse.decision;responseTxt += "Transactions:" + Environment.NewLine;if (ddCheckResponse.transaction != null){ for (int i = 0; i < ddCheckResponse.transaction.Length; i++) { responseTxt += " - confirmationNumber: " +

ddCheckResponse.transaction[i].confirmationNumber + Environment.NewLine; responseTxt += " - merchantRefNum: " +

ddCheckResponse.transaction[i].merchantRefNum + Environment.NewLine;

responseTxt += " - txnTime: " +ddCheckResponse.transaction[i].txnTime + Environment.NewLine;

responseTxt += " - amount: " +ddCheckResponse.transaction[i].amount + Environment.NewLine;

StatusV1 status = ddCheckResponse.transaction[i].status; if (status != null){ responseTxt += " - status: " +

status.code + Environment.NewLine; responseTxt += " - status effective date:" +

status.effectiveDate + Environment.NewLine; } responseTxt += Environment.NewLine; }}

responseTxt = responseTxt.Replace("\n", Environment.NewLine);System.Console.WriteLine(responseTxt);if (DecisionV1.ACCEPTED.Equals(ddCheckResponse.decision)){ System.Console.WriteLine("Transaction Found.");}else{ System.Console.WriteLine("Transaction Failed or Not Found with decision: " + ddCheckResponse.decision);}


32/180


2-18

ddLookupRequestV1 schemaA ddLookupRequestV1document object has the following structure:

ddLookupRequestV1 elementsThe ddLookupRequestV1document object may contain the following elements:


33/180

February 2014 ddLookupRequestV1 elements


Table 2-5: ddLookupRequestV1 Elements




storeID Yes StringMax = 20


storePwd Yes StringMax = 20


confirmationNumber Optional StringMax = 20

This is the confirmation number returned byNETBANX in response to the originalrequest. Include this element only if youwant to search using this field. This fieldtakes precedence over the merchantRefNumfield.

merchantRefNum Conditional StringMax = 255

This is a unique ID number associated withthe original request. The value is created bythe merchant and submitted as part of therequest.

startDate year Required Int Max = 9999

This is the year set for the search start.

month Required Int Min = 1Max = 12

This is the month set for the search start.

day Required Int Min = 1

Max = 31

This is the day set for the search start.

hour Required Int Min = 0Max = 23

This is the hour set for the search start.

minute Required Int Min = 0Max = 59

This is the minute set for the search start.

second Required Int Min = 0

Max = 59

This is the second set for the search start.


34/180


2-20

Building mandate requestsThe Direct Debit mandate allows you to create a mandate for a customers UK bank account andlodge it at their bank, which permits you to transfer money from that customers bank account

to your merchant account.When you submit a ddMandateRequestV1, NETBANX will return a value for theconfirmationNumberparameter in the response. You will use this value in the mandateReferenceele-ment (which is a child element of the checkelement) when you process future chargerequestsagainst the customers bank account using the ddCheckRequestV1.

Initially, the status of the mandate is set to Completed, and the mandate cannot yet be used forDirect Debit transactions. The banking network typically takes 5 days to process the mandate, soafter 5 days, NETBANX changes the status of the mandate to Active. At that point it can be usedto authorize Direct Debit transactions on the UK bank account for which it was set up.

mandate example C#The following is a ddMandateRequest example in C#.

// Prepare the call to the Direct Debit Web ServiceDDMandateRequestV1 ddMandateRequest = new DDMandateRequestV1();MerchantAccountV1 merchantAccount = new MerchantAccountV1();merchantAccount.accountNum = "12345678";merchantAccount.storeID = "myStoreID";merchantAccount.storePwd = "myStorePWD";ddCheckRequest.merchantAccount = merchantAccount;CheckV1 check = new CheckV1();

endDate year Required Int Max = 9999

This is the year set for the search end.

month Required Int Min = 1Max = 12

This is the month set for the search end.

day Required Int Min = 1Max = 31

This is the day set for the search end.

hour Required Int

Min = 0Max = 23

This is the hour set for the search end.

minute Required Int

Min = 0Max = 59

This is the minute set for the search end.

second Required Int Min = 0Max = 59

This is the second set for the search end.

Table 2-5: ddLookupRequestV1 Elements (Continued)



35/180

February 2014 mandate example C#


check.routingNum = "123456789";check.accountNum = "987654321";check.bankName = "Chase";check.payee = "ACME Inc.";ddMandateRequest.check = check;BillingDetailsV1 billingDetails = new BillingDetailsV1();billingDetails.firstName = "Jane";

billingDetails.lastName = "Jones";billingDetails.street = "123 Main Street";billingDetails.city = "Cambridge";billingDetails.country = CountryV1.UK;billingDetails.zip = "CB12345";billingDetails.phone = "1222 444000";billingDetails.checkPayMethod = CheckPayMethodV1.WEB;ddMandateRequest.billingDetails = billingDetails;ddMandateRequest.autoSend = "Y";//Perform the Web Services call to process the chargeDirectDebitServiceV1 ddService = new DirectDebitServiceV1();DDCheckResponseV1 ddTxnResponse = ddService.mandate(ddCheckRequest);

// Print out the result

String responseTxt = ddTxnResponse.code + " - " + ddTxnResponse.decision +" - " + ddTxnResponse.description;

responseTxt += "Details:" + Environment.NewLine;if (ddTxnResponse.detail != null){





}else{


}


36/180


2-22

ddMandateRequestV1 schemaA ddMandateRequestV1document object has the following structure:


37/180

February 2014 ddMandateRequestV1 elements


ddMandateRequestV1 elementsThe ddMandateRequestV1document object may contain the following elements:

Table 2-6: ddMandateRequestV1 Elements




storeID Yes String

Max = 80


storePwd Yes String

Max = 20


merchantRefNum Conditional String

Max = 255

This is the unique ID number associated

with the original request. The value is cre-ated by the merchant and submitted as partof the original request.


38/180


2-24

check accountType Optional Enumeration This is the type of checking account used forthe transaction. Possible values are: PC (Personal Checking)

PS (Personal Savings) PL (Personal Loan) BC (Business Checking) BS (Business Savings) BL (Business Loan)

bankName Optional StringMax = 40

This is the name of the customers bank, towhich this transaction is posted.

checkNum Optional Long

Max = 8

This is the check serial number, provided atthe time of the transaction request.

accountNum Yes String

Max = 17

This is the customers bank account number.

routingNum Yes StringMin = 6Max = 9

For USD accounts, this is the 9-digit routingnumber of the customers bank.For British pound accounts, this is the 6-digitsort code of the customers bank.For Canadian dollar accounts, this is a com-bination of the 3-digit institution ID fol-lowed bythe 5-digit transit number of thecustomers bank branch. They must beentered in this order. Do not include spacesor dashes.

payee Optional StringMax = 81

This is the descriptor that will appear on thecustomers bank account. It is required only

for creditand verifytransactions.If you provide a value for this field, this valuewill be used as the statement descriptor. Ifyou do notprovide a value for this field, adefault value configured for the merchantaccount will be used.

bankCountry Conditional Enumeration This is the country in which the bank islocated. See Country codes on page C-3forcorrect codes to use. This is a required ele-ment only for certain countries.

bankCity Conditional StringMax = 40

This is the city in which the bank is located.This is a required element only for certain

countries.

Table 2-6: ddMandateRequestV1 Elements (Continued)



39/180

February 2014 ddMandateRequestV1 elements


billingDetails checkPayMethod Optional Enumeration This is the payment type.Possible values are: WEB (Personal Check Only)

TEL (Personal Check Only) PPD (Personal Check Only) CCD (Business Check Only)

firstName Conditional StringMax = 40

This is the customers first name.Required if checkPayMethodis set to WEBor TEL.

lastName Conditional StringMax = 40

This is the customers last name.Required if checkPayMethodis set to WEBor TEL.

companyName Conditional String

Max = 50

This is the companys name.

Required if checkPayMethodis a business

check.street Optional String

Max = 50This is the first line of the customers streetaddress.





state/region Conditional If state, thenEnumerationIf region, then

stringMax = 40

This is the state/province/region in which thecustomer resides.Providestateif within U.S./Canada. Provide

regionif outside of U.S./Canada.SeeAppendix C: Geographical Codesforcorrect codes to use.

country Optional Enumeration This is the country in which the customerresides. See Country codes on page C-3forcorrect codes to use.


This is the customers ZIP code if in the U.S.;otherwise, this is the customers postal code



email Optional StringMax = 100 This is the customers email address.

customerIP Optional StringMax = 50

This is the customers IP address.




40/180


2-26

Building change status requestsA change status request allows you to change the status of some Direct Debit transactions. Youcan make the following status changes:

You can change the status of a mandate request from W (Waiting) to C (Completed).

You can change the status of a charge, credit, or mandate request from C (Completed) to X(Cancelled), but only in cases where the Direct Debit request has not yet been sent to thebank.

NETBANX responds to your change status request with the ddCheckResponseV1. In this response,the confirmationNumberidentifies the request that was updated (charge, credit, or mandateRequest),and you can confirm the new status of the transaction you updated. See Processing the response onpage 2-29for details.

Change status example C#The following is a ddChangeStatusRequest example in C#.

// Prepare the call to the Direct Debit Web ServiceDDChangeStatusRequestV1 ddChangeStatusRequest = new DDChangeStatusRequestV1();MerchantAccountV1 merchantAccount = new MerchantAccountV1();merchantAccount.accountNum = "12345678";merchantAccount.storeID = "myStoreID";

txnDate Optional dateTime This is the date and time that the transactiontook place.

For a chargeor credit, or for a

ddMandateRequestV1, this can be the futuredate and time when the transaction will takeplace.

autoSend Optional Boolean This controls when the mandate is sent tothe bank.Possible values are: Y = The mandate will be set to Com-

pleted status, ready to be sent to the bank N = The mandate will remain with the

status of Waiting, and will not be sent tothe bank.

If the autoSendstatus is set to N, it can laterbe changed to a status of Y by using thesta-tusChangerequest, at which point the man-date will then be sent to the bank at the nextbatching time (see Building change statusrequests on page 2-26).

addendumData tag Optional StringMax = 30


value Optional StringMax = 1024





41/180

February 2014 Change status example C#


merchantAccount.storePwd = "myStorePWD";ddChangeStatusRequest.merchantAccount = merchantAccount;ddChangeStatusRequest.confirmationNumber = "123456"; // A valid confirmationnumber from a previous mandate or echeck;ddChangeStatusRequest.status = "C";//Perform the Web Services call to process the chargeDirectDebitServiceV1 ddService = new DirectDebitServiceV1();

DDCheckResponseV1 ddTxnResponse = ddService.changeStatus(ddCheckRequest);

// Print out the resultString responseTxt = ddTxnResponse.code + " - " + ddTxnResponse.decision +

" - " + ddTxnResponse.description;responseTxt += "Details:" + Environment.NewLine;if (ddTxnResponse.detail != null){



}}

responseTxt = responseTxt.Replace("\n", Environment.NewLine);System.Console.WriteLine(responseTxt);if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision)){

System.Console.WriteLine("Transaction Successful.");}else{


}


42/180


2-28

ddChangeStatusRequest schemaA ddChangeStatusRequestV1document object has the following structure:

ddChangeStatusRequestV1 elementsThe ddChangeStatusRequestV1document object may contain the following elements:

Table 2-7: ddChangeStatusRequestV1 Elements


merchantAccount accountNum Yes String

Max = 10


storeID Yes StringMax = 20

This is the NETBANX store identifier, used toauthenticate the request. It is defined by NET-BANX and provided to the merchant as part ofthe integration process.

storePwd Yes StringMax = 20

This is the NETBANX store password, used toauthenticate the request. It is defined byNETBANX and provided to the merchant aspart of the integration process.

confirmationNumber Optional StringMax = 20

This value identifies the transaction whose sta-tus you want to change.

This is the confirmationNumberreturned byNETBANX in response to the original transac-tion request.

status Required Enumeration This is the new status code for the transaction.Possible values are: C Completed W Waiting X Cancelled


43/180

February 2014 Processing the response


Processing the responseA ddCheckResponseV1has the following structure:

The following elements are relevant for a ddCheckResponseV1:


44/180


2-30

Table 2-8: ddCheckResponseV1 Elements


requestId Optional This is the unique ID number returnedby NETBANX for a record if it was pro-cessed in a batch file.

confirmationNumber Yes StringMax = 20

This is the confirmation numberreturned by NETBANX.If this is returned in response to addMandateRequestV1, then use thisvalue for the mandateReferenceelement in a ddCheckRequestV1.

merchantRefNum Optional StringMax = 255

This is the unique ID number associatedwith the original request. The value iscreated by the merchant and submittedas part of the original request. This isreturned only in response to a lookuprequest.

decision Yes Enumeration This is the status of the transaction. Oneof the following is returned: Accepted the transaction was pro-

cessed. Error the transaction was

attempted, but failed for some rea-son.

Declined the transaction wasdeclined before it was sent for pro-cessing.

Not Found the transaction lookupdid not find any matches.

code Yes Int This is a numeric code that categorizesthe response. See Response codes onpage B-1.

actionCode Optional Enumeration This indicates what action to take.The following values are possible: C = Consumer Parameter Error. The

consumer has provided incorrectinformation. Ask the customer to cor-rect the information.

D = Do Not Retry. Further attemptswill fail.

M = Merchant Parameter Error. Yourapplication has provided incorrectinformation. Verify your information.

R = Retry. The problem is temporary.Retrying the request will likely suc-ceed.

description Optional String

Max = 100

This is a human readable description ofthe codeelement.


45/180



detail tag Optional StringMax = 1024

This is the classification of the detail ele-ment.

value Optional StringMax = 30 This is the description of the detail.

txnTime Yes dateTime This is the date and time the transactionwas processed by NETBANX.

status Optional

code Conditional Enumeration This is the status of the first transactionthat matches a lookup request. Possiblevalues are: C Complete batch DE Declined E Error batch F Failed

PR1 Presented 1 PR2 Presented 2 RE Rejected REF Rejected final RF Refunded RV Reversed T Transferred W Send to Echo clearing house W1 Send to Echo clearing house X Cancelled

effectiveDate Conditional dateTime This is the date and time at which thestatus of the lookup request is in effect.

currency Optional String The value will be one of the currencycodes in Table 3-15:Currency Codes onpage 3-56. This value is returned only inresponse to lookup requests.

amount Optional StringMax =999999999.99

This is the amount of the first transac-tion that matches a lookup request.

Table 2-8: ddCheckResponseV1 Elements (Continued)



46/180


2-32

To process the response:

1. Get the response details, which are available via get() methods of the response.

String responseTxt = ddTxnResponse.code+ " - " + ddTxnResponse.decision+" - " + ddTxnResponse.description;responseTxt += "Details:" + Environment.NewLine;if (ddTxnResponse.detail != null){





}else{


}

transaction Optional This is returned only in response to alookup request. All transactions thatmatch the lookup request are returned

here.confirmationNumber Conditional String

Max = 20This is the confirmation numberreturned by NETBANX for a previoustransaction.

merchantRefNum Optional StringMax = 255

This is the unique ID number associatedwith the original request. The value iscreated by the merchant and submittedas part of the original request. This isreturned only in response to a lookuprequest.

txnTime Conditional dateTime This is the date and time the transactionwas processed by NETBANX.

status Conditional This contains codeand effectiveDateelements for the transaction. See thestatuselement above in this table fordetails.

amount Conditional String

Max =999999999.99

This is the amount of the transaction.

Table 2-8: ddCheckResponseV1 Elements (Continued)



47/180



2. Process based on the decision element. You would insert handling code appropriate to yourapplication. You can also look at the codeelement to provide more fine-grained control foryour application. See Response codes on page B-1for more details.


48/180


49/180


CHAPTER3

Credit/Debit Card Transactions

IntroductionThis chapter describes how to process credit and debit card transactions via the NETBANX WebService. The following operations are supported:



Authorization Allows you to authorize an amount on a customers credit/debit card. The authorized amount must be settled in a sub-sequent settlement transaction.

See Building Purchase/Authorization/Ver-ification requests on page 3-5.Purchase Allows you to both authorize and settle an amount on a cus-tomers credit/debit card in a single transaction.

Verification Allows you to run an AVS and/or CVD check on a customerscredit card without processing a charge against that card.

AuthorizationReversal

Allows you to reverse all or part of an existing authorization,provided no settlements (either full or partial) have been pro-cessed against that authorization. This transaction type doesnot function with purchase transactions, but only with autho-rizations.

See Building Authorization Reversalrequests on page 3-17.

Credit Allows you to credit back to a customers credit/debit card anamount that has previously been settled. You can credit all orpart of an existing settlement. See Building Settlement/Credit requests

on page 3-20.Settlement Allows you to settle an amount that was previously authorizedon a customers credit/debit card. You can settle all or part ofan existing authorization.

Stored DataAuthorization

Allows you to authorize an amount on a customerscredit/debit card using customer data that is stored in ourdatabase. You provide only a minimum of information, savingyou time and effort. See Building Stored Data Requests on

page 3-23.Stored DataPurchase

Allows you to both authorize and settle an amount on a cus-tomers credit/debit card using customer data that is stored inour database. You provide only a minimum of information,saving you time and effort.

Cancel Allows you to cancel a Credit, Settlement, Payment, orIndependent Credit transaction. You can cancel one of thesetransactions as long as it is in a Pending state, which typicallyis before midnight of the day that it is requested. In somecases, you may find older Credit transactions in a Pendingstate.

See Building Cancel requests on page3-27.


50/180

Credit/Debit Card Transactions February 2014

3-2

TheAuthorization, Purchase, and Verificationoperations accept a ccAuthRequestV1documentobject.

TheAuthorization Reversaloperation accepts a ccAuthReversalRequestV1 document object.

The Settlementand Creditoperations accept a ccPostAuthRequestV1document object.

The Stored Dataoperations accept a ccStoredDataRequestV1document object. The Cancel Settle, Cancel Credit, and Cancel Paymentoperations accept a ccCancelRequestV1 doc-

ument object.

The Paymentand Independent Credit operations accept a ccPaymentRequestV1document object.

The Information Lookupoperation accepts a ccTxnLookupRequestV1document object.

The Enrollment Lookupoperation accepts a ccEnrollmentLookupRequestV1document object.

TheAuthenticationoperation accepts a ccAuthenticateRequestV1document object.

All operations return a ccTxnResponseV1response.

Payment Allows you to credit an amount to a customers credit card.The Payment transaction is not associated with a previouslyexisting authorization, so the amount of the transaction is not

restricted in this way. See Building Payment/IndependentCredit requests on page 3-30.Independent

CreditAllows you to credit an amount to a customers credit card.The Independent Credit transaction is not associated with apreviously existing authorization, so the amount of the trans-action is not restricted in this way.

InformationLookup

Allows you to run a report through the API over a date rangeyou specify to return data on credit card transactions pro-cessed through your merchant account.

See Building Information Lookuprequests on page 3-36.

EnrollmentLookup

Allows you to determine whether a customers credit card isenrolled in the 3D Secure program.

See Building Enrollment Lookup requestson page 3-40.

Authentication Allows you to send an Authentication request, in order to val-

idate a cardholders password for credit cards enrolled in the3D Secure program.

See Building Authentication requests on

page 3-45.

Availability of credit card operation types is allotted on a merchant-by-merchant basis, since not all mer-chant banks support all operations. If you have any questions, contact your account manager.




51/180

February 2014 .NET example


.NET example

To build the .NET example:

1. Create a new project.

2. Add a Web Reference.

3. Enter the WSDL URL and click the Add Reference button.


52/180

Credit/Debit Card Transactions February 2014

3-4

The Web client is now built.

4. Build the request and process response:

See Building Purchase/Authorization/Verification requests on page 3-5

See Building Authorization Reversal requests on page 3-17

See Building Settlement/Credit request

WebServices_API_1.0

Documents

Transcript of WebServices_API_1.0