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