Checkout API Reference Guide

Checkout API Reference Guide November 2014 This manual and accompanying electronic media are proprietary products of Optimal Payments plc. They are ...
Author: Calvin Bennett
18 downloads 1 Views 3MB Size
Checkout API Reference Guide November 2014

This manual and accompanying electronic media are proprietary products of Optimal Payments plc. They are to be used only by licensed users of the product. © 1999–2014 Optimal Payments plc. All rights reserved. The information within this document is subject to change without notice. The software described in this document is provided under a license agreement, and may be used or copied only in accordance with this agreement. No part of this manual may be reproduced or transferred in any form or by any means without the express written consent of Optimal Payments plc. All other names, trademarks, and registered trademarks are the property of their respective owners. Optimal Payments plc makes no warranty, either express or implied, with respect to this product, its merchantability or fitness for a particular purpose, other than as expressly provided in the license agreement of this product. For further information, please contact Optimal Payments plc.

International Head Office 3500 de Maisonneuve W., Suite 700 Montreal, Quebec H3Z 3C1 Canada Tel.: (514) 380-2700 Fax: (514) 380-2760 Email: [email protected] Technical support: [email protected] Web: www.optimalpayments.com

U.K. Office Compass House, Vision Park Chivers Way, Histon Cambridge CB24 9AD United Kingdom Email: [email protected] Technical Support: [email protected] Web: www.netbanx.com

U.S. Office 1209 Orange Street Wilmington, DE 19801

Gatineau Office 75 Promenade du Portage Gatineau, Quebec J8X 2J9 Canada

Contents

1 NETBANX Checkout API What is the NETBANX Checkout API?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transactions supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing NETBANX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Callback URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing with NETBANX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-1 1-1 1-2 1-2 1-3

Using this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Functionality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-3 1-3 1-3 1-3

Customer-initiated payment process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-4

Checkout API transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createProfileRequest transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createProfileRequest XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createProfileRequest schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createProfileRequest elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . updateProfileRequest transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . updateProfileRequest XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . updateProfileRequest schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . updateProfileRequest elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileCheckoutRequest transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileCheckoutRequest XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileCheckoutRequest schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileCheckoutRequest elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileSettleRequest transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileSettleRequest XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileSettleRequest schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileSettleRequest elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profilePurchaseRequest transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profilePurchaseRequest XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profilePurchaseRequest schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profilePurchaseRequest elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . creditRequest transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . creditRequest XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . creditRequest schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . creditRequest elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cancelCreditRequest transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cancelCreditRequest XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cancelCreditRequest schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cancelCreditRequest elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-5 1-5 1-5 1-5 1-6 1-10 1-10 1-12 1-13 1-17 1-17 1-18 1-19 1-23 1-23 1-23 1-24 1-25 1-25 1-26 1-26 1-27 1-28 1-28 1-29 1-31 1-31 1-31 1-31

Checkout API Reference Guide

III

November 2014

profileEftRegistrationRequest transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileEftRegistrationRequest XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileEftRegistrationRequest schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileEftRegistrationRequest elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileEftRegistrationStatusRequest transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileEftRegistrationStatusRequest XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileEftRegistrationStatusRequest schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileEftRegistrationStatusRequest elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . transactionLookupRequest transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . transactionLookupRequest XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . transactionLookupRequest schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . transactionLookupRequest elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileLookupRequest transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileLookupRequest XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileLookupRequest schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileLookupRequest elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-32 1-32 1-33 1-33 1-35 1-35 1-35 1-35 1-35 1-35 1-35 1-36 1-36 1-36 1-36 1-36

Standalone payment page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-37 Private label branding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-37 Posting transactions to NETBANX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-38 Processing the response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Responses directed to your callback URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Responses directed to your API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileResponse XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileResponse schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileResponse elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileCheckoutResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileCheckoutResponse XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileCheckoutResponse schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileCheckoutResponse elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileSettleResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileSettleResponse XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileSettleResponse schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileSettleResponse elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . creditResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . creditResponse XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . creditResponse schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . creditResponse elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cancelCreditResponse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cancelCreditResponse XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cancelCreditResponse schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cancelCreditResponse elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileEftRegistrationResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileEftRegistrationResponse XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileEftRegistrationResponse schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileEftRegistrationResponse elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileEftRegistrationStatusResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileEftRegistrationStatusResponse XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileEftRegistrationStatusResponse schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileEftRegistrationStatusResponse elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

IV

1-39 1-40 1-40 1-41 1-41 1-41 1-42 1-42 1-42 1-44 1-45 1-46 1-47 1-47 1-48 1-49 1-49 1-50 1-50 1-52 1-52 1-53 1-53 1-54 1-54 1-54 1-55 1-56 1-56 1-56 1-57

November 2014

transactionLookupResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . transactionLookupResponse XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . transactionLookupResponse schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . transactionLookupResponse elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileLookupResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileLookupResponse XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileLookupResponse schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profileLookupResponse elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-58 1-58 1-60 1-61 1-62 1-62 1-63 1-64

Code examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Java examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending a profilePurchaseRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Processing a response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Signing, generating, and authenticating messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JSP example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iFrame code sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JSP code sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-66 1-66 1-66 1-67 1-67 1-69 1-69 1-69

A Request Workflow Using the NETBANX Checkout API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 1 – Submit a createProfileRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample createProfileRequest XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 2 – NETBANX sends a response to your callback URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample profileResponse XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 3 – Use the token to generate a payment page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample profileCheckoutRequest XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 4 – Your customer is redirected to the hosted payment page. . . . . . . . . . . . . . . . . . . . . . . . . . Step 5 – The customer is redirected to the returnURL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample profileCheckoutResponse XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

A-1 A-1 A-1 A-2 A-2 A-2 A-2 A-3 A-3 A-3

What if you do not have the customer’s information? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample profileCheckoutRequest XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

A-4 A-4

If you need help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

A-5

B Response Codes Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1 Response codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1 Action codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-12

C Geographical Codes Province codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C-1

State codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C-2

Country codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C-3

D 3D Secure Test Cases Checkout API Reference Guide

V

November 2014

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Verified by Visa test cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VBV test case 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VBV test case 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VBV test case 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VBV test case 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VBV test case 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VBV test case 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VBV test case 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VBV test case 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VBV test case 9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VBV test case 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VBV test case 11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MasterCard SecureCode test cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MCSC test case 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MCSC test case 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MCSC test case 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MCSC test case 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MCSC test case 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MCSC test case 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MCSC test case 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MCSC test case 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MCSC test case 9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MCSC test case 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

VI

D-1 D-1 D-1 D-1 D-2 D-2 D-3 D-3 D-4 D-4 D-4 D-5 D-5 D-6 D-6 D-6 D-7 D-7 D-7 D-8 D-8 D-8 D-9 D-9

C HAPTER 1

NETBANX Checkout API What is the NETBANX Checkout API? The Checkout API allows you to securely submit several transaction types to NETBANX by way of your own e-commerce site. •

Your customer can create a profile that includes personal information and billing details. NETBANX stores this profile, which is used for future e-commerce transactions and can be modified by the customer when required.



You can create a customer profile, providing personal information such as name, address, contact information, date of birth, etc. NETBANX responds with a token, sent to your callback URL, which you can use in subsequent transaction requests.



Your customer can transparently process purchases on your e-commerce site via NETBANX – the customer experiences your branded site only.



You can use existing customer profiles to process purchase transaction requests, e.g., for billing requests that occur regularly.

Transactions supported The NETBANX Checkout API currently supports the following transaction types: Table 1-1: Checkout API Transactions Transaction createProfileRequest

Description This allows you to create a customer profile, providing personal information such as name, address, contact information, date of birth, etc. NETBANX responds with a token, which you use in subsequent transaction requests. See createProfileRequest transactions on page 1-5.

updateProfileRequest

This allows you to modify a customer profile that you previously created using the createProfileRequest transaction type. See updateProfileRequest transactions on page 1-10.

profileCheckoutRequest

This is a customer-initiated purchase request made using an existing customer profile. If a customer profile does not already exist, one will be created as part of the transaction process. You can also initiate an authorization request, which can be settled later. See profileCheckoutRequest transactions on page 1-17.

profileSettleRequest

This is a customer-initiated settlement request, used to settle an Authorization created with a profileCheckoutRequest. See profileSettleRequest transactions on page 1-23.

profilePurchaseRequest

This is a merchant-initiated purchase request made using an existing customer profile. See profilePurchaseRequest transactions on page 1-25.

Checkout API Reference Guide

1-1

NETBANX Checkout API

November 2014

Table 1-1: Checkout API Transactions Transaction

Description

creditRequest

This allows you to credit an amount to a customer’s credit card. This credit transaction is not associated with a previously existing authorization, so the amount of the transaction is not restricted in this way. See creditRequest transactions on page 1-27.

cancelCreditRequest

This allows you to cancel a previously existing creditRequest transaction, provided it is in a Pending state, which typically is before midnight of the day that it is requested. In some cases, you may find older credit transactions in a Pending state. See cancelCreditRequest transactions on page 1-31.

profileEftRegistrationRequest

This is a customer-initiated request that allows you to initiate the registration of a customer’s bank account. See profileEftRegistrationRequest transactions on page 1-32.

profileEftRegistrationStatusRequest

This allows you to determine the status of a customer’s bank account registration. See profileEftRegistrationStatusRequest transactions on page 1-35.

transactionLookupRequest

This allows the merchant to look up a response from a previously processed transaction. See transactionLookupRequest transactions on page 1-35.

profileLookupRequest

This allows the merchant to look up a customer profile that was previously created. See profileLookupRequest transactions on page 1-36.

Accessing NETBANX Once your account has been set up, NETBANX will provide you with the following information: •

Shop ID – used as identification in requests sent to NETBANX



Shop Key – used to digitally sign requests sent to NETBANX

Transaction requests will be posted to the following URL: https://checkout.optimalpayments.com/securePayment/op/.htm where transaction_type is the name of the transaction you are sending. For example: https://checkout.optimalpayments.com/securePayment/op/profileCheckoutRequest.htm

Callback URL When you set up your account, you must also provide NETBANX with a Callback URL. This is the URL to which responses to your transaction requests will be sent. See Processing the response on page 1-39 for more information. Your customer will be redirected to the returnURL you specify in your transaction request on both successful and failed attempts. Therefore, you must check the transaction status NETBANX sends to your callbackURL before displaying a Success or Failure page.

1-2

November 2014

Testing with NETBANX

Testing with NETBANX Once you have configured your Checkout API application, please contact our Technical Support team for instructions on how to test it. •

Email [email protected]



Telephone 1-888-709-8753

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

Audience This user’s guide is intended for NETBANX merchants using our Checkout API to process transaction requests with NETBANX.

Functionality This guide may document some features to which you do not have access. Access to such functionality is allotted on a merchant-by-merchant basis. If you have any questions, contact your account manager.

Symbols This user guide uses the following symbols to bring important items to your attention: Table 1-2: Symbols Symbol

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

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

Checkout API Reference Guide

1-3

NETBANX Checkout API

November 2014

Customer-initiated payment process Here is an overview of what takes place during a customer-initiated payment process, e.g., when processing a profileCheckoutRequest from your e-commerce site.

1-4

1.

Your customer has selected all their items to purchase and enters the checkout on your ecommerce site.

2.

The customer clicks the payment button.

3.

This initiates an HTTP Post request to NETBANX. This request contains both the encoded profileCheckoutRequest XML document and a digital signature (see Posting transactions to NETBANX on page 1-38 for details).

4.

The customer – now in an NETBANX inline frame on your e-commerce site – creates a payment instrument. (This is not required if a customer profile has been set.)

5.

The customer views the purchase details and then confirms the transaction.

6.

A payment request is then initiated with the NETBANX back end.

7.

NETBANX sends an XML response back to you.

November 2014

Checkout API transactions

8.

NETBANX displays a confirmation page to the customer.

Checkout API transactions See Appendix A: Request Workflow for a useful overview of a typical workflow when sending Checkout API requests.

createProfileRequest transactions This transaction allows you to create a customer profile, providing personal information such as name, address, contact information, date of birth, etc. NETBANX responds with a token, sent to your callback URL, which you can use in subsequent transaction requests.

createProfileRequest XML This is the XML for a sample createProfileRequest transaction. 99996666 Jane Jones 123 Main Street Montreal QC CA H3H3H3 10 15 Main Street Apartment 55 Montreal QC CA H3H3H2 514-999-3333 [email protected] fr CA

createProfileRequest schema A createProfileRequest has the following structure:

Checkout API Reference Guide

1-5

NETBANX Checkout API

createProfileRequest elements The createProfileRequest transaction may contain the following elements:

1-6

November 2014

November 2014

createProfileRequest transactions

Table 1-3: createProfileRequest Elements Element

Child Element

merchantCustomerId

Required Yes

Type String Max = 50

Description This is a customer ID that the merchant creates and provides with the transaction. This ID helps the merchant to identify the customer internally. NOTE: Do not use the customer’s email address for this element.

billingDetails

Yes title

Optional

Enumeration

This is the customer’s title. Possible values are: • MR • MS • MRS

firstName

Yes

String

This is the customer’s first name.

Max = 80

Accepted characters are: • a to z • A to Z • ÀàÂâÄäÅåÇçÉéÈèÊêËëÎîÏïÔôÙùÛûÜü.-'

String

This is the customer’s last name.

Max = 80

Accepted characters are: • a to z • A to Z • ÀàÂâÄäÅåÇçÉéÈèÊêËëÎîÏïÔôÙùÛûÜü.-'

String

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

lastName

street

Yes

Yes

Max = 50

street2

Optional

String Max = 50

city

Yes

String Max = 40

Checkout API Reference Guide

Accepted characters are: • a to z • A to Z • 0 to 9 • #,'.ÀàÂâÄäÅåÇçÉéÈèÊêËëÎîÏïÔôÖöÙùÛûÜ ü This is the second line of the customer’s street address Accepted characters are: • a to z • A to Z • 0 to 9 • #,'.ÀàÂâÄäÅåÇçÉéÈèÊêËëÎîÏïÔôÖöÙùÛûÜ ü This is the city in which the customer resides. Accepted characters are: • a to z • A to Z • 0 to 9 • .'ÀàÂâÄäÅåÇçÉéÈèÊêËëÎîÏïÔôÖöÙùÛûÜü

1-7

NETBANX Checkout API

November 2014

Table 1-3: createProfileRequest Elements (Continued) Element billingDetails

Child Element state/region

Required Conditional

(continued)

Type If state, then enumeration

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

If region, then string

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

Max = 40

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

country

Yes

Enumeration

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

zip

Yes

String

This is the customer’s postal code. If the customer is in the U.S., it is the Zip code.

Min = 5

timeAtAddress

Yes

Max = 10

Accepted characters are: • [a-zA-Z][0-9][a-zA-Z]*[0-9][a-zA-Z][0-9] • [0-9][0-9][0-9][0-9][0-9] • [0-9][0-9][0-9][0-9][0-9]\-[0-9][0-9][09][0-9]

Integer

This is the number of months the customer has been at this address. If less than one full month, value should be set to 0 (zero).

Min = 0 Max = 120

1-8

Description

November 2014

createProfileRequest transactions

Table 1-3: createProfileRequest Elements (Continued) Element

Child Element

previousAddress

Required

Type

Conditional

street

Conditional

This is the customer’s previous address. It must be provided if the customer has lived at a different address in the last two years. Otherwise, the profile validation could fail. String Max = 50

street2

Optional

String Max = 50

city

state/region

Conditional

Conditional

Description

String

This is the first line of the customer’s street address. Accepted characters are: • a to z • A to Z • 0 to 9 • #,'.ÀàÂâÄäÅåÇçÉéÈèÊêËëÎîÏïÔôÖöÙùÛûÜ ü This is the second line of the customer’s street address Accepted characters are: • a to z • A to Z • 0 to 9 • #,'.ÀàÂâÄäÅåÇçÉéÈèÊêËëÎîÏïÔôÖöÙùÛûÜ ü

Max = 40

This is the city in which the customer resides.

If state, then enumeration

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

If region, then string

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

Max = 40

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

Accepted characters are: • a to z • A to Z • 0 to 9 • .'ÀàÂâÄäÅåÇçÉéÈèÊêËëÎîÏïÔôÖöÙùÛûÜü

country

Conditional

Enumeration

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

zip

Conditional

String

This is the customer’s postal code. If the customer is in the U.S., it is the Zip code.

Min = 5 Max = 10

Checkout API Reference Guide

Accepted characters are: • [a-zA-Z][0-9][a-zA-Z]*[0-9][a-zA-Z][0-9] • [0-9][0-9][0-9][0-9][0-9] • [0-9][0-9][0-9][0-9][0-9]\-[0-9][0-9][09][0-9]

1-9

NETBANX Checkout API

November 2014

Table 1-3: createProfileRequest Elements (Continued) Element

Child Element

dateOfBirth

Required

Type

Description

Optional Child Element of dateOfBirth year

Optional

Integer

This is the year of the customer’s birth.

Length = 4 month

Optional

Integer

This is the month of the customer’s birth.

Length = 2 day

Optional

Integer

This is the day of the customer’s birth.

Length = 2 phone

Optional

String

This is the customer’s phone number.

Max = 40 notificationEmail

Yes

String

This is the customer’s email address.

Max = 100 mobilePhone

Optional

String

This is the customer’s cell phone number.

Max = 40 companyName

Optional

String

This is the company the customer works for.

Max = 80 locale

Yes

This is the geographic region that indicates the language and currency required.

language

Yes

Enumeration

This is the language of the merchant. Possible values are: • en • fr

country

Yes

Enumeration

This is the country of the merchant. Possible values are: • US • CA

For locale, the language child element can be set to en only when the country child element is set to US; and the language child element can be set to fr only when the country child element is set to CA.

updateProfileRequest transactions This transaction allows you to modify a customer profile that you previously created using the createProfileRequest transaction type.

updateProfileRequest XML This is the XML for a sample updateProfileRequest transaction. 12312211

1-10

November 2014

updateProfileRequest transactions

Jane Jones 123 Main Street Montreal QC CA H3H3H3 10 15 Main Street Apartment 55 Montreal QC CA H3H3H2 INITIAL 514-999-3333 [email protected] fr CA

Checkout API Reference Guide

1-11

NETBANX Checkout API

updateProfileRequest schema An updateProfileRequest has the following structure:

1-12

November 2014

November 2014

updateProfileRequest transactions

updateProfileRequest elements The updateProfileRequest transaction may contain the following elements: Table 1-4: updateProfileRequest Elements Element

Child Element

customerTokenId

Required Yes

Type String Max = 50

billingDetails

Description This is a token generated by NETBANX that represents the customer.

Optional title

Optional

Enumeration

This is the customer’s title. Possible values are: • MR • MS • MRS

firstName

Conditional

String

This is the customer’s first name.

Max = 80

Accepted characters are: • a to z • A to Z • ÀàÂâÄäÅåÇçÉéÈèÊêËëÎîÏïÔôÙùÛûÜü.-'

lastName

street

Conditional

Conditional

String

This is the customer’s last name.

Max = 80

Accepted characters are: • a to z • A to Z • ÀàÂâÄäÅåÇçÉéÈèÊêËëÎîÏïÔôÙùÛûÜü.-'

String

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

Max = 50

street2

Optional

String Max = 50

city

Conditional

String Max = 40

Checkout API Reference Guide

Accepted characters are: • a to z • A to Z • 0 to 9 • #,'.ÀàÂâÄäÅåÇçÉéÈèÊêËëÎîÏïÔôÖöÙùÛûÜ ü This is the second line of the customer’s street address Accepted characters are: • a to z • A to Z • 0 to 9 • #,'.ÀàÂâÄäÅåÇçÉéÈèÊêËëÎîÏïÔôÖöÙùÛûÜ ü This is the city in which the customer resides. Accepted characters are: • a to z • A to Z • 0 to 9 • .'ÀàÂâÄäÅåÇçÉéÈèÊêËëÎîÏïÔôÖöÙùÛûÜü

1-13

NETBANX Checkout API

November 2014

Table 1-4: updateProfileRequest Elements (Continued) Element billingDetails (continued)

Child Element state/region

Required Conditional

Type If state, then enumeration

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

If region, then string

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

Max = 40

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

country

Conditional

Enumeration

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

zip

Conditional

String

This is the customer’s postal code. If the customer is in the U.S., it is the Zip code.

Min = 5

timeAtAddress

Yes

Max = 10

Accepted characters are: • [a-zA-Z][0-9][a-zA-Z]*[0-9][a-zA-Z][0-9] • [0-9][0-9][0-9][0-9][0-9] • [0-9][0-9][0-9][0-9][0-9]\-[0-9][0-9][09][0-9]

Integer

This is the number of months the customer has been at this address. If less than one full month, value should be set to 0 (zero).

Min = 0 Max = 120

1-14

Description

November 2014

updateProfileRequest transactions

Table 1-4: updateProfileRequest Elements (Continued) Element

Child Element

previousAddress

Required

Type

Optional

street

Conditional

This is the customer’s previous address. It must be provided if the customer has lived at a different address in the last two years. Otherwise, the profile validation could fail. String Max = 50

street2

Optional

String Max = 50

city

state/region

Conditional

Conditional

Description

String

This is the first line of the customer’s street address. Accepted characters are: • a to z • A to Z • 0 to 9 • #,'.ÀàÂâÄäÅåÇçÉéÈèÊêËëÎîÏïÔôÖöÙùÛûÜ ü This is the second line of the customer’s street address Accepted characters are: • a to z • A to Z • 0 to 9 • #,'.ÀàÂâÄäÅåÇçÉéÈèÊêËëÎîÏïÔôÖöÙùÛûÜ ü

Max = 40

This is the city in which the customer resides.

If state, then enumeration

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

If region, then string

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

Max = 40

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

Accepted characters are: • a to z • A to Z • 0 to 9 • .'ÀàÂâÄäÅåÇçÉéÈèÊêËëÎîÏïÔôÖöÙùÛûÜü

country

Conditional

Enumeration

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

zip

Conditional

String

This is the customer’s postal code. If the customer is in the U.S., it is the Zip code.

Min = 5 Max = 10

Checkout API Reference Guide

Accepted characters are: • [a-zA-Z][0-9][a-zA-Z]*[0-9][a-zA-Z][0-9] • [0-9][0-9][0-9][0-9][0-9] • [0-9][0-9][0-9][0-9][0-9]\-[0-9][0-9][09][0-9]

1-15

NETBANX Checkout API

November 2014

Table 1-4: updateProfileRequest Elements (Continued) Element

Child Element

dateOfBirth

Required

Type

Description

Optional Child Element of dateOfBirth year

Optional

Integer

This is the year of the customer’s birth.

Length = 4 month

Optional

Integer

This is the month of the customer’s birth.

Length = 2 day

Optional

Integer

This is the day of the customer’s birth.

Length = 2 customerStatus

Optional

Enumeration

This is the status of the customer: Possible values are: • INITIAL – Customer’s profile has not been validated. • ACTIVE – Customer’s profile has been validated and they can now initiate transactions. • DISABLED – Customer’s has been disabled and they cannot initiate transactions.

phone

Optional

String

This is the customer’s phone number.

Max = 40 notificationEmail

Optional

String

This is the customer’s email address.

Max = 100 mobilePhone

Optional

String

This is the customer’s cell phone number.

Max = 40 companyName

Optional

String

This is the company the customer works for.

Max = 80 locale

Optional

This is the geographic region that indicates the language and currency required.

language

Conditional

Enumeration

This is the language of the merchant. Possible values are: • en • fr

country

Conditional

Enumeration

This is the country of the merchant. Possible values are: • US • CA

For locale, the language child element can be set to en only when the country child element is set to US; and the language child element can be set to fr only when the country child element is set to CA.

1-16

November 2014

profileCheckoutRequest transactions

profileCheckoutRequest transactions The profileCheckoutRequest transaction is a customer-initiated purchase request made from your ecommerce site, typically using an existing customer profile. However, if a customer profile does not already exist, it will be created as part of this transaction process. You can use the profileCheckoutRequest for Purchase transactions, for which both Authorization and Settlement are completed, and for Authorization transactions, where the Settlement occurs later in a separate transaction (see profileSettleRequest transactions on page 1-23).

profileCheckoutRequest XML This is the XML for a sample profileCheckoutRequest transaction. In this sample, the Authorization that is being initiated is not being settled at the same time. See profileSettleRequest transactions on page 1-23 for details on settling Authorizations. 12312331 JSESSIONID 12312311231 JSESSIONID 12312311231 CC USD Potash Shipment 3 2500.00 PST 200.00 GST 100.00 2800.00 customer_info shop_id < value>123423 99996666 12312211 false en US

Checkout API Reference Guide

1-17

NETBANX Checkout API



profileCheckoutRequest schema A profileCheckoutRequest has the following structure:

1-18

November 2014

November 2014

profileCheckoutRequest transactions

profileCheckoutRequest elements The profileCheckoutRequest transaction may contain the following elements: Table 1-5: profileCheckoutRequest Elements Element

Child Element

merchantRefNum

Required Yes

Type String Max = 40

returnUrl

param

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

Yes

Your customer will be redirected to the returnURL you specify here on both successful and failed attempts. Therefore, you must check the transaction status NETBANX sends to your callbackURL before displaying a Success or Failure page.

Optional

You can use multiple param elements if required.

Child Element of param key

Conditional

String Max = 30

value

Conditional

String Max = 30

cancelUrl

param

This is the key/value pair returned as part of the returnUrl. Note: The confirmation number for a profileCheckoutRequest will also be returned to the returnURL specified

Yes

The URL of the Web site to which your customer is redirected after they elect to abandon the request without actually attempting to process it.

Optional

You can use multiple param elements if required.

Child Element of param key

Conditional

String Max = 30

value

Conditional

This is the key/value pair returned as part of the cancelUrl.

String Max = 30

accountNum

Optional

String Max = 10

paymentMethod

Checkout API Reference Guide

Optional

Enumeration

This is the merchant account number. If one is not provided the system will route the request to the appropriate account based on the card information collected. This is the method of payment used for the transaction. Possible values are: • CC – credit card • DD – direct debit

1-19

NETBANX Checkout API

November 2014

Table 1-5: profileCheckoutRequest Elements (Continued) Element

Child Element

Required

Type

Description

Attribute of paymentMethod settleAuth

Optional

Boolean

This indicates whether the credit card Authorization initiated with this transaction request will be settled immediately. Possible values are: • false • true NOTE: If this attribute set to “true” or if it is omitted, then the Authorization is settled immediately, as with a standard credit card purchase.

currencyCode

Yes

shoppingCart

Optional description

Conditional

Enumeration

This is the currency specified for this request. The currency specified must match the currency of the account number. Possible values are: • USD • CAD This is a description and cost of the items in the shopping cart.

String

This is a description of the item.

Max = 255 quantity

Optional

Integer

This is the number of the item(s).

amount

Conditional

String

This is the amount of the item(s) in dollars. For example 1200 is $1200.00.

Max = 10

ancillaryFees

totalAmount

Optional

This is a description and amount of additional fees that may be charged, for example, taxes, shipping fees, or coupons.

description

Conditional

This is a description of the fee.

amount

Conditional

This is the amount of the fee in dollars. For example 1200 is $1200.00.

Yes

String Max = 10

1-20

Note: The system does not multiply the amount by the quantity. The amount provided must be the full amount for all items.

This is the total amount in dollars. For example 1200 is $1200.00.

November 2014

profileCheckoutRequest transactions

Table 1-5: profileCheckoutRequest Elements (Continued) Element

Child Element

addendumItems

Required

Type

Optional

service

Conditional

This element allows you to append any tag/value pair you want to the transaction request, and the same tag/value pair will be returned in the addendumResponse element of the profileCheckoutResponse. String Max = 50

detail

Description

Conditional

Use this element to name the tag/value pairs included with the request. This will be returned as part of the addendumResponse. You can include multiple detail elements if required.

Child Elements of detail tag

Conditional

String Max = 30

value

Conditional

String

This is the tag/value pair returned as part of the addendumResponse.

Max = 30

Checkout API Reference Guide

1-21

NETBANX Checkout API

November 2014

Table 1-5: profileCheckoutRequest Elements (Continued) Element

Child Element

customerProfile

Required

Type

Description

Optional merchantCustomerId

Conditional

String Max = 100

customerTokenId

Optional

String Max = 50

This is a description provided by the merchant to identify this customer internally. NOTE: Do not use the customer’s email address for this element. This is a token generated by NETBANX that represents the buyer. For new customers, this field is not required as the system will create a profile as part of the payment collection process.

isNewCustomer

Conditional

Boolean

This indicates whether a new customer record is being created. Possible values are: • true • false

saveProfile

Optional

Enumeration

This specifies whether to overwrite the previous profile configuration. For example, if a new credit card is provided in the request, and this element is set to ALWAYS, then the new credit card will be stored in the existing profile. The following values are possible: • ALWAYS – profile information in the request is saved to the existing profile. • NEVER – profile information in the request is not saved to the existing profile. • USER_SELECT – allows user to decide whether or not to save profile information to the existing profile.

firstName

Optional

String

This is the customer’s first name.

Max = 80 lastName

Optional

String

This is the customer’s last name.

Max = 80 email

Optional

String

This is the customer’s email address.

Max = 100 phone

Optional

String

This is the customer’s phone number.

max = 40 mobilePhone

Optional

String

This is the customer’s cell phone number.

Max = 40 companyName

Optional

String Max = 80

1-22

This is the company the customer works for.

November 2014

profileSettleRequest transactions

Table 1-5: profileCheckoutRequest Elements (Continued) Element

Child Element

locale

Required

Type

Yes

Description This is the geographic region that indicates the language and currency required.

language

Yes

Enumeration

This is the language of the merchant. Possible values are: • en • fr

country

Yes

Enumeration

This is the country of the merchant. Possible values are: • US • CA

accordD

Optional

NOTE: Include this element only when instructed to do so by NETBANX.

financingType

Conditional

Enumeration

This is the type of financing offered. Possible values are: • D – Deferred payment financing • E – Equal payment financing

plan

Conditional

String

This is the plan number for this financing transaction.

Max = 3 gracePeriod

Optional

Integer Max = 2

term

Optional

Integer Max = 2

This is the grace period, in months, associated with deferred payment transactions. This is the number of payments, in months, for equal payment transactions.

For locale, the language child element can be set to en only when the country child element is set to US; and the language child element can be set to fr only when the country child element is set to CA.

profileSettleRequest transactions This transaction is a customer-initated settlement request, used to settle an Authorization created with a profileCheckoutRequest.

profileSettleRequest XML This is the XML for a sample profileSettleRequest transaction. 12312331 102048684 2578.00 en US

profileSettleRequest schema A profileSettleRequest has the following structure:

Checkout API Reference Guide

1-23

NETBANX Checkout API

November 2014

profileSettleRequest elements The profileSettleRequest transaction can contain the following elements: Table 1-6: profileSettleRequest Elements Element customerTokenId

Child Element

Required Optional

Type String Max = 50

merchantRefNum

Yes

String Max = 40

confirmationNumber

Yes

totalAmount

Optional

This is a token generated by NETBANX that represents the customer. This is a unique ID number associated with each request. The value is created by the merchant and submitted as part of the request. This will be included in the callback and used to correlate the post back with the original request. This is the paymentMethodConfirmationNumber returned by NETBANX in response to the profileCheckoutRequest transaction containing the Authorization you are now settling.

String Max = 10

1-24

Description

This is the amount in dollars. For example 1200 is $1200.00. If no value is provided, the full amount of the Authorization is settled.

November 2014

profilePurchaseRequest transactions

Table 1-6: profileSettleRequest Elements (Continued) Element

Child Element

locale

Required

Type

Yes

Description This is the geographic region that indicates the language and currency required.

language

Yes

Enumeration

This is the language of the merchant. Possible values are: • en • fr

country

Yes

Enumeration

This is the country of the merchant. Possible values are: • US • CA

For locale, the language child element can be set to en only when the country child element is set to US; and the language child element can be set to fr only when the country child element is set to CA.

profilePurchaseRequest transactions The profilePurchase transaction is a merchant-initiated purchase request made using an existing customer profile (in contrast to the profileCheckoutRequest, which is initiated by the customer).

profilePurchaseRequest XML This is the XML for a sample profilePurchaseRequest transaction. 1231221 12312331 CC USD 2578.00 en US

Checkout API Reference Guide

1-25

NETBANX Checkout API

November 2014

profilePurchaseRequest schema A profilePurchaseRequest has the following structure:

profilePurchaseRequest elements The profilePurchaseRequest transaction contains the following elements: Table 1-7: profilePurchaseRequest Elements Element customerTokenId

Child Element

Required Yes

Type String Max = 50

1-26

Description This is a token generated by NETBANX that represents the buyer.

November 2014

creditRequest transactions

Table 1-7: profilePurchaseRequest Elements (Continued) Element

Child Element

merchantRefNum

Required Yes

Type String Max = 100

accountNum

Optional

String Max = 10

Description This is a unique ID number associated with each request. The value is created by the merchant and submitted as part of the request. This will be included in the callback and used to correlate the post back with the original request. This is the merchant account number. If one is not provided the system will route the request to the appropriate account based on the card information collected.

paymentMethod

Optional

Enumeration

This is the payment method used for the transaction request. Possible values are: • CC – credit card • DD – direct debit

paymentToken

Optional

String

This is a unique ID to identify this payment instrument in the NETBANX system. The paymentToken is returned in the profileLookupResponse. See profileLookupResponse on page 1-62 for details.

Max = 50

currencyCode

Yes

Enumeration

This is the currency specified for this request. The currency specified must match the currency of the account number. Possible values are: • USD • CAD

totalAmount

Yes

String

This is the amount in dollars. For example 1200 is $1200.00.

Max = 10 locale

Yes

This is the geographic region that indicates the language and currency required.

language

Yes

Enumeration

This is the language of the merchant. Possible values are: • en • fr

country

Yes

Enumeration

This is the country of the merchant. Possible values are: • US • CA

For locale, the language child element can be set to en only when the country child element is set to US; and the language child element can be set to fr only when the country child element is set to CA.

creditRequest transactions This allows you to credit an amount to a customer’s credit card. This credit transaction is not associated with a previously existing authorization, so the amount of the transaction is not restricted in this way.

Checkout API Reference Guide

1-27

NETBANX Checkout API

creditRequest XML This is the XML for a sample creditRequest transaction. 1231221 12312331 12345678 CC PTLTk0MzU4MzkyOQ USD 125.00 en US 100296

creditRequest schema A creditRequest has the following structure:

1-28

November 2014

November 2014

creditRequest transactions

creditRequest elements The creditRequest transaction contains the following elements: Table 1-8: creditRequest Elements Element

Child Element

customerTokenId

Required Yes

Type String Max = 50

merchantRefNum

Yes

String Max = 100

accountNum

Optional

String

Description This is a token generated by NETBANX that represents the buyer. This is a unique ID number associated with each request. The value is created by the merchant and submitted as part of the request. This will be included in the callback and used to correlate the post back with the original request. This is the merchant account number.

Max = 10

Checkout API Reference Guide

1-29

NETBANX Checkout API

November 2014

Table 1-8: creditRequest Elements (Continued) Element

Child Element

Required

Type

Description

paymentMethod

Optional

Enumeration

This is the payment method used for the transaction request. Possible values are: • CC – credit card • DD – direct debit

paymentToken

Optional

String

This is a unique ID to identify this payment instrument in the NETBANX system. The paymentToken is returned in the profileLookupResponse. See profileLookupResponse on page 1-62 for details.

Max = 50

If this value is not provided and if the selected payment method is CC, the saved default card will be used. Otherwise, it will default to the bank account. currencyCode

Yes

Enumeration

This is the currency specified for this request. The currency specified must match the currency of the account number. Possible values are: • USD • CAD

totalAmount

Yes

String

This is the amount in dollars. For example 1200 is $1200.00.

Max = 10

locale

authCode

Yes

The amount maximum is configured on a merchant-by-merchant basis. It applies to each transaction and to the daily maximum per credit card. Contact your account manager for details. This is the geographic region that indicates the language and currency required.

language

Yes

Enumeration

This is the language of the merchant. Possible values are: • en • fr

country

Yes

Enumeration

This is the country of the merchant. Possible values are: • US • CA

Optional

String

This is the Authorization code assigned by the issuing bank and returned by NETBANX for a previous transaction.

Max = 50

NOTE: Include this element only when instructed to do so by NETBANX.

For locale, the language child element can be set to en only when the country child element is set to US; and the language child element can be set to fr only when the country child element is set to CA.

1-30

November 2014

cancelCreditRequest transactions

cancelCreditRequest transactions This allows you to cancel a previously existing creditRequest transaction, provided it is in a Pending state, which typically is before midnight of the day that it is requested. In some cases, you may find older credit transactions in a Pending state.

cancelCreditRequest XML This is the XML for a sample cancelCreditRequest transaction. 12312331 102048684 en US

cancelCreditRequest schema A cancelCreditRequest has the following structure:

cancelCreditRequest elements The cancelCreditRequest transaction contains the following elements: Table 1-9: cancelCreditRequest Elements Element

Child Element

merchantRefNum

Required Yes

Type String Max = 100

Checkout API Reference Guide

Description This is a unique ID number associated with each request. The value is created by the merchant and submitted as part of the request. This will be included in the callback and used to correlate the post back with the original request.

1-31

NETBANX Checkout API

November 2014

Table 1-9: cancelCreditRequest Elements (Continued) Element

Child Element

confirmationNumber

Required Yes

Type String Max = 20

locale

Description This is the confirmation number returned by NETBANX in response to the initial creditRequest that is being cancelled. This is the geographic region that indicates the language and currency required.

language

Yes

Enumeration

This is the language of the merchant. Possible values are: • en • fr

country

Yes

Enumeration

This is the country of the merchant. Possible values are: • US • CA

For locale, the language child element can be set to en only when the country child element is set to US; and the language child element can be set to fr only when the country child element is set to CA.

profileEftRegistrationRequest transactions This transaction is a customer-initiated request that allows you to initiate the registration of a customer ’s bank account.

profileEftRegistrationRequest XML This is the XML for a sample profileEftRegistrationRequest transaction. 12312211 12312331 JSESSIONID 12312311231 JSESSIONID 12312311231 fr CA CA

1-32

November 2014

profileEftRegistrationRequest transactions

profileEftRegistrationRequest schema A profileEftRegistrationRequest has the following structure:

profileEftRegistrationRequest elements The profileEftRegistrationRequest transaction contains the following elements: Table 1-10: profileEftRegistrationRequest Elements Element

Child Element

customerTokenId

Required Required

Type String Max = 50

merchantRefNum

Yes

String Max = 40

Checkout API Reference Guide

Description This is a token generated by NETBANX that represents the customer. This is a request ID that the merchant creates and provides with the transaction. This ID helps the merchant to identify the request internally.

1-33

NETBANX Checkout API

November 2014

Table 1-10: profileEftRegistrationRequest Elements (Continued) Element

Child Element

returnUrl

param

Required

Type

Description

Yes

Your customer will be redirected to the returnURL you specify here on both successful and failed attempts. Therefore, you must check the transaction status NETBANX sends to your callbackURL before displaying a Success or Failure page.

Optional

You can use multiple param elements if required.

Child Element of param key

Conditional

String Max = 30

value

Conditional

String Max = 30

cancelUrl

param

This is the key/value pair returned as part of the returnUrl. Note: The confirmation number for a profileCheckoutRequest will also be returned to the returnURL specified

Yes

The URL of the Web site to which your customer is redirected after they elect to abandon the request without actually attempting to process it.

Optional

You can use multiple param elements if required.

Child Element of param key

Conditional

String Max = 30

value

Conditional

This is the key/value pair returned as part of the cancelUrl.

String Max = 30

locale

bankCountry

Yes

This is the geographic region that indicates the language and currency required.

language

Yes

Enumeration

This is the language of the merchant. Possible values are: • en • fr

country

Yes

Enumeration

This is the country of the merchant. Possible values are: • US • CA

Optional

String

This is the country where the bank is located. Possible values are: • CA – Canada • US – United States

Value = 2

If this element is not specified, the value defaults to CA.

For locale, the language child element can be set to en only when the country child element is set to US; and the language child element can be set to fr only when the country child element is set to CA.

1-34

November 2014

profileEftRegistrationStatusRequest transactions

profileEftRegistrationStatusRequest transactions This transaction allows you to determine the status of a customer’s bank account registration (i.e., the status of the profileEftRegistrationRequest).

profileEftRegistrationStatusRequest XML This is the XML for a sample profileEftRegistrationStatusRequest transaction. 12312211

profileEftRegistrationStatusRequest schema A profileEftRegistrationStatusRequest has the following structure:

profileEftRegistrationStatusRequest elements The profileEftRegistrationStatusRequest transaction contains the following element: Table 1-11: profileEftRegistrationStatusRequest Elements Element

Child Element

customerTokenId

Required Yes

Type String Max = 50

Description This is a token generated by NETBANX that represents the customer.

transactionLookupRequest transactions The transactionLookupRequest transaction allows you to look up a response from a previously processed transaction (e.g., a profileCheckoutRequest), using the merchantRefNum value that you had included in that original request.

transactionLookupRequest XML This is the XML for a sample transactionLookupRequest transaction. 12312331

transactionLookupRequest schema A transactionLookupRequest has the following structure:

Checkout API Reference Guide

1-35

NETBANX Checkout API

November 2014

transactionLookupRequest elements The transactionLookupRequest transaction contains the following elements: Table 1-12: transactionLookupRequest Elements Element

Child Element

merchantRefNum

Required Yes

Type String Max = 40

Description This is the merchantRefNum that was included as part of the original request that you are now attempting to look up.

profileLookupRequest transactions The profileLookupRequest transaction allows you to look up a previously created customer profile, using one of the following values: •

The customerTokenId value that you received in response to the profile creation (see profileResponse on page 1-41)



The merchantCustomerId that you created for this customer (see createProfileRequest transactions on page 1-5 or profileCheckoutRequest transactions on page 1-17).

profileLookupRequest XML This is the XML for a sample profileLookupRequest transaction. 12312331

profileLookupRequest schema A profileLookupRequest has the following structure:

profileLookupRequest elements The profileLookupRequest transaction contains the following element:

1-36

November 2014

Standalone payment page

Table 1-13: profileLookupRequest Element Element

Child Element

customerTokenId

Required Conditional

Type String Max = 50

merchantCustomerId

Conditional

String Max = 100

Description This is a token generated by NETBANX that represents the customer. It is returned in profileResponse (see profileResponse on page 1-41 for details). This is a description previously provided by the merchant to identify this customer internally.

Standalone payment page With the standard implementation of the NETBANX Checkout API, when your customer clicks the payment button on your e-commerce site, they are presented with an inline frame on your site. See step 4 in Customer-initiated payment process on page 1-4 for details. The Checkout API also provides a “standalone” option for some transaction types. With the standalone option, when your customer clicks the payment button on your e-commerce site, instead of being presented with in inline frame on your site, the customer is taken to a separate payment page, distinct from your site. Once the transaction is completed, however, the rest of the workflow remains the same, and the customer is returned to the Web page you specify in your returnUrl. If the transaction fails for a “retryable” reason (e.g., an invalid expiry date was provided), NETBANX will display a retry page. If you want NETBANX to display a confirmation page before proceeding to the page specified in your returnUrl, you can inform Technical Support. This standalone option is available for the following transaction types: •

profileCheckoutRequest



profilePurchaseRequest



profileSettleRequest



transactionLookupRequest

There is no additional integration required for you to implement the standalone option. All you have to do is modify the URL to which you send your transaction requests. For the standalone option, post your transaction requests to the following URL: https://checkout.optimalpayments.com/securePayment/standalone/.htm where transaction_type is the name of the transaction you are sending. For example: https://checkout.optimalpayments.com/securePayment/standalone/profileCheckoutRequest.htm See Posting transactions to NETBANX on page 1-38 for details.

Private label branding The standalone model also permits merchants to display their own logo on the payment page. To do so, you must provide NETBANX with your logo. The logo should be: •

A JPG, GIF, or PNG file



A maximum size of 2 MB

Checkout API Reference Guide

1-37

NETBANX Checkout API



November 2014

A maximum of 271 pixels wide

To provide your logo to NETBANX, email it and your Shop ID to Technical Support at [email protected] Your account manager will inform you if you should use the standard URLs for posting your transaction requests or the standalone URLs.

Posting transactions to NETBANX Once you have created a transaction request you must post it to NETBANX.

To post a transaction to NETBANX: 1.

Create an XML request. See Checkout API transactions on page 1-5 for details.

2.

With the XML request and your Shop Key, use the HMAC-SHA-1 encryption function to create a signature (see Java examples on page 1-66 for details).

3.

Encode both the XML request and the signature using Base64.

4.

Include these encoded elements in a Post to NETBANX.

5.



Shop ID – provided to you by NETBANX



The Base64–encoded XML request



The Base64–encoded digital signature

Post the request to https://checkout.optimalpayments.com/securePayment/op/profileCheckoutRequest.htm



1-38

November 2014

Processing the response

6.

NETBANX will respond to your post: •

For a profilePurchaseRequest, a confirmation number is returned in the response.



For a profileCheckoutRequest, NETBANX returns a private-labeled page that should be displayed on your site in an inline frame.

For more details on creating and posting transaction requests, see JSP example on page 1-69.

Processing the response The NETBANX Checkout API currently returns the following responses: Table 1-14: Checkout API Responses Transaction profileResponse

Description This is a response to the createProfileRequest and updateProfileRequest transactions. See profileResponse on page 1-41.

profileCheckoutResponse

This is a response to the profileCheckoutRequest transaction. See profileCheckoutResponse on page 1-42.

profileSettleResponse

This is a response to the profileSettleRequest transaction. See profileSettleResponse on page 1-46.

profilePurchaseResponse

This is a response to the profilePurchaseRequest transaction. It contains the same elements as found in the profileCheckoutResponse. See profileCheckoutResponse on page 1-42.

creditResponse

This is a response to the creditRequest transaction. See creditResponse on page 1-49.

cancelCreditResponse

This is a response to the cancelCreditRequest transaction. See cancelCreditResponse on page 1-52.

profileEftRegistrationResponse

This is a response to the profileEftRegistrationRequest transactuion. See profileEftRegistrationResponse on page 1-54.

Checkout API Reference Guide

1-39

NETBANX Checkout API

November 2014

Table 1-14: Checkout API Responses (Continued) Transaction

Description

profileEftRegistrationStatusResponse

This is a response to: • The profileEftRegistrationStatusRequest transaction (see profileEftRegistrationStatusResponse on page 1-56) • The creditRequest transaction, in cases where the transaction could not be completed due to problems with the customer’s bank account • A failed micro-deposit NETBANX attempted to make in order to verify the customer’s bank, when the failure is due to problems with the customer’s bank account.

transactionLookupResponse

This is a response to the transactionLookupRequest transaction. See transactionLookupResponse on page 1-58.

profileLookupResponse

This is a response to the profileLookupRequest transaction. See profileLookupResponse on page 1-62.

Responses directed to your callback URL NETBANX directs the following responses to your callback URL: •

profileResponse



profileCheckoutResponse



profilePurchaseResponse



creditResponse



cancelCreditResponse



profileSettleResponse



profileEftRegistrationResponse

NETBANX returns two items in response to each transaction request you submit. •

A Base64-encoded XML response to the transaction request



A Base64-encoded HMAC-SHA-1–encrypted signature

NETBANX will send the response as an SSL post request with the following parameters: •

An encodedMessage parameter, representing the XML response



A signature parameter, representing the HMAC signature

You will receive these at the Callback URL you provided to NETBANX when you set up your account. Your server must acknowledge the response from NETBANX by sending the HTTP status code 204 to indicate that the response posted to your Callback URL was received. See Processing a response on page 1-67 to view an example.

Responses directed to your API NETBANX directs the following responses to your API:

1-40



profileEftRegistrationStatusResponse (also sent to your callback URL in some cases – see profileEftRegistrationStatusResponse on page 1-56 for details)



transactionLookupResponse



profileLookupResponse

November 2014

profileResponse

NETBANX returns two items in response to each transactionLookupRequest and profileLookupRequest. •

A Base64-encoded XML response to the transaction request



A Base64-encoded HMAC-SHA-1–encrypted signature

NETBANX will send the response with the following parameters: •

An encodedMessage parameter, representing the XML response



A signature parameter, representing the HMAC signature

You will receive these as a result of your Post request.

profileResponse The profileResponse is the XML response returned by NETBANX in response to a createProfileRequest or an updateProfileRequest, or to a profileCheckoutRequest transaction when that transaction included the modification of the customer profile information, (e.g., the addition of a credit card number).

profileResponse XML This is the XML for a sample profileResponse. CREATED 0 Profile created successfully. 99996666 12312211 true

profileResponse schema A profileResponse has the following structure:

Checkout API Reference Guide

1-41

NETBANX Checkout API

November 2014

profileResponse elements The profileResponse may contain the following elements: Table 1-15: profileResponse Elements Element

Child Element

Required

Type

Description

decision

Yes

Enumeration

This is the status of the transaction. One of the following is returned: • CREATED – The customerProfile in the profileRequest transaction was created successfully. • MODIFIED – The customerProfile in the profileRequest transaction was modified successfully. • ERROR – The profileRequest transaction was attempted, but failed for some reason.

customerStatus

Optional

Enumeration

This is the status of the customer: Possible values are: • INITIAL – Customer’s profile has not been validated. • ACTIVE – Customer’s profile has been validated and they can now initiate transactions. • DISABLED – Customer’s has been disabled and they cannot initiate transactions.

code

Yes

description

Yes

Integer

This is a numeric code that categorizes the response. See Response codes on page B-1 for details.

String

This is a human readable description of the code element.

Max = 1024 customerProfile

Yes

For a description of these elements, see the customerProfile element in Table 1-5: profileCheckoutRequest Elements on page 1-19.

profileCheckoutResponse The profileCheckoutResponse is the XML response returned by NETBANX in response to a profileCheckoutRequest transaction. The profilePurchaseResponse is returned by NETBANX in response to a profilePurchaseRequest transaction. It contains the same elements as the profileCheckoutResponse.

profileCheckoutResponse XML This is the XML for a sample profileCheckoutResponse. 102048684 12312331 [email protected] 12345678 VI ACCEPTED 0 No Error

1-42

November 2014

profileCheckoutResponse

2010-05-10T14:23:10.184-04:00 CC 8951 0 102048684 customer_info shop_id 123423

Checkout API Reference Guide

1-43

NETBANX Checkout API

profileCheckoutResponse schema A profileCheckoutResponse has the following structure:

1-44

November 2014

November 2014

profileCheckoutResponse

profileCheckoutResponse elements The profileCheckoutResponse may contain the following elements: Table 1-16: profileCheckoutResponse Elements Element

Child Element

confirmationNumber

Required Yes

Type String Max=20

merchantRefNum

Yes

String Max = 40

customerName

Optional

customerEmail

Optional

String

Description This is the confirmation number returned by NETBANX in response to the transaction request. This is a unique ID number associated with each request. The value is created by the merchant and submitted as part of the request.

Max = 255

This is the cardholder’s name for the credit card transaction.

String

This is the customer’s email address.

Max = 100 accountNum

Yes

String Max = 10

cardType

Yes

cardExpiry

Optional month

Conditional

This is the merchant account number for which the transaction was processed.

Enumeration

This is the type of card used for the transaction. Possible values are: • AM = American Express • DC = Diners Club • DI = Discover • JC = JCB • LA = Laser • MC = MasterCard • MD = Maestro • SO = Solo • SW = Switch • VD = Visa Debit • VE = Visa Electron • VI = Visa

Integer

This is the month the card expires.

Length = 2 year

Conditional

Integer

This is the year the card expires.

Length = 4 decision

Yes

Enumeration

This is the status of the transaction. One of the following is returned: • Accepted – The transaction was processed. • Error – An internal error occurred. • Declined – The transaction was declined.

code

Yes

Integer

This is a numeric code that categorizes the response. See Response codes on page B-1 for details.

Checkout API Reference Guide

1-45

NETBANX Checkout API

November 2014

Table 1-16: profileCheckoutResponse Elements (Continued) Element

Child Element

Required

Type

Description

actionCode

Optional

Enumeration

This indicates what action the caller should take. Possible values are: • C = Consumer Parameter Error. The consumer has provided incorrect information. Ask the customer to correct the information. • D = Do Not Retry. Further attempts will fail. • M = Merchant Parameter Error. Your application has provided incorrect information. Verify your information. • R = Retry. The problem is temporary. Retrying the request will likely succeed.

description

Yes

String

This is a human readable description of the code element.

Max = 1024 txnTime

Yes

This is the date and time the transaction was processed by NETBANX.

paymentMethod

Optional

Enumeration

This is the method of payment used for the transaction. Possible values are: • CC – credit card • DD – direct debit

lastFourDigits

Optional

String

This is the last digits of the payment instrument that was used for the transaction.

attempts

Optional

Integer

This indicates the number of attempts that the customer attempted the transaction.

paymentMethod ConfirmationNumber

Optional

String

This is the confirmation number that is returned by NETBANX for the request.

addendumResponse

Optional

Max = 20

service

Conditional

String Max = 50

detail

Conditional

This is the service provider for which the values are being returned. There may be multiple detail elements if required.

Child Element of detail tag

Conditional

String Max = 30

value

Conditional

This is the tag/value pair returned as part of the addendumResponse.

String Max = 30

profileSettleResponse This transaction is a response to the profileSettleRequest transaction.

1-46

November 2014

profileSettleResponse

profileSettleResponse XML This is the XML for a sample profileSettleResponse. 102048684 12312331 12345678 ACCEPTED 0 No Error 2010-05-10T14:23:10.184-04:00

profileSettleResponse schema A profileSettleResponse has the following structure:

Checkout API Reference Guide

1-47

NETBANX Checkout API

November 2014

profileSettleResponse elements The profileSettleResponse may contain the following elements: Table 1-17: profileSettleResponse Elements Element confirmationNumber

Child Element

Required Yes

Type String Max=20

merchantRefNum

Yes

String Max = 40

accountNum

Yes

String Max = 10

Description This is the confirmation number returned by NETBANX in response to the transaction request. This is a unique ID number associated with each request. The value is created by the merchant and submitted as part of the request. This is the merchant account number for which the transaction was processed.

decision

Yes

Enumeration

This is the status of the transaction. One of the following is returned: • Accepted – The transaction was processed. • Error – An internal error occurred. • Declined – The transaction was declined.

code

Yes

Integer

This is a numeric code that categorizes the response. See Response codes on page B-1 for details.

actionCode

Optional

Enumeration

This indicates what action the caller should take. Possible values are: • C = Consumer Parameter Error. The consumer has provided incorrect information. Ask the customer to correct the information. • D = Do Not Retry. Further attempts will fail. • M = Merchant Parameter Error. Your application has provided incorrect information. Verify your information. • R = Retry. The problem is temporary. Retrying the request will likely succeed.

description

Yes

String

This is a human readable description of the code element.

Max = 1024 txnTime

1-48

Yes

This is the date and time the transaction was processed by NETBANX.

November 2014

creditResponse

Table 1-17: profileSettleResponse Elements (Continued) Element

Child Element

addendumResponse

Required

Type

Description

Optional service

Conditional

String Max = 50

detail

Conditional

This is the service provider for which the values are being returned. There may be multiple detail elements if required.

Child Element of detail tag

Conditional

String Max = 30

value

Conditional

This is the tag/value pair returned as part of the addendumResponse.

String Max = 30

creditResponse This transaction is a response to the creditRequest transaction.

creditResponse XML 102048684 12312331 Jane Jones [email protected] 12345678 ACCEPTED 0 No Error CC 2001-12-17T09:30:47.0Z 102048684 VI 12 2015 1111 customer_info shop_id 123423

Checkout API Reference Guide

1-49

NETBANX Checkout API

November 2014

creditResponse schema A creditResponse has the following structure:

creditResponse elements Table 1-18: creditResponse Elements Element confirmationNumber

Child Element

Required Yes

Type String Max=20

1-50

Description This is the confirmation number returned by NETBANX in response to the transaction request.

November 2014

creditResponse

Table 1-18: creditResponse Elements (Continued) Element

Child Element

merchantRefNum

Required Yes

Type String Max = 40

customerName customerEmail

Optional Optional

String

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

Max = 255

This is the cardholder’s name for the credit card transaction.

String

This is the customer’s email address.

Max = 100 accountNum

Yes

String Max = 10

This is the merchant account number for which the transaction was processed.

decision

Yes

Enumeration

This is the status of the transaction. One of the following is returned: • Accepted – The transaction was processed. • Error – An internal error occurred. • Declined – The transaction was declined.

code

Yes

Integer

This is a numeric code that categorizes the response. See Response codes on page B-1 for details.

description

Yes

String

This is a human readable description of the code element.

Max = 1024 paymentMethod

Optional

txnTime

Yes

paymentMethod ConfirmationNumber

Optional

cardType

Optional

Checkout API Reference Guide

Enumeration

This is the method of payment used for the transaction. Possible values are: • CC – credit card • DD – direct debit This is the date and time the transaction was processed by NETBANX.

String Max = 20 Enumeration

This is the confirmation number that is returned by NETBANX for the request. This is the type of card used for the transaction. Possible values are: • AM = American Express • DC = Diners Club • DI = Discover • JC = JCB • LA = Laser • MC = MasterCard • MD = Maestro • SO = Solo • SW = Switch • VD = Visa Debit • VE = Visa Electron • VI = Visa

1-51

NETBANX Checkout API

November 2014

Table 1-18: creditResponse Elements (Continued) Element

Child Element

cardExpiry

Required

Type

Description

Optional month

Conditional

Integer

This is the month the card expires.

Length = 2 year

Conditional

Integer

This is the year the card expires.

Length = 4 lastFourDigits

Optional

addendumResponse

Optional service

Conditional

String

This is the last digits of the payment instrument that was used for the transaction.

String

This is the service provider for which the values are being returned.

Max = 50 detail

Conditional

There may be multiple detail elements if required.

Child Element of detail tag

Conditional

String Max = 30

value

Conditional

This is the tag/value pair returned as part of the addendumResponse.

String Max = 30

cancelCreditResponse This transaction is a response to the cancelCreditRequest transaction.

cancelCreditResponse XML 102048684 12312331 12345678 ACCEPTED 0 No Error 2001-12-17T09:30:47.0Z

1-52

November 2014

cancelCreditResponse

cancelCreditResponse schema A cancelCreditResponse has the following structure:

cancelCreditResponse elements The cancelCreditResponse may contain the following elements: Table 1-19: cancelCreditResponse Elements Element

Child Element

confirmationNumber

Required Yes

Type String Max=20

merchantRefNum

Yes

String Max = 40

accountNum

Optional

String Max = 10

Description This is the confirmation number returned by NETBANX in response to the transaction request. This is a unique ID number associated with each request. The value is created by the merchant and submitted as part of the request. This is the merchant account number for which the transaction was processed.

decision

Yes

Enumeration

This is the status of the transaction. One of the following is returned: • Accepted – The transaction was processed. • Error – An internal error occurred. • Declined – The transaction was declined.

code

Yes

Integer

This is a numeric code that categorizes the response. See Response codes on page A-1 for details.

actionCode

Optional

Enumeration

This indicates what action the caller should take. Possible values are: • C = Consumer Parameter Error. The consumer has provided incorrect information. Ask the customer to correct the information. • D = Do Not Retry. Further attempts will fail. • M = Merchant Parameter Error. Your application has provided incorrect information. Verify your information. • R = Retry. The problem is temporary. Retrying the request will likely succeed.

Checkout API Reference Guide

1-53

NETBANX Checkout API

November 2014

Table 1-19: cancelCreditResponse Elements (Continued) Element description

Child Element

Required Yes

Type String Max = 1024

txnTime

Yes

Description This is a human readable description of the code element. This is the date and time the transaction was processed by NETBANX.

profileEftRegistrationResponse This transaction is a response to the profileEftRegistrationRequest transaction.

profileEftRegistrationResponse XML This is the XML for a sample profileEftRegistrationResponse. ACCEPTED PENDING 0 41 0 No Error 99996666 12312211 false

profileEftRegistrationResponse schema A profileEftRegistrationResponse has the following structure:

1-54

November 2014

profileEftRegistrationResponse

profileEftRegistrationResponse elements The profileEftRegistrationResponse may contain the following elements: Table 1-20: profileEftRegistrationResponse Elements Element

Child Element

Required

Type

Description

decision

Yes

Enumeration

This is the status of the transaction. One of the following is returned: • ACCEPTED – The transaction was processed. • ERROR – An internal error has occurred.

status

Optional

Enumeration

This is the status of bank account validation process. Possible values are: • PENDING – The bank account is registered but not yet validated. • VALIDATED – The bank account has been validated. • INITIAL – The bank account status was reset by Customer Service to allow the customer to reregister that account. • INVALID – The customer attempted to validate the bank account but was unsuccessful.

attempts

Yes

Integer

This indicates the number of attempts that the customer attempted the transaction.

bankAccountEnding

Optional

String

This is the last two digits of the bank account number.

Max = 2 code

Checkout API Reference Guide

Yes

Integer

This is a numeric code that categorizes the response. See Response codes on page A-1 for details.

1-55

NETBANX Checkout API

November 2014

Table 1-20: profileEftRegistrationResponse Elements (Continued) Element

Child Element

description

Required Yes

Type String Max = 1024

customerProfile

Yes

Description This is a human readable description of the code element. For a description of these elements, see the customerProfile element in Table 1-5: profileCheckoutRequest Elements on page 1-19.

profileEftRegistrationStatusResponse The profileEftRegistrationStatusResponse can be returned in two scenarios: 1.

It is returned as a synchronous response to the profileEftRegistrationStatusRequest transaction.

2.

It is returned to your callback URL if the micro-deposit NETBANX attempted to make in order to verify the customer’s bank account fails. In this case: •

This response is returned to your callback URL, typically 3–7 days later, with the status set to Invalid.



The customer must repeat the process of registering his or her bank account.

profileEftRegistrationStatusResponse XML This is the XML for a sample profileEftRegistrationStatusResponse. FOUND 12312211 VALIDATED 0 45 102048708 12312331 828158

profileEftRegistrationStatusResponse schema A profileEftRegistrationStatusResponse has the following structure:

1-56

November 2014

profileEftRegistrationStatusResponse

profileEftRegistrationStatusResponse elements The profileEftRegistrationStatusResponse may contain the following elements: Table 1-21: profileEftRegistrationStatusResponse Elements Element

Child Element

Required

Type

Description

decision

Yes

Enumeration

This is the status of the transaction. One of the following is returned: • FOUND – The customer token was found. • NOT_FOUND – The customer token was not found. • ERROR – An internal error has occurred. Please try again.

customerTokenId

Optional

String

This is a token generated by NETBANX that represents the customer.

Max = 50

Checkout API Reference Guide

1-57

NETBANX Checkout API

November 2014

Table 1-21: profileEftRegistrationStatusResponse Elements (Continued) Element

Child Element

Required

Type

Description

status

Optional

Enumeration

This is the status of bank account validation process. • PENDING – The bank account is registered but not yet validated. • VALIDATED – The bank account has been validated. • INITIAL – The bank account status was reset by Customer Service to allow the customer to re-register that account. • INVALID – The customer attempted to validate the bank account but was unsuccessful.

attempts

Optional

Integer

This indicates the number of attempts that the customer attempted the transaction.

bankAccountEnding

Optional

String

This is the last two digits of the bank account number.

Max = 2 code

Optional

Integer

This is a numeric code that categorizes the response. See Response codes on page A-1 for details.

description

Optional

String

This is a human readable description of the code element.

Max = 1024 returnedCheckDetails

Optional

confirmationNumber

Conditional

This element is included only when the response is returned to your callback URL in the case of a creditRequest failure resulting from problems with the customer’s bank account (e.g., when a creditRequest transaction could not be completed due to bank routing number errors). String Max=20

merchantRefNum

Conditional

String Max = 40

paymentMethod ConfirmationNumber

Conditional

String Max = 20

This is the confirmation number returned by NETBANX in the creditResponse to the original creditRequest transaction. This is the merchantRefNum that was included as part of the original creditRequest and included in the creditResponse. This is the payment method confirmation number that is returned by NETBANX in the creditResponse to the original creditRequest transaction.

transactionLookupResponse The transactionLookupResponse is the XML response returned by NETBANX in response to a transactionLookupRequest transaction.

transactionLookupResponse XML This is the XML for a sample transactionLookupResponse.

1-58

November 2014

transactionLookupResponse