Direct Payment Protocol Specification October 2005 Version 1.1 This manual and accompanying electronic media are proprietary products of Optimal Payments Inc. They are to be used only by licensed users of the product. © 1999–2006 Optimal Payments Inc. 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 accor- dance 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 Inc. FirePay and FireCash are registered trademarks of Optimal Payments Inc. All other names, trade- marks, and registered trademarks are the property of their respective owners. Optimal Payments Inc. 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 li- cense agreement of this product. For further information, please contact Optimal Payments Inc. International Head Office Optimal Payments Inc. 2 Place Alexis Nihon, Suite 700 Westmount, 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 Optimal Payments Ltd. Quern House, Mill Court Hinton Way, Great Shelford Cambridge CB2 5LD United Kingdom Email: [email protected] Technical Support: [email protected] Web: www.optimalpayments.co.uk U.S. Office Optimal Payments Corp. 1800 West Loop South, #770 Houston, TX 77027 Hull Office Optimal Payments Inc. 75 Promenade du Portage Gatineau, Quebec J8X 2J9 Canada Contents 1Transaction Requests The Optimal Payments account model . 1-1 Building transaction requests . 1-2 Decoding responses . 1-3 Example scenario . 1-4 Definitions and conventions . 1-5 Using this guide . 1-7 Audience . 1-7 Functionality . 1-7 Symbols . 1-8 Merchant transactions. 1-8 Security features . 1-9 AVS . 1-9 CVD . 1-11 Negative database . 1-11 Purchase . 1-12 Purchase message format . 1-12 Purchase successful response . 1-20 Purchase error response . 1-22 AVS Check . 1-24 AVS Check message format . 1-24 AVS Check successful response . 1-26 AVS Check error response . 1-27 Risk Only . 1-29 Risk Only message format . 1-29 Risk Only successful response. 1-32 Risk Only error response . 1-33 Authorization . 1-33 Authorization message format . 1-34 Authorization successful response. 1-41 Authorization error response . 1-43 Settlement . 1-45 Settlement message format. 1-46 Settlement successful response. 1-48 Settlement error response . 1-49 Direct Payment Protocol Specification 1.1 III October 2005 Cancel Settlement . 1-50 Cancel Settlement message format . 1-50 Cancel Settlement successful response . 1-52 Cancel Settlement error response. 1-52 Credit . 1-53 Credit message format . 1-54 Credit successful response . 1-56 Credit error response . 1-57 Cancel Credit . 1-58 Cancel Credit message format . 1-58 Cancel Credit successful response . 1-60 Cancel Credit error response . 1-60 Transaction recovery . 1-61 Transaction Lookup . 1-62 Transaction Lookup message format. 1-62 Transaction Lookup successful response . 1-65 Transaction Lookup error response. 1-65 Query . 1-66 Query message format . 1-67 Query successful response . 1-68 Query error response . 1-71 A Error Return Codes Error message types . A-1 Payment service error messages . A-1 Action codes . A-2 Error codes and strings . A-2 Suberror codes and strings . A-12 Unmapped suberror codes and strings . A-15 B Geographical Codes Province codes . B-1 State codes. B-2 Country codes . B-3 IV October 2005 C Merchant SIC Codes D Product Codes Index Direct Payment Protocol Specification 1.1 V October 2005 VI CHAPTER 1 Transaction Requests The Optimal Payments account model Optimal Payments merchants are assigned one or more accounts upon registration. Each account may process transactions for one currency only. These accounts have an account number of up to eight digits, an account transaction processing ID, and a password, provided upon reg- istration, which must be included in all transaction processing requests. These three identifiers link each transaction to the account. Direct Payment Protocol Specification 1.1 1-1 Transaction Requests October 2005 Building transaction requests All transaction requests are submitted to the Optimal Payments transac- tion-processing engine as URL-encoded data. The request message is built as follows: 1. Each field is created as a name=value pair. For example: “account=400021”. 2. All non-alphanumeric characters in the name and value compo- nents are replaced by “%” followed by the hex value associated with the character. For example, all spaces are replaced with “%20”. Thus “Thanks for the help!” would be modified to “Thanks%20for%20the%20help%21”. 3. The fields are concatenated together into a single string, with each field separated by the “&” character. For example: account=40021&amount=1000&operation=A&cardNumber=405025900504 0&cardExp=12%2f99&cardType=VI 4. Determine the length of the string. Build the message as the following header concatenated with a blank line and the string containing the fields. The value URL_FOR_Direct_Payment should be replaced by the URL provided to you when you registered with the service, and length should be replaced by the length you calculated in step 4 above. POST URL_FOR_Direct_Payment<CR><LF> Content-type: application/x-www-form-urlencoded<CR><LF> Content-length: length<CR><LF> Upon testing, if the URL provided to you during registration were https://realtime.test.firepay.com an example of the complete message would be: POST /realtime.test.firepay.com HTTP/1.0<CR><LF> Content-type: application/x-www-form-urlencoded<CR><LF> Content-length: 91<CR><LF> <CR><LF> account=40021&amount=1000&operation=A&cardNumber=405025900504 0&cardExp=12%2f99&cardType=VI To submit this request, the merchant application then opens an SSL pro- tected socket connection to Optimal Payments’ transaction-processing engine and sends the request data. 1-2 October 2005 Decoding responses Any tool that creates and submits a standard HTTP Post using SSL could be employed. One example is the Microsoft URL Control, which allows you to set the data to be posted and then to do a secure POST of that data. Decoding responses The response to a request is returned as an HTTP header, a blank line and then a string containing a number of name=value pairs. The string is URL encoded so that all non-alphanumeric characters in the name or value components are replaced by “%” followed by the ASCII code in hex for that character. For example, “!” is replaced with “%21”. Spaces may also be replaced by the “+” character. In order to extract the fields from the response, the following steps should be followed: 1. Split the string after the blank line into name=value pairs at each “&” separator. 2. Split the name=value pairs into their name and value components based on the “=” separator. 3. Replace all “+” characters in the name and value components with a space character. 4. Replace all %XX occurrences in the name and value components with the ASCII character represented by the hex value XX. An example of a response message would be: HTTP/1.1 200 OK Server: Netscape-Enterprise/3.5.1 Date: Mon, 27 Nov 2000 15:58:03 GMT Content-type: text/plain Status=E&errCode=131&errString=Operation+not+supported+%28131 %29+-Please+check+request+parameters&subError=0 This response message would decode into the following values: Response Parameter Value status E errCode 131 Table 1-1: Response Parameters Direct Payment Protocol Specification 1.1 1-3 Transaction Requests October 2005 Response Parameter Value errString Operation not supported (131) - Please check request parameters. subError 0 Table 1-1: Response Parameters (Continued) Example scenario The following presents a series of real-world scenarios that demonstrate the Optimal Payments account model. The following participants inter- act in the scenarios: • Store – an online bookstore • Smith – a consumer • Optimal Payments – the Optimal Payments transaction processor A) Smith buys 3 books 1. Smith purchases the following books at Store • Book a: $10 • Book b: $25 • Book c: $25 2. Store sends an Authorization request to Optimal Payments for the total amount ($60) 3. An Authorization transaction is created for $60 (Authorization TRID = 0020) B) Store ships the first two books 1. A Settlement is made: $35 ($10 + $25) against Authorization 0020 (Settlement TRID = 0123) 2. Remaining on Authorization 0020 = $25 3. Status of Authorization 0020 = partially settled C) Settlement batch run 1. State of Settlement 0123 = complete 2. State of Authorization 0020 = partially settled 1-4 October 2005 Definitions and conventions D) Store ships the third book 1. A Settlement is made: $25 against Authorization 0020 (Settlement TRID = 0232) 2. Remaining on Authorization 0020 = $0 3. State of Settlement 0232 = pending 4. Status of Authorization 0020 = settled E) Settlement batch run 1. State of Settlement 0232 = complete 2. State of Authorization 0020 = settled F) Smith returns third book 1. A Credit is made: $25 against Settlement TRID= 0123 (Credit TRID = 0256) 2. Remaining on Settlement 0123 = $10 3. Remaining on Authorization 0020 = $0 4. State of Settlement 0232 = complete 5. State of Authorization 0020 = settled 6. State of Credit 0256 = pending G) Credit batch run 1. State of Settlement 0232 = complete 2. State of Authorization 0020 = settled Definitions and conventions This section defines the message formats for merchant–transaction processor interactions. Messages are defined in terms of a set of fields. Each field has the following: •A name • A requirement setting, which may be: • (mandatory) – the transaction cannot be processed without this parameter. Direct Payment Protocol Specification 1.1 1-5 Transaction Requests October 2005 • (optional) – the transaction can always be processed without this parameter.