API Reference Guide for Web Services

(1)

for Web Services

June 2015

(2)

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 usprovid-ed or copiprovid-ed only in accordance with this agreement. No part of this manual may be 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 fitness for 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 Office

3500 de Maisonneuve W., Suite 700 Montreal, Quebec H3Z 3C1 Canada Tel.: (514) 380-2700 Fax: (514) 380-2760 Email: [email protected]

Technical support: [email protected] Web: www.optimalpayments.com

U.K. Office

Compass House, Vision Park Chivers Way, Histon Cambridge CB24 9AD United Kingdom

Email: [email protected]

Technical Support: [email protected] Web: www.optimalpayments.com

U.S. Office

1209 Orange Street Wilmington, DE 19801

Gatineau Office

75 Promenade du Portage Gatineau, Quebec J8X 2J9 Canada

(3)

1 Optimal Payments Web Services

What are Optimal Payments Web Services? . . . 1-1 Web Services supported for Direct Debit . . . 1-1 Web Services supported for credit cards . . . 1-2 Web Services supported for Information Lookup Service. . . 1-3 System requirements . . . 1-3 Accessing the Optimal Payments WSDLs and links . . . 1-3 Direct Debit . . . 1-3 Credit card . . . 1-4 Information Lookup Service . . . 1-4 Testing Optimal Payments Web Services. . . 1-4 Security features . . . 1-4 AVS . . . 1-4 CVD . . . 1-5 Negative database . . . 1-6 3D Secure . . . 1-6 Using this guide . . . 1-6 Audience . . . 1-6 Functionality. . . 1-6 Symbols . . . 1-7

2 Direct Debit Transactions

Introduction . . . 2-1 .NET example. . . 2-2 Building charge, verify, or credit requests . . . 2-4 charge example – C# . . . 2-4 ddCheckRequestV1 schema . . . 2-6 ddCheckRequestV1 elements . . . 2-7 Special considerations for Direct Debit elements . . . 2-13 Building updateShippingInfo requests . . . 2-14 updateShippingInfo example – C# . . . 2-14 ddShippingRequestV1 schema . . . 2-16 ddShippingRequestV1 elements . . . 2-16 Building lookup requests . . . 2-18 Lookup example – C# . . . 2-18 ddLookupRequestV1 schema . . . 2-20

(4)

Building SEPA mandate requests. . . 2-22 mandate example – C# . . . 2-23 ddMandateRequestV1 schema . . . 2-24 ddMandateRequestV1 elements . . . 2-25 Building change status requests. . . 2-28 Change status example – C# . . . 2-28 ddChangeStatusRequest schema. . . . 2-29 ddChangeStatusRequestV1 elements . . . 2-30 Building mandate update requests . . . 2-31 Mandate update example – C# . . . . 2-31 ddUpdateMandateRequestV1 schema . . . 2-32 ddUpdateMandateRequestV1 elements . . . 2-32 Processing the response . . . 2-33

3 Credit/Debit Card Transactions

Introduction . . . 3-1 .NET example. . . 3-3 Building Purchase/Authorization/Verification requests . . . 3-4 Purchase example – C# . . . 3-5 ccAuthRequestV1 schema . . . 3-7 ccAuthRequestV1 elements . . . 3-8 addendumData tag/value pairs . . . 3-17 Building Authorization Reversal requests. . . 3-18 Authorization Reversal example – C#. . . 3-18 ccAuthReversalRequestV1 schema . . . 3-19 ccAuthReversalRequestV1 elements . . . 3-20 Building Settlement/Credit requests . . . 3-21 Settlement example – C#. . . 3-21 ccPostAuthRequestV1 schema . . . 3-22 ccPostAuthRequestV1 elements . . . 3-23 Building Stored Data Requests . . . 3-25 Stored Data Authorization example – C# . . . 3-25 ccStoredDataRequestV1 schema. . . . 3-27 ccStoredDataRequestV1 elements . . . 3-27 Building Cancel requests. . . 3-29 Cancel Settle example – C# . . . 3-29 ccCancelRequestV1 schema . . . 3-30 ccCancelRequestV1 elements . . . 3-30 Building Payment/Independent Credit requests. . . 3-32 Payment example – C# . . . 3-32 ccPaymentRequestV1 schema . . . . 3-34 ccPaymentRequestV1 elements . . . . 3-34 Building Transaction Lookup requests. . . 3-37 Transaction Lookup example – C# . . . 3-37

(5)

ccTxnLookupRequestV1 elements . . . 3-39 Building Enrollment Lookup requests . . . 3-41 Enrollment Lookup example – C# . . . 3-41 ccEnrollmentLookupRequestV1 schema . . . 3-43 ccEnrollmentLookupRequestV1 elements . . . 3-43 Building Authentication requests . . . 3-44 Authentication example – C#. . . 3-44 ccAuthenticateRequestV1 schema . . . 3-45 ccAuthenticateRequestV1 elements . . . 3-46 Processing the response . . . 3-48 detail tag/value pairs. . . 3-55 addendumResponse tag/value pairs . . . 3-55 Currency codes . . . 3-55

4 Information Lookup Service Transactions

Introduction . . . 4-1 Optimal Payments ILS WSDLs and links . . . 4-1 .NET example . . . 4-2 Building ILS requests . . . 4-3 ILS – C#. . . 4-3 ilsLookupRequestV1 schema . . . 4-4 ilsLookupRequestV1 elements . . . 4-5 Processing the response . . . 4-8 ilsLookupResponseV1 schema . . . 4-9 Response element contents . . . 4-12 Authorizations response details . . . 4-12 Settlements response details. . . . 4-13 Credits response details . . . 4-13 Chargebacks response details. . . 4-14 Direct Debit response details . . . 4-15 Reason codes . . . 4-16 Chargeback reason codes . . . 4-16 Retrieval request reason codes . . . 4-17 Discover chargeback and retrieval request reason codes . . . 4-18

A Using the HTTP Post Method

Introduction . . . A-1 Direct Debit requests . . . A-1 charge/verify/credit. . . A-1 HTML example – charge . . . A-2 updateShippingInfo . . . A-4 HTML example – updateShippingInfo . . . A-4

(6)

Mandate request . . . A-7 HTML example – mandate request . . . A-8 Change status request. . . A-9 HTML example – change status request . . . A-10 Mandate update request. . . A-10 HTML example – mandate update request. . . A-11 Credit card requests . . . A-12 Purchase/Authorization/Verification . . . A-12 HTML example – Authorization . . . A-13 Authorization Reversal . . . A-15 HTML example – Authorization Reversal . . . A-16 Settlement/Credit . . . A-17 HTML example – Settlement . . . A-17 Stored Data Authorization/Purchase . . . . A-18 HTML example – Stored Data Authorization . . . A-19 Cancel Settle/Credit/Payment/Independent Credit . . . A-20 HTML example – Cancel . . . A-20 Payment request. . . A-21 HTML example – Payment. . . A-22 Credit card Information Lookup . . . A-23 HTML example – Information Lookup . . . A-24 Enrollment Lookup . . . A-25 HTML example – Enrollment Lookup. . . A-26 Authentication . . . A-27 HTML example – Authentication . . . A-27 Information Lookup Service requests . . . A-28 HTML example - ILS. . . A-29 Sample HTTP Post . . . A-30 Sample HTTP Post responses . . . A-30

B Response Codes

Overview . . . B-1 Response codes . . . B-1 Action codes. . . B-19 Return codes . . . B-19

C Geographical Codes

Province codes . . . C-1 State codes . . . C-2 Country codes . . . C-3

(7)

Optimal Payments Web Services

What are Optimal Payments Web Services?

Web Services are a technology that allows applications to communicate with each other in a plat-form- and programming language–independent manner. A Web Service is a software interface that 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 to execute or data to exchange with another Web Service. Web Services are built on open standards such as SOAP and WSDL.

Optimal Payments Web Services offer the following benefits:

• Merchants can integrate easily with the Web Service API, using their favourite platform and language.

• Merchants can automate operation and avoid manually keying in information via the Optimal Payments Web page.

• Merchants can operate independently of changes and updates to the Optimal Payments Web site.

Web Services supported for Direct Debit

Optimal Payments currently supports the following Web Services for Direct Debit:

Table 1-1: Direct Debit Operations

Operation Description

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

Charge Allows you to transfer money from a customer’s bank account to your merchant account. This trans-action is completed in real time, though the banking network takes 3–5 days to transfer the funds. Credit Allows you to transfer money from your merchant account directly to a customer’s bank account. This transaction is completed in real time, though the banking network takes 3–5 days to transfer the funds.

Update Shipping Info Allows you to send shipping information, including a tracking number, once you have shipped goods for which you previously processed a charge transaction.

Information Lookup Allows you to run a report through the API over a date range you specify to return data on Direct Debit charge and credit transactions processed through your merchant account.

Mandate Request Allows you to create a mandate for a customer’s bank account and lodge it at their bank, which per-mits you to transfer money from the customer’s bank account to your merchant account. The bank-ing network typically takes 5 days to process the mandate.

(8)

Web Services supported for credit cards

Optimal Payments currently supports the following Web Services for credit cards:

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.

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 without settling 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 that card.

Authorization

Reversal 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 not function 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 Data

Authorization Allows you to authorize an amount on a customer’s credit card using customer data that is stored in our database. You provide only a minimum of information, saving you time and effort. Stored Data

Purchase Allows you to both authorize and settle an amount on a customer’s credit card using customer data that is 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 cancel one of these transactions as long as it is in a Pending state, which typically is before midnight of the day that 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 customer’s credit card. The Payment transaction is not associated with a previously existing authorization, so the amount of the transaction is not restricted in this way. Independent

Credit Allows you to credit an amount to a customer’s credit card. The Independent Credit transaction is not associated with a previously existing authorization, so the amount of the transaction is not restricted in this way.

Information

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

Lookup Allows you to determine whether a customer’s 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 to

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

Web Services supported for Information Lookup Service

Optimal Payments currently supports the following Web Service:

System requirements

The 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 Foundation

http://www.apache.org/dyn/closer.cgi/ws/axis/1_4

• Apache Axis2, 1.2, The Apache Software Foundation

http://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 Optimal Payments WSDLs and links

Direct Debit

WSDL:

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

Web Service:

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 to return 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.0

Framework 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

(10)

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

Credit card

WSDL: https://webservices.optimalpayments.com/creditcardWS/CreditCardService/v1?wsdl Web Service: https://webservices.optimalpayments.com/creditcardWS/CreditCardService/v1 HTTP Post: https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1

Information Lookup Service

WSDL: 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 Optimal Payments Web Services

Once you have configured your Web Services–enabled application, please contact our Technical Support team for instructions on how to test your API calls.

• Email [email protected]

• Telephone 888-709-8753

Security features

For some transactions (e.g., Purchase) Optimal Payments provides additional features to protect the merchant from fraudulent card usage.

• Address verification system (AVS) • Card validation data (CVD) • Negative database

• 3D Secure

AVS

Optimal Payments supports address verification checks (AVS) wherever the issuing bank sup-ports this feature. AVS verifies whether the address supplied by the customer using a card matches the billing address associated with that card at the issuing bank. This makes it more dif-ficult to use the card fraudulently, since in order to use a stolen card someone must also know the billing address associated with it. In addition, if goods are to be shipped, the merchant can

(11)

Within Optimal Payments, each payment method is configured with the acceptable set of AVS return codes. If the bank returns a code that is not acceptable for the payment method, then the request is rejected with an Authorization Failed error. If you get an Authorization Failed error in response to a transaction request, and an Authorization number is returned in the response, then the failure was caused by the AVS check. You can look at the AVS code returned to determine exactly why the AVS check failed. Optimal Payments returns the following codes, in the avsResponse element, to the merchant application in response to a transaction request, with A, N, and E indicating AVS failure:

When you registered with Optimal Payments, your account was set up to automatically apply AVS checks. Optimal Payments accepts only transactions for which the allowable AVS return codes are returned.

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

• 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 to

addresses 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.

CVD

The CVD value is a 3- or 4-digit number printed on the credit card, but which is not present on

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 format or 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)

actions where a card is not present, is a requirement of Optimal Payments. We support the CVD feature wherever the issuing banks do.

When customers enter their card and cardholder information, the CVD value is requested at the same 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 CVD value 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 database

Optimal Payments administers a negative database that provides additional protection against misuse of cards and inappropriate transaction requests. Card numbers and email addresses are entered into 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 transaction request that attempts to use either a card number or email address that is in the negative data-base will not be processed.

3D Secure

Optimal Payments supports 3D Secure, an online cardholder authentication program designed to make Internet purchase transactions safer by authenticating a cardholder’s identity at the time of purchase, before the merchant submits an authorization request. It is currently supported by several card brands, including Visa (Verified by Visa), MasterCard (SecureCode), and JCB (J/Secure). Authorizations processed using 3D Secure are guaranteed against most common types of chargeback disputes.

Using this guide

This 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.

Audience

This user’s guide is intended for Optimal Payments merchants using our Web Services API to process transaction requests with Optimal Payments.

Functionality

This 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 your account manager.

(13)

Symbols

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

Table 1-6: Symbols

Symbol Description

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

This warning icon alerts you about actions you might take that could have important consequences. This access icon alerts you about functionality that might be available only for certain merchant configurations.

(14)

(15)

Direct Debit Transactions

Introduction

This chapter describes how to process Direct Debit transactions via the Optimal Payments Web Service. The following operations are supported:

Table 2-1: Supported Operations

Operation Description For Request Type

Verify Allows you to confirm that a customer’s bank account is in good standing, without actually trans-ferring money out of that account.

• EFT • ACH

See Building charge, verify, or credit requests on page 2-4. Charge Allows you to transfer money from a customer’s

bank account to your merchant account. This transaction is completed in real time, though the banking network takes 3–5 days to transfer the funds.

• EFT • ACH • BACS • SEPA Credit Allows you to transfer money from your merchant

account directly to a customer’s bank account. This transaction is completed in real time, though the banking network takes 3–5 days to transfer the funds.

• EFT • ACH • BACS

Update Shipping Info Allows you to send shipping information, including a tracking number, once you have shipped goods for which you previously processed a charge trans-action.

• EFT • ACH • SEPA

See Building updateShippingInfo requests on page 2-14.

Information Lookup Allows you to run a report through the API over a date range you specify to return data on Direct Debit charge and credit transactions processed through your merchant account.

• EFT • ACH • BACS • SEPA

See Building lookup requests on page 2-18.

Mandate Request Allows you to create a mandate for a customer’s bank account and lodge it at their bank, which per-mits you to transfer money from the customer’s bank account to your merchant account. The banking network typically takes 5 days to process the mandate.

• BACS

• SEPA See Building BACS mandate requests (UK) on page 2-22.

Change Status Allows you to change the status of a charge, credit,

or mandate transaction. • EFT• ACH

• BACS • SEPA

See Building change status requests on page 2-28.

Update Mandate Allows you to update the information contained

(16)

• The verify, charge, and credit operations accept a ddCheckRequestV1 document object. • The updateShippingInfo operation accepts a ddShippingRequestV1 document object. • The lookup operation accepts a ddLookupRequestV1 document object.

• The mandate request operation accepts a ddMandateRequest document object. • The change status operation accepts a ddChangeStatusRequest document object. • The mandate update operation accepts a ddUpdateMandateRequest document object. • All operations return a ddCheckResponseV1 response.

.NET example

To build the .NET example: 1. Create a new project.

2. Add a Web Reference.

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.

(17)

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

(18)

4. Build a Direct Debit request and process response. • See Building charge, verify, or credit requests on page 2-4 • See Building updateShippingInfo requests on page 2-14 • See Processing the response on page 2-33

Building charge, verify, or credit requests

Charge, verify, and credit requests require the ddCheckRequestV1 document object. This section describes the structure of a ddCheckRequestV1 and how to construct one. See Table 2-2: ddCheck-RequestV1 Elements on page 2-7 for details on elements required.

charge example – C#

The following is a charge example in C#.

// Prepare the call to the Direct Debit Web Service DDCheckRequestV1 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();

To make this a credit or verify request, modify the value “charge” – in the line “DDCheckResponseV1 ddTxnResponse = ddService.charge(ddCheckRequest)” below – to “credit” or “verify”, respectively.

(19)

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 charge

DirectDebitServiceV1 ddService = new DirectDebitServiceV1();

DDCheckResponseV1 ddTxnResponse = ddService.charge(ddCheckRequest);

// Print out the result

String 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);

(20)

ddCheckRequestV1 schema

(21)

ddCheckRequestV1 elements

The ddCheckRequestV1 document object may contain the following elements:

This request is used for Direct Debit transactions for a variety of schemes. Please see Table 2-3: Addi-tional Direct Debit Element Requirements on page 2-13 for variations on certain required elements.

Table 2-2: ddCheckRequestV1 Elements

Element Child Element Required Type Description

merchantAccount accountNum Yes String

Max = 10

This is the merchant account number.

storeID Yes String

Max = 80

This is the Optimal Payments store identifier, used to authenticate the request. It is defined by Optimal Payments and provided to the merchant as part of the integration process.

storePwd Yes String

Max = 20

This is the Optimal Payments store pass-word, used to authenticate the request. It is defined by Optimal Payments and provided to the merchant as part of the integration process.

merchantRefNum Conditional String

Max = 40

This is the unique ID number associated with the original request. The value is cre-ated by the merchant and submitted as part of the original request. This is returned only in response to a lookup request.

amount Yes String

Max = 9999999.99

This is the amount of the transaction request.

NOTE: This field requires a leading non-zero digit and two digits after the decimal place. An exception is made in cases where a leading zero is by itself (e.g., 0.99). check accountType Optional Enumeration This is the type of checking account used for

the transaction. Possible values are: • PC (Personal Checking) • PS (Personal Savings) • PL (Personal Loan) • BC (Business Checking) • BS (Business Savings) • BL (Business Loan)

NOTE: If this element is not specified, the value defaults to PC.

bankName Optional String

Max = 40

This is the name of the customer’s bank, to which this transaction is posted.

(22)

checkNum Yes Long Max = 8

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

NOTE: The checkNum element is required for the verify operation, where it serves as a unique transaction ID, even though no money is transferred between accounts for this operation. It cannot be set to 0 (zero).

accountNum Yes String

Max = 17 If IBAN, Max = 32

This is the customer’s bank account number. For SEPA transactions, this is IBAN (Interna-tional Bank Account Number) of the cus-tomer’s bank account.

NOTE: This cannot be zero (0) and can con-tain alphanumeric characters only.

routingNum Yes String

Min = 6 Max = 9 If BIC, Min = 8 Max = 11

For USD accounts, this is the 9-digit routing number of the customer’s bank.

For British pound accounts, this is the 6-digit sort code of the customer’s bank.

For Canadian dollar accounts, this is a com-bination of the 3-digit institution ID followed by the 5-digit transit number of the customer’s bank branch. They must be entered in this order. Do not include spaces or dashes.

For SEPA transactions, this is the BIC (Bank Identifier Code) of the customer’s bank account.

NOTE: This cannot be zero (0) and can con-tain alphanumeric characters only.

payee Conditional String

Max = 81

This is the descriptor that will appear on the customer’s bank account. It is required only for credit and verify transactions.

If you provide a value for this field, this value will be used as the statement descriptor. If you do not provide a value for this field, a default value configured for the merchant account will be used.

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

bankCity Conditional String

Max = 40

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

Table 2-2: ddCheckRequestV1 Elements (Continued)

(23)

mandateReference Conditional String Max = 10 For SEPA, Max = 35

This is the mandate reference that allows the account to be charged. This is the value returned for the mandateReference parameter in the response to a ddMandateRequestV1.

For SEPA, this element is mandatory. 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)

NOTE: If this element is not specified, the value defaults to WEB. It cannot be set to WEB or TEL for credit requests.

firstName Conditional String Max = 40

This is the customer’s first name.

Required if checkPayMethod is set to WEB or TEL.

lastName Conditional String Max = 40

This is the customer’s last name.

Required if accountType is set to PC, PS, or PL.

companyName Conditional String Max = 50

This is the company’s name.

Required if accountType is set to BC, BS, or BL.

street Yes String

Max = 50

This is the first line of the customer’s street address.

street2 Optional String

Max = 50

This is the second line of the customer’s street address.

city Yes String

Max = 40

This is the city in which the customer resides.

state/region Conditional If state, then Enumeration If region, then string

Max = 40

This is the state/province/region in which the customer resides.

Provide state if within U.S./Canada. Provide region if outside of U.S./Canada.

See Appendix C: Geographical Codes for correct codes to use.

country Yes Enumeration This is the country in which the customer resides. See Country codes on page C-3 for correct codes to use.

zip Optional String

Max = 10

This is the customer’s ZIP code if in the U.S.; otherwise, this is the customer’s postal code.

(24)

email Optional String Max = 100

This is the customer’s email address.

personalID idNumber Optional String

Max = 20

This is the number of the ID provided for the idType element.

idType Optional Enumeration This is the type of ID used to identify the owner of the bank account.

Possible values are: • DL (Driver’s License) • SS (Government ID) • MI (Military ID) • GN (Generic ID) state/region Optional If state, then

Enumeration If region, then string

Max = 40

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

country Optional String

Length = 2

This is the country in which the ID was issued. Possible values are:

• CA (Canada) • US (United States)

expiry Optional The expiry child element has three further

child elements. Child Element of expiry

day Optional Int

Length = 2

This is the day the ID expires.

month Optional Int

Length = 2

This is the month the ID expires.

year Conditional Int

Length = 4

This is the year the ID expires.

This element is required if the expiry ele-ment is included.

socialSecurityNumber Optional String

Max = 12

This is the customer’s Social Security Number.

dateOfBirth Optional This is the customer’s date of birth.

year Conditional String

Max = 4 1900–9999

This is the customer’s year of birth.

month Conditional String

Max = 12

This is the customer’s month of birth. day Conditional String This is the customer’s day of birth.

(25)

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 String

Max = 40

This is the recipients’s first name.

lastName Optional String

Max = 40

This is the recipient’s last name.

street Optional String

Max = 50

This is the first line of the recipient’s street address.

Max = 50

This is the second line of the recipient’s street address.

city Optional String

Max = 40

This is the city in which the recipient resides. state/region Optional If state,

Max = 40

This is the state/province/region in which the recipient resides.

country Optional Enumeration This is the country in which the recipient resides. See Country codes on page C-3 for correct codes to use.

zip Optional String

Max = 10

This is the recipient’s ZIP code if in the U.S.; otherwise, this is the recipient’s postal code. phone Optional String This is the recipient’s phone number.

(26)

email Optional String Max = 100

This is the recipient’s email address.

customerIP Optional String

Max = 50

This is the customer’s 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 Direct

Debit transactions.

confirmationNumber Conditional String

Max = 15

This is the confirmation number returned by Optimal Payments in response to the origi-nal request.

Include this element only if you are using the ddCheckRequestV1 to process a credit request.

targetVirtualAccount No This element is not applicable for Direct

Debit transactions.

checkRiskService No This element is not applicable for Direct

Debit transactions.

txnDate Optional dateTime This is the date and time that the transaction

took place.

For a charge or credit, or for a

ddMandateRequestV1, this can be the future date and time when the transaction will take place.

For SEPA, this specifies the future collection date. It must be a minimum of 6 business days in the future for First and One-Off transactions, and a minimum of 3 business days in the future for Recurring and Final transactions.

NOTE: The resulting collection date will be returned in the tag/value pair for the detail element in the response (see Table 2-10: ddCheckResponseV1 Elements on page 2-34).

sdk version Conditional String

Max = 20

This is the version of the SDK used, if any. Required if sdk element is provided.

(27)

Special considerations for Direct Debit elements

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

platform Conditional String

Max = 10

This is the integration language of the SDK used (e.g., Java, .NET).

Required if sdk element is provided.

provider Conditional String

Max = 20

This is the author of the SDK used. Set to value “op” when the SDK is provided by Optimal Payments.

Required if sdk element is provided.

origin Optional Enumeration The is the origin of the request.

Possible values are: • Wireless • Wireline

addendumData tag Optional String

Max = 30

This is additional data that the merchant can include with the transaction request.

value Optional String

Max = 1024

Table 2-3: Additional Direct Debit Element Requirements

Element Regular Transactions Guaranteed Transactions SEPA Transactions

check.accountType Optional Required Optional

check.bankName Optional Required Optional

check.checkNum Required Required Optional

check.payee Optional Optional Required

check.bankCountry Conditional Conditional Optional

check.bankCity Conditional Conditional Optional

check.mandateReference Conditional Conditional Required

billingDetails.firstName Conditional Required Required

billingDetails.lastName Conditional Required Required

billingDetails.companyName Conditional Conditional Optional

billingDetails.state Conditional Required Optional

billingDetails.zip Optional Required Required

billingDetails.phone Optional Required Optional

(28)

Building updateShippingInfo requests

The updateShippingInfo request requires the ddShippingRequestV1 document object. This section describes the structure of a ddShippingRequestV1 and how to construct one. See Table 2-4: ddShip-pingRequestV1 Elements on page 2-16 for details on elements required.

updateShippingInfo example – C#

The following is an updateShippingInfo example in C#. // Prepare the call to the Direct Debit Web Service

DDShippingRequestV1 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 number from a previous settle auth or purchase

ddShippingRequest.carrier = CarrierV1.FEX; // Fedex ddShippingRequest.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

dateOfBirth.year Optional Required Optional

dateOfBirth.month Optional Required Optional

dateOfBirth.day Optional Required Optional

personalID.idNumber Optional Required Optional

personalID.state Optional Required Optional

socialSecurityNumber Optional Required Optional

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

All optional elements that take non-nullable data types (e.g., int or enum) must have their specified attribute set to true when setting values for those elements. See the shipMethod element in the example below.

Table 2-3: Additional Direct Debit Element Requirements (Continued)

(29)

//Perform the Web Services call to update the shipping info DirectDebitServiceV1 ddService = new DirectDebitServiceV1(); DDCheckResponseV1 ddTxnResponse =

ddService.updateShippingInfo(ddShippingRequest); // Print out the result

{

} }

(30)

ddShippingRequestV1 schema

A ddShippingRequestV1 document object has the following structure:

ddShippingRequestV1 elements

The ddShippingRequestV1 document object may contain the following elements:

Table 2-4: ddShippingRequestV1 Elements

Max = 10

(31)

storeID Yes String Max = 80

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 String

Max = 50

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

confirmationNumber Yes String

Max = 15

This is the confirmation number returned by Optimal Payments.

shipMethod Optional Enumeration This is the method of shipment.

• N = Next Day/Overnight • T = Two-Day Service • C = Lowest Cost • O = Other

firstName Optional String

Max = 40

lastName Optional String

Max = 40

Max = 50

This is the second line of the customer’s street address.

city Optional String

Max = 40

Table 2-4: ddShippingRequestV1 Elements (Continued)

(32)

Building lookup requests

The Direct Debit lookup request allows you to run a report, over a date range you specify, to return data on Direct Debit charge and credit transactions processed through your merchant account.

Lookup example – C#

The following is a ddLookupRequest example in C#. // Prepare the call to the Direct Debit Web Service

DDLookupRequestV1 ddLookupRequest = new DDLookupRequestV1(); MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678";

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"; endDate.day = "15";

state/region Optional If state, then

Max = 40

country Optional Enumeration This is the country in which the customer

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

zip Optional String

Max = 10

phone Optional String

Max = 40

This is the customer’s telephone number.

email Optional String

Max = 100

Table 2-4: ddShippingRequestV1 Elements (Continued)

(33)

endDate.second = "00";

ddLookupRequest.endDate = endDate; ddLookupRequest.endDateSpecified = true;

//Perform the Web Services call to process the charge

DDCheckResponseV1 ddCheckResponse = ddService.lookup(ddLookupRequest); // Print out the result

String 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);

(34)

ddLookupRequestV1 schema

A ddLookupRequestV1 document object has the following structure:

ddLookupRequestV1 elements

The ddLookupRequestV1 document object may contain the following elements:

Table 2-5: ddLookupRequestV1 Elements

Max = 10

storeID Yes String

Max = 80

storePwd Yes String

Max = 20

(35)

confirmationNumber Optional String Max = 15

This is the confirmation number returned by Optimal Payments in response to the origi-nal request. Include this element only if you want to search using this field. This field takes precedence over the merchantRefNum field.

Max = 40

This is a unique ID number associated with the original request. The value is created by the merchant and submitted as part of the request.

startDate year Required Int

Max = 9999

This is the year set for the search start.

month Required Int

Min = 1 Max = 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 = 0 Max = 23

This is the hour set for the search start.

minute Required Int

Min = 0 Max = 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.

endDate year Required Int

Max = 9999

This is the year set for the search end.

month Required Int

Min = 1 Max = 12

This is the month set for the search end.

day Required Int

Min = 1 Max = 31

This is the day set for the search end.

hour Required Int

Min = 0 Max = 23

This is the hour set for the search end.

Table 2-5: ddLookupRequestV1 Elements (Continued)

(36)

Building BACS mandate requests (UK)

The Direct Debit mandate allows you to create a mandate for a customer’s bank account and lodge it at their bank, which is required before you can perform a charge operation to transfer money from that customer’s bank account to your merchant account.

When you submit a ddMandateRequestV1, Optimal Payments will return a value for the

mandateReference element in the response. This value is either based on the value you send in the request, or it is automatically generated by the Optimal Payments system. You will use this value in the mandateReference element (which is a child element of the check element) when you process future charge requests against the customer’s bank account using the ddCheckRequestV1.

The mandateReference is 10 characters in length. If you send a request with a value of fewer than 10 characters, Optimal Payments will pre-fill the reference with 0’s to make up 10 characters. For example, a requested value of “ABCDEFG” will return a value of “000ABCDEFG”. If no value is passed, Optimal Payments will create the value for you and return it within the response. Initially, the status of the mandate is set to W (Pending), followed by C (Completed) when it has been batched – at this point the mandate cannot yet be used for Direct Debit transactions. The banking network typically takes 5 days to process the mandate, so 5 days after the mandate has been batched, Optimal Payments changes the status of the mandate to AP (Active). At that point it can be used to authorize Direct Debit transactions on the bank account for which it was set up. Note that if the charge is postdated by setting the txnDate in the ddCheckRequestV1 request, then the mandate may be used while it is not yet active, provided the txnDate is set to a minimum of 5 working days in the future to allow the mandate time to become active. To assist this process, the date a mandate will become active is returned in the effectiveDate element of the response to the ddMandateRequestV1.

Mandates are automatically batched the next working day unless the autoSend value is not set to Y, in which case the mandate will remain in a PCA (Pending Customer Approval) state. This optional intermediate state before W allows you to perform extra checks on the customer, or for the customer to review the information having received the mandateReference, before proceeding. The mandate may then be turned from a PCA to W state by using either the changeStatus request or the Optimal Payments merchant back office.

Building SEPA mandate requests

In order to process a SEPA Direct Debit transaction, you will need to pre-establish a mandate agreement with your customer and send your mandate reference ID in the mandateReference ele-ment. Please note that your mandate reference ID can have up to 35 characters.

SEPA Direct Debit mandates are active as soon they are created by the merchant, so you can

minute Required Int

Min = 0 Max = 59

This is the minute set for the search end.

second Required Int

Min = 0 Max = 59

This is the second set for the search end.

Table 2-5: ddLookupRequestV1 Elements (Continued)

(37)

The SEPA Direct Debit Merchant Implementation Guide contains more information about the busi-ness logic and processes surrounding the SEPA Direct Debit transaction.

mandate example – C#

The following is a ddMandateRequest example in C#. // Prepare the call to the Direct Debit Web Service

DDMandateRequestV1 ddMandateRequest = new DDMandateRequestV1(); MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678";

ddCheckRequest.merchantAccount = merchantAccount; CheckV1 check = new CheckV1();

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";

DDCheckResponseV1 ddTxnResponse = ddService.mandate(ddCheckRequest); // Print out the result

{

} }

(38)

ddMandateRequestV1 schema

(39)

ddMandateRequestV1 elements

The ddMandateRequestV1 document object may contain the following elements:

Table 2-6: ddMandateRequestV1 Elements

Max = 10

storeID Yes String

Max = 80

storePwd Yes String

Max = 20

Max = 40

This is the unique ID number associated with the original request. The value is cre-ated by the merchant and submitted as part of the original request.

check accountType Optional Enumeration This is the type of checking account used for the transaction. Possible values are: • PC (Personal Checking) • PS (Personal Savings) • PL (Personal Loan) • BC (Business Checking) • BS (Business Savings) • BL (Business Loan)

NOTE: If this element is not specified, the value defaults to PC.

bankName Optional String

Max = 40

This is the name of the customer’s bank, to which this transaction is posted.

checkNum Optional Long

Max = 8

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

accountNum Yes String

Max = 17

This is the customer’s bank account number. For SEPA transactions, this is IBAN (Interna-tional Bank Account Number) of the cus-tomer’s bank account.

routingNum Yes String

Min = 6 Max = 9

For British pound accounts, this is the 6-digit sort code of the customer’s bank.

For SEPA transactions, this is the BIC (Bank Identifier Code) of the customer’s bank account.

(40)

payee Optional String Max = 81

This is the descriptor that will appear on the customer’s bank account. It is required only for credit and verify transactions.

If you provide a value for this field, this value will be used as the statement descriptor. If you do not provide a value for this field, a default value configured for the merchant account will be used.

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

bankCity Conditional String

Max = 40

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

mandateReference Conditional String Max = 10 For SEPA, Max = 35

This is the mandate reference that allows the account to be charged. You may optionally set the value of the mandateReference your-self when making the request. If you do not supply a value here then it will be set by Optimal Payments and returned in the response.

For SEPA, this element is mandatory, and the merchant creates their own

mandateReference. billingDetails checkPayMethod Optional Enumeration This is the payment type.

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

NOTE: If this element is not specified, the value defaults to WEB.

firstName Conditional String Max = 40

Required if checkPayMethod is set to WEB or TEL.

lastName Conditional String Max = 40

Required if accountType is set to PC, PS, or PL.

companyName Conditional String Max = 50

This is the company’s name.

Required if accountType is set to BC, BS, or BL.

Max = 50

street2 Optional String This is the second line of the customer’s

Table 2-6: ddMandateRequestV1 Elements (Continued)

(41)

city Optional String Max = 40

state/region Conditional If state, then Enumeration If region, then string

Max = 40

country Optional Enumeration This is the country in which the customer resides. See Country codes on page C-3 for correct codes to use.

zip Optional String

Max = 10

phone Optional String

Max = 40

This is the customer’s telephone number.

email Optional String

Max = 100

customerIP Optional String

Max = 50

This is the customer’s IP address.

txnDate Optional dateTime This is the date and time that the transaction

took place.

For a charge or credit, or for a ddMandat-eRequestV1, this can be the future date and time when the transaction will take place.

autoSend Optional Boolean This controls when the mandate is sent to

the bank.

• Y = The mandate will be set to W (Pending) status, ready to be batched and then sent to the bank

• N = The mandate will remain with the status of PCA (Pending Customer Approval), and will not be sent to the bank.

If the autoSend status is set to N, the man-date can later be changed to a status of W by using the changeStatus request, at which point the mandate will then be sent to the bank at the next batching time (see Building change status requests on page 2-28).

NOTE: For SEPA, this must be set to Y, and the mandate will be set to AP (Active).

(42)

Building change status requests

A change status request allows you to change the status of some Direct Debit transactions. You can make the following status changes:

Optimal Payments responds to your change status request with the ddCheckResponseV1. In this response, the confirmationNumber identifies the request that was updated (charge, credit, or mandateRequest), and you can confirm the new status of the transaction you updated. See Process-ing the response on page 2-33 for details.

Change status example – C#

The following is a ddChangeStatusRequest example in C#. // Prepare the call to the Direct Debit Web Service

Max = 1024

Table 2-7: Status Changes

Solution Request Type Initial Status Resulting Status UK Direct Debit (BACS) • Mandate • PCA – Pending Customer Approval • W – Pending

• X – Cancelled UK Direct Debit (BACS) • Charge

• Credit • Mandate

• W – Pending • X – Cancelled

UK Direct Debit

(gateway merchants) • Charge• Credit • Mandate

• C – Completed

• CL – Cleared • RE – Returned_NOTE:_{Use only when your} sponsoring bank has rejected the transaction and no BACS report has been produced. Allow 5 working days from the completed date and then contact Technical Support before making this change request.

EFT/ACH • Charge

• Credit • C – Completed • X – Cancelled_NOTE:_{Only possible where} the request has not yet been sent to the bank.

SEPA Direct Debit • Mandate • AP – Active • X – Cancelled

SEPA Direct Debit • Charge • W – Pending

• C – Completed • X – Cancelled_NOTE:_{Possible only up to 5} days after the clearing date of the charge.

(43)

MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678";

ddChangeStatusRequest.merchantAccount = merchantAccount;

ddChangeStatusRequest.confirmationNumber = "123456"; // A valid confirmation number from a previous mandate or echeck;

ddChangeStatusRequest.status = "C";

DDCheckResponseV1 ddTxnResponse = ddService.changeStatus(ddCheckRequest); // Print out the result

{

} }

}

ddChangeStatusRequest schema

(44)

ddChangeStatusRequestV1 elements

The ddChangeStatusRequestV1 document object may contain the following elements:

Table 2-8: ddChangeStatusRequestV1 Elements

Max = 10

storeID Yes String

Max = 80

This is the Optimal Payments store identifier, used to authenticate the request. It is defined by Optimal Payments and provided to the mer-chant as part of the integration process.

storePwd Yes String

Max = 20

This is the Optimal Payments store password, used to authenticate the request. It is defined by Optimal Payments and provided to the mer-chant as part of the integration process.

confirmationNumber Optional String

Max = 15

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

This is the confirmationNumber returned by Optimal Payments in response to the original transaction request.

status Required Enumeration This is the new status code for the transaction. Possible values are:

• C – Completed • RE – Returned • W – Pending • X – Cancelled

addendumData tag Optional String

Max = 30

Max = 1024