CIT-040630 myCitadel DevCitadel Commerce Corp. xv Preface The preface provides information for using...

myCitadel Wallet

Release 8.0

Developer Guide

Revision 1.1

Copyright 2007Citadel Commerce Corp.

Suite 1500, 4710 KingswayBurnaby, British Columbia

CanadaV5H 4M2

MYC8.0-R1.1

ii Citadel Commerce Corp.

Revised October 26, 2007 myCitadel Wallet Developer Guide

DisclaimerWhile every reasonable effort has been made to achieve technical accuracy and completeness, information in this document is subject to change without notice and does not represent a commitment on the part of Citadel Commerce Corp., or any of its subsidiaries, affiliates, or licensors. There are no warranties, express or implied, with respect to the content of this document.

Features and specifications of Citadel Commerce Corp. products are subject to change without notice.

Copyright 2007 by Citadel Commerce Corp. All rights reserved.

Confidentiality NoticeREADER acknowledges that all material and information which has or will come into his/her possession of knowledge in connection with the use of these SPECIFICATIONS consists of confidential and proprietary data and that disclosure of it or use of it by third parties will be damaging to Citadel Commerce. READER, therefore, agrees to hold such material and information in strictest confidence, not to make use thereof other than for the purpose of putting these SPECIFICATIONS into effect, and not to release or disclose it to any other party. READER shall take appropriate action to ensure that the obligations of non-use and non-disclosure of confidential information under this NOTICE regarding confidentiality, to which READER has agreed by acceptance of these SPECIFICATIONS.

Trademark NoticesAdobe and Acrobat are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.

Crystal Reports is a registered trademark of Business Objects SA and/or its affiliated companies in the United States and other countries.

Microsoft, Excel, Explorer, and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

All other names mentioned herein may be trademarks of their respective owners.

Citadel Commerce Corp. iii

Revision History

Citadel Commerce periodically issues revisions to documents as we implement enhancements and changes. With each revision, we include a Revision History specifying changes to document content.

Revision Author Date Description

1.0 MP Sep. 13, 2006 • Changed document revision number from MYC7.3-R1.31 to MYC7.5-R1.0.

• Added “wasGuaranteed” attribute to:• Direct Payment Debit Request Response (table) on page

37.• Direct Payment Debit Request Response Sample on

page 40• In section Wallet Limits on page 4, replaced outdated limits

information with a reference to a document and Web page.• Changed all occurrences of “Merchant Support” to

“Merchant Services”.• Changed all occurrences of “Merchant Support

Representative” to “Integration and Support Specialist”.

1.1 JG Oct. 25, 2007 • Added error_number parameter to:• Direct Payment Debit Request Response (Table 3-6)• Web Credit Request Response (Table 5-2)

• Added Error Messages - Direct Debit Request Response (Table 3-7).

myCitadel Wallet Developer Guide Revised October 26, 2007

iv Citadel Commerce Corp.

Citadel Commerce Corp. v

Table of Contents

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii

List of Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

List of Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

List of Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

About this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xv

Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xv

Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xv

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Organization of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Time References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Contact Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviCitadel Commerce Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviCitadel Commerce Merchant Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

System and Integration Overview [1] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

System Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1Consumer Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1Merchant Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

System Integration Process and Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1System Integration Process Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2

Merchant Accounts and Store Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2

Web Payment Transaction Fees Structure and Payment Risk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2Check Acceptance Risk Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

Consumer Wallets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4Wallet Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4International Wallet Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4

Integration Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5Payment Sequence Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

myCitadel Wallet API [2] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

myCitadel Wallet Debit Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7Web Payment Direct Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7


vi Citadel Commerce Corp.

Web Payment Redirect Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

myCitadel Wallet API Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Web Payment Direct Interface [3] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

High-Level Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Web Payment Direct Interface Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Web Payment Direct Interface with Security Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Transaction Flow, Screen Sequence, and Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Recommended Payment Screens and Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Web Payment Direct Interface with Payment Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Transaction Flow, Screen Sequence, and Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Recommended Payment Screens and Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Payment Permission Status Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Payment Permission Status Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Payment Permission Status Request Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Payment Permission Status Request Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Payment Exception Handling Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27New Account Setup Link–No Wallet Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Existing Wallet Login Link–No Funds Available Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Payment Permission Configuration Link–No Permissions Exceptions . . . . . . . . . . . . . . . . . . . . . . . 28

Direct Payment Debit Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Direct Payment Debit Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Direct Payment Debit Request Form Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Direct Payment Debit Request Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Direct Payment Debit Status Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Request Fields for Transaction Status Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Transaction Status Request Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Sending the Report Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Web Payment Direct Status Report Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Web Payment Debit Status Report Response Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Web Payment Redirect Interface [4] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

High-Level Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Technical Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Creating the Payment Button Using HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Redirect Link Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Web Payment Redirect Transaction Link Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Web Payment Redirect Link Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Web Payment Redirect Status Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Web Payment Redirect Status Report Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Web Payment Redirect Status Report Request Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Sending the Web Payment Redirect Status Report Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Web Payment Redirect Status Report Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Revised October 26, 2007 myCitadel Wallet Developer Guide

Citadel Commerce Corp. vii

Redirect Payment Debit Request Response Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51

Web Credit Service [5] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

High-Level Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53

Merchant Account Administration User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54

HTTP POST Directly to myCitadel Wallet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54

Web Credit Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55Request Fields for Web Credit Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55Submitting a Web Credit Request Using XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57Submitting a Web Credit Request Without Using XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59

Web Credit Request Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59Responses When Using XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60Responses When Not Using XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61Error Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61

Web Credit Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62Foreign Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62Consumers Who are not Members of myCitadel Wallet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62Pending Transactions Due to Consumer's Uncleared Funds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62Pending Transactions Due to Merchant's NSF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63Web Credit Fees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63Cashout Fees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63Consumer Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63

Combined Web Credit/Web Payment Service [6] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

High-Level Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65

HTTP POST Directly to myCitadel Wallet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65

Combined Web Credit/Web Payment Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66Request Fields for Combined Web Credit/Web Payment Requests . . . . . . . . . . . . . . . . . . . . . . . . . . .66Submitting a Combined Web Credit/Web Payment Request Using XML . . . . . . . . . . . . . . . . . . . . . .67Submitting a Combined Web Credit/Web Payment RequestWithout Using XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69

Combined Web Credit/Web Payment Request Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69Responses Using XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70Responses Not Using XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70

Transaction Status Change Report [7] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

High-Level Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73Transaction Status Change Report Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73Transaction Status Change Report Request Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74Sending the Transaction Status Change Report Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74Transaction Status Change Report Request Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74

User Registration Link [8] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

High-Level Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77User Registration Link Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77


viii Citadel Commerce Corp.

Get Wallet Status Request [9] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

High-Level Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Get Wallet Status Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Get Wallet Status Request Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Get Wallet Status Request Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Request Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Citadel Commerce Corp. ix

List of Figures

Figure 3-1 Web Payment Direct Transaction Flowchart (Security Codes) . . . . . . . . . . . . . . . . . . . . . . . . 12

Figure 3-2 Initial Payment (Security Code) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Figure 3-3 Exception #1–Wallet Does Not Exist (Security Code) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Figure 3-4 Exception #2–Security Code is Incorrect (Security Code) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Figure 3-5 Exception #3–Insufficient Funds (Security Code) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Figure 3-6 Transaction Completion Success (Security Code) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Figure 3-7 Web Payment Direct Transaction Flowchart (Payment Permissions) . . . . . . . . . . . . . . . . . . . 18

Figure 3-8 Initial Payment (Payment Permission) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Figure 3-9 Exception #1–Wallet Does Not Exist (Payment Permission) . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Figure 3-10 Exception #2–No Permissions (Payment Permission) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Figure 3-11 Exception #3–Insufficient Funds (Payment Permission) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Figure 3-12 Transaction Completion Success (Payment Permission) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Figure 3-13 Payment Permission (Typical) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Figure 4-1 Link to myCitadel Wallet Web Payment Redirect Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Figure 5-1 Web Credit Merchant Interface Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54


x Citadel Commerce Corp.

Citadel Commerce Corp. xi

List of Code Samples

Code Sample 3-1 General Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26

Code Sample 3-2 Existing Payment Permission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

Code Sample 3-3 Direct Link to myCitadel Wallet Signup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28

Code Sample 3-4 Opening a New Browser Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

Code Sample 3-5 Linking Refresh to Event Onfocus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32

Code Sample 3-6 Sample Link for Direct Payment Debit Request Form . . . . . . . . . . . . . . . . . . . . . . . . . .35

Code Sample 3-7 Direct Payment Debit Request Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

Code Sample 3-8 Transaction Status Request Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42

Code Sample 3-9 Web Payment Debit Status Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44

Code Sample 4-1 Web Payment Redirect Transaction Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47

Code Sample 4-2 Merchant Link to Web Payment Redirect Interface . . . . . . . . . . . . . . . . . . . . . . . . . . .47

Code Sample 4-3 Redirect Payment Status Report Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48

Code Sample 4-4 Redirect Payment Debit Request Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51

Code Sample 5-1 Web Credit Request (Single) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57

Code Sample 5-2 Web Credit Request (Multiple) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58

Code Sample 5-3 Web Credit Request Response (Multiple) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61

Code Sample 5-4 Web Credit Request Response (When Not Using XML) . . . . . . . . . . . . . . . . . . . . . . . .61

Code Sample 6-1 Combined Web Credit/Web Payment Request (Single) . . . . . . . . . . . . . . . . . . . . . . . . .67

Code Sample 6-2 Combined Web Credit/Web Payment Request (Multiple) . . . . . . . . . . . . . . . . . . . . . . .68

Code Sample 6-3 Combined Web Credit/Web Payment Request Response (Multiple) . . . . . . . . . . . . . .70

Code Sample 6-4 Combined Web Credit/Web Payment Request Response (When Not Using XML) . .71

Code Sample 7-1 Transaction Status Change Report Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74

Code Sample 7-2 Transaction Status Change Report Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76

Code Sample 8-1 User Registration Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77

Code Sample 9-1 Get Wallet Status Request Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80


xii Citadel Commerce Corp.

Citadel Commerce Corp. xiii

List of Tables

Table 3-1 Mandatory and Optional Fields (Payment Permission Status Request) . . . . . . . . . . . . . . . . . . 24

Table 3-2 paymentPermission Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Table 3-3 Status Values (Payment Permission Status Request) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Table 3-4 Mandatory and Optional Fields (Payment Permission Configuration Link) . . . . . . . . . . . . . . 30

Table 3-5 Mandatory and Optional Fields (Direct Payment Debit Request) . . . . . . . . . . . . . . . . . . . . . . . 34

Table 3-6 WEBPAYMENT Element Attributes (Direct Payment Debit Request Response) . . . . . . . . . . 36

Table 3-7 Error Messages – Direct Payment Debit Request Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Table 3-8 Transaction Status Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Table 3-9 REPORT Element Attributes (Web Payment Direct Status Report Response) . . . . . . . . . . . . 42

Table 3-10 WEBPAYMENT Sub-element Attributes (Web Payment Direct Status Report Response) . 43

Table 4-1 Mandatory and Optional Fields (Redirect Link Fields ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Table 4-2 Web Payment Redirect Status Report Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Table 4-3 REPORT Element Attributes (Web Payment Redirect Status Report Response) . . . . . . . . . . 49

Table 4-4 WEBPAYMENT Sub-element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Table 5-1 Mandatory and Optional Fields (Web Credit Request) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Table 5-2 Web Credit Request Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Table 6-1 Mandatory and Optional Fields (Combined Web Credit/Web Payment Request) . . . . . . . . . 66

Table 6-2 Combined Web Credit/Web Payment Request Response Fields . . . . . . . . . . . . . . . . . . . . . . . . 69

Table 7-1 Mandatory and Optional Fields (Transaction Status Change Report) . . . . . . . . . . . . . . . . . . . 73

Table 7-2 REPORT Element Attributes (Transaction Status Change Report Request Response) . . . . . 74

Table 7-3 WEBPAYMENT Sub-element Attributes (Transaction Status Change Report Request Response) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Table 9-1 Mandatory and Optional Fields (Get Wallet Status Request) . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Table 9-2 Status Values (Get Wallet Status Request Response) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80


xiv Citadel Commerce Corp.

Citadel Commerce Corp. xv

Preface

The preface provides information for using this guide.

About this GuideThis technical guide was created for merchant customers of the Citadel Commerce Web payment service (www.mycitadel.com). It provides the merchant's development team with the information required to easily and quickly integrate their commercial Web site with the myCitadel Wallet platform to accept online payments from their Web site consumers.

This guide defines the structures, methods, parameters, and best practices that are needed to integrate a merchant site with the myCitadel Wallet Web payment system, also known as the myCitadel Wallet Application Programming Interface (API). We have also included operational background information to provide context for the technical integration aspects.

To integrate with the myCitadel Wallet service, merchants must:• Complete the Citadel Commerce Corp. Merchant Agreement• Pass the Citadel Commerce due diligence investigation process• Establish a Merchant Account within the myCitadel Wallet system with the assistance of the

Citadel Commerce Merchant Services team

AudienceThis guide is confidential and is intended to be used only by merchant development resources assigned to implement merchant Web site interfaces to the myCitadel Wallet platform.

It assumes you have specific knowledge in the following areas:• Familiarity with the myCitadel Wallet system at a high level• Specific technical knowledge of HTML, XML, and general Web interface API conventions

ConventionsThis section describes the fonts used in this guide.

Arial bold is used to refer to user buttons and options in a dialog box or Web page.

Times Italic is used to refer to chapters or titles in the guide and titles of other guides.

Courier is used to refer to command line, filenames, or source code.

myCitadel Developer Guide Revised October 26, 2007

xvi Citadel Commerce Corp.

Related Documentation

Organization of this GuideThis document covers the integration of myCitadel Wallet using:• The Web Payment Direct Interface, where the consumer never leaves the merchant site, and

the merchant communicates with the myCitadel Wallet site using HTTP POST commands; see Web Payment Direct Interface [3].

• The Web Payment Redirect Interface, where the consumer is taken to the myCitadel Wallet site to perform the transaction, and is then returned to the merchant site; see Web Payment Redirect Interface [4].

• The Web Credit Service, which allows merchants to directly transfer funds to a consumer's existing myCitadel Wallet account; see Web Credit Service [5].

• The Transaction Status Change Report, which provides merchants with a generalized mechanism for extracting transaction information from the myCitadel Wallet system; see Transaction Status Change Report [7].

Time ReferencesCitadel Commerce is a global company with locations in several time zones. The Citadel Commerce operations and business center is in Vancouver, Canada.

When expressing time, Citadel Commerce Web sites, HTTP responses, online reports, and documentation use Pacific Standard Time (GMT -8 hours).

Contact Information

Citadel Commerce Customer SupportObtain support in any of the following ways:

Email:

Address emails to: [email protected]

Telephone:

Phone 24 hours a day, 7 days a weekU.S. and Canada (toll free): 1-877-747-8433Outside of U.S. (toll free): 00-800-2952-4390Outside of U.S. (long distance): +1 604-639-2971

Fax: +1 281-754-4843

Publication Title Content

myCitadel Wallet Merchant Guide Describes myCitadel Wallet functionality, and serves as a reference guide for merchant staff acting in the role of a myCitadel Wallet merchant administrator.

Revised October 26, 2007 Preface

Citadel Commerce Corp. xvii

Web Sites:

To access Citadel Commerce Web sites go to:

http://www.citadelcommerce.comhttp://www.mycitadel.com

Live Chat:

Live chat is available on the myCitadel Wallet web site at http://www.mycitadel.com

Citadel Commerce Merchant ServicesObtain support in any of the following ways:

Email:

[email protected]

Telephone:

9 A.M. to 5 P.M. PST, Monday to Friday: 604-299-6924

myCitadel Developer Guide Revised October 26, 2007

xviii Citadel Commerce Corp.

Citadel Commerce Corp. 1

System and Integration Overview [1]

This chapter provides an overview of the myCitadel Wallet system and its integration, including the following topics:• System Description• System Integration Process and Support• Merchant Accounts and Store Accounts• Web Payment Transaction Fees Structure and Payment Risk• Consumer Wallets• Integration Best Practices

System DescriptionmyCitadel Wallet is a secure online payment processing system that consumers use to make payments at the online stores of myCitadel Wallet merchants. When consumers create a myCitadel Wallet account, they can access their own encrypted online wallet to fund transactions at merchant sites, withdraw funds, and deposit funds into their wallet directly from their bank accounts.

Consumer FeaturesConsumers can use myCitadel Wallet to perform the following tasks:• Deposit money from their bank accounts into their myCitadel Wallet• Make a payment to a merchant that supports myCitadel Wallet from the merchant site• Receive a payment (Web Credit) from a merchant• Withdraw money from their myCitadel Wallet for deposit to their bank account (cash out)

Merchant FeaturesMerchants can use myCitadel Wallet to perform the following tasks:• Pay out a consumer instantly using Web Credits• Debit a myCitadel Wallet consumer account directly with permission from a consumer• Debit a consumer bank account directly with permission from a consumer

In order for merchants to use the myCitadel Wallet system to accept payments from a myCitadel Wallet consumer, merchants need to integrate their payment processing mechanism with the myCitadel Wallet system.

System Integration Process and SupportThe myCitadel Wallet integration process and support resources are designed to assist merchants and their development team to rapidly integrate and deploy the myCitadel Wallet interface on the merchant Web site with a minimum of work.


2 Citadel Commerce Corp.

The Merchant Services team at Citadel Commerce is available to help merchant development teams throughout the integration cycle by providing test platform access, development documentation (including this guide), and the assistance of experienced integration staff. For contact details, see Citadel Commerce Merchant Services on page xvii.

System Integration Process FlowThe myCitadel Wallet integration process involves the following steps:1. A Citadel Commerce Integration and Support Specialist collects the necessary technical

information from the merchant in order to create and set up the merchant wallet.

2. Citadel Commerce provides the merchant with a test account, together with the necessary documentation and connectivity parameters.

3. Citadel Commerce Merchant Services provides technical assistance to the merchant while the integration work is underway, and helps test the implementation once completed.

4. When the merchant is satisfied with the integration, the system undergoes a certification test to ensure that all aspects of the configuration are correct before the system is turned live.

5. Once the certification test has been completed, real transaction processing begins.

Merchant Accounts and Store AccountsThe merchant accounts side of the myCitadel Wallet platform is set up in a two-level hierarchy: • Merchant level (top level)• Store level (second level)

A myCitadel Wallet merchant will have a single merchant account with Citadel Commerce, but may have one or more store accounts under their merchant level. Citadel Commerce Merchant Services will initially create a single myCitadel Wallet merchant level account in addition to one or more store level access accounts, depending upon the needs of the merchant.

Citadel Commerce Merchant Services will set up the individual merchant stores, as requested, and assign a separate account ID, user ID, and password to each store. Store managers can use myCitadel Wallet to view transaction summaries and details, issue refunds for Web payments, and update their profile, depending on the permissions granted by the Merchant Administrative user, the top level role in the store hierarchy.

Web Payment Transaction Fees Structure and Payment RiskThe myCitadel Wallet system offers merchants different transaction fee arrangements based upon whether the merchant is carrying the risk for returned or disputed transactions, or whether Citadel Commerce is carrying the risk for these returns. Merchants need to consider which of the fee arrangements they wish to use as part of the system integration setup configuration.

This section reviews some of the risk management issues with respect to processing North American bank checks, and describes the transaction fee arrangements that are based upon the check acceptance risk model. The merchant needs to consider which fee arrangement to use as part of the system integration setup configuration.

Revised October 26, 2007 System and Integration Overview [1]


Check Acceptance Risk OverviewWhen a myCitadel Wallet consumer makes a deposit to his/her wallet using the North American Automated Clearing House (ACH) bank checking system, there is a delay of 8 days before the funds can be considered cleared. Between the time that the check is processed (presented for payment) and for 8 days after, the check can be returned by the bank it has been drawn upon for any number of valid reasons: non-existent bank account, insufficient funds, stop payment, etc.

After 8 days (but before 60 days), the check can still be returned, but only by the consumer swearing an affidavit to his/her bank revoking the transaction. This special post 8-day return case is called an R10 return, after the ACH system banking designation for such longer-term revoked transactions. Citadel Commerce assumes the risk for all R10 transactions, and has built the cost of these returns into the pricing model.

As a result of the ability for checks to be returned from the banking system, the myCitadel Wallet system differentiates consumer funds between uncleared and cleared: uncleared funds are those funds which are less than 8 days (and have not been yet returned), while cleared funds are those that have passed the 8-day mark.

Within the myCitadel Wallet system, merchants can choose to allow consumers to pay for services using the options described below:• Uncleared funds–if the merchant wants to accept the risk of 8-day returns; see Uncleared

Funds (includes Cleared Funds) Acceptance below.• Cleared funds–if the merchant wants to eliminate the risk of returns at the expense of

making the consumer wait 8 days for their funds to clear; see Cleared Funds Only Acceptance on page 4.

• Guaranteed funds–if the merchants wants to eliminate consumer dissatisfaction with waiting for 8 days for funds to clear, and remove the risk for accepting uncleared funds immediately; see Guaranteed Funds on page 4. For this option, the merchant can choose to have Citadel Commerce assume all the risk for returned checks, especially uncleared checks.

Citadel Commerce maintains a fee structure with different fees, depending upon the level of risk that Citadel Commerce is asked to assume.

Uncleared Funds (includes Cleared Funds) AcceptanceIf the merchant wants to accept the risk for accepting uncleared funds from a consumer (to allow the consumer immediate access to a service, for example) then the merchant wallet can be configured to allow the consumer to spend uncleared funds at the merchant site. If a consumer has cleared funds in the wallet, the myCitadel Wallet system ensures that these funds are used first, before any uncleared funds are used, in order to minimize the risk for the merchant.

The parameter setting that controls the acceptance of uncleared funds is at the merchant store level, and can be changed to one of the other two risk acceptance choices upon request to Citadel Commerce Merchant Services.

Citadel Commerce will only disburse funds (forward the money to the merchant) once the consumer check has cleared, and a percentage-based fee is charged on funds thus disbursed. Funds for checks which are returned by the bank within 8 days are not disbursed to the merchant unless collection attempts are successful.



Cleared Funds Only AcceptanceA merchant can request to accept cleared funds only, eliminating completely the risk of 8-day returns. Citadel Commerce charges a percentage-based fee on cleared funds disbursed to the merchant.

For cleared funds only, consumers are limited to spending only cleared funds at the merchant site, and will be unable to purchase services from the merchant immediately if they do not already have cleared funds available. Since it takes 8 days for a check to clear, this can result in a disappointed consumer, who may have an expectation of using the merchant services instantly. Merchants need to be aware of the impact to consumer satisfaction levels when they decide to accept cleared funds only.

Guaranteed FundsSubject to certain Citadel Commerce defined limits, merchants can receive funds from consumers which are guaranteed by Citadel Commerce against returns. In addition to the standard percentage fee for cleared and uncleared transactions, Citadel Commerce charges an additional percentage to cover the cost of 8-day returns. The guaranteed funds transaction arrangement is a very attractive way for merchants to provide consumers with instant funds for the purchase of services, while eliminating the risk of returns, and even more importantly, the costs associated with accounting and tracking uncleared funds disbursements.

Using the myCitadel Wallet, the guaranteed funds arrangement allows merchants to provide top-quality fund deposit services to their consumers, while maintaining fixed percentage costs for transaction and risk management.

Consumer WalletsThis section describes consumer wallets, including wallet limits and international wallet considerations.

Wallet LimitsIn order to limit the exposure to fraud and delinquent consumers, various velocity and other limits apply to consumer funds into and out of the wallet. It is useful for merchants to understand these limits as they apply to their consumers using the myCitadel Wallet.

For an up-to-date list of myCitadel Wallet limits, refer to the document MYC7.5-R1.0 myCitadel Wallet Deposit Limits, or the Web page https://www.mycitadel.com/fundLimitsInfo.jsp.

International Wallet ConsiderationsThe myCitadel Wallet system supports consumer wallets in several international languages and currencies, including UK, French, Spanish, German, Chinese, and Turkish. Consumer wallets from any country can purchase services from any myCitadel Wallet merchant using the base currency set up for a merchant store. The base currency would normally be set for U.S. dollars, and any consumer wallet making purchases from the merchant store with a base currency of U.S. dollars will automatically have their currency converted at the time of the transaction if their wallet funds are in a different currency.

Revised October 26, 2007 System and Integration Overview [1]


Merchants who want to receive funds in a different currency will need to set up additional stores with the base currency. There is normally not a need for a merchant to do this: a single store based in USD can be used by all consumer wallets regardless of the nationality or language, and this will provide automatic currency conversion services as well, making administration simple for the merchant.

Only consumer wallets are currently available in different languages. All myCitadel Wallet merchant wallets and administration screens are available in English only.

Within the myCitadel Wallet Web Credit system interface, merchants can choose to issue credits to consumer wallets in any of the supported currencies. The merchant can simply select the currency to use at the time of the credit, and the myCitadel Wallet system will perform the currency exchange automatically and debit the merchant store for the appropriate amount. There is no requirement for the merchant to have separate stores set up in order to use different currencies for Web Credits.

Integration Best PracticesThe myCitadel Wallet system development interfaces, especially the Web Payment Direct Interface, are powerful and simple. However, in order to use these basic interface mechanisms to provide a simple and robust payment mechanism at the merchant site, it is important for the merchant developer to ensure that a specific sequence flow is followed, and any exceptions handling (e.g. a bad consumer, a myCitadel Wallet password, etc.) are dealt with in such a way as to maintain a simple processing flow that does not confuse or alienate the consumer. The Citadel Commerce Merchant Services team is happy to work closely with the merchant's development team to advise on how to best integrate with the myCitadel Wallet platform, and can offer a huge amount of myCitadel Wallet integration expertise at no charge to the merchant.

Payment Sequence FlowThe merchant developer should follow the recommended approach closely for payment sequence flow, and remember to avoid any types of pop-up browser windows, keeping in mind that many consumers have pop-up blockers enabled, and some new browsers and updated browsers now have pop-up blockers installed and activated by default.

Reminder: Pay very close attention to the myCitadel Wallet recommended approach for payment screen sequence flow at the risk of alienating and losing consumers as a result of sub-optimal integration approaches.




myCitadel Wallet API [2]

This chapter provides an overview of the myCitadel Wallet API, including the following topics:• myCitadel Wallet Debit Options• myCitadel Wallet API Summary

myCitadel Wallet Debit OptionsmyCitadel Wallet is a Web-based wallet that provides users with an online mechanism for funding Web purchases. Consumers can fund their wallet in a number of ways, and merchants can offer consumers different methods for using those funds at the merchant site.

There are two main methods for providing consumers with payment access to their myCitadel Wallet accounts while they are at the merchant site executing a transaction:• The Web Payment Direct Interface method allows the merchant to directly debit the

consumer's myCitadel Wallet account without having the consumer leave the merchant site. The Web Payment Direct Interface is the integration method of choice, as the consumer never leaves the merchant site, resulting in a much cleaner financial transaction and consumer experience. For details on implementing this method, see Web Payment Direct Interface [3] on page 11.

• The Web Payment Redirect Interface method is a fallback method for merchants who, for various reasons, do not wish to implement the Web Payment Direct Interface. While operationally and esthetically inferior, the Web Payment Redirect method, is technically easier to implement. For details on implementing this method, see Web Payment Redirect Interface [4] on page 45.

A merchant can choose to implement one or the other method, depending upon development resource limitations.

Note: Citadel Commerce strongly recommends that merchants implement the Web Payment Direct Interface, wherever possible, in order to benefit from future enhancements to the myCitadel Wallet system.

Web Payment Direct InterfaceThe Web Payment Direct Interface allows a merchant to debit the account of any myCitadel Wallet account holder, who has already pre-authorized the merchant for such debits, without any further permission. A maximum currency amount can be set by the consumer for each merchant the consumer deals with, representing the total amount that the consumer will allow a given merchant to remove from his or her account. The consumer can also set the duration (date and time) for which the debit permission is granted. For example, a consumer can authorize a merchant to debit up to $200 until 5 P.M. tomorrow.

Note: If consumers use a security code, pre-authorization is not required.



In addition, the Web Payment Direct Interface provides the merchant with a real-time method to check to see if the debit permission authorization is already in place, and also provides a link that will allow the consumer to log in to their myCitadel Wallet account and set the authorization, if necessary, at the time the transaction is being executed. This authorization must be in place for the merchant to successfully execute a direct debit from the wallet.

Once the necessary authorization has been granted, the API provides a method for debiting the consumer's myCitadel Wallet account and completing the transaction. Using the myCitadel Wallet Web site, consumers can specify a bank account or credit card to be debited when their myCitadel Wallet does not contain sufficient funds to cover a Web payment transaction either via:• Web Payment Direct with Security Code; see Web Payment Direct Interface with Security

Codes on page 12• Web Payment Direct with Payment Permission; see Web Payment Direct Interface with

Payment Permissions on page 18

Web Payment Redirect InterfaceThe Web Payment Redirect Interface is a simple transaction method that allows the merchant to receive payments from a consumer by:• Redirecting the consumer to the www.mycitadel.com site via a prepared link• Allowing the consumer to complete the transaction at the myCitadel Wallet site and return• Checking via a status query with the myCitadel Wallet system to ensure that the transaction

completed successfully before allowing the consumer's transaction to proceed at the merchant site

myCitadel Wallet API SummaryThe myCitadel Wallet API includes the following components:

Web Payment Direct API A sophisticated HTTPS Post interface that allows a merchant to debit the consumer's account in real-time.

Web Payment Redirect API A basic myCitadel Wallet payment API that redirects the consumer to their myCitadel Wallet account at the www.mycitadel.com site, waits for the consumer to complete the transaction at the site and return to the merchant, and then allows the merchant to check myCitadel Wallet to ensure that the transaction completed successfully before proceeding.

User Registration API A simple link that merchants should provide on their sites to allow non-myCitadel Wallet consumers to register with myCitadel Wallet. This link simply takes the consumer to the www.mycitadel.com site in order for them to create an account.

Revised October 26, 2007 myCitadel Wallet API [2]


myCitadel Wallet Web Credit API

An HTTP POST API that allows a merchant to credit the account of a myCitadel Wallet consumer. The API automatically checks to ensure that the consumer has no uncleared funds owing to the merchant, and, if so, will make the transfer pending the clearance of the original funds.

myCitadel Wallet TransactionReport API

An HTTPS POST request in XML format that provides the merchant with access to various transaction reports.

Get Wallet Status API An HTTPS POST that allows the merchant to request infor-mation about a consumer’s myCitadel wallet.




Web Payment Direct Interface [3]

This chapter describes the Web Payment Direct Interface, including the following topics:• High-Level Description• Web Payment Direct Interface with Security Codes• Web Payment Direct Interface with Payment Permissions• Payment Permission Status Request• Payment Exception Handling Links• Direct Payment Debit Request• Direct Payment Debit Status Request

High-Level DescriptionThe Web Payment Direct interface allows a Web site consumer to pay the merchant for products or services with the consumer's myCitadel Wallet account. The Web Payment Direct Interface differs from the Web Payment Redirect Interface in that rather than redirecting the consumer to the myCitadel Wallet site to process the payment, the consumer's myCitadel Wallet account is debited directly via a system-to-system transaction.

Web Payment Direct Interface OptionsThe Web Payment Direct Interface provides two ways for consumers to make secure Web Payments:• Web Payment Direct with Security Code

Consumers set up a security code required to confirm their myCitadel Wallet Web payments when creating their myCitadel Wallet account, or they can add a security code any time afterwards; see Web Payment Direct Interface with Security Codes on page 12. Merchants prompt consumers for this security code as part of every payment they initiate. Merchants must provide Citadel Commerce with the correct customer security code, or the transaction will be rejected. Consumers can change their security code at will by accessing the relevant area of the mycitadel.com Web site.

• Web Payment Direct with Payment PermissionConsumers must provide a merchant with permission to debit their account, essentially pre-authorizing the merchant for up to a specified amount of money for a given amount of time; see Web Payment Direct Interface with Payment Permissions on page 18. Merchants implementing secure Web payments via payment permissions will also have to check for a consumer's payment pre-authorization. In the event the consumer has not yet authorized the merchant to automatically debit funds, a pop-up window is provided for consumers to log in to mycitadel.com and complete the required merchant authorization so



that the transaction can be completed. This extra functionality comes at the cost of a more complex merchant integration process. The interactive nature of payment permission configuration also makes this approach unsuitable for wireless solutions.

Note: Merchants can implement both security codes and payment permission. However, to provide consumers a consistent direct payment experience, Citadel Commerce recommends using a single method. The Web Payment Direct Security Code is the preferred approach, providing straightforward merchant integration (including wireless solutions) while maintaining a high level of security for both the consumer and merchant.

Web Payment Direct Interface with Security CodesThis section describes the Web Payment Direct Interface with Security Codes, including:• Transaction Flow, Screen Sequence, and Exception Handling• Recommended Payment Screens and Sequence

Transaction Flow, Screen Sequence, and Exception HandlingFigure 3-1 shows the relationship of the Web Payment Direct Interface components with security codes implemented.Figure 3-1 Web Payment Direct Transaction Flowchart (Security Codes)

Recommended Payment Screens and SequenceCitadel Commerce strongly recommends that the merchant development team closely follow the functionality and sequence of payment screens as follows:• Initial Payment• Exception #1–Wallet Does not Exist• Exception #2–Security Code is Incorrect• Exception #3–Insufficient Funds Available for the Transaction• Final Screen–Transaction Completion Success

Execute Direct Payment Debit

Request

Is security code correct?

Prompt user for correct security code

User enters wallet email address and

security code

Execute Payment Status Request To Verify Debit

Provide user with appropriate prompt and button (link) to

Wallet Logon Screen

Yes Yes Yes

No No

Done

Start

Does wallet exist?

Provide user with appropriate prompt and button (link) to New Account setup

No

Are funds available?

Revised October 26, 2007 Web Payment Direct Interface [3]


Initial PaymentThe Initial Payment screen for the myCitadel Wallet Direct Debit at the merchant cashier site should contain a field for entering the consumer wallet email address, a transaction amount field, and a security code field. Graphics and a high-level description of the myCitadel Wallet service, and any merchant policies surrounding the use of myCitadel Wallet can also be included on the Initial Payment screen.

Figure 3-2 shows the suggested layout for the Initial Payment screen.Figure 3-2 Initial Payment (Security Code)

Amount to Deposit

Deposit

Deposit using myCitadel - the online wallet from Citadel Commerce

New myCitadel Users: Register for a myCitadel

Wallet

To create a myCitadel Account, follow the steps below:1. Click the New myCitadel Users button below to go to www.mycitadel.com2. Click ‘New User Signup!’3. Complete the form provided and return to this screen.

Cancel

myCitadel Security Code

myCitadel Email Address



The Initial Payment screen should provide functionality as follows: • The New myCitadel Wallet Users: button should provide a link to the

www.mycitadel.com site if they do not currently have one.• The myCitadel Wallet email address field should be in the form of a valid email address

(e.g. [email protected] or [email protected]).• The amount field should be a currency amount, and would not normally contain alpha

characters.• The myCitadel Wallet security code field may contain alpha characters, although Citadel

Commerce recommends consumers use a numeric code to facilitate ease of entry on wireless devices.

• The Deposit button should lead to the execution of the Direct Payment Debit Request; see Direct Payment Debit Request on page 33.• If the proper security code is not provided, the "Security Code is Incorrect" error message

should be displayed as shown in Figure 3-4. • If there is no corresponding wallet, the "Wallet Does Not Exist" error message should be

displayed as shown in Figure 3-3. For details on invoking this request and interpreting the results, see Direct Payment Debit Status Request on page 41.

Note: A maximum of three failed attempts due to an invalid security code can be tried within a thirty (30) minute period before access to the wallet is locked out for 30 minutes.

• If there are no exceptions raised, i.e. the security code is correct and the corresponding wallet exists, the Direct Payment Debit Request attempts to complete the transaction. This is subject to funds being available, and will either succeed or fail with an "Insufficient Funds" exception.

• If there are insufficient funds, the error message shown in Figure 3-5 and its associated functionality should be invoked. If the transaction completes successfully, the Final Screen should be displayed as shown in Figure 3-6.

Exception #1–Wallet Does not ExistIf the Direct Payment Debit Request invoked from the Initial Payment screen returns a "No Account" error code, the developer should display the Wallet Does Not Exist screen.



Figure 3-3 shows the suggested layout for the Wallet Does not Exist screen.Figure 3-3 Exception #1–Wallet Does Not Exist (Security Code)

This screen allows the consumer to retry an incorrect myCitadel Wallet email address repeatedly, link to create a new account, or cancel/go back. Clicking Deposit should invoke the Direct Payment Debit Request (see Direct Payment Debit Status Request for a sample of this link), and attempt to complete the transaction which may display one of the first two exception screens (see Figure 3-3 and Figure 3-4) or raise an "Insufficient Funds" exception and display Exception #3 (see Figure 3-5).

Exception #2–Security Code is IncorrectIf the Direct Payment Debit Request invoked from the Initial Payment screen returns an "Incorrect Security Code" error code, the developer should display the Security Code is Incorrect screen.

[email protected]

200.00


Amount to Deposit

Deposit



Wallet

Sorry, that myCitadel Account ID appears to be invalid. Please check the Account ID and try again, or click New myCitadel Users (below) to create a new myCitadel account.

Cancel




Figure 3-4 shows the suggested layout for the Security Code is Incorrect screen.Figure 3-4 Exception #2–Security Code is Incorrect (Security Code)

Exception #3–Insufficient Funds Available for the TransactionIf the Direct Payment Debit Request transaction invoked from the Initial Payment screen returns an "Insufficient Funds" error code, the developer should display the Insufficient Funds Available for the Transaction screen.

Figure 3-5 shows the suggested layout for the Insufficient Funds Available for the Transaction screen.Figure 3-5 Exception #3–Insufficient Funds (Security Code)

[email protected]

200.00Amount to Deposit

Deposit


www.mycitadel.com

Sorry, that myCitadel Security Code appears to be invalid. Please check the Security Code and try again, or click www.mycitadel.com (below) to log in to your myCitadel wallet and check or change your Security Code.

Cancel



[email protected]

200.00

myCitadel Account ID

Amount to Deposit

Deposit


www.myCitadel.com

Sorry, that myCitadel Security Code appears to be invalid. Please check the Security Code and try again, or click www.myCitadel.com (below) to log in to your myCitadel wallet and check or change your Security Code.

Cancel


[email protected]


Deposit


www.mycitadel.com

Your myCitadel Account does not currently have sufficient funds to complete this transaction for this amount. Please try a different amount, or click www.mycitadel.com (below) to go to your wallet and add funds.

Cancel





This screen should allow consumers to either try a lower transaction amount (by changing the amount and clicking Deposit) or open a separate window to the myCitadel Wallet site to access their wallet normally, add funds, and return to this screen. When the consumer clicks the www.mycitadel.com button, this screen should change to the Initial Payment screen shown in Figure 3-2 (fully populated with the email address, amount, and security code) in order to clear the error text and allow the consumer to start the transaction again, presumably with available funds.

There are several other errors that may be returned by the Direct Payment Debit Request transaction. The merchant developer should handle these errors in a similar manner to those discussed previously.

Final Screen–Transaction Completion SuccessOnce the Direct Payment Debit Request transaction returns a "Success" code, the developer should display the Transaction Completion Success screen. Alternatively, some other action should be taken by the merchant site to inform the consumer that the transaction completed successfully.

Figure 3-6 shows the suggested layout for the Transaction Completion Screen.Figure 3-6 Transaction Completion Success (Security Code)


Your deposit of $200.00 from your myCitadel account was successful. We have credited your account accordingly.

Continue



Web Payment Direct Interface with Payment PermissionsUsing this approach to making secure Web payments, a consumer must provide a merchant with permission to debit their account, essentially pre-authorizing the merchant for up to a specified amount of money for a given amount of time. Managing the transaction flow properly is the key to successful myCitadel Wallet merchant integration when the Payment Permission method is used. Where the merchant implementation of this functionality is poorly handled, consumers report high levels of dissatisfaction with the merchant site and with the myCitadel Wallet payment method, which is in everyone's interest to avoid.

This section describes Web Payment Direct with Payment Permissions, including:• Transaction Flow, Screen Sequence, and Exception Handling• Recommended Payment Screens and Sequence

Transaction Flow, Screen Sequence, and Exception HandlingThe standard transaction flow for a typical myCitadel Wallet consumer transaction is fairly straightforward, however, the myCitadel Wallet system has some unique payment permissions functionality and other exception handling situations. This requires that the developer spend extra time on the transaction flow design in order to prevent the implementation of a technically correct, but functionally problematic transaction flow.

The Web Payment Direct Interface provides four components that support the flow of transactions with Payment Permissions:1. Collect wallet email address and deposit amount, and execute Payment Exception

Handling.

2. Execute Payment Permission Status Request.

3. Execute Direct Payment Debit Request.

4. Execute Payment Status Request to verify debit.

Figure 3-7 shows the relationship of the four Web Payment Direct components with payment permissions implemented.Figure 3-7 Web Payment Direct Transaction Flowchart (Payment Permissions)

Execute Get Payment Permission

Status Request

Are Permissions

Set OK?


Payment Permissions Screen

User enters wallet email address

Execute Payment Status Request To Verify Debit


Wallet Logon Screen

Yes Yes

No NoDone

Start

Does wallet exist?

Provide user with appropriate prompt and button (link) to New Account setup

No

Are funds available?

Execute Direct Payment Debit

RequestYes Yes

1

2 3 4



Recommended Payment Screens and SequenceCitadel Commerce strongly recommends that the merchant development team closely follow the payment screens functionality and sequence as follows:• Initial Payment• Exception #1–Wallet Does Not Exist• Exception #2–Payment Permissions are Not Set for Merchant• Exception #3–Insufficient Funds Available for the Transaction• Final Screen–Transaction Completion Success

Initial PaymentThe Initial Payment screen for the myCitadel Wallet Direct Debit at the merchant cashier site should contain a field for entering the consumer myCitadel Wallet email address and a transaction amount field. Graphics and a high-level description of the myCitadel Wallet service, and any merchant policies surrounding the use of myCitadel Wallet can also be included on the Initial Payment screen.

Figure 3-8 shows the suggested layout for the Initial Payment screen.Figure 3-8 Initial Payment (Payment Permission)

Amount to Deposit

Deposit



Wallet

To create a myCitadel Account, follow the steps below:1. Click the New myCitadel Users button below to go to www.mycitadel.com2. Click ‘New User Signup!’3. Complete the form provided and return to this screen.

Cancel




The Initial Payment screen should provide functionality as follows: • From this initial screen, the New myCitadel Wallet Users: button should provide a link to

the www.mycitadel.com site to allow consumers the opportunity to sign up for a myCitadel Wallet if they do not currently have one.

• The myCitadel Wallet email address field should be in the form of a valid email address (e.g. [email protected] or [email protected]).

• The amount field should be a currency amount, and would not normally contain any alpha characters.

• The Deposit button should invoke the Payment Permission Status Request, and display either the Wallet Does Not Exist screen or the Payment Permissions are Not Set for Merchants screen.There may be other responses, for example, if the payment permission has expired or the transaction amount is greater than the payment permission. See Payment Exception Handling Links for details on invoking this request and interpreting the results.

• If no exceptions are raised, i.e. the wallet exists, and permissions are set correctly, then the developer should invoke the Direct Payment Debit Request automatically after the Payment Permission Status Request completes without errors in order to attempt to complete the transaction. This is subject to funds being available, and will either succeed or fail with an "Insufficient Funds" exception.

• If there are insufficient funds, the screen and functionality of Exception #3 should be invoked as shown in Figure 3-11. If the transaction completed successfully, then the Final Screen should be displayed as shown in Figure 3-12.

Exception #1–Wallet Does Not ExistIf the Payment Permission Status Request invoked from the Initial Payment screen returns a "No Account" error code, the developer should display the Wallet Does Not Exist screen.

Figure 3-9 shows the suggested layout for the Wallet Does not Exist screen.Figure 3-9 Exception #1–Wallet Does Not Exist (Payment Permission)

This screen allows the consumer to retry an incorrect myCitadel Wallet email address repeatedly, link to create a new account, or cancel/go back. Clicking Deposit should invoke the Payment Permission Status Request (see New Account Setup Link–No Wallet Exceptions

Amount to Deposit

Deposit



Wallet

Cancel

200.00

Sorry, that myCitadel Account ID appears to be invalid. Please check the Account ID and try again, or press the New myCitadel Users button below to create a new myCitadel account.




on page 27 for a sample of this link) and display one of the first two exception screens, or execute the Direct Payment Debit Request to attempt to complete the transaction or raise an "Insufficient Funds" exception and display Exception #3 screen.

Exception #2–Payment Permissions are Not Set for MerchantThis exception is a very common one that the merchant development team will need to handle when payment permissions are implemented. Consumer accounts which do not have a payment permission for the merchant set up will raise this exception error. Figure 3-10 shows the suggested layout for the Payment Permissions are Not Set for Merchant screen that the developer should display for this exception.Figure 3-10 Exception #2–No Permissions (Payment Permission)

Clicking the Payment Permission Setup button should create and send a Payment Permission Link as defined in New Account Setup Link–No Wallet Exceptions on page 27.

Upon returning from the Payment Permission setup, the consumer should be returned to the Initial Payment screen, pre-populated with the email address and the amount to avoid having the consumer re-enter the amounts.

Exception #3–Insufficient Funds Available for the TransactionOnce the merchant development team has checked for a valid email address and the existence of payment permissions, they should execute the Direct Payment Debit Request transaction in order to attempt to complete the transaction. The common exception to this call is for insufficient funds.

Amount to Deposit


Cancel

200.00

[email protected]

Your myCitadel Account does not yet have any Payment Permissions set up to allow this transaction to complete. Please click the “Set up Payment Permissions” button below, complete your permissions, and return to this screen.

Payment Permission Setup




Figure 3-11 shows the suggested layout for the Insufficient Funds screen that the developer should display for this exception.Figure 3-11 Exception #3–Insufficient Funds (Payment Permission)

This screen allows the consumer to either try a lower transaction amount (by changing the amount and clicking Deposit) or open a separate window to the myCitadel Wallet site to access his/her wallet normally in order to add funds and return to this screen. This screen should change to the Initial Payment screen (fully populated with email address and amount) upon clicking the www.mycitadel.com button, in order to clear the error text and allow the consumer to start the transaction again, presumably with available funds this time.

There are several other errors that may be returned by the Direct Payment Debit Request transaction, and the merchant developer should handle these in a similar manner to those discussed previously.

Final Screen–Transaction Completion SuccessOnce the Direct Payment Debit Request transaction returns a "Success" code, the developer should display the Transaction Completion Screen. Alternatively, some other action should be taken by the merchant site to inform the consumer that the transaction completed successfully.

[email protected]



Your myCitadel Account does not currently have sufficient funds to complete this transaction for this amount. Please try a different amount or click on the myCitadel button to go to your wallet to add funds.

Cancel

Depositwww.myCitadel.com




Figure 3-12 shows the suggested layout for the Transaction Completion ScreenFigure 3-12 Transaction Completion Success (Payment Permission)


Your deposit of $200.00 from your myCitadel account was successful. We have credited your account accordingly.

Continue



Payment Permission Status RequestThis section describes the Payment Permission Status Request, including the following topics:• Overview• Payment Permission Status Request Fields• Payment Permission Status Request Sample• Payment Permission Status Request Response

OverviewThe Payment Permission Status Request is used to obtain the current status of a payment permission for a merchant and a myCitadel Wallet consumer. It can (and should) be used to determine, before a payment request attempt, whether the consumer has previously granted the merchant direct debit authorization sufficient to cover the transaction.

An HTTP POST command is assembled dynamically at the merchant site using the mandatory and optional fields listed in Table 3-1 (and shown in the sample code that follows), and sent over an SSL link to the myCitadel Wallet site: https://www.mycitadel.com/paymentPermissionStatus.do

Payment Permission Status Request FieldsTable 3-1 shows the mandatory and optional fields that may appear in the Payment Permission Status Request.

Table 3-1 Mandatory and Optional Fields (Payment Permission Status Request)

Field Name Selection Description

PID Mandatory The identification number of the Web Payment Service that was set up by the user, e.g. 129. The PID information is available from your myCitadel Wallet Integration and Support Specialist.

userId Mandatory An authorized merchant-user for this merchant wallet associated with the PID, e.g. store_manager.

userPassword Mandatory The password for the above merchant userId, e.g. mypassword.

email Mandatory The email address that uniquely identifies the consumer’s myCitadel Wallet account, e.g. john [email protected].

cur Mandatory The currency code (ISO-3 character code) for which the payment permission is defined. This should be set according to the currency code set for the merchant store involved with the transaction. Valid currency codes include: USD (U.S. $), CAD (Canadian $), EUR (Euro), GBP (Great Britain £), and CNY (Chinese Yuan). In most cases, this field is set to USD.



Payment Permission Status Request Sample The following link shows a sample request formatted for requesting a Payment Permission Status using the fields described in Table 3-1 below.https://www.mycitadel.com/paymentPermissionStatus.do?PID=129&userId=madeupusername&userPassword=madeup&[email protected]&cur=USD

Note: This sample is in the form of the Web browser URL, but would normally be sent as an HTTP POST over SSL to https://www.mycitadel.com/paymentPermissionStatus.do.

Payment Permission Status Request ResponseThe response to the Payment Permission Status Request is an XML document that will contain the current status of the payment permission. The response will have a root paymentPermission element that contains the attributes described in Table 3-2.

Table 3-2 paymentPermission Element Attributes

Attribute Description

PID The same PID passed in to the request.

email The same email address passed in to the request.

amt The total remaining amount for the payment permission.

cur The currency of the amt field.

count The total number of remaining payments for the payment permission.

expiry The date on which the payment permission expires (U.S. Pacific time zone).

status The status of the payment permission.



Table 3-3 describes status values for the Payment Permission Status Request..

Payment Permission Status Request Response SamplesThis section includes the following samples that show responses as a result of a Payment Permission Status Request:• General Failure• Existing Payment Permission

General Failure

Code Sample 3-1 shows the XML code for a general failure.

Table 3-3 Status Values (Payment Permission Status Request)

Status Value Description

OK Valid (but not necessarily sufficient) payment permission data has been returned.

Fail An unknown error has occurred.

NO_WALLET No wallet corresponds to the supplied email address, therefore, the wallet is invalid.

NO_PERMISSION The consumer has not previously provided payment permission. The consumer should be directed via the myCitadel Wallet Payment Permission page link.

INVALID_LOGIN The login details provided are invalid.

MISSING_LOGIN_DATA Some of the login details have not been provided.

INVALID_PID The PID provided does not exist or is not enabled.

INVALID_WALLET No wallet corresponds to the supplied email address, or the wallet is in an invalid state.

Code Sample 3-1 General Failure<?xml version="1.0" encoding="UTF-8"?><paymentPermission> <pid>129</pid> <email>[email protected]</email> <amt>0.00</amt> <cur>USD</cur> <count>0</count> <expiry /> <status>FAIL</status></paymentPermission>



Existing Payment Permission

Code Sample 3-2 shows the XML code for an existing payment permission.

Payment Exception Handling LinksWhen the merchant requires the consumer to take further action to complete a successful wallet transaction, an appropriate prompt should be provided on their page, with a button which will invoke one of the following links in order to resolve the current exception:• New Account Setup Link–No Wallet Exceptions• Existing Wallet Login Link–No Funds Available Exceptions• Payment Permission Configuration Link–No Permissions Exceptions

The link should invoke a separate window so that the consumer can return to the existing merchant window. Additionally, the merchant should update the page at the time of the button press in order to have the page refreshed with new prompting and ready for the return of the consumer from the link to which they were sent.

Reminder: Do not use pop-up windows, as the prevalence of pop-up blockers on consumer browsers will render the interface unusable. Only a window which appears as the result of a consumer clicking on a link will be an effective and reliable method for handling exceptions.

New Account Setup Link–No Wallet ExceptionsWhen a consumer provides a wallet email address that returns INVALID_WALLET, consumers should be advised that no such wallet exists and prompted to either re-enter the wallet email address to try again, or be directed to the link https://www.mycitadel.com so that they can create a new wallet.

Alternatively, the merchant can provide a direct link to the myCitadel Wallet signup screen to enable consumers to register with myCitadel Wallet via the merchant's Web site.

Code Sample 3-2 Existing Payment Permission<?xml version="1.0" encoding="UTF-8"?><paymentPermission> <pid>129</pid> <email>[email protected]</email> <amt>300.00</amt> <cur>USD</cur> <count>1</count> <expiry>2004-09-01 00:00:00</expiry> <status>OK</status></paymentPermission>



Code Sample 3-3 shows sample HTML code that can be used by the merchant to create a direct link.

Existing Wallet Login Link–No Funds Available ExceptionsWhen the consumer has permissions set, but there are insufficient funds in the account to handle the transaction, the merchant should advise the consumer that there are insufficient funds, provide the link https://www.mycitadel.com, and suggest that the consumer log in and arrange to have funds moved into their wallet.

Payment Permission Configuration Link–No Permissions ExceptionsWhen a consumer does not have valid permissions set for a merchant, he/she needs to be directed via a button (link) on the merchant site to the Payment Permissions page. The merchant can create a link that will pre-populate the permissions page with the necessary information for the consumer to quickly return to the merchant site after granting the necessary payment permissions.

This section describes the requirements for creating this link, including:• Payment Permission Configuration Link Sample• Payment Permission Configuration Link Fields• Access to the Payment Permission Page

Code Sample 3-3 Direct Link to myCitadel Wallet Signup<center><b>Open a myCitadel account!</b><br><br><a href="https://www.mycitadel.com/signupNew.jsp?content=signupNewChoice" target=_blank><img border=0 src="https://www.mycitadel.com/skins/myCitadel/images/signup.gif" alt="Open a myCitadel account!"></a>

</center>



Payment Permission Configuration Link SampleThe Payment Permission page is an existing myCitadel Wallet page that can be called by the merchant to allow consumers to correctly set payment permissions for their transaction, if necessary.Figure 3-13 Payment Permission (Typical)

The following link shows pre-populated fields for the Payment Permission page so that the consumer can enter the password, click Confirm, close the page, and continue at the merchant site without further action:<A HREF="https://www.mycitadel.com/configurePaymentPermission.do?PID=129&amt=$400.00&cur=USD&[email protected]" target="_blank">Give us permission please!</A>



Payment Permission Configuration Link FieldsTable 3-4 describes the mandatory and optional fields that may appear in this link to the Payment Permission page.

Access to the Payment Permission PageCitadel Commerce recommends that the merchant use a new Web browser window to provide access to the Payment Permission page, as consumers can then close the window and continue at the merchant site where they left off. This requires that the merchant refresh and update their screen when the consumer opens the new window, so that the merchant site screen is ready for the consumer's return.

Table 3-4 Mandatory and Optional Fields (Payment Permission Configuration Link)


PID Mandatory The identification number of the Web Payment Service that was set up by the consumer. The PID information is available on the Web Pay-ment Configuration Summary form, e.g. 129.

email Mandatory The email address that uniquely identifies the consumer's myCitadel Wallet account,e.g. john [email protected].

amt Mandatory The amount of the payment permission. If accepted by the user for "one-time" permission, this will be the new total remaining amount for this consumer, e.g. 25.00.

cur Mandatory The currency of the payment permission. Valid currency codes include: USD (U.S. $), CAD (Canadian $), EUR (Euro), GBP (Great Britain £), and CNY (Chinese Yuan). In most cases, this is set to USD.



Code Sample 3-4 shows a sample of JavaScript code that opens a new browser window.

In this sample, the page has a button called giveUsPermission, which calls giveUsPermission_onclick() when clicked.

Once the function is called, a new browser window will be open. This is the action where the consumer can select the access level to his/her wallet. Additionally, the variable focusInEnabled is true. This will be important in the next step.

As soon as the new window opens, this one will lose focus. When the new window closes, this one receives the focus back, which will trigger the onfocusin event that will be executed because focusInEnabled is true. This will resubmit the current form which, by default, tries to withdraw money from the consumer’s wallet. To modify this behavior, modify the lines in the onfocusin event. The focusInEnabled variable must also be set as false before submitting the form.

This variable is used to avoid resubmission every time the window gets focus, as we desire this execution only if the consumer started the process of giving the merchants permission to access the consumer’s wallet.

Code Sample 3-4 Opening a New Browser Window<SCRIPT ID=clientEventHandlersJS LANGUAGE=javascript></SCRIPT> <SCRIPT LANGUAGE=javascript FOR=document EVENT=onfocusin></SCRIPT>



This solution works on Internet Explorer, version 6 or later. For FireFox, Netscape, and older versions of Internet Explorer, a workaround shown in Code Sample 3-5 can be achieved by linking the refresh of the page to the onfocus event of the Submit button.Code Sample 3-5 Linking Refresh to Event Onfocus<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML><HEAD><META http-equiv=Content-Type content="text/html; charset=unicode"><SCRIPT ID=clientEventHandlersJS LANGUAGE=javascript></SCRIPT></HEAD><BODY><form name=form1 LANGUAGE=javascript>Email address: <INPUT><BR>Amount: <INPUT><BR><INPUT type="button" value="Give Us Permission to your wallet" id=button1 name=button1 LANGUAGE=javascript onfocus="return button1_onfocus()" onclick="return button1_onclick()"> </FORM></BODY></HTML>



Direct Payment Debit RequestThe Direct Payment Debit Request requires that an HTTP POST string be dynamically composed, contain the mandatory and optional data elements described in Direct Payment Debit Request Fields on page 34, and be submitted to https://www.mycitadel.com/payNow.do.

This section includes the following topics:• Direct Payment Debit Request Fields• Direct Payment Debit Request Form Sample• Direct Payment Debit Request Response• Direct Payment Debit Request Response Sample



Direct Payment Debit Request FieldsTable 3-5 describes the mandatory and optional fields that may appear in the link to the Direct Payment Debit Request.

Note: While it is not strictly necessary, it is recommended that merchants force consumers to use the same email address for their merchant account as they used for their myCitadel Wallet account. This helps to reduce administration and support issues.

Table 3-5 Mandatory and Optional Fields (Direct Payment Debit Request)

Field Name Selection Desciption

PID Mandatory The identification number of the Web Payment Service that was set up by the consumer. The PID information is available on the Web Payment Configuration Summary form. The PID parameter is the digit + "-" + number combination. For example, 3-129 identifies the following:• 3-Payment method (3- for Web Payment Direct)• 129-Payment configuration ID of the store accepting the

payment

amt Mandatory The amount of the transaction, e.g. 1.00.

cur Mandatory The currency of the transaction. Valid currency codes include: USD (U.S. $), CAD (Canadian $), EUR (Euro), GBP (Great Britain £), and CNY (Chinese Yuan). In most cases, this is set for USD.

userId Mandatory An authorized store-user for this store wallet associated with the PID, e.g. madeupusername.

userPassword Mandatory The password for the above store-userId, e.g. mypassword.

email Mandatory The email address that uniquely identifies the consumer's myCitadel Wallet account, e.g. john [email protected].

desc Mandatory The description of the purchase, e.g. 1 month Membership.

ship Optional The shipping fees for the purchase, e.g. 0.00.

tax Optional The tax for the purchase, e.g. 0.00.

mref Mandatory The unique merchant's reference number of the payment, e.g. 12345678.

securityCode Optional(if Web Payment permission is not set)

The consumer’s myCitadel Wallet security code. This must be provided by the consumer for every transaction, e.g. 1234.



Direct Payment Debit Request Form SampleCode Sample 3-6 shows a sample link for a typical Direct Payment Debit Request Form.Code Sample 3-6 Sample Link for Direct Payment Debit Request Form<html><head><title>webPaymentDirectReqTest</title></head>

<OBJECT id="snare" classid="clsid:7A0D1738-10EA-47FF-92BE-4E137B5BE1A4" DESIGNTIMEDRAGDROP="17"codebase="http://sharepoint/Development%20Docs/Snare/Deliverables/v%202.00/StmOCX.cab">

</OBJECT>

<body bgcolor="#ffffff"><form action="https://www.mycitadel.com/payNow.do" method="POST" name="payment"> <input type="hidden" name="PID" value="3-1951"/> <input type="hidden" name="email" value="[email protected]"/> <input type="hidden" name="userId" value="Store_manager"/> <input type="hidden" name="userPassword" value="start123!"/> <input type="hidden" name="amt" value="1.00" /> <input type="hidden" name="cur" value="USD"/> <input type="hidden" name="desc" value="birthday gift"/> <input type="text" name="mref" value="20050906-01"/> <input type="hidden" name="ship" value="0.00"/> <input type="hidden" name="tax" value="0.00"/> <input type="hidden" name="securityCode" value="1234" />

<input type="submit" name="submit" value="submit" /></form></body></html>



Direct Payment Debit Request ResponseThe response to the Direct Payment Debit Request is an XML document that will contain the current status of the Web Payment. This response follows the same general reporting request response format as used elsewhere in the myCitadel Wallet platform.

The response will have a root WEBPAYMENT element that contains the elements described in Table 3-6.

Note: To address changing business requirements, Citadel Commerce may periodically add attributes to the Direct Payment Debit Response without providing merchants with advance notice. Therefore, merchant implementation of this response must support the potential addition of parameters to those shown in Table 3-6.

Table 3-6 WEBPAYMENT Element Attributes (Direct Payment Debit Request Response)


journalNumber The myCitadel Wallet journal number for this Web Payment.

paymentReference The myCitadel Wallet payment reference number for this Web Payment.

merchantReference The merchant's reference number supplied by the merchant for this Web Payment.

status The current status for this Web Payment, either CREATED, COMPLETE or CANCELLED or one of the following:CANCELLED combined with the description Login data invalid, missing or incorrect: The email address or Wallet does not exist.DUPLICATE: The merchant reference (mref) supplied is a duplicate of a pre-vious transaction.NO_PERMISSION: There is no valid payment permission for this merchant and this consumer.INVALID_SECURITY_CODE: The security code contained in the request does not match the security code stored for the consumer. NSF: The consumer has insufficient funds to cover this payment.EXCEEDS_LIMIT: The merchant's Web Payment limit has been exceeded.EXCEEDS_GUARANTEED_LIMIT: The merchant’s guaranteed limit exceeds the total amount that myCitadel Wallet will guarantee for the wallet attempting the Web Payment. The availableAmount indicates the maximum amount of a transaction that can be performed.INVALID_AMOUNT: The fee associated with the transaction is higher than the transaction amount.REQUIRED_PAYMENT_METHOD_NOT_AVAILABLE: There are no funds to cover the transaction, and permission has not been granted to directly debit the consumer's bank account. The merchant should request access to the con-sumer's bank account if the consumer has an account stored, or ask that the consumer set up a bank account via the consumer Web site (https://www.mycitadel.com). This is done via the Personal Information page, using the Financial Institution Information option (in the Other Information section). It is most likely that U.S. consumers will already have at least one saved account.

fundsStatus The current status for funds used in the Web Payment, either UNCLEARED, PENDING, CLEARED, or RECALLED.



Direct Payment Debit Request Reponse – Error MessagesTable 3-7 lists the error_number, status, and description values that can appear in a Direct Payment Debit Request Reponse.

paymentMethod The payment method that was used for this Web Payment.

currency The currency code for the Web Payment.

amount The amount of the Web Payment.

feeAmount The Web Payment fee (optional–only for guaranteed payments).

taxAmount The tax amount of the Web Payment.

shippingAmount The shipping amount of the Web Payment.

totalAmount The tax amount of the Web Payment.

date The date of the Web Payment.

description The Web Payment description.Login data invalid, missing or incorrect combined with the status CANCELLED: The email address or Wallet does not exist.

noteToSeller The Web Payment note to seller.

shippingInfo The Web Payment shipping information, as supplied by the consumer.

availableAmount The maximum transaction amount that will keep the transaction below the limit exceeded.

wasGuaranteed Indicates a Guaranteed Web Payment.

Set to "true" if the following three conditions are met:• consumer does not have sufficient funds in wallet.• consumer has set a preferred payment method to use a bank account.• merchant is in the Guaranteed program.

Set to "false" if the Web Payment was performed using cleared funds. That is, consumer wallet has sufficient funds.

error_number Error number (optional) – for more information, see Table 3-7, Error Mes-sages – Direct Payment Debit Request Response.

Table 3-7 Error Messages – Direct Payment Debit Request Response

Error Number Status Description

0 COMPLETED <No errors encountered during process-ing>.

Table 3-6 WEBPAYMENT Element Attributes (Direct Payment Debit Request Response)




1 CANCELLED An unexpected processing error occured. Please try again.

101 CANCELLED Merchant Login data invalid, missing, or incorrect.

112 CANCELLED Invalid payer identiification.

113 BLOCKED_JURISDICTION We have determined that you are cur-rently located in, or are a resident of, a jurisdiction that has been blocked by this merchant. We are unable to complete this transaction.

114 CANCELLED Due to repeated myCitadel Security Code failures, customer [customer] is blocked from direct Web Payment using security code for the next [#] minutes.

115 CANCELLED Your wallet has been temporarily dis-abled. Please contact [email protected].

116 INVALID_SECURITY_CODE The provided myCitadel Security Code doesn't match the customer's record. Please verify it and try again or contact [email protected].

117 CANCELLED Wallet does not exist. (Invalid email address/security code combination).

118 NO_PERMISSION No permission for payment.

119 CANCELLED The buyer and seller must have different Wallet accounts.

120 CANCELLED The seller is not accepting buyer-initiated payments. Please contact the seller for more information.

121 CANCELLED Payment Permission Status failed.

223 CANCELLED Multiple concurrent Web Payment trans-actions requested. Please try again.

231 CANCELLED [currency] is not an accepted currency for this seller. Please contact the seller for more information.

249 CANCELLED The required [amount] parameter is missing or invalid.





253 CANCELLED The request is missing a required parame-ter.

255 CANCELLED Merchant did not specify a merchant ref-erence number; merchant specified an invalid amount.

500 NSF Security Code was not used and no Pay-ment Permission is set for this Merchant; you do not have enough funds in your Wallet to perform this payment.

501 NSF You do not have enough funds in your Wallet to perform this payment.

502 NSF Insufficient funds to cover[##.## <currency>].

503 NSF The entered amount [##.## <cur-rency>] is less than the minimum cheque deposit amount [##.## <currency>]; you do not have enough funds in your Wallet to perform this payment.

504 NSF The entered amount [##.## <cur-rency>]is less than the minimum credit card deposit amount [##.## <cur-rency>]; you do not have enough funds in your Wallet to perform this payment.

505 NSF myCitadel Express Pay is set up to Credit Card, but the merchant does not accept Credit Card for Web Payments; you do not have enough funds in your Wallet to perform this payment.

506 NSF Non-sufficient Cleared Funds, and myCi-tadel Express Pay was not set up; you do not have enough funds in your Wallet to perform this payment.

507 NSF Non-sufficient Cleared Funds. myCita-del Express Pay specifies a bank account which uses UNCLEARED funds only; you do not have enough funds in your Wallet to perform this payment.





Direct Payment Debit Request Response SampleCode Sample 3-7 shows a sample response for a Direct Payment Debit Request.

508 NSF Non-sufficient Cleared Funds. Payment Permission specifies a bank account which uses UNCLEARED funds only; you do not have enough funds in your Wallet to perform this payment.

509 CANCELLED PREAUTHORIZE transaction DECLINED (reference #46549763). Please contact [email protected], quoting the reference number.

510 EXCEEDS_GUARANTEED_LIMIT Exceeds maximum amount of uncleared guaranteed funds used by this Wallet. Amount Remaining = [##.## <cur-rency>].

511 EXCEEDS_LIMIT Transaction not allowed - exceeds your maximum daily transfer amount. Amount Remaining = [##.## <currency>].

Code Sample 3-7 Direct Payment Debit Request Response<?xml version="1.0" encoding="UTF-8"?> <webPayment> <journalNumber>2992</journalNumber> <paymentReference>129-164</paymentReference> <merchantReference>12345678</merchantReference> <status>COMPLETE</status> <fundsStatus>CLEAR</fundsStatus> <paymentMethod>CASH</paymentMethod> <currency>USD</currency> <amount>5.00</amount> <feeAmount>0.08</feeAmount> <taxAmount>0.00</taxAmount> <shippingAmount>0.00</shippingAmount> <totalAmount>5.00</totalAmount> <date>2004-04-02 11:01:02</date> <description>1 Month Membership</description> <noteToSeller>This is a note from the consumer to the merchant</noteToSeller> <shippingInfo>Bob Smith, 1234 Main Street, Anytown NY, 12345</shippingInfo>

<wasGuaranteed>false</wasGuaranteed></webPayment>





Direct Payment Debit Status RequestThe myCitadel Wallet system provides the merchant with the ability to format and send separate transaction status requests. The report requests are HTTPS POSTS in XML format.

Note: As the response to the actual Direct Payment Debit Request is secure and contains the same information as the status report, it is usually unnecessary to use this report with the Web Payment Direct Interface.

This section describes the interface for this functionality, including the following topics:• Request Fields for Transaction Status Request• Transaction Status Request Sample• Sending the Report Request• Web Payment Direct Status Report Response• Web Payment Debit Status Report Response Sample

Request Fields for Transaction Status RequestTable 3-8 describes the required fields which are in the XML document as separate elements, under the reportRequest root element.

Table 3-8 Transaction Status Request Fields

Field Name Description

reportType The type of report (this must to be set to WebPaymentStatus).

walletId The merchant's wallet ID, e.g. IS12345678.

userId The authorized merchant user ID to this wallet ID, e.g. store_manager.

userPassword The merchant's wallet password, e.g. mypass.

merchantReference The merchant reference number for the Web Payment, e.g. 12345678.



Transaction Status Request SampleCode Sample 3-8 shows a sample of the Transaction Status Request.

Sending the Report RequestThe request is sent to myCitadel Wallet using an HTTPS POST to the following URL:https://www.myCitadel.com/merchantReport.do

The XML text of the request must be in an HTTP POST parameter called xml.

Web Payment Direct Status Report ResponseThe response to the request is an XML document that will contain the current status of the Web Payment Redirect transaction. The response will have a root REPORT element that contains the following attributes.

Table 3-9 describes the REPORT element attributes.

Code Sample 3-8 Transaction Status Request Sample<?xml version="1.0" encoding="UTF-8"?><reportRequest> <reportType>WebPaymentStatus</reportType> <walletId>IS12345678</walletId> <userId>store_manager</userId> <userPassword>mypass</userPassword> <merchantReference>12345678</merchantReference></reportRequest>

Table 3-9 REPORT Element Attributes (Web Payment Direct Status Report Response)


TYPE The type of report (this must be set to WEBPAYMENTSTATUS).

WALLETID The wallet ID of the report (this will be the same wallet ID as specified in the request).

DATE The date of the report.



Under the REPORT element, there will be one WEBPAYMENT element. The WEBPAYMENT element contains the sub-elements described in Table 3-10.

Table 3-10 WEBPAYMENT Sub-element Attributes (Web Payment Direct Status Report Response)


JOURNALNUMBER The myCitadel Wallet journal number for this Web Payment.

PAYMENTREFERENCE The myCitadel Wallet payment reference number for this Web Payment.

MERCHANTREFERENCE The merchant's reference number supplied by the merchant for this Web Payment.

STATUS The current status for this Web Payment, either CREATED, COMPLETE, or CANCELLED.

FUNDSSTATUS The current status for funds used in the Web Payment, either UNCLEARED, PENDING, CLEARED, or RECALLED.

PAYMENTMETHOD The payment method that was used for this Web Payment.

CURRENCY The currency code for the Web Payment.

AMOUNT The amount of the Web Payment.

TAXAMOUNT The tax amount of the Web Payment.

SHIPPINGAMOUNT The shipping amount of the Web Payment.

TOTALAMOUNT The total amount of the Web Payment.

DATE The date of the Web Payment.

DESCRIPTION The Web Payment description.

NOTETOSELLER The Web Payment note to seller.

SHIPPINGINFO The Web Payment shipping information, as supplied by the consumer.

FEEAMOUNT The Web Payment fee (optional–only for guaranteed payments).



Web Payment Debit Status Report Response SampleCode Sample 3-9 shows a sample of a Web Payment Debit Status Report Response.Code Sample 3-9 Web Payment Debit Status Report<?xml version="1.0" encoding="UTF-8"?><REPORT TYPE="WEBPAYMENTSTATUS" WALLETID="IS12345678" DATE="2004-04-02 13:06:42"> <WEBPAYMENT> <JOURNALNUMBER>2992</JOURNALNUMBER> <PAYMENTREFERENCE>129-164</PAYMENTREFERENCE> <MERCHANTREFERENCE>12345678</MERCHANTREFERENCE> <STATUS>COMPLETE</STATUS> <FUNDSSTATUS>CLEAR</FUNDSSTATUS> <PAYMENTMETHOD>CASH</PAYMENTMETHOD> <CURRENCY>USD</CURRENCY> <AMOUNT>5.00</AMOUNT> <TAXAMOUNT>0.00</TAXAMOUNT>

<FEEAMOUNT>0.08</FEEAMOUNT> <SHIPPINGAMOUNT>0.00</SHIPPINGAMOUNT>

<TOTALAMOUNT>5.00</TOTALAMOUNT> <DATE>2004-04-02 11:01:02</DATE> <DESCRIPTION>1 Month Membership</DESCRIPTION> <NOTETOSELLER>This is a note from the consumer to the merchant</NOTETOSELLER> <SHIPPINGINFO>Bob Smith, 1234 Main Street, Anytown NY, 12345</SHIPPINGINFO> </WEBPAYMENT></REPORT>


Web Payment Redirect Interface [4]

This chapter provides an overview of the myCitadel Wallet Web Payment Redirect Interface. It includes the following topics:• High-Level Description• Technical Description• Creating the Payment Button Using HTML• Web Payment Redirect Status Report

High-Level DescriptionThe Web Payment Redirect API allows a Web site consumer to pay the merchant for products or services, but requires that the consumer be redirected from the merchant site to the myCitadel Wallet site, and then redirected back to the merchant site once the transaction is complete.

The setup for this method of payment interface requires that the merchant's programmer create a Payment Button link to the www.mycitadel.com site. This link needs to include all of the necessary transaction information, including the return link to the page that the merchant wants the consumer to return to. Following the return to the merchant site, the merchant then invokes a Web Payment Status Report to determine if the transaction completed successfully before allowing the consumer to continue.

Technical DescriptionTypically, merchant programmers will set up their site so that in order to initiate a payment, the consumer will click on a myCitadel Wallet Pay Online Payment button or other link on the merchant's Web site, which will then direct the consumer to the www.mycitadel.com site using a specially formatted (by the merchant's developer) HTML link. Consumers will then log into the myCitadel Wallet system with their login and password, or create a new myCitadel Wallet account if they are not already members.

Once the consumer is logged in, they will be directed to a Web Payment page, which will show the consumer the details of the payment they are about to make, based on the information passed by the merchant site within the redirect HTML link. After consumers are satisfied with the details, they will submit the payment.

If the Web Payment is successful, then the consumer will be redirected back to the merchant's Web site specified by the next URL that the merchant supplied within the redirect link (one of the various HTML link parameters described below).

The merchant can then proceed to verify independently with myCitadel Wallet that the transaction completed successfully, and subsequently complete the transaction with the user.



Creating the Payment Button Using HTMLThe merchant's developer needs to create the HTML redirect link by hand, using:• Mandatory and optional redirect link fields; see Table 4-1 below• Sample links as a template; see Web Payment Redirect Transaction Link Sample on page 47

and Web Payment Redirect Link Sample on page 47

Redirect Link FieldsTable 4-1 describes the fields that create the HTML redirect link.

Table 4-1 Mandatory and Optional Fields (Redirect Link Fields )


Select Logo Size Mandatory The size of the myCitadel Wallet Pay Online logo. The merchant can select one of the following image sizes:• Small (88 x 33 pixels)• Medium (150 x 47 pixels)• Large (200 x 63 pixels)

Logo Caption Optional The text that will appear above the myCitadel Wallet Pay Online logo.

PID Mandatory The identification number of the Web Payment Service that was set up by the merchant. The PID information is available on the Web Payment Configuration Summary form. The PID parameter is the first digit/dash combination (n-) and is 2- for Web Payment Redirect, e.g. 2-129.

amt Mandatory The amount of the transaction, e.g. 1.00.

cur Mandatory The currency of the transaction. Valid currency codes include: USD (U.S. $), CAD (Canadian $), EUR (Euro), GBP (Great Britain £), and CNY (Chinese Yuan). In most cases, this is set for USD.

desc Mandatory The description of the purchase, e.g. 1 Month Membership.

ship Optional The shipping fees for the purchase, e.g. 0.00.

tax Optional The tax for the purchase, e.g 0.00.

next Mandatory The URL of the merchant Web site page to which the consumer should be directed after the payment is completed. This URL can also be dynamically created to include information specific to the user’s purchase.Also, the original request parameters, apart from the “next” parameter, are appended to this URL when the user is redirected.If the field is omitted, the consumer will not be redirected after the purchase is complete, e.g. https://www.merchantweb.compurchase_completed.asp

mref Mandatory The merchant’s reference number of the payment, e.g. 12345678.

Revised October 26, 2007 Web Payment Redirect Interface [4]


Web Payment Redirect Transaction Link SampleCode Sample 4-1 shows the HTML code to create a Web Payment Redirect Transaction link.

Web Payment Redirect Link SampleCode Sample 4-2 shows the HTML code to create a link on the merchant Web site to the myCitadel Wallet Web Payment Redirect Interface.

Figure 4-1 shows how the link to Web Payment Redirect Interface appears on the Web page.Figure 4-1 Link to myCitadel Wallet Web Payment Redirect Interface

Code Sample 4-1 Web Payment Redirect Transaction Linkhttps://www.mycitadel.com/payNow.do?PID=2-129&amt=1.00&cur=USD&desc=1%20Month%20Membership.&ship=0.00&tax=0.00&next=https://www.merchantweb.com/purchasecomplete.asp&mref=12345678

https://www.mycitadel.com/payNow.do?PID=2-129&cur=USD&desc=Donation%20of%20any%20Amount&ship=0.00&tax=0.00&mref=12345678

Code Sample 4-2 Merchant Link to Web Payment Redirect Interfacecenter><b>Pay by myCitadel!</b><br><br><a href="https://www.mycitadel.com/payNow.do?PID=2-129&amt=1.00&cur=USD&desc=1 Month Membership&ship=0.00&tax=0.00&mref=12345678&next=https://www.merchantweb.com/purchase_completed.asp" target=_blank><img border="0"src=https://www.mycitadel.com/skins/myCitadel/images/logo_s.gifalt="Pay by myCitadel!"></a></center>



Web Payment Redirect Status ReportThis section describes the Web Payment Redirect Status Report, including:• Overview• Web Payment Redirect Status Report Request Fields• Web Payment Redirect Status Report Request Sample• Sending the Web Payment Redirect Status Report Request• Web Payment Redirect Status Report Response• Web Payment Redirect Status Report Request Sample

OverviewAfter consumers complete the payment and are redirected back to the merchant site, the merchant must verify with myCitadel Wallet that the payment was processed properly. This is achieved by using the Web Payment Redirect Status Report. The report request is an HTTPS POST in XML format.

Web Payment Redirect Status Report Request FieldsTable 4-2 describes the required fields of the Web Payment Redirect Status Report Request. These fields are in the XML document as separate elements under the ReportRequest element.

Web Payment Redirect Status Report Request SampleCode Sample 4-3 shows a sample of the Redirect Payment Status Report Request.

Table 4-2 Web Payment Redirect Status Report Request Fields

Field Name Description

reportType The type of the report (this must be set to WEBPAYMENTSTATUS).

walletId The merchant's wallet ID, e.g. IS12345678.

userId The authorized merchant ID to this wallet ID, e.g. store_manager.

userPassword The merchant’s wallet password, e.g. mypass.

merchantReference The merchant reference number for the Web Payment, e.g. 12345678.

Code Sample 4-3 Redirect Payment Status Report Request<?xml version="1.0" encoding="UTF-8"?><reportRequest> <reportType>WebPaymentStatus</reportType> <walletId>IS12345678</walletId> <userId>store_manager</userId> <userPassword>mypass</userPassword> <merchantReference>12345678</merchantReference></reportRequest>



Sending the Web Payment Redirect Status Report RequestThe request is sent to myCitadel Wallet using an HTTPS POST to the following URL:https://www.myCitadel.com/merchantReport.do


Web Payment Redirect Status Report ResponseThe response to the request is an XML document that will contain the current status of the Web Payment Redirect transaction. The response will have a root REPORT element that contains the attributes described in Table 4-3.

Table 4-3 REPORT Element Attributes (Web Payment Redirect Status Report Response)


TYPE The type of the report (this must be WEBPAYMENTSTATUS).

WALLETID The wallet ID of the report. This will be the same wallet ID specified in the request.

DATE The date of the report.



Under the REPORT element, there will be one WEBPAYMENT element.The WEBPAYMENT element contains the sub-elements described in Table 4-4.

Table 4-4 WEBPAYMENT Sub-element Attributes


JOURNALNUMBER The myCitadel Wallet journal number for this Web Payment.

PAYMENTREFERENCE The myCitadel Wallet payment reference number for this Web Payment.

MERCHANTREFERENCE The merchant's reference number supplied by the merchant for this Web Payment.

STATUS The current status for this Web Payment, either CREATED, COMPLETE, or CANCELLED.

FUNDSSTATUS The current status for funds used in the Web Payment, either UNCLEARED, PENDING, CLEARED, or RECALLED.

PAYMENTMETHOD The payment method that was used for this Web Payment.

CURRENCY The currency code for the Web Payment.

AMOUNT The amount of the Web Payment.

TAXAMOUNT The tax amount of the Web Payment.

SHIPPINGAMOUNT The shipping amount of the Web Payment.

TOTALAMOUNT The total amount of the Web Payment.

DATE The date of the Web Payment.

DESCRIPTION The Web Payment description.

NOTETOSELLER The Web Payment note to seller.

SHIPPINGINFO The Web Payment shipping information, as supplied by the consumer.

FEEAMOUNT The Web Payment fee (optional–only for guaranteed payments).



Redirect Payment Debit Request Response SampleCode Sample 4-4 shows a sample of a Redirect Payment Debit Request Response.Code Sample 4-4 Redirect Payment Debit Request Response<?xml version="1.0" encoding="UTF-8"?><REPORT TYPE="WEBPAYMENTSTATUS" WALLETID="IS12345678" DATE="2004-04-02 13:06:42"> <WEBPAYMENT> <JOURNALNUMBER>2992</JOURNALNUMBER> <PAYMENTREFERENCE>129-164</PAYMENTREFERENCE> <MERCHANTREFERENCE>12345678</MERCHANTREFERENCE> <STATUS>COMPLETE</STATUS> <FUNDSSTATUS>CLEAR</FUNDSSTATUS> <PAYMENTMETHOD>CASH</PAYMENTMETHOD> <CURRENCY>USD</CURRENCY> <AMOUNT>5.00</AMOUNT> <TAXAMOUNT>0.00</TAXAMOUNT>

<FEEAMOUNT>0.08</FEEAMOUNT> <SHIPPINGAMOUNT>0.00</SHIPPINGAMOUNT> <TOTALAMOUNT>5.00</TOTALAMOUNT> <DATE>2004-04-02 11:01:02</DATE> <DESCRIPTION>1 Month Membership</DESCRIPTION> <NOTETOSELLER>This is a note from the consumer to the

merchant</NOTETOSELLER> <SHIPPINGINFO>Bob Smith, 1234 Main Street, Anytown NY, 12345</SHIPPINGINFO> </WEBPAYMENT></REPORT>




Web Credit Service [5]

This chapter provides an overview of the myCitadel Wallet Web Credit Service, including the following topics:• High-Level Description• Merchant Account Administration User Interface• HTTP POST Directly to myCitadel Wallet• Web Credit Requests• Web Credit Request Responses• Web Credit Considerations

High-Level DescriptionThe myCitadel Wallet Web Credit Service allows a merchant to directly transfer funds into a consumer's existing myCitadel Wallet account. A merchant can perform these credits via two methods:• Merchant Account Administration User Interface• HTTP POST Directly to myCitadel Wallet

Both methods will also determine if the consumer has uncleared funds owing to the merchant, and, if so, will make the transfer pending the clearing of the uncleared funds.



Merchant Account Administration User InterfaceFigure 5-1 shows the Web Credit page within the myCitadel Wallet Merchant Administration site. Merchants must ensure that they have available funds in their wallet account in order to execute a Web Credit.Figure 5-1 Web Credit Merchant Interface Page

HTTP POST Directly to myCitadel WalletIn order to make Web Credits of any kind, the merchant must first ensure that they have available funds in their wallet account. The merchant then initiates the transfer by sending an HTTP POST to the myCitadel Wallet Web site containing the necessary information about the transfer. The response to the HTTP POST will inform the merchant if the transfer completed, and provide the transaction ID of the transfer.

The merchant can send only one Web Credit Request or many Web Credit Requests in the same page. The merchant has the option of sending and receiving with or without XML.

Revised October 26, 2007 Web Credit Service [5]


Web Credit RequestsThis section describes Web Credit Requests, including the following topics:• Request Fields for Web Credit Requests• Submitting a Web Credit Request Using XML• Submitting a Web Credit Request Without Using XML

Request Fields for Web Credit RequestsTable 5-1 describes the mandatory and optional request fields of a Web Credit Request.

Table 5-1 Mandatory and Optional Fields (Web Credit Request)


walletId Mandatory The wallet number of the store, e.g. IS12345678.

userId Mandatory The user ID for the store, e.g. store_manager.

userPassword Mandatory The password for the store's user ID, e.g. d74s2$.

customerEmail Mandatory The email address of the consumer that is receiving the transfer of money, e.g. [email protected].

amount Mandatory The amount of the payment, e.g. 1.00.

currency Mandatory The currency of the payment. Valid currency codes include: USD (U.S. $), CAD (Canadian $), EUR (Euro), GBP (Great Britain £), and CNY (Chinese Yuan). In most cases, this is set for USD.

merchantReference Mandatory A unique identifying reference number (or code) supplied by the merchant, e.g. DT4895473.

notifyCustomer "Yes" if the merchants wants the consumer to be notified by email after the completion of the transfer. If this field is missing, "No" is assumed.

payCashoutFees "Yes" if the merchant wants to pay for the consumers cashout fees associated with this transfer. If this field is missing, "No" is assumed.

allowPayNonMember "Yes" if the merchant wants to allow a transfer to take place if the recipient consumer is not a member of myCitadel Wallet (the consumer email address is not registered to any myCitadel Wallet holder). If this field is missing, "No" is assumed. Note that it is recommended that the merchant use "No" (or omit this field).

allowMerchantNSF "Yes" if the merchant wants to allow a transfer to take place if the merchant does not have sufficient funds. When the merchant does not have sufficient funds, a "pending" transaction will be created. Once the merchant has sufficient funds to cover the transfer, the transfer will take place automatically. If this field is missing, "No" is assumed.



warnUnclearedFunds N/A "Yes" if the merchant wants credits to consumers, with outstanding uncleared funds owed to the merchant, to fail and include a notification in the response. If this field is missing, "No" is assumed in which case the transaction will be "pending" until the funds owing to the merchant have cleared.Note that the option "Force" has been added. It is used when the merchant wants to credit a customer, who has outstanding uncleared funds owed to that merchant. The transaction has a status of CLEARED. Therefore, the funds are immediately available to the customer. When the value is "No", the transaction is PENDING and therefore the funds are available to the customer.

customerDescription N/A The description of the transfer.

Table 5-1 Mandatory and Optional Fields (Continued)(Web Credit Request)




Submitting a Web Credit Request Using XMLThis section describes how to submit Web Credit Requests, including:• Submitting a Single Web Credit Request• Submitting Multiple Web Credit Requests

Submitting a Single Web Credit RequestWhen using XML to submit the request, it must conform to the following requirements:• The XML version must be 1.0 and the encoding must be UTF-8.• The document (root) element must be named transfer (all lower case).

Within the document element, there will be a sub-element for each of the fields. The sub-element name will be the same as the field name. The element value will contain the value for the field.

Code Sample 5-1 shows a sample of a single Web Credit Request.

Note: The XML text must be in the HTTP POST parameter called xml.

The request is then posted to either of the following myCitadel Wallet Web servers, depending on the current merchant integration status: • https://test.mycitadel.com/webCredit.do (merchant test server)

Or:

• https://www.mycitadel.com/webCredit.do ("live" myCitadel Wallet Web server)

Submitting Multiple Web Credit RequestsWhen using XML to submit multiple request, it must conform to the following requirements:• The XML version must be 1.0 and the encoding must be UTF-8.• The document (root) element must be named transferRequests.

There must be only one element of walletId, userId, and userPassword (these are the merchant walletId, userId and userPassword).

Code Sample 5-1 Web Credit Request (Single)<?xml version="1.0" encoding="UTF-8"?><transfer>

<walletId>IS12345678</walletId><userId>store_manager</userId><userPassword>d74s2$</userPassword><customerEmail>[email protected]</customerEmail><amount>1.00</amount><currency>USD</currency><merchantReference>DT4895473</merchantReference><customerDescription>Casino X Cashout</customerDescription></transfer>



Each Web Credit Request must contain the following elements:• customerEmail

• amount

• currency

• merchantReference

• customerDescription

Code Sample 5-2 shows a sample of a multiple Web Credit Request.

Note: The XML text must be in the HTTP POST parameter called xml.

The request is then posted to the myCitadel Wallet Web server:

http://www.mycitadel.com/multipleWebCredit.do myCitadel Wallet

If more than 1000 Web Credits are submitted for processing at a time, a warning email is sent to operations. The number of records is configured using the com.citadelcommerce.action.WebCreditAction.MaxRecCount property in the ResourceBundle.properties file.

Code Sample 5-2 Web Credit Request (Multiple)<?xml version="1.0" encoding="UTF-8"?><transferRequests>

<walletId>IS12345678</walletId><userId>store_manager</userId><userPassword>d74s2$</userPassword>

<transfer><customerEmail>[email protected]</customerEmail><amount>1.00</amount><currency>USD</currency><merchantReference>DT4895473</merchantReference><customerDescription>Casino X Cashout</customerDescription>

</transfer>

<transfer><customerEmail>[email protected]</customerEmail><amount>2.00</amount><currency>USD</currency><merchantReference>DT4895474</merchantReference><customerDescription>Casino X Cashout</customerDescription>

</transfer>

</transferRequests>



Submitting a Web Credit Request Without Using XMLThe request can also be submitted without using XML. To do this, each request field will be put into the HTTP POST or GET as a request parameter, with the value of the parameter being the value of the field. For example, the walletId field will go into an HTTP POST or GET parameter named walletId, and with a value of IS12345678.

The request is then sent to the myCitadel Wallet Web server.

HTTP GET SampleThe following link is a sample using HTTP GET:

https://www.mycitadel.com/webCredit.do?walletId=IS12345678&userId=store_manager&userPassword=d74s2$&[email protected]&amount=1.00&currency=USD&merchantReference=DT4895473&customerDescription=Casino_X_Cashout

Web Credit Request ResponsesTable 5-2 describes the fields that the response from the HTTP POST request or HTTP GET query string may contain.

Note: To address changing business requirements, Citadel Commerce may periodically add attributes to the Web Credit Request Response without providing merchants with advance notice. Therefore, merchant implementation of this response must support the potential addition of parameters to those shown in the following table.

Table 5-2 Web Credit Request Response Fields

Field Description

TRANSACTION_ID The transaction ID number for the transfer issued by the myCitadel Wallet system. The transaction ID could either be a number or number-dash-number, e.g. 23456-1.

TRANSFER_COMPLETE This field is "true" if the transfer has completed successfully, "false" if the transfer was held pending, or the consumer does not exist.



Responses When Using XMLIf the request was made using XML, the response will also be in XML. All elements may not be present, depending on the transaction state. The response will conform to the following requirement:• The XML version will be 1.0 and the encoding will be UTF-8.

Response for a Single Web Credit RequestThe document (root) element will be named TRANSFER_RESULT.

Within the document element, there will be a sub-element for each of the fields. The sub-element name will be the same as the field name. The element value will contain the value for the field; Code Sample 5-3 shows a sample XML response.

Response for Multiple Web Credit RequestThe document (root) element will be named TRANSFERRESULTS.

Within the document element, there will be a sub-element for each Web Credit Request. Each Web Credit result will have sub-elements. The sub-element name will be the same as the field name. The element value will contain the value for the field.

TRANSFER_PENDING_UNCLEARED This field is "true" if the transfer is held in a pending state because the consumer has previously transferred uncleared funds to the merchant, and the funds are not cleared; see Pending Transactions Due to Consumer's Uncleared Funds on page 62.

TRANSFER_PENDING_NSF_MERCHANT This field is "true" if the transfer is held in a pending state because the merchant does not have sufficient funds to perform the transfer, and allowMerchantNSF was set to "Yes" in the request; see Pending Transactions Due to Merchant's NSF on page 63.

CUSTOMER_NOT_MEMBER This field is "true" if the consumer's email address (as specified in the request) was not found, and allowPayNonMember was set to "Yes" in the request. The funds are held in a temporary account until the consumer joins myCitadel Wallet; see Foreign Exchange on page 62.

MERCHANT_REFERENCE The merchant reference number or code that was supplied by the merchant in the request. It is returned back to the merchant in the response, e.g. DT4895473.

error_number Error number (optional) - reserved for future use.

Table 5-2 Web Credit Request Response Fields

Field Description



Code Sample 5-3 shows a sample of a response.

Responses When Not Using XMLIf the request was made without using XML, then the response will also not be in XML. Instead, it will be in an alternate format that can be easily parsed by software.

The format consists of the field name followed by an equals sign (=), then followed by the field value, and then finally followed by a semicolon (;). This is repeated for each of the fields.

Code Sample 5-4 shows a sample of a response when not using XML.

Note: The fields and values in the Web Credit Request Response will be on one single line. Code Sample 5-4 shows separate lines for readability purposes.

Error ResponsesIf an error occurs during the Web Credit process, an error code and description is returned via the HTTP POST error mechanism, not via the response mechanism. Currently, all errors have a code of 500, and the description may provide further details in some circumstances.

Code Sample 5-3 Web Credit Request Response (Multiple)<?xml version="1.0" encoding="UTF-8"?><TRANSFERRESULTS>

<TRANSFER_RESULT><TRANSFER_PENDING_NSF_MERCHANT>false<TRANSFER_PENDING_NSF_MERCHANT><TRANSFER_PENDING_UNCLEARED>true</TRANSFER_PENDING_UNCLEARED><MERCHANT_REFERENCE>DT4895473</MERCHANT_REFERENCE><TRANSACTION_ID>2615</TRANSACTION_ID><CUSTOMER_NOT_MEMBER>false</CUSTOMER_NOT_MEMBER><TRANSFER_COMPLETE>false</TRANSFER_COMPLETE>

</TRANSFER_RESULT></TRANSFERRESULTS>

Code Sample 5-4 Web Credit Request Response (When Not Using XML)TRANSFER_PENDING_NSF_MERCHANT=false;TRANSFER_PENDING_UNCLEARED=true;TRANSACTION_ID=2615;MERCHANT_REFERENCE=DT4895473;CUSTOMER_NOT_MEMBER=false;TRANSFER_COMPLETE=true;



Web Credit ConsiderationsThis section describes the issues for the merchant to consider when using the Web Credit Service, including the following topics:• Foreign Exchange• Consumers Who are not Members of myCitadel Wallet• Pending Transactions Due to Consumer's Uncleared Funds• Pending Transactions Due to Merchant's NSF• Web Credit Fees• Cashout Fees• Consumer Notification

Foreign ExchangeIf a Web Credit is initiated with a currency that the merchant does not have set up, or has a balance of less than the transfer amount, the myCitadel Wallet system will attempt to perform a foreign exchange into the desired currency. If myCitadel Wallet is not able to perform the foreign exchange due to insufficient funds in the merchants other currency accounts, the Web Credit will be held in a pending state. It is recommended that merchants initiate transfers with currencies in which the merchant has a balance.

Consumers Who are not Members of myCitadel WalletAlthough it is possible to initiate a Web Credit to a consumer who is not a member of myCitadel Wallet, it is not recommended. Doing so may cause confusion with a consumer who is not a myCitadel Wallet member, but is expecting to receive money from the merchant. It is recommended that the merchant advise the consumer that he/she must first be a member of myCitadel Wallet to receive the Web Credit.

When the merchant initiates the Web Credit, and the myCitadel Wallet system cannot find the consumer's email address in the system, an error will be returned with a description of "Consumer Does not have Account".

If there is a reason to initiate a Web Credit to a consumer who does not have an account with myCitadel Wallet, the HTTP POST request must include the allowPayNonMember field set to a value of "Yes". The response will come back with the CUSTOMER_NOT_MEMBER set to "true" if the consumer is not a member, or "false" if the consumer was found in the myCitadel Wallet system. An account with PRE_ACTIVATION status is created using the specified email. Pending transactions are created for the sending merchant and the pre_activation recipient. After the recipient signs up using the specified email, the pending Web Credit transaction will be processed automatically during the execution of batch process for pending transactions. Before that, the sending merchant has the option to cancel the pending Web Credit transaction.

Pending Transactions Due to Consumer's Uncleared FundsThe merchant may have previously accepted uncleared funds from a consumer. If the funds are still uncleared, and the merchant is initiating a Web Credit to the consumer, and the request field warnUnclearedFunds is not set to "Yes", the myCitadel Wallet system will hold the Web Credit in a pending state. The response from the HTTP POST request will contain a field named TRANSFER_PENDING_UNCLEARED with a value of "true".



The merchant's account will show a pending beam transaction for this transfer, and the consumer's account will show a pending transfer transaction for this transaction. When the original uncleared funds from the consumer are cleared, the pending Direct Transfer will proceed.

It is possible for a merchant to cancel the pending transfer (beam) to the consumer before the consumer's uncleared funds have cleared. The merchant can do this from the myCitadel Wallet Web site. After the merchant cancels the pending transfer, the consumer will be notified by email that the merchant has cancelled the transfer and that the consumer must contact the merchant directly to resolve any problem arising.

Pending Transactions Due to Merchant's NSFWhen a merchant initiates a Web Credit for an amount that exceeds that balance in the merchant's myCitadel Wallet accounts, and the allowMerchantNSF request field has a value of "Yes", the myCitadel Wallet system will hold the Web Credit in a pending state. The response from the HTTP POST request will contain a field named TRANSFER_PENDING_NSF_MERCHANT with a value of "true".

The merchant's account will show a pending beam transaction for this transfer, and the consumer's account will show a pending transfer transaction for this transaction.

When the merchant has sufficient funds (of all currencies) to cover the pending Web Credit transaction in his/her account, the pending Web Credit will be processed automatically. Foreign exchange transaction(s) might be performed if necessary.

It is possible for a merchant to cancel the pending transfer (beam) to the consumer before the merchant has sufficient funds in their account. The merchant can do this from the myCitadel Wallet Web site. After the merchant cancels the pending transfer, the consumer will be notified by email that the merchant has cancelled the transfer and that the consumer must contact the merchant directly to resolve any problem arising.

Web Credit FeesThe merchant will not be assessed fees for Web Credit transactions.

Cashout FeesWhen a consumer wants to cash out, or withdraw funds from his/her myCitadel Wallet account, the consumer may have to pay a small fee. The merchant may want to pay this fee for the consumer, to ensure the consumer's satisfaction and convenience.

To do this, the HTTP POST request must contain a field called payCashoutFees with a value of "Yes". This will issue a cashout coupon to the consumer that can be used by the consumer for a free cashout.

Note: The cashout fee will be charged to the merchant.

Consumer NotificationIf the merchant chooses to notify the consumer by email when a Web Credit is initiated, the HTTP POST request must contain a field called notifyCustomer with a value of "Yes".



If the Web Credit is held pending for any reason, the consumer notification email will inform the consumer about the pending transfer, otherwise the email will inform the consumer that a transfer has been completed.


Combined Web Credit/Web PaymentService [6]

This chapter provides an overview of the myCitadel Wallet Combined Web Credit/Web Payment Service, including the following topics:• High-Level Description• HTTP POST Directly to myCitadel Wallet• Combined Web Credit/Web Payment Requests• Combined Web Credit/Web Payment Request Responses

High-Level DescriptionThe myCitadel Wallet Combined Web Credit/Web Payment Service allows a merchant to initiate a Web Credit to a myCitadel consumer wallet and have the funds automatically move to a second merchant (via Web Payment), without the ability for the consumer to touch the funds en route. These transactions are initiated via an HTTP POST directly to myCitadel Wallet.

The following conditions must be met in order for this method to complete the transfer:• IDs for both the merchant initiating the Web Credit <walletId> and the merchant receiving

the Web Payment <recipientMerchantWalletId> include the "IS" prefix (indicating a wallet type of "Issuing_Store").

• The merchant initiating the transfer has a sufficient balance to cover the amount being credited.

• The consumer email address matches a valid, active myCitadel Wallet account.• The recipient merchant is configured for Web Payments and supports the currency used for

the transfer.

If any of these conditions are not met, an appropriate error message is generated.

Note: If a component transaction fails - for example, the Web Payment - the entire process fails.

HTTP POST Directly to myCitadel WalletIn order to make Web Credits of any kind, the merchant must first ensure they have available funds in their wallet account. The merchant then initiates the transfer by sending an HTTP POST to the myCitadel Wallet Web site containing the necessary information about the transfer. The response to the HTTP POST informs the merchant if the transfer completed, and provides the transaction ID of the transfer.

The merchant can send only one Combined Web Credit/Web Payment Request, or many Combined Web Credit/Web Payment Requests in the same page. The merchant has the option of sending and receiving with or without XML.



Combined Web Credit/Web Payment RequestsThis section describes Combined Web Credit/Web Payment Requests, including the following topics:• Request Fields for Combined Web Credit/Web Payment Requests• Submitting a Combined Web Credit/Web Payment Request Using XML• Submitting a Combined Web Credit/Web Payment Request Without Using XML

Request Fields for Combined Web Credit/Web Payment RequestsTable 6-1 describes the mandatory and optional request fields of a Combined Web Credit/Web Payment Request.

Table 6-1 Mandatory and Optional Fields (Combined Web Credit/Web Payment Request)


userId Mandatory The user ID for the merchant-store originating the trans-fer (e.g. store_manager).

userPassword Mandatory For the merchant-store originating the transfer, the pass-word for the store’s user ID (e.g. d74s2$).

walletId Mandatory For the merchant-store originating the transfer, the wal-let number of the store (e.g. IS12345678).

customerEmail Mandatory Email address of the consumer used for the transfer (e.g. [email protected]).

amount Mandatory Amount of the transfer (e.g. 1.00).

currency Mandatory Currency of the transfer. Valid currency codes include: USD (U.S. $), CAD (Canadian $), EUR (Euro), GBP (Great Britain £), and CNY (Chinese Yuan). In most cases, this is set for USD. The recipient merchant must support the specified currency.

merchantReference Mandatory A unique identifying reference number (or code) sup-plied by the merchant originating the transfer (e.g. DT4895473).

customerDescription Optional Description of the transfer.

recipientMerchantWalletId Mandatory The wallet number of the merchant-store receiving the Web Payment (e.g. IS12345678).

Revised October 26, 2007 Combined Web Credit/Web Payment Service [6]


Submitting a Combined Web Credit/Web Payment Request Using XMLThis section describes how to submit Combined Web Credit/Web Payment Requests, including:• Submitting a Single Combined Web Credit/Web Payment Request• Submitting Multiple Combined Web Credit/Web Payment Requests

Submitting a Single Combined Web Credit/Web Payment RequestWhen using XML to submit the request, it must conform to the following requirements:• The XML version must be 1.0 and the encoding must be UTF-8.• The document (root) element must be named transferRequests.

Within the document element, there is sub-element named transfer, which in turn contains sub-elements for each of the fields (sub-element names are the same as the corresponding field names; each element contains the value for the field).

Code Sample 6-1 shows a single Combined Web Credit/Web Payment Request.

Note: The XML text must be in the HTTP POST parameter named xml.

The request is posted to either of the following myCitadel Wallet Web servers, depending on the current merchant integration status: • https://test.mycitadel.com/merchant2MerchantPayment.do (merchant test server)

Or:

• https://www.mycitadel.com/merchant2MerchantPayment.do ("live" myCitadel Wallet Web server)

Submitting Multiple Combined Web Credit/Web Payment RequestsWhen using XML to submit a request containing multiple transfers, the request must conform to the following requirements:• The XML version must be 1.0 and the encoding must be UTF-8.• The document (root) element must be named transferRequests.

There must be only one element for each walletId, userId, and userPassword (these are the walletId, userId and userPassword for the merchant originating the transfer).

Code Sample 6-1 Combined Web Credit/Web Payment Request (Single)<?xml version="1.0" encoding="UTF-8" ?> <transferRequests> <userId>store</userId> <userPassword>password1@</userPassword> <walletId>IS34532754</walletId> <transfer> <customerEmail>[email protected]</customerEmail> <amount>4.76</amount> <currency>USD</currency> <merchantReference>200500202-019</merchantReference> <customerDescription>Testing WC - WP 006</customerDescription> <recipientMerchantWalletId>IS24867566</recipientMerchantWalletId> </transfer></transferRequests>



Each Combined Web Credit/Web Payment Request must contain the following elements:• customerEmail

• amount

• currency

• merchantReference

• customerDescription

• recipientMerchantWalletid

Code Sample 6-2 shows a multiple Combined Web Credit/Web Payment Request.

Note: The XML text must be in the HTTP POST parameter named xml.

The request is then posted to the myCitadel Wallet Web server:

https://www.mycitadel.com/merchant2MerchantPayment.do

Code Sample 6-2 Combined Web Credit/Web Payment Request (Multiple)<?xml version="1.0" encoding="UTF-8" ?> <transferRequests> <userId>store</userId> <userPassword>password1@</userPassword> <walletId>IS34532754</walletId> <transfer> <customerEmail>[email protected]</customerEmail> <amount>4.76</amount> <currency>USD</currency> <merchantReference>200500202-019</merchantReference> <customerDescription>Testing WC - WP 006</customerDescription> <recipientMerchantWalletId>IS24867566</recipientMerchantWalletId> </transfer> <transfer> <customerEmail>[email protected]</customerEmail> <amount>4.75</amount> <currency>CAD</currency> <merchantReference>200500202-020</merchantReference> <customerDescription>Testing WC - WP 007</customerDescription> <recipientMerchantWalletId>IS24867566</recipientMerchantWalletId> </transfer></transferRequests>



Submitting a Combined Web Credit/Web Payment RequestWithout Using XML

The request can also be submitted without using XML. To do this, each request field is placed in the HTTP POST or GET as a request parameter, with the value of the parameter being the value of the field. For example, for the transfers used in code samples earlier in this section, the walletId field would go into an HTTP POST or GET parameter named walletId, with a value of IS34532754.

The request is sent to the myCitadel Wallet Web server.

HTTP GET SampleThe following link is a sample using HTTP GET:

https://www.mycitadel.com/merchant2MerchantPayment.do?userId=store&userPassword=password1@&walletId=IS34532754&[email protected]&amount=4.76&currency=USD&merchantReference=200500202-019&customerDescription=Testing BC - WP 006&recipientMerchantWalletId=IS24867566

Combined Web Credit/Web Payment Request ResponsesTable 6-2 describes the fields that the response from the HTTP POST request or HTTP GET query string may contain.

Table 6-2 Combined Web Credit/Web Payment Request Response Fields

Field Description

TRANSFER_PENDING_NSF_MERCHANT This field is "true" if the merchant initiating the request does not have sufficient funds to perform the transfer; otherwise, it is "false".

TRANSFER_PENDING_UNCLEARED This field is "true" if the consumer previously transferred uncleared funds to the merchant, and the funds are not cleared; otherwise, it is "false".

TRANSACTION_ID The transaction ID number for the transfer issued by the myCitadel Wallet system. The transaction ID can either be a number, or in the format "number-dash-number" (e.g. 23456-1).

MERCHANT_REFERENCE The merchant reference number or code supplied by the merchant in the request. It is returned to the merchant in the response (e.g. DT4895473).

CUSTOMER_NOT_MEMBER This field is "true" if the consumer's email address (as specified in the request) was not found.

TRANSFER_COMPLETE This field is "true" if the transfer completed successfully; otherwise, it is "false".



Responses Using XMLIf a request is made using XML, the response is also in XML. All elements may not be present, depending on the transaction state. The response conforms to the following requirements:• The XML version is 1.0 and the encoding is UTF-8.

Response for a Single Combined Web Credit/Web Payment RequestThe document (root) element is named TRANSFER_RESULTS.

Within the document element, there is a sub-element named TRANSFER_RESULT, which in turn contains sub-elements for each of the fields (sub-element names are the same as the corresponding field names; each element contains the value for the field; Code Sample 6-3 shows an XML response.

Response for Multiple Combined Web Credit/Web Payment RequestThe document (root) element is named TRANSFER_RESULTS.

Within the document element, there is a sub-element named TRANSFER_RESULT for each transfer, which in turn contains sub-elements for each of the fields (sub-element names are the same as the corresponding field names; each element contains the value for the field; Code Sample 6-3 shows an XML response.

Responses Not Using XMLIf a request was made without using XML, then the response is not in XML. Instead, it uses an alternate format which can be easily parsed by software.

The format consists of the field name, followed by an equals sign (=), the field value, and a semicolon (;). This structure is repeated for each of the fields.

Code Sample 6-3 Combined Web Credit/Web Payment Request Response (Multiple)<?xml version="1.0" encoding="UTF-8"?><TRANSFER_RESULTS>

<TRANSFER_RESULT><TRANSFER_PENDING_NSF_MERCHANT>false</TRANSFER_PENDING_NSF_MERCHANT><TRANSFER_PENDING_UNCLEARED>false</TRANSFER_PENDING_UNCLEARED><TRANSACTION_ID>19533-1</TRANSACTION_ID><MERCHANT_REFERENCE>200500202-019</MERCHANT_REFERENCE><CUSTOMER_NOT_MEMBER>false</CUSTOMER_NOT_MEMBER><TRANSFER_COMPLETE>true</TRANSFER_COMPLETE></TRANSFER_RESULT>

<TRANSFER_RESULT><TRANSFER_PENDING_NSF_MERCHANT>false</TRANSFER_PENDING_NSF_MERCHANT><TRANSFER_PENDING_UNCLEARED>false</TRANSFER_PENDING_UNCLEARED><TRANSACTION_ID>19538-1</TRANSACTION_ID><MERCHANT_REFERENCE>200500202-020</MERCHANT_REFERENCE><CUSTOMER_NOT_MEMBER>false</CUSTOMER_NOT_MEMBER><TRANSFER_COMPLETE>true</TRANSFER_COMPLETE></TRANSFER_RESULT>

</TRANSFER_RESULTS>



Code Sample 6-4 shows a response to a request not using XML.

Note: The fields and values in the Combined Web Credit/Web Payment Request Response will be on a single line. Code Sample 6-4 shows separate lines for readability purposes.

Code Sample 6-4 Combined Web Credit/Web Payment Request Response (When Not Using XML)TRANSFER_PENDING_NSF_MERCHANT=false;TRANSFER_PENDING_UNCLEARED=false;TRANSACTION_ID=19533-1;MERCHANT_REFERENCE=200500202-019;CUSTOMER_NOT_MEMBER=false;TRANSFER_COMPLETE=true;




Transaction Status Change Report [7]

This chapter describes the Transaction Status Change Report.

High-Level DescriptionThe Transaction Status Change Report allows the merchant to retrieve a list of all the transactions that have changed status for a specified day. The data that is retrieved will allow the merchant to reconcile their records. The Transaction Status Change Report Request is an HTTPS POST in XML format.

Transaction Status Change Report Request FieldsTable 7-1 describes the mandatory and optional request fields of a Transaction Status Change Report.

These fields are in the XML document as separate elements, under the root element called reportRequest. The combination of walletId, userId, and userPassword determines the scope of transactions that go into the report response. A user can view transactions in which itself or any of its descendants was a participant.

Table 7-1 Mandatory and Optional Fields (Transaction Status Change Report)


reportType Mandatory The type of report (this must be set to StatusChange).

walletId Mandatory The merchant's wallet ID, e.g. IS12345678.

userId Mandatory The authorized merchant ID to this wallet ID, e.g. store_manager.

userPassword Mandatory The merchant wallet password, e.g. mypass.

reportDate Mandatory The date of the report that is to be returned, e.g. 11/24/2003.

transactionType Optional The type(s) of transactions that should be included in the report. Valid values are:• "PN"–Report on WEBPAYMENT and

WEBPAYMENT REFUND transactions.• "WC"–Report on WEB CREDIT transactions.• "PN, WC" or "WC, PN"–Report on WEB CREDIT,

WEBPAYMENT, and WEBPAYMENT REFUND transactions.

• Empty or absent–Report on WEB CREDIT, WEB-PAYMENT, and WEBPAYMENT REFUND trans-actions.



Transaction Status Change Report Request SampleCode Sample 7-1 shows a sample of the Transaction Status Change Report Request.

Sending the Transaction Status Change Report RequestThe request is sent to myCitadel Wallet using an HTTPS POST to the following URL:

https://www.myCitadel.com/merchantReport.do


Transaction Status Change Report Request ResponseThe response for the request is an XML document that will contain transactions that have changed status on the day specified in the request.

The response will have a root REPORT element that contains the attributes described in Table 7-2.

Code Sample 7-1 Transaction Status Change Report Request<?xml version="1.0" encoding="UTF-8"?><reportRequest> <reportType>StatusChange</reportType> <walletId>IS12345678</walletId> <userId>store_manager</userId> <userPassword>mypass</userPassword> <reportDate>11/24/2003</reportDate>

<transactionType>PN</transactionType></reportRequest>

Table 7-2 REPORT Element Attributes (Transaction Status Change Report Request Response)


TYPE The type of report (this will always be StatusChange).

WALLETID The wallet ID of the report. This will be the same wallet ID specified in the request.

DATE The date of the report. This will be the same date as was specified in the request.

Revised October 26, 2007 Transaction Status Change Report [7]


The root REPORT element will contain zero, one, or more TRANSACTION elements. Each TRANSACTION element will contain data about a single transaction that has changed status on the report date. The TRANSACTION element contains the sub-elements described in Table 7-3.

Table 7-3 WEBPAYMENT Sub-element Attributes (Transaction Status Change Report Request Response)


ACCOUNTNUMBER The store account that participated in the transaction.

CUSTOMEREMAIL The consumer's email that participated in the transaction.

JOURNALNUMBER The myCitadel Wallet journal number for this transaction.

FUNDSSTATUS The current status for funds used in the Web Payment or Web Credit, either UNCLEARED, PENDING (Web Credit only), CLEARED, or RECALLED.

AMOUNT The amount of the transaction including transaction fees, if any.

FEEAMOUNT The fee amount associated with the transaction.

CURRENCY The currency code for the transaction amount.

DATE The date of the transaction.

CLEARINGDATE The date that this transaction was cleared. This field will not be present if the transaction has not cleared.

RECALLDATE The date that this transaction was recalled. This field will not be present if the transaction has not been recalled.

DESCRIPTION The transaction description.

TYPE The type of transaction, either WEBPAYMENT, WEBPAYMENT REFUND, or WEB CREDIT.

MERCHANTREFERENCE The merchant reference ID associated with this transaction.



Code Sample 7-2 shows a sample of a report response.Code Sample 7-2 Transaction Status Change Report Response<?xml version="1.0" encoding="UTF-8"?><REPORT TYPE="StatusChange" WALLETID="IS12345678" DATE="2003-11-24 00:00:00">

<TRANSACTION><ACCOUNTNUMBER>12345678</ACCOUNTNUMBER><CUSTOMEREMAIL>[email protected]</CUSTOMEREMAIL ><JOURNALNUMBER>3614</JOURNALNUMBER><TYPE>WEBPAYMENT</TYPE><FUNDSSTATUS>RECALLED</FUNDSSTATUS><AMOUNT>4.00</AMOUNT><FEEAMOUNT>0.40</FEEAMOUNT><CURRENCY>USD</CURRENCY><DATE>2003-11-24 12:15:18</DATE><CLEARINGDATE>2003-11-11 12:15:18</CLEARINGDATE><RECALLDATE>2003-11-24 14:10:00</RECALLDATE><MERCHANTREFERENCE>12344556</MERCHANTREFERENCE><DESCRIPTION>coolstuff.com</DESCRIPTION>

</TRANSACTION> <TRANSACTION>

<ACCOUNTNUMBER>12345678</ACCOUNTNUMBER><CUSTOMEREMAIL>[email protected]</CUSTOMEREMAIL ><JOURNALNUMBER>11448</JOURNALNUMBER>

<TYPE>WEB CREDIT</TYPE> <FUNDSSTATUS>CLEARED</FUNDSSTATUS> <AMOUNT>25.00</AMOUNT>

<FEEAMOUNT>5.00</FEEAMOUNT> <CURRENCY>USD</CURRENCY> <DATE>2003-11-24 12:16:23</DATE> <CLEARINGDATE>2003-11-24 12:16:23</CLEARINGDATE> <MERCHANTREFERENCE>200401209-003</MERCHANTREFERENCE> <DESCRIPTION>Web Credit to: [email protected]</DESCRIPTION> </TRANSACTION> <TRANSACTION>

<ACCOUNTNUMBER>12345678</ACCOUNTNUMBER><CUSTOMEREMAIL>[email protected]</CUSTOMEREMAIL >

<JOURNALNUMBER>3620</JOURNALNUMBER> <TYPE>WEBPAYMENT REFUND</TYPE> <FUNDSSTATUS>CLEARED</FUNDSSTATUS> <AMOUNT>3.62</AMOUNT>

<FEEAMOUNT>0.00</FEEAMOUNT> <CURRENCY>USD</CURRENCY> <DATE>2003-11-24 12:20:41</DATE> <CLEARINGDATE>2003-11-24 12:20:41</CLEARINGDATE> <DESCRIPTION>coolstuff.com</DESCRIPTION> <MERCHANTREFERENCE>12344557</MERCHANTREFERENCE> </TRANSACTION></REPORT>


User Registration Link [8]

This chapter describes the User Registration Link, and provides a Registration Link sample.

High-Level DescriptionBefore a Web site consumer can pay a merchant for products and services using myCitadel Wallet, the consumer must first register for a myCitadel Wallet. This involves providing an email address and some personal details, and choosing a password. New myCitadel Wallet registrants must confirm their email address and password by following instructions sent in an email. Once the consumer has a myCitadel Wallet, the consumer can then fund the wallet using his/her bank account or other methods depending on the country of residence.

The merchant would normally provide this link in order to encourage new consumers to sign up for a myCitadel Wallet.

User Registration Link SampleThe merchant should provide a link to enable consumers to register with myCitadel Wallet via the merchant's Web site.

Code Sample 8-1 shows a sample of the user registration link.Code Sample 8-1 User Registration Link<center><b>Open a myCitadel account!</b><br><br><a href="https://www.mycitadel.com/signupNew.jsp?content=signupNewChoice"target="_blank"><img border=0src="https://www.mycitadel.com/skins/myCitadel/images/signup.gif" alt="Open a myCitadel account!"></a>

</center>




Get Wallet Status Request [9]

This chapter describes the Get Wallet Status Request, and provides a sample HTTP POST and XML response.

High-Level DescriptionThe Get Wallet Status Request allows the merchant to request information about a consumer’s myCitadel Wallet. The merchant may submit this request at any time to determine if:• consumer has a myCitadel wallet• the consumer’s wallet is open or frozen• consumer has a SecureSwipe device• consumer has defined a preferred payment method.

The merchant can submit a Get Wallet Status Request before attempting a payment request. This enables the merchant to suggest a payment method to the consumer that would minimize the potential for chargebacks.

An HTTP POST command is assembled dynamically at the merchant site using the fields listed in Table 9-1 (and shown in the sample code that follows), and sent over an SSL link to the myCitadel Wallet site:https://www.mycitadel.com/getWalletStatus.do

Get Wallet Status Request FieldsTable 9-1 describes the mandatory and optional request fields of a Get Wallet Status Request.

Get Wallet Status Request SampleThe following link shows a sample Get Wallet Status Request using the fields described in Table 9-1 above.

Table 9-1 Mandatory and Optional Fields (Get Wallet Status Request)


merchantWalletId Mandatory The merchant's wallet ID, e.g. IS12345678.

userId Mandatory The authorized merchant ID to this wallet ID, e.g. store_manager.

password Mandatory The merchant wallet password, e.g. mypass.

customerEmail Mandatory The email address that uniquely identifies the con-sumer’s myCitadel Wallet account, e.g. [email protected].



https://www.mycitadel.com/getWalletStatus.do?merchantWalletId=IS12345678&userId=store_manager&password=mypass&[email protected]

Note: This sample is in the form of the Web browser URL, but would normally be sent as an HTTP POST over SSL to https://www.mycitadel.com/getWalletStatus.do.

Get Wallet Status Request ResponseThe response for the request is an XML document that contains the status of the consumer’s myCitadel Wallet.

The response will have a root WalletStatus element that contains the attributes described in Table 9-2.

Code Sample 9-1 shows a sample of a request response.

Request TrackingCitadel Commerce Corp. saves all merchants’ Get Wallet Status Requests to a database for tracking and analysis purposes.

Table 9-2 Status Values (Get Wallet Status Request Response)


customerWallet The email address that uniquely identifies the consumer’s myCitadel Wallet account, e.g. [email protected].

walletStatus “WALLET_OPEN” if the wallet is open.“WALLET_FROZEN” if the wallet is frozen or if the wallet does not exist.

hasAssignedSecureSwipe “true” if the consumer has a SecureSwipe device.“false” if the user does not have a SecureSwipe device.

hasDefaultMethodPayment “true” if the consumer has defined preferred payment methods.“false” if the consumer has not defined preferred payment methods.

Code Sample 9-1 Get Wallet Status Request Response<?xml version="1.0" encoding="UTF-8"?><WalletStatus> <customerWallet>[email protected]</customerWallet> <walletStatus>WALLET_OPEN</walletStatus> <hasAssignedSecureSwipe>true</hasAssignedSecureSwipe> <hasDefaultMethodPayment>true</hasDefaultMethodPayment></WalletStatus>


AAPI components 8

Get Wallet Status 9myCitadel Wallet Transaction Report 9myCitadel Wallet Web Credit 9User Registration API 8Web Payment Direct 8Web Payment Redirect 8

Ccashout fees 63check acceptance risk 3

cleared funds 4guaranteed funds 4uncleared funds 3

cleared funds 4consumer notification 63contact information xvi

Ddebit options 7Direct Payment Debit Request

fields 34Direct Payment Debit Request Form

sample 35Direct Payment Debit Request Response 36

sample 40documentation

related xvi

Ffees

cashount 63Web Credit 63

foreign exchange 62

GGet Wallet Status API 9Get Wallet Status Request

description 79fields 79request tracking 80response 80sample 79

guaranteed funds 4

HHTML Redirect link

fields 46HTTP POST

to myCitadel Wallet 54, 65

IInital Payment screen

Payment Permissions 19Security Code 13

Insufficient Funds Available for the Transaction screenPayment Permissions 21Security Code 16

MMerchant account administration user interface 54merchant accounts 2myCitadel Wallet

consumer features 1debit options 7merchant features 1payment sequence flow 5process flow 2system description 1

myCitadel Wallet Transaction Report API 9myCitadel Wallet Web Credit API 9

Nnew account setup link 27

Ppayment exception handling

existing wallet login link 28new account setup link 27no permissions exceptions 28payment permission configuration link 28

Payment Permissionaccess 30configuration link

fields 30sample 29

status request sample 25Payment Permission Status Request

fields 24overview 24

Payment Permission Status Request Response 25samples

existing payment permission 27

Index



general failure 26Payment Permissions are Not Set for Merchant screen 21payment sequence flow 5process flow

myCitadel Wallet 2

RRedirect Payment Debit Request Response

sample 51revision history iii

SSecurity is Incorrect screen 15sending Transaction Status Change Report Request 74single Web Credit Request 60, 70store accounts 2submitting

multiple Web Credit Request 57, 67single Web Credit Request 57, 67Web Credit Request using XML 57, 67Web Credit Request without XML 59, 69

TTransaction Completion Success screen 17, 22transaction flow

Web Payment Direct InterfacePayment Permissions 18Security Code 12

Transaction Status Change Reportdescription 73request fields 73Request Response 74sample 74

Transaction Status Change Report Requestsending 74

Transaction Status Requestfields 41sample 42

Uuncleared funds 3User Registration API 8User Registration Link

description 77sample 77

Wwallet

consumerinternational 4

Wallet Does Not Exist screen 14, 20Web Credit Request

request fields 55, 66submitting multiple 57, 67submitting single 57, 67submitting using XML 57, 67submitting without XML 59, 69

Web Credit Request Responseerrors 61fields 59, 69single Web Credit Request 60, 70when not using XML 61, 70when using XML 60, 70

Web Credit Serviceconsiderations 62

foreign exchange 62merchant NSF 63nonmembers 62uncleared funds 62

consumer notification 63description 53, 60, 65, 70fees 63foreign exchange 62pending transactions due to merchant NSF 63

Web Payment Direct API 8Web Payment Direct Interface

description 7options 11Payment Permissions

description 11Inital Payment Screen 19Insufficient Funds Available for Transaction

screen 21Payment Permissions are Not Set for Merchant

screen 21Transaction Completion Success screen 22transaction flow 18Wallet Does Not Exist screen 20

Security Codedescription 11Inital Payment screen 13Insufficient Funds Available for the Transaction

screen 16Security is Incorrect screen 15Transaction Completion Success screen 17transaction flow 12Wallet Does Not Exist screen 14

Web Payment Direct Status Report Response 42sample 44

Web Payment Redirect API 8Web Payment Redirect Interface

description 8, 45technical details 45

Web Payment Redirect Status Report Request

Revised October 26, 2007 Index


fields 48Web Payment Redirect Status Report Response 49Web Payment Redirect Transaction link

sample 47

Date post:	22-Mar-2020
Category:	Documents
Upload:	others
View:	0 times
Download:	0 times

CIT-040630 myCitadel DevCitadel Commerce Corp. xv Preface The preface provides information for using...

Documents